{"id":49363770,"url":"https://github.com/fritzprix/role-playing-mcp-server","last_synced_at":"2026-04-27T18:07:02.980Z","repository":{"id":308800486,"uuid":"1031240378","full_name":"fritzprix/role-playing-mcp-server","owner":"fritzprix","description":"Role-playing game server for MCP. Lets AI assistants create, manage, and narrate interactive RPGs with dynamic storylines and character management.","archived":false,"fork":false,"pushed_at":"2025-10-20T14:48:10.000Z","size":182,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-20T16:39:33.081Z","etag":null,"topics":["interactive-story","mcp","mcp-server","rpg-game","text-based-game"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fritzprix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"agents.md","dco":null,"cla":null}},"created_at":"2025-08-03T10:20:48.000Z","updated_at":"2025-10-20T14:48:14.000Z","dependencies_parsed_at":"2025-08-08T01:20:55.465Z","dependency_job_id":"f6932f96-f8ae-4281-a09e-368f72c2e8f4","html_url":"https://github.com/fritzprix/role-playing-mcp-server","commit_stats":null,"previous_names":["fritzprix/role-playing-mcp-server"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/fritzprix/role-playing-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fritzprix%2Frole-playing-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fritzprix%2Frole-playing-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fritzprix%2Frole-playing-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fritzprix%2Frole-playing-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fritzprix","download_url":"https://codeload.github.com/fritzprix/role-playing-mcp-server/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fritzprix%2Frole-playing-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32348073,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-27T17:12:42.749Z","status":"ssl_error","status_checked_at":"2026-04-27T17:12:41.658Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["interactive-story","mcp","mcp-server","rpg-game","text-based-game"],"created_at":"2026-04-27T18:07:02.244Z","updated_at":"2026-04-27T18:07:02.972Z","avatar_url":"https://github.com/fritzprix.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RPG MCP Server\n\nAn 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.\n\n## Features\n\n### 🎮 Game Tools\n\nThe server provides 7 core tools for building and managing RPG games:\n\n1. **`createGame`** - Initialize a new RPG game\n   - Set up initial game state (characters, world, inventory, etc.)\n   - Auto-generates unique game ID\n\n2. **`updateGame`** - Update game state\n   - Supports nested field paths (e.g., `characters[0].level`, `world.location`)\n   - Real-time change tracking with Delta system\n   - **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.\n\n3. **`getGame`** - Retrieve current game state\n   - Access complete game state at any time\n\n4. **`progressStory`** - Advance the narrative\n   - Record current situation and events\n   - Manage narrative flow\n\n5. **`promptUserActions`** - Present action choices to users\n   - **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.\n   - Generate interactive UI\n   - Web-based action selection interface\n\n6. **`selectAction`** - Process user selections\n   - Apply chosen actions to game state\n   - Automatically record game history\n\n7. **`selectRestart`** - Restart the game after game over\n   - Called when player clicks Restart button on Game Over screen\n   - Provides game summary and context for creating a new game\n   - AI agent receives guidance to create a contextually relevant new adventure\n\n### 🎯 User Interaction\n\n#### Basic Game Flow\n\n```text\ncreateGame → progressStory → promptUserActions → selectAction → updateGame → progressStory → ...\n```\n\n#### Game Over \u0026 Restart Flow\n\nWhen a game ends (e.g., character HP reaches 0 or story reaches an ending):\n\n```text\nupdateGame (isGameOver=true) → Game Over UI displayed →\nUser clicks Restart button → selectRestart →\nAI creates new game with context → progressStory → ...\n```\n\nThe restart flow includes:\n\n- **Context Preservation**: Previous game summary is provided to the AI\n- **AI-Suggested Continuation**: AI can create thematically related or evolved adventures\n- **One-Click Restart**: No manual intervention needed from the player\n- **Empathetic Messaging**: Game Over screen explains what happened and suggests improvements\n\n#### Interactive UI\n\n- **Web-based Selection Interface**: Beautiful UI automatically generated with story progression\n- **Real-time Change Display**: Visual feedback for recent changes via Delta system\n- **Game Over Screen**: When the game ends, a special UI explains why, what could have been done differently, and includes a Restart button\n- **Game History**: Automatically saves last 10 situation-choice records\n- **Restart Button**: Interactive button on Game Over screen that triggers `selectRestart` tool\n\n#### Example Game Scenario\n\n```typescript\n// 1. Create Game\n{\n  \"title\": \"Wizard's Adventure\",\n  \"characters\": [\n    {\"name\": \"Elara\", \"level\": 1, \"hp\": 100, \"mp\": 50, \"class\": \"Wizard\"}\n  ],\n  \"world\": {\"location\": \"Magic Academy\", \"time\": \"morning\", \"weather\": \"sunny\"},\n  \"inventory\": [{\"name\": \"Magic Staff\", \"type\": \"weapon\"}]\n}\n\n// 2. Progress Story\n\"Elara discovers an ancient spellbook in the academy library...\"\n\n// 3. Present Choices (always mix positive/negative outcomes)\n[\n  \"Read the spellbook (may gain power, but risk a curse)\",\n  \"Tell the professor (safe, but lose a chance for secret knowledge)\",\n  \"Leave it where it is (avoid risk, but miss opportunity)\",\n  \"Try to sell it secretly (potential reward, but risk being caught)\"\n]\n\n// 4. Update game state after user selection\n\"characters[0].hp\": 0, // triggers game over\n\"isGameOver\": true,\n\"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.\"\n```\n\n## MCP Client Requirements\n\n### Essential Requirements\n\n- **MCP Protocol Support**: MCP SDK 0.5.0 or higher\n- **MCP-UI Integration**: HTML resource rendering support\n- **Tool Execution**: Ability to execute all 6 game tools\n\n### Recommended Clients\n\n- **Claude Desktop** (officially supported)\n- **MCP-UI compatible clients**\n- Alternative: [synaptic-flow](https://github.com/idosal/mcp-ui) and other MCP-UI compatible clients\n\n## Claude Desktop Setup\n\n### Step 1: Locate Configuration File\n\nPlatform-specific config file locations:\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`  \n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n### Step 2: Edit Configuration File\n\n```json\n{\n  \"mcpServers\": {\n    \"rpg-game-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"rpg-mcp-server\"],\n      \"env\": {\n        \"NODE_ENV\": \"production\"\n      }\n    }\n  }\n}\n```\n\n### Step 3: Restart Claude Desktop\n\nCompletely quit and restart Claude Desktop to apply the configuration.\n\n### Step 4: Test the Setup\n\n```text\nHi! Can you create a fantasy RPG game for me?\n```\n\n## Installation \u0026 Usage\n\n### Global Installation (Recommended)\n\n```bash\nnpm install -g rpg-mcp-server\n```\n\n### Local Development\n\n```bash\ngit clone \u003crepository-url\u003e\ncd rpg-mcp-server\nnpm install\nnpm run build\nnpm start\n```\n\n### Testing with MCP Inspector\n\n```bash\nnpm run inspector\n```\n\n## Technology Stack\n\n- **TypeScript** - Type safety and developer experience\n- **MCP SDK** - Model Context Protocol implementation\n- **MCP-UI** - Interactive web UI generation\n- **Node.js** - Runtime environment\n\n## System Requirements\n\n- **Node.js** 18.0.0 or higher\n- **npm** 9.0.0 or higher\n- **MCP-compatible client**\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffritzprix%2Frole-playing-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffritzprix%2Frole-playing-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffritzprix%2Frole-playing-mcp-server/lists"}