RPG MCP Server

中文文档 | English | NPM Package | GitHub

A complete, production-ready RPG game system MCP server implementation with PostgreSQL database, enabling LLMs to run sophisticated text-based RPG games with reliable data persistence.

✨ Features

Core Capabilities

• 🎮 50+ MCP Tools: Comprehensive game system with query, calculation, update, and management tools
• 💾 PostgreSQL Database: Enterprise-grade data persistence with ACID transactions
• 🤖 LLM-Friendly: Auto database initialization, dynamic content generation, flexible CRUD operations
• ⚡ High Performance: LRU caching system, connection pooling, optimized queries with indexes
• 🔒 Type Safety: Full TypeScript implementation with Zod validation
• 📊 Monitoring: Built-in health checks, logging system, cache statistics

Game Systems

• ⚔️ Combat System: Automated damage calculation, experience rewards, loot generation
• 🎯 Quest System: Quest tracking, progress updates, completion rewards
• 🛠️ Crafting System: 6 professions, recipe learning, quality tiers, proficiency progression
• 🏆 Achievement System: Progress tracking, rewards, statistics, multiple categories
• 🌍 World System: Time progression, weather changes, dynamic events
• 💼 Inventory & Equipment: Item management, quality system, equipment bonuses
• 👥 NPC & Faction System: Relationship tracking, reputation, companions
• 💾 Save System: Complete game state snapshots, multiple save slots

📦 Installation

Option 1: NPM Global Install (Recommended)

npm install -g @qianjue/rpg-mcp-server
rpg-mcp-server

Option 2: NPX (No Installation)

npx @qianjue/rpg-mcp-server

Option 3: Build from Source

git clone https://github.com/QianJue-CN/RPGMCP.git
cd RPGMCP
npm install
npm run build
npm start

🚀 Quick Start

Prerequisites

• Node.js 18.0.0 or higher
• PostgreSQL 14 or higher

1. Database Setup

Create a PostgreSQL database:

createdb rpg_game

2. Configuration

Create a .env file (or configure via Claude Desktop):

DB_HOST=localhost
DB_PORT=5432
DB_NAME=rpg_game
DB_USER=postgres
DB_PASSWORD=your_password

3. Database Initialization

Method A: Auto-initialization via LLM (Recommended)

Start the server and let the LLM initialize the database:

npm start

Then ask Claude:

Check database status and initialize if needed

Method B: Manual initialization

npm run build
npm run db:migrate
npm run db:seed  # Optional: load sample data

🔧 Claude Desktop Configuration

Config File Location

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Using NPX (Recommended)

