AI GM - Universal Game Master Assistant

AI GM is a Model Context Protocol (MCP) server that provides intelligent game master assistance for tabletop RPGs. It can process rulebook PDFs, adjudicate rules, and integrate with Foundry VTT using local LLMs via Ollama.

Features

• Universal Game System Support: Built-in support for D&D 5e and Cyberpunk RED, with extensible architecture for any RPG system
• PDF Rulebook Processing: Extract and index rules from PDF rulebooks
• Intelligent Rules Adjudication: Use local LLMs to interpret and adjudicate rules
• Foundry VTT Integration: Automate VTT operations and assist with game management
• Local LLM Integration: Uses Ollama for privacy-focused, offline AI assistance
• MCP Protocol: Compatible with Claude Code and other MCP clients

Supported Game Systems

• D&D 5e: Full support for fifth edition mechanics, character generation, and rules
• Cyberpunk RED: Complete implementation of CP RED systems and mechanics
• Extensible: Easy to add new game systems with the base system architecture

Installation

1. Prerequisites:

   • Node.js 18+
   • Ollama installed and running

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Usage

As an MCP Server

Add to your Claude Code configuration:

{
  "mcpServers": {
    "ai-gm": {
      "command": "node",
      "args": ["/path/to/ai-gm/dist/index.js"],
      "cwd": "/path/to/ai-gm"
    }
  }
}

Available Tools

1. process_rulebook: Process a PDF rulebook and extract rules

   process_rulebook(file_path: "/path/to/rulebook.pdf")
   

2. adjudicate_rule: Get AI-powered rule adjudication

   adjudicate_rule(query: "How does advantage work with critical hits?", context: "Combat situation")
   

3. set_game_system: Set the active game system

   set_game_system(system_id: "dnd5e")
   

4. list_game_systems: See all available game systems

   list_game_systems()
   

5. detect_game_system: Auto-detect game system from rule text

   detect_game_system(rule_text: "Roll 1d20 + ability modifier vs AC")
   

6. generate_character: Generate characters for the active system

   generate_character(level: 3, options: {"class": "Fighter", "race": "Human"})
   

7. foundry_assist: Automate Foundry VTT operations

   foundry_assist(action: "roll_dice", parameters: {"formula": "1d20+5", "reason": "Attack roll"})
   

Game System Architecture

AI GM uses a modular system architecture that makes it easy to add new RPG systems:

// Example: Adding a new system
class MyGameSystem extends BaseGameSystem {
  id = 'my_game';
  name = 'My RPG System';
  diceSystem = { primaryDie: 20, exploding: false };
  // ... implement required methods
}

systemManager.registerSystem(new MyGameSystem());

Each system defines:

• Dice mechanics and modifiers
• Attribute and skill systems
• Combat rules and health systems
• Magic/special ability systems
• Equipment and advancement rules

Local LLM Setup

1. Install Ollama: Follow instructions at https://ollama.ai

2. Pull a compatible model:

   ollama pull llama3.2

3. Configure model (optional): Edit the default model in src/llm/ollama-client.ts

PDF Processing

Place your rulebook PDFs in an accessible directory and use the process_rulebook tool:

await processRulebook("/path/to/players-handbook.pdf");

The system will:

• Extract text from the PDF
• Identify sections and rules
• Create searchable indexes
• Enable intelligent rule lookup

Foundry VTT Integration

AI GM can assist with common Foundry operations:

• Dice Rolling: Automated rolls with reasoning
• Token Management: Create and manage tokens
• Scene Updates: Modify lighting, weather, backgrounds
• Combat Automation: Initiative tracking, NPC actions
• Character Generation: Create characters directly in Foundry

Contributing

1. Fork the repository
2. Create a feature branch
3. Add new game systems by extending BaseGameSystem
4. Add tests for new functionality
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Roadmap

• Additional game systems (Pathfinder, World of Darkness, Call of Cthulhu)
• Vector database integration for better rule search
• Web interface for standalone use
• Campaign management features
• Enhanced Foundry VTT API integration
• Multi-language support