# mc-mod-mcp

An MCP server that gives Claude grounded answers when you're writing Minecraft mods.

It targets the two eras of the modding scene that are actually still alive — **1.8.9** (Forge/MCP, Java 8, Hypixel-style client mods) and **1.21.10+** (NeoForge or Fabric, Java 21, Mojang-mapped, Data Components). For 1.21.x it can also do live mapping lookups against linkie and pull mappings straight from piston-meta when linkie hasn't ingested a fresh release yet.

Without this, Claude tends to mix the two eras, hallucinate `new ResourceLocation(...)` (gone since 1.20.5), forget that items use Data Components instead of NBT, and write `ServerboundUseItemPacket` without the new sequence/yaw/pitch fields. With it, the model has a fact to look up instead of a name to guess.

## Install

```bash
git clone https://github.com/ratph6/mc-mod-mcp
cd mc-mod-mcp
npm install
npm run build
```

Then point Claude Code at the built binary:

```bash
claude mcp add mc-mod node "$PWD/dist/index.js"
```

(or hand-edit `~/.claude/config.json` if you prefer).

## Usage

Just ask in plain English. Claude picks the tool. Some examples that actually exercise it:

> How do I send a useItem packet in 1.21.10 Fabric?
>
> Translate this 1.8.9 snippet to 1.21+: `Minecraft.getMinecraft().thePlayer.addChatMessage(new ChatComponentText("hi"))`
>
> Scaffold a NeoForge 1.21.10 mod main class for `examplemod`
>
> Show me a `@ModifyVariable` mixin example
>
> What's the Yarn name for `LocalPlayer` in 1.21.10?

## Tools

| name | what it does |
| --- | --- |
| `mc_version_info` | Loaders, Java, mappings, build system, doc links for an era |
| `mc_lookup_class` | Fully-qualified class name in 1.8.9 vs 1.21+ for a concept (`Block`, `Level`, `BlockEntity`, …) |
| `mc_lookup_api` | Canonical snippet for a task (`send chat`, `open gui`, `register block`, …) |
| `mc_translate` | Given a symbol from one era, suggest the equivalent in the other |
| `mc_event` | "What event fires when X?" — gives 1.8.9 + NeoForge + Fabric |
| `mc_mixin` | Mixin pattern catalog (`@Inject`, `@ModifyArg`, `@WrapOperation`, `@Accessor`, …) plus mixin config JSON |
| `mc_gotchas` | Era-specific pitfalls — Data Components, ResourceLocation factory, mod bus vs game bus, etc. Filterable. |
| `mc_gradle` | `build.gradle` / `settings.gradle` / `gradle.properties` for an era + loader |
| `mc_mappings_translate` | Yarn ↔ Mojang class name translation (curated) |
| `mc_list_scaffolds` | Enumerate scaffold templates |
| `mc_scaffold` | Emit boilerplate (mod main, item/block, command, key binding, mixin, network payload, …) |
| `mc_docs` | Doc links for an era |
| `mc_list_versions` | Live: every version linkie knows, per namespace |
| `mc_mappings_search` | Live: full-text search against linkie's mappings API |
| `mc_lookup_field` | Live: field-name lookup against linkie (the curated tables don't track fields) |
| `mc_mojang_mappings` | Pulls Mojang's `client_mappings.txt` directly via piston-meta. Used for 26.1.x and any version linkie chokes on. |

The first twelve are curated — fast, deterministic, no network. The last four hit the network on demand.

## Extending

Knowledge lives in `src/knowledge.ts` as flat data. Add an entry to `CLASSES` / `METHODS` / `EVENTS` / `MIXIN_PATTERNS` / `GOTCHAS` / `YARN_TO_MOJANG` / `GRADLE_TEMPLATES`, run `npm test`, done. Scaffolds are template functions in the same file, listed via `SCAFFOLD_KINDS`.

```
src/
  index.ts          MCP server, tool definitions, stdio transport
  knowledge.ts      Curated data + scaffold templates
  linkie.ts         Live calls to linkie's mappings API
  mojang.ts         Live piston-meta + proguard parser
  smoke.test.ts     node:test smoke tests
```

## Caveats

It doesn't ship Mojang/Yarn/Parchment mapping files (multi-MB) — for raw obf names use the live tools or [linkie](https://linkie.shedaniel.dev/mappings). It won't tell you whether your specific code compiles, only that the API shape is right for the era. Translations target 1.8.9 and 1.21.10; intermediate versions usually still apply but treat them as approximate.