role-playing-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

RPG MCP Server is a Model Context Protocol (MCP) server that enables AI assistants to run interactive role-playing games with users. The server provides 7 core tools that form a complete game loop: creating games, progressing narratives, prompting user choices, processing selections, updating game state, handling game over scenarios, and restarting games.

Development Commands

Build and Run

npm run build        # Compile TypeScript to JavaScript
npm start           # Run the compiled server
npm run dev         # Build and run in one step

Code Quality

npm run type-check   # Run TypeScript type checking without compilation
npm run lint         # Check code for linting errors
npm run lint:fix     # Auto-fix linting errors
npm run format       # Format code with Prettier
npm run format:check # Check code formatting
npm run check        # Run all checks: type-check, lint, and format:check

Testing & Debugging

npm run inspector     # Launch MCP Inspector for interactive testing
npm run inspector:dev # Build and launch inspector in one step
npm run clean        # Remove dist directory

Important: Always run npm run build before testing with MCP Inspector or publishing.

Architecture

Core Components

src/index.ts - Main Server & Tool Handler

• RPGMCPServer class orchestrates all MCP protocol interactions
• Registers 7 tools via ListToolsRequestSchema: createGame, updateGame, getGame, progressStory, promptUserActions, selectAction, selectRestart
• Handles tool invocation via CallToolRequestSchema
• Generates interactive HTML UIs for game progression and game over screens
• Uses formatToolResponse() to provide AI-friendly guidance on workflow state and next steps

src/gameManager.ts - Game State Management

• GameManager class maintains in-memory game storage via Map<string, Game>
• Implements all core game operations (create, update, get, progress, prompt, select)
• Handles nested field updates using path notation (e.g., characters[0].hp, world.location)
• Manages Delta system for tracking state changes between UI prompts
• Maintains game history (last 10 situation-action pairs)