GameMaker Documentation MCP Server

# GameMaker Documentation Tools A comprehensive toolkit for GameMaker Language (GML) documentation management, featuring an MCP server, CLI tools, and HTML-to-Markdown conversion utilities. > **Includes GameMaker Documentation**: This package comes with GameMaker Language documentation built-in. No additional setup or file downloads required! ## Features - **MCP Server**: Model Context Protocol server for programmatic documentation access - **CLI Documentation Tool**: Search, lookup, and browse GameMaker documentation from the command line - **HTML Converter**: Convert GameMaker HTML documentation to clean Markdown format - **Modern Node.js**: Built with ES modules, structured error handling, and performance monitoring ## Requirements - **Node.js**: >= 22.0.0 - **npm**: Latest version recommended ## Installation ### Quick Start with npx (Recommended) No installation needed! Run directly with npx: ```bash # Run MCP server npx @petah/gamemaker-mcp # Run CLI tool npx @petah/gamemaker-mcp gm-cli --help # Alternative command names npx @petah/gamemaker-mcp gamemaker-mcp # MCP server npx @petah/gamemaker-mcp gm-docs lookup draw_sprite # CLI tool ``` ### Global Installation ```bash # Install globally npm install -g @petah/gamemaker-mcp # Then use directly gamemaker-mcp gm-cli --help gm-docs lookup draw_sprite ``` ### Local Development ```bash # Clone the repository git clone <repository-url> cd gm-mcp # Install dependencies npm install ``` ## Usage ### CLI Documentation Tool The CLI provides comprehensive GameMaker documentation lookup and search capabilities: ```bash # Using npx (recommended) npx @petah/gamemaker-mcp gm-cli --help npx @petah/gamemaker-mcp gm-docs lookup draw_sprite # Alternative npx usage npx @petah/gamemaker-mcp gm-cli lookup draw_sprite npx @petah/gamemaker-mcp gm-docs search collision # Global installation gm-cli --help gm-docs lookup draw_sprite # All CLI commands work the same way: # Look up a specific function gm-docs lookup draw_sprite # Search documentation gm-docs search collision # List functions by pattern gm-docs list draw # Show available categories gm-docs categories # List functions in a category gm-docs category Drawing # Get specific file content gm-docs file GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite.md # Convert HTML docs to Markdown gm-docs convert gm-docs convert ./html ./markdown # Local development npm run cli -- --help npm run cli lookup draw_sprite ``` #### Development Mode Use watch mode for development with automatic reloading: ```bash # Local development only npm run cli:dev -- --help ``` #### Custom Documentation Path (Optional) The package includes GameMaker documentation by default. If you need to use custom docs: ```bash # Using npx npx @petah/gamemaker-mcp gm-docs --path /path/to/docs lookup draw_sprite # Global installation gm-docs --path /path/to/docs lookup draw_sprite # Local development npm run cli -- --path /path/to/docs lookup draw_sprite ``` ### MCP Server Start the Model Context Protocol server for programmatic access: ```bash # Using npx (recommended) - includes built-in GameMaker docs npx @petah/gamemaker-mcp # Or with alternative command npx @petah/gamemaker-mcp gamemaker-mcp # Global installation gamemaker-mcp gamemaker-docs-server # Local development npm run mcp node src/gamemaker-docs-server.js # Custom documentation path (optional) npx @petah/gamemaker-mcp /path/to/custom/docs ``` The MCP server provides 5 tools: - `lookup_gamemaker_function` - Look up specific GML functions - `search_gamemaker_docs` - Search documentation content - `list_gamemaker_functions` - List functions by pattern or category - `get_gamemaker_file` - Retrieve specific documentation files - `init_gamemaker_agent` - Initialize with comprehensive GML coding guide #### MCP Configuration For Claude Desktop or other MCP clients, add this to your configuration: **Claude Desktop (claude_desktop_config.json):** ```json { "mcpServers": { "gamemaker-docs": { "command": "npx", "args": ["@petah/gamemaker-mcp"], "env": {} } } } ``` **VS Code (.vscode/settings.json):** ```json { "mcp.servers": { "gamemaker-docs": { "command": "npx", "args": ["@petah/gamemaker-mcp"], "cwd": "${workspaceFolder}" } } } ``` **With custom documentation path (optional):** ```json { "mcpServers": { "gamemaker-docs": { "command": "npx", "args": ["@petah/gamemaker-mcp", "/path/to/your/gamemaker/docs"], "env": {} } } } ``` > **Note**: The package includes GameMaker documentation by default, so no path configuration is needed for standard usage. ### HTML to Markdown Conversion Convert GameMaker HTML documentation to clean Markdown: ```bash # Convert with default paths (docs -> md) npm run convert # Convert with custom paths npm run cli convert /path/to/html /path/to/output ``` ## Project Structure ``` src/ ├── cli.js # Main CLI entry point ├── gamemaker-docs-server.js # MCP server implementation ├── commands/ # CLI command implementations │ ├── base-command.js # Shared command functionality │ ├── lookup.js # Function lookup command │ ├── search.js # Documentation search command │ ├── list.js # Function listing command │ ├── categories.js # Category browsing command │ ├── category.js # Category-specific listing │ ├── file.js # File retrieval command │ ├── convert.js # HTML conversion command │ └── index.js # Command registry ├── lib/ # Shared libraries │ ├── docs-indexer.js # Documentation indexing and search │ ├── gamemaker-cli.js # GameMaker CLI functionality │ ├── html-converter.js # HTML to Markdown converter │ └── errors.js # Structured error handling docs/ # Raw HTML documentation md/ # Converted Markdown documentation init.txt # GameMaker coding guide for LLM agents .vscode/mcp.json # VS Code MCP configuration ``` ## Key Features ### Modern Node.js Architecture - **ES Modules**: Full ESM support with proper import/export syntax - **Node.js Built-ins**: Uses `node:` prefix for built-in modules - **Structured Error Handling**: Rich error context and logging - **Performance Monitoring**: Automatic timing and slow operation detection ### Documentation Management - **Smart Indexing**: Efficient function and content indexing - **Fuzzy Search**: Find functions even with partial or misspelled names - **Category Organization**: Browse documentation by logical categories - **Link Conversion**: Automatic conversion of HTML links to Markdown paths ### Development Experience - **Watch Mode**: Hot reloading during development (`npm run cli:dev`) - **Structured Logging**: Rich error context and debugging information - **Performance Insights**: Automatic timing measurements for operations - **Comprehensive Error Handling**: Clear error messages with context ## Examples ### Function Lookup ```bash $ npm run cli lookup draw_sprite # draw_sprite(sprite, subimg, x, y) Draws a sprite at the given position. **Parameters:** - sprite: The sprite to draw - subimg: The sub-image of the sprite - x: The x coordinate - y: The y coordinate **Example:** ```gml draw_sprite(spr_player, 0, x, y); ``` ``` ### Documentation Search ```bash $ npm run cli search "collision detection" Found 15 result(s) for "collision detection": ## Result 1: GameMaker_Language/GML_Reference/Movement_And_Collisions/Collisions/collision_point.md **Category:** Movement and Collisions **Relevance Score:** 8.5 Returns true if there is a collision at the specified point... ``` ### Performance Monitoring ```bash $ npm run cli convert ./docs ./output Starting conversion from ./docs to ./output Found 1247 HTML files to convert ... Conversion complete! Converted 1247 files. htmlConversion: 15.43s ``` ## Development ### Architecture Principles 1. **Modular Design**: Each command is self-contained in its own file 2. **Shared Utilities**: Common functionality in the `lib/` directory 3. **Error Handling**: Structured error classes with rich context 4. **Performance**: Built-in timing and monitoring capabilities ### Adding New Commands 1. Create a new command file in `src/commands/` 2. Extend `BaseCommand` for shared functionality 3. Register the command in `src/commands/index.js` 4. Follow the existing pattern for error handling and performance monitoring ### Error Handling The project uses structured error handling with contextual information: ```javascript import { ErrorHandler, ValidationError } from './lib/errors.js'; // Wrap async operations await ErrorHandler.wrapAsync(async () => { // Your async code here }, { operation: 'myOperation', context: 'additional info' }); // Handle specific errors throw new ValidationError('Invalid input', 'fieldName', inputValue); ``` ## License MIT License - see LICENSE file for details. ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes following the existing code style 4. Submit a pull request