fritzprix/role-playing-mcp-server

RPG MCP Server

An immersive Role-Playing Game server built on the Model Context Protocol (MCP), designed to work with AI assistants like Claude to create interactive storytelling experiences.

Features

🎮 Game Tools

The server provides 7 core tools for building and managing RPG games:

1. createGame - Initialize a new RPG game

   • Set up initial game state (characters, world, inventory, etc.)
   • Auto-generates unique game ID

2. updateGame - Update game state

   • Supports nested field paths (e.g., characters[0].level, world.location)
   • Real-time change tracking with Delta system
   • Game Over Support: If a state update results in game over (e.g., HP reaches 0, bad ending), set isGameOver=true and provide a gameOverReason. The server will return a special Game Over UI with an empathetic explanation and suggestions for improvement.

3. getGame - Retrieve current game state

   • Access complete game state at any time

4. progressStory - Advance the narrative

   • Record current situation and events
   • Manage narrative flow

5. promptUserActions - Present action choices to users

   • Dynamic Choices: Always present 2-4 options that mix positive and negative outcomes for dynamic, engaging gameplay. Each option should have distinct consequences and risk/reward tradeoffs.
   • Generate interactive UI
   • Web-based action selection interface

6. selectAction - Process user selections

   • Apply chosen actions to game state
   • Automatically record game history

7. selectRestart - Restart the game after game over

   • Called when player clicks Restart button on Game Over screen
   • Provides game summary and context for creating a new game
   • AI agent receives guidance to create a contextually relevant new adventure

🎯 User Interaction

Basic Game Flow

createGame → progressStory → promptUserActions → selectAction → updateGame → progressStory → ...

Game Over & Restart Flow

When a game ends (e.g., character HP reaches 0 or story reaches an ending):

updateGame (isGameOver=true) → Game Over UI displayed →
User clicks Restart button → selectRestart →
AI creates new game with context → progressStory → ...

The restart flow includes:

• Context Preservation: Previous game summary is provided to the AI
• AI-Suggested Continuation: AI can create thematically related or evolved adventures
• One-Click Restart: No manual intervention needed from the player
• Empathetic Messaging: Game Over screen explains what happened and suggests improvements

Interactive UI

• Web-based Selection Interface: Beautiful UI automatically generated with story progression
• Real-time Change Display: Visual feedback for recent changes via Delta system
• Game Over Screen: When the game ends, a special UI explains why, what could have been done differently, and includes a Restart button
• Game History: Automatically saves last 10 situation-choice records
• Restart Button: Interactive button on Game Over screen that triggers selectRestart tool

Example Game Scenario

// 1. Create Game
{
  "title": "Wizard's Adventure",
  "characters": [
    {"name": "Elara", "level": 1, "hp": 100, "mp": 50, "class": "Wizard"}
  ],
  "world": {"location": "Magic Academy", "time": "morning", "weather": "sunny"},
  "inventory": [{"name": "Magic Staff", "type": "weapon"}]
}

// 2. Progress Story
"Elara discovers an ancient spellbook in the academy library..."

// 3. Present Choices (always mix positive/negative outcomes)
[
  "Read the spellbook (may gain power, but risk a curse)",
  "Tell the professor (safe, but lose a chance for secret knowledge)",
  "Leave it where it is (avoid risk, but miss opportunity)",
  "Try to sell it secretly (potential reward, but risk being caught)"
]

// 4. Update game state after user selection
"characters[0].hp": 0, // triggers game over
"isGameOver": true,
"gameOverReason": "Elara triggered a powerful curse from the spellbook and lost all HP. If you had chosen to consult the professor or left the book alone, you might have avoided this fate."

MCP Client Requirements

Essential Requirements

• MCP Protocol Support: MCP SDK 0.5.0 or higher
• MCP-UI Integration: HTML resource rendering support
• Tool Execution: Ability to execute all 6 game tools

Recommended Clients

• Claude Desktop (officially supported)
• MCP-UI compatible clients
• Alternative: synaptic-flow and other MCP-UI compatible clients

Claude Desktop Setup

Step 1: Locate Configuration File

Platform-specific config file locations:

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

Step 2: Edit Configuration File

{
  "mcpServers": {
    "rpg-game-server": {
      "command": "npx",
      "args": ["rpg-mcp-server"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Step 3: Restart Claude Desktop

Completely quit and restart Claude Desktop to apply the configuration.

Step 4: Test the Setup

Hi! Can you create a fantasy RPG game for me?

Installation & Usage

Global Installation (Recommended)

npm install -g rpg-mcp-server

Local Development

git clone <repository-url>
cd rpg-mcp-server
npm install
npm run build
npm start

Testing with MCP Inspector

npm run inspector

Technology Stack

• TypeScript - Type safety and developer experience
• MCP SDK - Model Context Protocol implementation
• MCP-UI - Interactive web UI generation
• Node.js - Runtime environment

System Requirements

• Node.js 18.0.0 or higher
• npm 9.0.0 or higher
• MCP-compatible client

License

MIT License - see file for details.