{
  "mcpServers": {
    "rpg-game": {
      "command": "npx",
      "args": ["@qianjue/rpg-mcp-server"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "rpg_game",
        "DB_USER": "postgres",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

Using Absolute Path

{
  "mcpServers": {
    "rpg-game": {
      "command": "node",
      "args": ["/absolute/path/to/RPGMCP/dist/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "rpg_game",
        "DB_USER": "postgres",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

Note: Restart Claude Desktop after configuration changes.

🛠️ Tool Categories

🔐 Admin Tools (3)

• get_database_status - Check database initialization status
• initialize_database - Initialize database schema and seed data
• reset_database - Reset database (dangerous operation)

📊 Query Tools (10)

• get_player_status - Get complete player status
• get_inventory - Get inventory items
• get_equipment - Get equipped items
• get_active_quests - Get active quests
• get_skills - Get player skills
• get_faction_standings - Get faction reputation
• get_companions - Get companion list
• get_npc_info - Get NPC information
• get_npc_relations - Get NPC relationships
• get_world_state - Get world state

🧮 Calculation Tools (5)

• calculate_damage - Calculate combat damage
• calculate_exp_reward - Calculate experience rewards
• calculate_loot_drops - Calculate loot drops
• calculate_craft_result - Calculate crafting results
• calculate_reputation_change - Calculate reputation changes

✏️ Update Tools (10)

• apply_damage - Apply damage to target
• heal_target - Heal target
• add_experience - Add experience (auto level-up)
• modify_inventory - Modify inventory items
• equip_item - Equip/unequip items
• accept_quest - Accept quest
• update_quest_progress - Update quest progress
• complete_quest - Complete quest
• update_reputation - Update faction reputation
• update_npc_relation - Update NPC relationship

🌍 World & Save Tools (4)

• save_game - Save game state
• load_game - Load saved game
• list_saves - List all saves
• advance_time - Advance game time

🛠️ Crafting Tools (5)

• get_crafting_proficiency - Get crafting proficiency
• get_learned_recipes - Get learned recipes
• learn_recipe - Learn new recipe
• craft_item - Craft item from recipe
• create_or_get_recipe - Create/get recipe (LLM dynamic generation)

🏆 Achievement Tools (4)

• get_player_achievements - Get achievement progress
• update_achievement_progress - Update achievement progress
• update_player_statistics - Update player statistics
• create_or_get_achievement - Create/get achievement (LLM dynamic generation)

👤 Entity Creation Tools (6)

• create_player - Create new player character
• create_npc - Create new NPC
• create_faction - Create new faction
• delete_player - Delete player
• delete_npc - Delete NPC
• delete_faction - Delete faction

💾 Database CRUD Tools (7)

• db_query - Execute SELECT queries
• db_insert - Insert data into tables
• db_update - Update table data
• db_delete - Delete table data
• db_get_table_schema - Get table structure
• db_list_tables - List all tables
• db_transaction - Execute transactions

📁 Project Structure

rpg-mcp-server/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types.ts              # TypeScript type definitions
│   ├── cache/
│   │   ├── GameCache.ts      # LRU cache implementation
│   │   └── index.ts          # Cache exports
│   ├── database/
│   │   ├── connection.ts     # Database connection pool
│   │   ├── migrate.ts        # Migration script
│   │   └── seed.ts           # Seed data script
│   ├── tools/
│   │   ├── admin.ts          # Admin tools (DB init)
│   │   ├── query.ts          # Query tools
│   │   ├── calculate.ts      # Calculation tools
│   │   ├── update.ts         # Update tools
│   │   ├── world.ts          # World & save tools
│   │   ├── crafting.ts       # Crafting system tools
│   │   ├── achievement.ts    # Achievement system tools
│   │   ├── entity.ts         # Entity creation tools
│   │   └── database.ts       # Generic CRUD tools
│   ├── validators/
│   │   ├── player.ts         # Player validation
│   │   ├── item.ts           # Item validation
│   │   └── index.ts          # Validator exports
│   ├── health/
│   │   └── index.ts          # Health check system
│   ├── errors/
│   │   └── GameError.ts      # Custom error classes
│   └── utils/
│       ├── formulas.ts       # Game formulas
│       ├── constants.ts      # Game constants
│       └── logger.ts         # Logging system
├── database/
│   ├── schema.sql            # Database schema
│   ├── seed.sql              # Seed data
│   ├── add_indexes.sql       # Performance indexes
│   ├── add_constraints.sql   # Data constraints
│   └── optimizations.sql     # Query optimizations
├── prompts/
│   └── system_prompt_example.xml  # System prompt examples
└── package.json

🎮 Usage Examples

Combat Scenario

User: I attack the goblin with a fireball spell

Claude will automatically:
1. Call get_player_status() to get your stats
2. Call calculate_damage() to compute damage
3. Call apply_damage() to apply damage to goblin
4. Call calculate_loot_drops() if goblin dies
5. Call add_experience() to grant XP
6. Generate vivid combat narrative

Crafting Scenario

User: I want to craft an iron sword

Claude will:
1. Call get_learned_recipes() to check if you know the recipe
2. Call get_inventory() to verify materials
3. Call craft_item() to perform crafting
4. Update proficiency automatically
5. Describe the crafting process and result

Quest Scenario

User: I accept the merchant escort quest

Claude will:
1. Call accept_quest() to accept the quest
2. Describe quest details and objectives

User: I completed the escort

Claude will:
1. Call complete_quest() to complete quest
2. Automatically grant rewards (XP, gold, items)
3. Check for level-up

🔍 Advanced Features

Performance Optimization

• LRU Caching: Automatic caching of frequently accessed data (players, inventory, NPCs)
• Connection Pooling: Efficient database connection management
• Indexed Queries: Optimized database indexes for fast lookups
• Batch Operations: Transaction support for atomic multi-step operations

Monitoring & Health

• Health Checks: Database, memory, and cache health monitoring
• Logging System: Structured logging with Pino
• Cache Statistics: Hit rate, size, and performance metrics
• Error Handling: Custom error classes with detailed context

Type Safety

• TypeScript: Full type coverage
• Zod Validation: Runtime schema validation
• Type Guards: Safe type narrowing
• Strict Mode: Enabled for maximum safety

🧪 Development

# Development mode (auto-reload)
npm run dev

# Build
npm run build

# Run tests
npm test

# Test with UI
npm run test:ui

# Test coverage
npm run test:coverage

# Database operations
npm run db:migrate
npm run db:seed

📝 Environment Variables

# Database Configuration
DB_HOST=localhost          # Database host
DB_PORT=5432              # Database port
DB_NAME=rpg_game          # Database name
DB_USER=postgres          # Database user
DB_PASSWORD=your_password # Database password

# Optional Configuration
LOG_LEVEL=info            # Logging level (debug, info, warn, error)
CACHE_ENABLED=true        # Enable/disable caching

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE file for details

🔗 Links

• NPM Package
• GitHub Repository
• Issue Tracker
• Model Context Protocol

📧 Support

For questions and support, please open an issue on GitHub.