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
• Chunked PDF Processing: Efficiently handles large rulebook PDFs (200+ pages) using pdf2json with intelligent chunking
• Intelligent Rules Adjudication: Use local LLMs to interpret and adjudicate rules with context-aware responses
• Foundry VTT Integration: Automate VTT operations and assist with game management
• Local LLM Integration: Uses Ollama (Llama 3.2) for privacy-focused, offline AI assistance
• MCP Protocol: Compatible with Claude Code and other MCP clients
• Performance Optimized: Handles massive TTRPG rulebooks with memory-efficient processing

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

AI GM uses an advanced chunked processing system to handle large TTRPG rulebooks efficiently:

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

Features:

• Chunked Processing: Handles PDFs up to 400+ pages by processing 20 pages at a time
• Memory Optimization: Limits rules extraction to prevent memory issues with massive books
• Intelligent Text Extraction: Uses pdf2json for structured PDF parsing with layout preservation
• Rule Detection: Advanced heuristics to identify game rules vs. flavor text
• Section Recognition: Automatically detects chapters, sections, and subsections
• Keyword Extraction: Identifies game-specific terms (dice notation, skills, etc.)
• Timeout Protection: 60-second timeout prevents hanging on corrupted PDFs

Performance:

• Processes 200-page rulebooks in under 60 seconds
• Extracts 200-500 rules depending on book complexity
• Memory-safe chunking prevents crashes on large files

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.

Recent Updates

v1.1.0 - Advanced PDF Processing

• ✅ Chunked PDF Processing: Now handles massive TTRPG rulebooks (400+ pages) efficiently
• ✅ pdf2json Integration: Better text extraction with layout preservation
• ✅ Memory Optimization: Prevents crashes on large files with intelligent limits
• ✅ Performance Improvements: 60-second processing for 200-page books
• ✅ Enhanced Rule Detection: Better heuristics for identifying game mechanics

Roadmap

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