decomp-me-mcp

Decomp.me MCP Server

An MCP (Model Context Protocol) server that provides tools for interacting with the decomp.me API. This server allows AI assistants like Claude to help with video game decompilation projects by fetching scratches, compiling code, analyzing diffs, and iterating on improvements.

Features

• Fetch Scratches: Load decompilation scratches with all context (source code, target assembly, compiler settings, headers)
• Compile & Diff: Compile modified source code and get detailed assembly diffs with match scores
• Search: Find scratches and presets by query, platform, or other criteria with advanced filtering
• Context Search: Search through massive header files (45k+ lines) to find type definitions and struct layouts
• Compiler Info: List available compilers and their configurations for different platforms

Installation

Prerequisites

• Python 3.10 or higher
• uv (recommended) or pip

Install with uv (recommended)

# Clone or navigate to the repository
cd decomp-mcp-server

# Create a virtual environment and install
uv venv
uv pip install -e .

Install with pip

cd decomp-mcp-server
pip install -e .

Configuration

Add the MCP server to your Claude Desktop or other MCP client configuration.

Claude Desktop Configuration

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server configuration:

{
  "mcpServers": {
    "decomp": {
      "command": "/Users/YOUR_USERNAME/decomp-mcp-server/.venv/bin/python",
      "args": [
        "-m",
        "decomp_mcp.server"
      ]
    }
  }
}

Note: Replace /Users/YOUR_USERNAME/decomp-mcp-server/.venv/bin/python with the actual path to your Python interpreter in the virtual environment.

To find the correct path, run: ``bash cd ~/decomp-mcp-server source .venv/bin/activate which python ``

Available Tools

1. decomp_get_scratch

Fetch a scratch from decomp.me by URL or slug.

Parameters:

• url_or_slug (string, required): The decomp.me scratch URL (e.g., https://decomp.me/scratch/Jwtky) or just the slug (e.g., Jwtky)

Example: `` Get scratch Jwtky from decomp.me ``

Returns:

• Platform and compiler information
• Current match score
• Complete source code
• Compiler flags and settings

2. decomp_compile

Compile source code and get a diff showing how closely it matches the target assembly.

Parameters:

• url_or_slug (string, required): The decomp.me scratch URL or slug
• source_code (string, optional): Modified source code to compile. If not provided, compiles the existing code from the scratch.

Example: `` Compile scratch Jwtky with this modified code: [paste code here] ``

Returns:

• Match score (current/max)
• Detailed assembly diff showing matched and mismatched instructions
• Compilation errors (if any)

3. decomp_get_compilers

List available compilers for a platform or all platforms.

Parameters:

• platform (string, optional): Platform ID (e.g., gc_wii, n64, ps1, ps2, switch)

Example: `` Show me the available compilers for GameCube/Wii ``

Returns:

• List of compilers by platform
• Compiler IDs and default flags

4. decomp_search

Search for scratches and presets on decomp.me with advanced filtering.

Parameters:

• query (string, optional): Search query (searches function names, descriptions, etc.)
• platform (string, optional): Filter by platform (e.g., gc_wii, n64)
• only_incomplete (boolean, optional): Only show scratches that aren't perfectly matched
• min_match_percent (number, optional): Minimum match percentage (0-100)
• max_match_percent (number, optional): Maximum match percentage (0-100)
• sort_by (string, optional): Sort by match_percent, last_updated, or creation_time
• limit (integer, optional): Maximum results (default: 10)

Examples: `` Search decomp.me for Melee item functions ` ` Find scratches for Super Smash Bros that are between 70-90% matched ` ` Show me the most recent incomplete GameCube scratches ``

Returns:

• Project presets (if matching the search query)
• List of matching scratches with URLs
• Match percentages and scores
• Platform, compiler, and owner information

5. decomp_search_context

Search through the context (header files) of a scratch for type definitions, struct definitions, function declarations, or other patterns. Essential for finding types in massive context files.

Parameters:

• url_or_slug (string, required): The decomp.me scratch URL or slug
• pattern (string, required): Regex pattern or text to search for
• context_lines (integer, optional): Number of context lines around each match (default: 3)
• max_results (integer, optional): Maximum number of matches (default: 20)

Example: `` Search the context of scratch Jwtky for the Item struct definition ``

Returns:

• Matching lines with surrounding context
• Line numbers for easy reference
• Highlights of the matched pattern

Usage Examples

Once configured with Claude Desktop or another MCP client, you can interact naturally:

Basic Workflow

1. Load a scratch:

   Load scratch https://decomp.me/scratch/Jwtky

1. Analyze the code:

   What could be improved in this decompilation to get a better match?

1. Test changes:

   Try compiling this scratch with the temp variables consolidated

1. Iterate:

   The score improved! Now let's try adjusting the cast on line 8

Advanced Examples

Finding related work: `` Search for other Melee item-related scratches on GameCube ``

Exploring compilers: `` What compilers are available for Nintendo 64? ``

Analyzing diffs: `` Load scratch ABC123 and explain why the assembly doesn't match ``

Development

Running Tests

cd decomp-mcp-server
source .venv/bin/activate
python test_server.py

Project Structure

decomp-mcp-server/
├── src/
│   └── decomp_mcp/
│       ├── __init__.py
│       └── server.py          # Main MCP server implementation
├── pyproject.toml             # Project dependencies and metadata
├── test_server.py            # API integration tests
└── README.md                 # This file

Contributing

Contributions are welcome! Areas for improvement:

• Add support for creating new scratches via the API
• Implement caching for frequently accessed scratches
• Add more detailed diff analysis and suggestions
• Support for batch operations
• Integration with local decompilation projects

Resources

• decomp.me - The decompilation collaboration platform
• MCP Documentation - Learn about the Model Context Protocol
• decomp.me GitHub - Source code for decomp.me

License

MIT License - see LICENSE file for details

Acknowledgments

• The decomp.me team for building an amazing decompilation platform
• The video game decompilation community
• Anthropic for creating the Model Context Protocol