English | 中文

Native MC Mapping MCP Server

An MCP (Model Context Protocol) server that provides Minecraft obfuscated name mapping lookups. Helps AI coding agents work with Minecraft's obfuscated Java internals — for modding, plugin development, Mixin, Access Transformers, reflection-based scripting, and more.

What It Does

Minecraft's Java code is obfuscated at runtime — class, method, and field names are replaced with short meaningless identifiers (aed, func_70091_d, m_91087_). This MCP server lets your AI agent:

• Search obfuscated ↔ deobfuscated mappings across 38 Minecraft versions (1.7.10 – 1.20.1)
• Auto-build mapping caches on first use — downloads from NeoForge Maven and Mojang servers
• Boolean expression search — Entity&Player, {Block|Item}&client, func_149645

Use Cases

| Scenario | How This Helps | |----------|---------------| | Forge / NeoForge modding | Look up obfuscated method/field names when writing mixins or AT configs | | Fabric modding | Find intermediary ↔ named mappings for access wideners | | Spigot / Paper plugins | Resolve NMS (net.minecraft.server) class names across versions | | Mixin / Access Transformers | Discover the exact obfuscated name to target | | Reflection-based code | Find field/method names for getDeclaredField, getMethod, etc. | | Scripting engines | Resolve native Minecraft API names (CustomNPCs, CraftTweaker, etc.) | | Porting mods | Compare mappings between MC versions to find renamed APIs |

MCP Tools

| Tool | Description | |------|-------------| | search | Search Minecraft obfuscated class/method/field name mappings |

Quick Install (MCP Client)

Prerequisites

• Node.js ≥ 18

Step 1: Clone & Build

git clone https://github.com/SaltfishSheep/AI-MCP-NativeMinecraftAccess.git
cd AI-MCP-NativeMinecraftAccess
npm install
npm run build

Step 2: Add to Your MCP Client

Add the following to your MCP client configuration:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "native-mc-access": {
      "command": "node",
      "args": ["/absolute/path/to/AI-MCP-NativeMinecraftAccess/dist/index.js"]
    }
  }
}

OpenCode (opencode.json):

