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:

# 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

# Install globally
npm install -g @petah/gamemaker-mcp

# Then use directly
gamemaker-mcp
gm-cli --help
gm-docs lookup draw_sprite

Local Development

# 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:

# 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:

# 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:

# 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:

# 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):

{
  "mcpServers": {
    "gamemaker-docs": {
      "command": "npx",
      "args": ["@petah/gamemaker-mcp"],
      "env": {}
    }
  }
}

VS Code (.vscode/settings.json):

{
  "mcp.servers": {
    "gamemaker-docs": {
      "command": "npx",
      "args": ["@petah/gamemaker-mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}

With custom documentation path (optional):

{
  "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:

# 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

$ 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

$ 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:

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