AGS MCP Server

Model Context Protocol (MCP) server for Adventure Game Studio (AGS) compiled room (.crm) file manipulation.

Bridge tool that gives AI access to binary AGS room data for complete AI-powered adventure game development.

AI tools excel at reading and writing AGS script files (text), but cannot directly access compiled room (.crm) files. This creates a gap where developers must manually connect AI-generated scripts to room elements through the AGS editor.

The AGS MCP Server bridges this gap by providing programmatic access to binary .crm data, enabling AI to:

- Connect script functions to hotspots, objects, and interactive elements
- Read room layouts and interactive areas for context
- Complete the full development workflow without manual AGS editor intervention
- AI analyzes game requirements and room context
- AI writes script functions (text files)
- AI uses MCP server to connect functions to room elements in binary .crm files
- Complete game ready for testing - no manual hookup required

# Run directly without installation npx ags-mcp-server

# Clone the repository git clone <repository> cd ags-mcp-server # Install dependencies npm install # Run the demo npm run demo # Shows all functionality working

- 🔍 Read Room Data: Parse .crm files and extract structured information
- 📦 Block Management: List, export, and import specific blocks within room files
- 🎯 Hotspot Tools: Read and modify hotspot interactions programmatically
- 🔗 Script Integration: Wire hotspot events to script functions automatically
- 💻 Cross-Platform: Works on Windows, macOS, and Linux
- 🤖 AI Integration: Compatible with Claude Desktop, Cline, and other MCP clients

# Run directly without installation npx ags-mcp-server

# Clone the repository git clone <repository> cd ags-mcp-server # Install dependencies npm install # Build the project npm run build # Run the server npm start # Starts MCP server on stdio

# Run directly without installation npx ags-mcp-server

Claude Desktop Config(%APPDATA%\Claude\claude_desktop_config.json):

{ "mcpServers": { "ags-server": { "command": "npx", "args": ["ags-mcp-server"] } } }

# Run directly without installation npx ags-mcp-server

Claude Desktop Config(~/Library/Application Support/Claude/claude_desktop_config.json):

{ "mcpServers": { "ags-server": { "command": "npx", "args": ["ags-mcp-server"] } } }

# Run directly without installation npx ags-mcp-server

Claude Desktop Config(~/.config/Claude/claude_desktop_config.json):

{ "mcpServers": { "ags-server": { "command": "npx", "args": ["ags-mcp-server"] } } }

- read_room_data- Parse .crm file and return structured room data
- list_room_blocks- List all blocks in a .crm file with details

- export_room_block- Export specific block to file
- import_room_block- Import/replace block data in .crm file

- get_room_hotspots- Extract hotspot information and interactions
- add_hotspot_interaction- Add interaction event handler to hotspot

{ "tool": "add_hotspot_interaction", "arguments": { "roomFile": "room001.crm", "hotspotId": 1, "event": "Look", "functionName": "hotspot1_Look" } }

Add to yourclaude_desktop_config.json(location depends on your OS):

{ "mcpServers": { "ags-server": { "command": "npx", "args": ["ags-mcp-server"] } } }

{ "ags-mcp-server": { "command": "npx", "args": ["ags-mcp-server"], "type": "stdio" } }

AI → read_room_data → analyze layout → get_room_hotspots → identify missing interactions

AI: "Make the door interactive" MCP: add_hotspot_interaction(door, "Look", "door_Look") AI: Generated function: door_Look() { player.Say("A sturdy wooden door."); }

# AI processes multiple rooms for consistency for room in ["room001.crm", "room002.crm", "room003.crm"]: hotspots = mcp_call("get_room_hotspots", {"roomFile": room}) # Add missing interactions automatically for hotspot in hotspots: if "Look" not in hotspot["interactions"]: mcp_call("add_hotspot_interaction", {...})

The MCP server works with AGS's binary .crm (compiled room) format:

- Detection: Bitmap mask where pixel colors = hotspot IDs
- Interactions: Event-driven system (Look, Interact, UseInv, etc.)
- Script Linking: Functions namedhotspot{id}_{event}(e.g.,hotspot1_Look)
- Runtime Resolution: Dynamic function resolution from compiled scripts

Enable AI tools to fully manipulate AGS room files without manual AGS editor intervention.

- AGS tools compilation (crmpak, crm2ash)
- MCP server architecture
- .crm file reading/parsing implementation
- Basic hotspot manipulation tools
- Cross-platform support (Windows, macOS, Linux)
- Proof-of-concept demo and documentation

✅ Phase 2: Enhanced Hotspot Operations (COMPLETE - READ-ONLY)