{
  "mcp": {
    "native-mc-access": {
      "type": "local",
      "command": ["node", "/absolute/path/to/AI-MCP-NativeMinecraftAccess/dist/index.js"],
      "enabled": true
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "native-mc-access": {
      "command": "node",
      "args": ["/absolute/path/to/AI-MCP-NativeMinecraftAccess/dist/index.js"]
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "native-mc-access": {
      "command": "node",
      "args": ["/absolute/path/to/AI-MCP-NativeMinecraftAccess/dist/index.js"]
    }
  }
}

Replace /absolute/path/to/ with the actual path where you cloned the repo.

Usage

Once configured, your AI agent can call the search tool:

search(mc_version="1.12.2", expression="Entity&Player")

Tool Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | mc_version | string | Yes | - | Minecraft version (e.g. "1.12.2", "1.20.1") | | expression | string | Yes | - | Boolean search expression | | page | number | No | 1 | Page number (1-indexed) | | limit | number | No | 20 | Results per page (max 100) | | output | string | No | default template | Output format template using %variable% syntax |

Output template variables: %type%, %obf_class%, %deobf_class%, %obf_name%, %deobf_name%, %srg_name%, %obf_desc%, %deobf_desc%, %access%, %is_static%, %sideonly%, %match%, %mismatch%

Example queries:

| Query | Description | |-------|-------------| | Entity&Player | Entries containing both "Entity" AND "Player" | | Entity::classname | Class name exactly "Entity" | | walk:method | Methods with "walk" in name | | static::modifier | is_static exactly "static" | | Potion:classname&Duration:name | Class name "Potion", name "Duration" | | {Block\|Item}&client | Client-side Block or Item entries | | func_70091_d | Find a specific SRG method name by ID | | KeyBinding | All entries mentioning KeyBinding | | output="%deobf_class%" | Deduplicated class list |

Expression syntax:

| Syntax | Meaning | Example | |--------|---------|---------| | term | Case-insensitive substring match (exact case scores higher) | KeyBinding | | term:modifier | Restrict search to specific columns | Potion:classname, walk:method | | term::modifier | Strong modifier — exact match required | Entity::classname | | net.minecraft.Entity | Dot notation — matches net/minecraft/Entity and net/minecraft$Entity | net.minecraft.entity.Entity | | & | AND (both must match, higher precedence) | Entity&Living | | \| | OR (either must match) | Entity\|Player | | {} | Grouping | {a\|b}&c |

Modifiers:

| Modifier | Searches | Description | |----------|----------|-------------| | all | all columns | Default — searches all text columns (excludes sideonly) | | class | obf_class, deobf_class | Full class path (e.g. net/minecraft/entity/Entity) | | classname | deobf_class (after last /) | Class name only (e.g. Entity from net/minecraft/entity/Entity) | | package | deobf_class (before last /) | Package only (e.g. net/minecraft/entity) | | name | obf_name, deobf_name, srg_name | Field/method names (methods+fields only) | | method | obf_name, deobf_name, srg_name | Method names only (filters type=method) | | field | obf_name, deobf_name, srg_name | Field names only (filters type=field) | | desc | obf_desc, deobf_desc | Method/field descriptors | | modifier | access, is_static | Access level and static status (note: access is always empty — data sources lack access info) | | side | sideonly | Side filter (common/server/client) |

Tips: Use Player&Entity instead of PlayerEntity for cross-version compatibility, as naming conventions differ across MC versions.

Supported Versions

38 Minecraft versions across 4 workflow types:

| Workflow | Versions | Data Sources | |----------|----------|--------------| | Legacy SRG | 1.7.10, 1.8, 1.8.8–1.9.4, 1.10.2–1.11.2 | SRG ZIP + MCP Stable CSV + static_methods | | Legacy TSRGv1 | 1.12.2–1.14.4, 1.15–1.15.2 | TSRGv1 + MCP Stable CSV + static_methods + constructors | | Legacy ProGuard | 1.16.1–1.16.5 | TSRGv1 + Mojang ProGuard + static_methods | | Modern | 1.17–1.17.1, 1.18–1.18.2, 1.19–1.19.4, 1.20–1.20.1 | TSRGv2 + Mojang ProGuard |

How It Works

1. On first search for a given MC version, the server downloads mapping data from NeoForge Maven and Mojang
2. It parses SRG/TSRG/ProGuard formats and merges them with MCP CSV data
3. The merged cache is stored as .mapping-caches/<version>.csv
4. Subsequent searches use the cached data (validated against package.json version)
5. Boolean expressions are parsed into an AST and evaluated against all CSV rows

Output Format

Format: [type] obf_class/obf_name -> deobf_class deobf_name srg_name obf_desc deobf_desc access is_static sideonly
Found 382 results for "Entity&Player" in MC 1.12.2 (page 1/39)

  1. [method] aed/cD -> net/minecraft/entity/player/EntityPlayer.getAbsorptionAmount func_110139_bj ()F  non-static common
  2. [method] aed/bM -> net/minecraft/entity/player/EntityPlayer.applyEntityAttributes func_110147_ax ()V  non-static common
  ...

Project Structure

AI-MCP-NativeMinecraftAccess/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types.ts              # TypeScript type definitions
│   ├── util.ts               # Shared utilities (CSV parsing, package version)
│   ├── version-table.ts      # URL mapping table for 38 MC versions
│   ├── builder/
│   │   ├── index.ts          # buildMappingCache entry point
│   │   ├── download.ts       # HTTP fetch + minimal ZIP reader
│   │   ├── parsers.ts        # SRG, TSRGv1, TSRGv2, ProGuard, CSV parsers
│   │   ├── workflows.ts      # 4 merge workflow builders
│   │   └── cache.ts          # CSV cache writer + mapping-info update
│   └── search/
│       ├── index.ts          # Barrel exports
│       ├── expression.ts     # Boolean expression parser (AND/OR/braces)
│       └── csv-reader.ts     # CSV reader + scoring + in-memory cache
├── dist/                     # Built JavaScript (entry: dist/index.js)
└── .mapping-caches/          # Generated cache files (gitignored)

License

MIT License — see LICENSE.

Third-Party Data

• Mojang mappings — Provided under Mojang's custom license. This server fetches them at runtime; it does NOT redistribute them.
• MCP mappings — Maintained by the Mod Coder Pack community, distributed via NeoForge Maven.