Goal: Complete hotspot script-to-binary connection capabilities

- Advanced hotspot property modification (placeholder/read-only)
- Hotspot interaction event management (placeholder/read-only)
- Walk-to coordinate updates (placeholder/read-only)
- Hotspot validation and error handling
- Batch hotspot operations (placeholder/read-only)
- Comprehensive test suite (58 tests, 100% pass rate)

✅ UPDATE: All operations now use direct binary manipulation with accurate data!

✅ Phase 2.5: CRMPAK Elimination & Direct Binary Writing (COMPLETED)

Goal: Eliminate binary dependencies and implement real file writing

- Removed all CRMPAK dependencies from read operations
- Implemented direct binary writing for hotspot modifications
- Replacedlist_room_blockswith direct binary parsing
- Fixed hotspot data accuracy (IDs, script names, interactions)
- Added backup/versioning for file safety
- Pure Node.js/TypeScript solution - zero external dependencies

📋 Phase 3: Room Objects Integration (PLANNED - DIRECT BINARY)

Goal: Connect AI scripts to room objects via direct binary parsing

- Room object enumeration and properties (direct binary read)
- Object script function connections (direct binary write)
- Object positioning and state management (direct binary write)
- Interactive object behavior setup
- Object visibility and animation controls

🚶 Phase 4: Walkable Areas & Boundaries (PLANNED - DIRECT BINARY)

Goal: AI control over character movement via direct binary manipulation

- Walkable area reading and modification (direct binary)
- Walk-behind area management (direct binary)
- Character pathing validation
- Boundary collision setup
- Area transition scripting

🎯 Phase 5: Regions & Special Areas (PLANNED - DIRECT BINARY)

Goal: AI setup of trigger zones via direct binary manipulation

- Region definition and properties (direct binary)
- Region event handler connections (direct binary write)
- Trigger zone scripting
- Special area effects setup
- Multi-region interaction management

👤 Phase 6: Character Spawn Points (PLANNED - DIRECT BINARY)

Goal: AI character placement via direct binary manipulation

- Character spawn point definition (direct binary)
- Starting position management (direct binary write)
- Character state initialization
- Multi-character room setup
- Character interaction scripting

🔮 Phase 7: Advanced Features (FUTURE - FULL BINARY CONTROL)

- Complete script block manipulation (CompScript3 direct binary editing)
- Other AGS file format support (.ags, .chr, etc.)
- AGS project-wide script integration
- Automated testing and validation
- ACHIEVED: 100% CRMPAK-free AGS room manipulation

🎯 Status: Full Binary Manipulation Complete

- ✅Reading: Direct binary parsing with accurate hotspot data (fixed IDs, script names, interactions)
- ✅Writing: Real binary file modifications with backup/safety features
- ✅Dependencies: Zero external dependencies - pure Node.js/TypeScript solution
- ✅Accuracy: Fixed all data discrepancies reported between MCP and AGS Editor
- 🔧Benefit: No binary dependencies, pure Node.js/TypeScript solution

# If you've cloned the repository npm run demo # Shows all MCP tools with mock data # Or using npx npx ags-mcp-server demo

# Test the JSON-RPC interface echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npx ags-mcp-server

# Check if the MCP server is working correctly npx ags-mcp-server --version

# Install dependencies npm install # Build TypeScript code npm run build # Run tests npm test

AI Request → MCP Server → AGS Tools (crmpak) → Binary .crm Files → Structured Data → AI Response

- File Access: Controlled read/write to .crm files only
- Input Validation: All tool parameters validated
- Platform Support: Works on Windows, macOS, and Linux
- Error Handling: Graceful error handling and reporting

- Memory Usage: ~50MB typical, ~200MB peak during operations
- Response Time: <100ms for most MCP tool calls
- Concurrent Support: Handles multiple tool operations
- File Formats: Supports all AGS room versions (1.14+)

# Make sure Node.js is installed node --version # If needed, install or update npm npm install -g npm

# On Linux/macOS, you might need to use sudo sudo npx ags-mcp-server # Or fix npm permissions https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally

# Check stdio configuration and tool responses echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npx ags-mcp-server

# Make sure you're using absolute file paths or paths relative to your current directory # Not paths relative to the MCP server installation

- Fork the repository
- Create feature branch:git checkout -b feature/new-tool
- Add tests:npm test
- Update documentation
- Submit pull request

MIT License - see LICENSE file for details.

- Adventure Game Studio- The main AGS engine
- Model Context Protocol- MCP specification and examples

A server for Ebitengine games that provides debugging and recording tools by capturing game state.