Skip to content
Projects

guguzea/MC-AI-Coding-Assistant-Tool

View on GitHub

guguzea/MC-AI-Coding-Assistant-Tool has 141 GitHub stars and 3 forks. GitHot measured 0 stars in 24 hours, +5 in 7 days, and +26 in 15 days. Last checked 2026-11-18 03:37 UTC. Last push 2026-11-11.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
+5
in 15 days
+26
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

让 AI 编程助手(Cursor / Claude Code 等)能更好地编写 Minecraft 模组的完整工具包。

Developer Tools

README.en.md

Original

MC AI Coding Assistant Tool

简体中文 | English · Human README

A local MCP server that tells your agent which API set, build setup and mappings this exact Minecraft version uses.

Rule packs, official docs, mappings, library knowledge and in-game testing all live locally — the agent stops guessing from memory.

Human README · Setup · Contributing · Platforms · Tool list

  • 8 loaders + 2 server faces, rule packs per version: Forge · Fabric · NeoForge · Quilt · LiteLoader · Rift · ModLoader · Bedrock | Paper · Spigot
  • Official docs, page for page: you get the page for your version, not the neighbouring version's text
  • Six mapping layers plus crash-log deobfuscation: mojang · mcp · yarn · parchment · obfuscated · intermediary
  • Library mods: API summaries for 48 libraries, Modrinth version matrices, ready-made skills
  • Project and porting work: scaffolding, Gradle diagnosis, project validation, datagen, crash triage, cross-version port analysis
  • In-game playtesting: client driver / bridge / server driver — screenshots, qa.log and state.json or it does not count

[!IMPORTANT] Get the tool and its data from this repository only. A similarly named repository or a copied README does not make a download official. Human reader → Human README (plain language: what it does, how to start · 简体中文) This file is the technical contract the AI executes against — long and dense. Asking your agent beats reading it.


Read this first

If you are an agent, this file is the project overview. For installing and configuring the MCP server, see AUTO_SETUP.md.

If you are a human, see the notice at the top: the human-facing page is README_human.en.md

If you want the fine detail, just let the agent work it out for you.

A complete toolkit that lets AI coding assistants (Cursor, Claude Code, and others) write Minecraft mods with fewer wrong turns: it removes structural obstacles such as stale knowledge, API version confusion, complicated build systems and inconsistent mappings, and covers the whole path from writing code to testing the mod.

Installation (read this first if it's your first time)

The easiest way to install: let your AI install it for you

Installation tutorial for beginners

  1. Let your AI install it: Create a new conversation in the harness and enter:

    Help me install this MCP https://github.com/guguzea/MC-AI-Coding-Assistant-Tool.git to <the location where you want to install it>

    The Agent will identify the host itself → check Node → cd mcp-server && npm ci && npm run build → generate a configuration draft in the format for that host; it will first show you the target file and diff, and only write after you confirm (it will not silently overwrite existing MCP configuration). It can also install when the host is not in the listed inventory (see AUTO_SETUP.md Step 4.11).

  2. Reload the host: Reload MCP according to the AI's guidance (some require a restart, some require reconnecting; the comparison table is in AUTO_SETUP.md Step 5). After reloading, have it call get_server_status once; if it works, installation is complete.

Prerequisites: Node.js >= 22.5 (check with node -v). 22.5–22.12 and 23.0–23.3 must be started with --experimental-sqlite — the built-in node:sqlite is only enabled by default starting from 22.13 / 23.4; the MCP/CLI entry point will detect this window before any sqlite use, and when matched will print prominent guidance and exit with a non-zero code. It is recommended to install Node 22.13+ / 24 LTS directly to save trouble.

You can let AI help you install Node

Tool not visible / do not want to reload the host — it can still be used without configuring MCP; just let AI use the CLI tool directly.

Want to install manually / need to fix a broken installation: The only manual is AUTO_SETUP.md (Step 0-pre verify old paths → Step 0 identify host → Step 2 compile → Step 4 generate configuration by host → Step 5 reload and accept); service name MC-AI-Coding-Assistant-Tool (stdio, 89 tools). Another installation method (install the npm package into any project and retrieve platform data separately): see mcp-server/README.md "npm installation".

For the Agent: When the user says "help me install / how do I install / installation fails", follow the three steps above; the configuration format is subject to AUTO_SETUP.md; before writing to disk, you must first provide the checklist + diff and wait for user confirmation. Skill installation (Step 6) is unrelated to MCP; reloading MCP will not make an entry appear in the Skill panel. Skill is a dynamic context insertion mechanism.

What it is: AI does the work, you make the calls

Mod development is not a deterministic pipeline. Creative scope, performance trade-offs and debugging strategy must be decided by a human; the agent does not take those over. Compatibility trade-offs and API choices it may take for you: for a low-risk call it explains the choice, the alternatives and the revert right after acting, per the "explanation template" (see the Quick Start section); for a high-risk call (switch loader, restructure packages, drop a dependency, edit build scripts) it explains first and waits for your confirmation.

The agent handles version gating, documentation lookup, rules and anti-patterns, skeleton drafts, validation, and crash triage.

The high-risk operations below stop at a checklist or a dryRun by default and require a human in the loop (show first, act after the user confirms): writing files to disk, running Gradle, copying a jar into a game directory, uploading a release.

Project layout

MC_skill/
├── README.md                    # you are here
├── AGENTS.md                    # root master guide: points the AI at the right platform rules
├── CONTRIBUTING.md              # contribution guide
├── AUTO_SETUP.md                # any MCP host: build + host-format config draft
├── REPORT-FORMAT.md             # full delivery-report form (for agents: tier judging / main 4 blocks / maintenance 6 blocks / hard rules)
├── DELIVERY_LOG.md              # rolling delivery draft (newest on top; chat shows only the three human-facing items)
├── THIRD_PARTY_NOTICES.md       # third-party docs / mapping data licensing
├── LICENSE                      # this repo's code: PolyForm Noncommercial 1.0.0 + strong-copyleft addendum (non-commercial, notice, derivatives stay open)
├── Minecraft 社区常用库模组全览(2026 版).md  # pointer; full text in community_knowledge/authored/library-catalog-2026
│
├── forge/                       # Forge rules / skills / scaffold / knowledge (multi-version)
├── fabric/                      # Fabric rules and knowledge (multi-version)
├── neoforge/                    # NeoForge rules and knowledge
├── quilt/                       # Quilt QSL delta rules (02–10 read the same-version fabric tree)
├── liteloader/                  # LiteLoader (main push: 1.12.2) + HYBRID.md
├── rift/                        # Rift 1.13 (native pack) + 1.13.2 (community-branch experimental pack)
├── modloader/                   # Risugami ModLoader 1.6.4 + safe API table
├── bedrock/                     # Bedrock Add-On rules (flat bedrock/)
│
├── doc/                         # landing-spot ledgers and topics (18 files, excerpt): tool error codes / platform coverage (forge·fabric·neoforge·quilt) / server face / playtest loops and ladder / retrieval discipline / troubleshooting
├── community_knowledge/         # community practice knowledge → MCP search_community_docs
│   ├── authored/                # short essays written here (incl. the lib-* library integration series + publishing / crashes / GUI, etc.)
│   ├── permitted/               # community posts distilled with permission (e.g. mcmod 3993)
│   ├── links/                   # title / summary / external link only (e.g. mcmod 6071)
│   ├── patterns/                # code pattern samples (mcskill://patterns/README)
│   ├── indexes/index-l0.json    # L0 index (per-source counts are in the file itself; rebuild: `npm run community:index`)
│   ├── AGENT_USAGE.md           # usage rules for agents (short essays are not API specs)
│   └── README.md                # topic id quick reference
│
├── knowledge/                   # repo-level knowledge sources (never mirrored into platform .cursor/skills)
│   ├── libs/                    # library Skill sources (file counts / skillIds: read `knowledge/libs/README.md` §current scale)
│   │   ├── all-platforms/       # 20 (includes the mc-lib-catalog router)
│   │   ├── fabric-only/         # 10 (Trinkets / CCA / Polymer…)
│   │   ├── forge-only/          # 2 (Curios / KFF)
│   │   ├── neo-only/            # 2 (Curios / KFF mirrors)
│   │   ├── bedrock-only/        # 2 (Script API)
│   │   └── README.md            # grouping rules, resolution flow, data-chain pointers
│   └── patterns/                # short snippet pattern library (complements community_knowledge/patterns)
│
├── scripts/                     # maintenance scripts (library data chain + skill mirroring + rule validation)
│   ├── sync-skills.ps1          # multi-IDE skill mirroring (-All / -TargetDir)
│   ├── resolve-lib-skills.mjs   # knowledge/libs §3.6 resolution check
│   ├── (library catalog scripts live in mcp-server/scripts/, see below)
│   ├── build-lib-manifest.mjs   # → mcp-server/data/lib-manifests/
│   ├── build-api-summaries.mjs  # → mcp-server/data/lib-api-summaries/
│   ├── batch-decompile.mjs      # batch decompilation (sources → $MC_SKILL_CACHE, not committed)
│   └── merge-verified-api.mjs   # writes verifiedApi back into the catalog
│
├── mcp-server/                  # local stdio MCP Server (89 tools)
│   ├── src/                     # tool implementations (api / docs / diagnostics / wave…)
│   ├── scripts/                 # doc fetching, semantic indexing, data audits; includes build-library-catalog-from-authored.mjs
│   └── data/                    # MCP-side data shipped with the repo (not MC_SKILL_DATA)
│       ├── lib-manifests/       # Modrinth version matrix (slug / entry counts: read from the file; key-structure pitfalls: see the "Decompiled data artifacts" table)
│       ├── lib-api-summaries/   # public API summaries for 48 libraries
│       └── loader-api-summaries/ # Forge / Neo / Fabric-API / QSL style summaries
│
└── data/                        # offline official data (MC_SKILL_DATA points at this directory root)
    ├── forge_* / fabric_* / neoforge_* / …  # per-platform doc L0/L1/L2 + semantic/
    ├── paper_stable/            # server-side **tutorial** face: paper-docs/ (67 pages, **CC BY-SA 4.0**)
    ├── paper-api_stable/        # server-side **signature** face (current): paper-javadoc/ (Paper API, 2116 classes)
    ├── paper-api_<ver>/         # signature **history ×5** (1.21.4/1.21.1/1.20.1/1.16.5/1.12.2) — extracted from javadoc pages
    ├── spigot_stable/           # server-side signatures (current): Spigot/Bukkit Javadoc, 1396 classes (no tutorial body; see THIRD_PARTY_NOTICES.md)
    ├── spigot_<ver>/            # signature **history ×8** (1.21.8/1.21.4/1.21.1/1.20.6/1.20.1/1.19.4/1.16.5/1.12.2) — extracted from the **artifact via javap**, not javadoc
    ├── vanilla_<ver>/           # vanilla registry data (the data source for query_registry)
    ├── _models/                 # local embedding model (transformers.js; the only entry that may fetch a model remotely)
    ├── _yarn-mojmap-pairs/      # class-level derived comparison table (the second-tier source for from=mojang)
    └── <platform>_<ver>/mappings/  # that version's mappings (Yarn SQLite / MCP CSV / TSRG, etc.); mappings are per version — there is no repo-wide mappings/ directory

Inside each platform version directory there are also .cursor/rules/ (00–10), .agents/skills/, scaffold/, knowledge/antipatterns, and so on. Library Skills live only in the root knowledge/libs/, reached through activate_platform_pack or by reading the path directly; they are never written into per-platform skills directories.

Platforms

Platform Status Rules / data (summary)
Forge ✅ done multi-version rules (main push 1.20.1); data directories data/forge_*
Fabric ✅ done multi-version rules (main push 1.20.1 / 1.21.x / 26.1.2 / 26.2); data directories data/fabric_*; 26.1.2 / 26.2 are mojmap only; 26.3 has only a blog-level migration summary, no rule tree
NeoForge ✅ done rule set in neoforge/ (main push 1.20.4+ / 26.1 / 26.2 / 26.3); doc data in data/neoforge_* (main docs default to 26.1; 26.2 / 26.3 have rule trees but no version-specific docs, game-side changes go through the migration guide — see the note under "Supported versions")
Quilt ✅ mixed quilt/<ver>/ only carries the QSL deltas (00/01/05/06) + 3 QSL Skills for that version (registry/events/networking); 02–04/07–08/10 read fabric/<ver>; search_docs(platform=quilt) never falls back to Fabric Registry for QSL questions
Bedrock ✅ done flat bedrock/; search_bedrock_docs + a lagging docsStatus; experimental switches layered by min_engine_version
LiteLoader ✅ done liteloader/1.12.2/ client-only + HYBRID.md; diagnose_gradle runs in a lightweight mode for the liteloader plugin
Rift ✅ done Native pack rift/1.13/ (the artifact's profile.json says inheritsFrom: 1.13) plus rift/1.13.2/ marked as a community-branch experimental pack (the artifact is still the 1.13 one; cross-version is not guaranteed); metadata riftmod.json; Rift-side signatures verified against the real artifact via javap (verified-api.md); dependency via JitPack com.github.DimensionalDevelopment:Rift:1.0.4-106 (dev classifier; the old www.dimdev.org/maven/ returns DNS ENOTFOUND)
ModLoader ✅ done modloader/1.6.4/ + safe API table; passing off Forge Javadoc or func_* names is forbidden
Paper (server-side) ✅ server face A separate face, not an 11th mod platform (runServer, Bukkit abstraction layer, plugin.yml+onEnable; the per-version javap rewrite tables have zero applicability for plugins). data/paper_stable/paper-docs/ (67 tutorial pages, CC BY-SA 4.0); search_docs(platform=paper). The signature layer is a separate platform=paper-api: current pack paper-api_stable (2116 classes) + history ×5 (paper-api_1.21.4/1.21.1/1.20.1/1.16.5/1.12.2, extracted from javadoc pages) — same platform, different tree; FabricDocStore is single-source so each tree gets its own platform id. Rule tree paper/26.3/rules/ (10 rules); per-version packs paper/<ver>/rules/00-applicability.md ×5 (how the 26.3 rules apply to each version + that version's Bukkit-core-vs-Paper-extension split)
Spigot (signatures only) ✅ signatures only Current pack data/spigot_stable/spigot-javadoc/ (1396 classes) + history ×8 (data/spigot_<ver>/, 1.21.8/1.21.4/1.21.1/1.20.6/1.20.1/1.19.4/1.16.5/1.12.2) — history packs are extracted from the maven artifact via javap (the javadoc site has no version axis), every page carries sourceType: javap; search_docs(platform=spigot). No tutorial body — the SpigotMC Wiki has no open licence whatsoever (only © SpigotMC Pty. Ltd.) so it is not ingested under this repo's policy; use platform=paper for tutorials

Supported versions

The rule trees (activate_platform_pack action=list) and the official documentation data (list_*_versions) may disagree: having rules without docs, or docs without a complete 00–10 rule set, is normal. The agent must follow the project's exact version; substituting a neighbouring version is forbidden.

Platform Rule tree (platform/<ver>/) Doc data (list_*_versions) Main push Notes
Forge 1.7.10 · 1.8.9 · 1.9.4 · 1.10.2 · 1.11.2 · 1.12.2 · 1.13.2 · 1.14.4 · 1.15.2 · 1.16.5 · 1.17.1 · 1.18.2 · 1.19.4 · 1.20.1 · 1.20.4 1.7.10–1.20.4 (including javadoc-only versions such as 1.8.9 / 1.9.4 / 1.10.2 / 1.11.2) 1.20.1 1.12.2 has forge-docs tutorials; 1.7.10 is a javadoc verification table plus short rules (ready); 1.8.9–1.11.2 are thin packs (3 rules / 0 skills; pack.meta.json says ready, so session loads, but only 00/01/09 exists). forge/1.21.1 is draft (it has no .cursor/ at all ⇒ PACK_NOT_FOUND; doc search only)
Fabric 1.14.4 · 1.16.5 · 1.17.1 · 1.18.2 · 1.19.4 · 1.20.1 · 1.20.4 · 1.21.1 · 1.21.3 · 1.21.4 · 1.21.8 · 1.21.10 · 1.21.11 · 26.1.2 · 26.2 list_fabric_versions includes the versions above (no 1.21.5) 1.20.1 / 1.21.x / 26.1.2 / 26.2 26.1.2 / 26.2 have fabric-docs only, no wiki; both are mojmap only. 26.2's corpus comes from upstream's latest face (versions/26.2 is still 404 upstream) and does have versioned fabric-docs body. 1.21.4 / 1.21.8 / 1.21.10 have both versioned fabric-docs and the current fabric-wiki (the wiki is not a historical snapshot of that version). 1.21.5 has no versions/ source → PACK_NOT_FOUND. Copying 1.21.11 is forbidden. Attachments (Data Attachments) are registered per version: 1.21.10 / 1.21.11 / 26.1.2 are recorded from that version's own corpus page (only the short names that appear on the page; unverified FQCNs / module ids are flagged); 1.21.4 / 1.21.8 / 1.14.4 have no source for the topic → see each version's pack.meta.json gaps.attachments (in 1.14.4 the rules give it as a counter-example, not a hole). Copying from a neighbouring version is forbidden
NeoForge 1.20.1 · 1.20.4 · 1.20.6 · 1.21.1 · 1.21.3 · 1.21.5 · 1.21.8 · 1.21.10 · 1.21.11 · 26.1 · 26.2 · 26.3 1.20.1 (falls back to Forge) · 1.20.4 · 1.20.6 · 1.21.1 · 1.21.3 · 1.21.5 · 1.21.8 · 1.21.10 · 1.21.11 · 26.1 (NeoForge has no 1.21.4 / 1.21.6 / 1.21.7 / 1.21.9 pack; 26.2 / 26.3 have rule trees but no version-specific docs) 1.20.4+ / 26.1 / 26.2 / 26.3 main docs default to 26.1; 26.2 / 26.3 rule trees exist, but the version-specific main docs are missing (the 00 engineering facts come from the official MDK and sources jar; 01–10 changes go through the migration guide — note below the table). 1.20.1 has a verification table plus short rules (Forge-compatible data). Attachments (Data Attachments): 1.20.4 / 1.20.6 are verified against that version's datastorage/attachments page plus that version's loader-api summary (the 1.20.4 docs page writes the static method as AttachmentSerializer.serializable(), while the summary has no such class — the real one is AttachmentType.serializable(), pinned in the verification table as must-not-emit); 26.1 has no dedicated attachments page, so the rules carry a fallback note
Quilt 1.18.2 · 1.19.4 · 1.20.1 · 1.20.4 · 1.21.1 · 1.21.3 · 1.21.4 · 1.21.8 · 1.21.10 · 1.21.11 (10 versions) search_docs({platform:"quilt"}); data/quilt_* holds only 6 versions (1.18.2 / 1.19.4 / 1.20.1 / 1.20.4 / 1.21.1 / 1.21.11) — the other 4 have rules but no corpus, so hits come back with fallback:"fabric" + sourcePlatform, which is not QSL evidence same as Fabric 3 QSL Skills for the version + Fabric overlay; 00/01/05/06 are the QSL deltas (versions that ship 06-networking.mdc must not overlay Fabric networking), 02–04/07–08/10 read fabric/<ver>. 1.21.11 is MC 1.21.11, not a typo for 1.21.1 (both exist; neither may stand in for the other); QSL / QFAPI are frozen on that version and no usable artifact exists — see the banner at the top of quilt/1.21.11/AGENTS.md and in 00-project-setup.mdc
LiteLoader 1.8.9 · 1.10.2 · 1.12.2 search_docs({platform:"liteloader"}) (official wiki + hybrid semantic store; APIs per the verification table) 1.12.2 all three packs have an artifact-level signature face (each pack's knowledge/common/api-surface.md, read straight from the artifact via javap: 1.12.2 73 types / 249 signatures, 1.10.2 72 / 230, 1.8.9 70 / 209); 1.8.9 / 1.10.2 have pack.meta.json = draft, so session refuses outright (PACK_NOT_FOUND; the 11 rule files on disk must not be treated as loaded) — doc search only; client-only; for Forge hybrids see HYBRID.md
Rift 1.13 (native) · 1.13.2 (community-branch experimental) search_docs({platform:"rift"}) (official wiki + hybrid; method names per the verification table) 1.13 the artifact's profile.json says inheritsFrom: 1.13 ⇒ the native line stops at 1.13; 1.13.2 has no native artifact and cross-version is not guaranteed; both packs share one Rift API artifact (39 listener interfaces); Gradle runClient does NOT dispatch listeners (dev env is deobf vs notch target names) — verify with a real client jar
ModLoader 1.2.5 · 1.5.2 · 1.6.4 no Java doc tree 1.6.4 1.2.5 / 1.5.2 have pack.meta.json = draft, so session refuses outright (PACK_NOT_FOUND); rules on disk must not be treated as loaded, and 1.6.4 must never stand in; safe-api table only; Forge Javadoc is forbidden
Bedrock flat bedrock/ (*) search_bedrock_docs + docsStatus per manifest no platform/<ver>/ split; experimental switches follow min_engine_version
Paper (server face) 26.3 (rule tree paper/26.3/rules/, 10 rules) + per-version packs ×5 (paper/<ver>/rules/00-applicability.md: 1.21.4 · 1.21.1 · 1.20.1 · 1.16.5 · 1.12.2) search_docs({platform:"paper"}): 67 tutorial pages (CC BY-SA 4.0; upstream does not split tutorials by MC version) 26.3 carrier is runServer (not runClient); the per-version packs do not copy the 10 rules — they carry "how the 26.3 rules survive on this version" plus "that version's Bukkit core vs Paper extension" (the latter caught ItemMeta#setDamageType being Paper-only)
Paper API (signature face) no rule tree (a signature face is not a rule carrier) search_docs({platform:"paper-api"}): current pack stable 2116 classes + history ×5 (1.21.4 1871 · 1.21.1 1702 · 1.20.1 1496 · 1.16.5 1254 · 1.12.2 877) stable same platform, different tree from paper (FabricDocStore is single-source so each tree gets its own platform id); history packs come from javadoc pages (jd.papermc.io/paper/<ver>/); all packs have semantic stores
Spigot (signature face) no rule tree search_docs({platform:"spigot"}): current pack stable 1396 classes + history ×8 (1.21.8 1352 · 1.21.4 1335 · 1.21.1 1282 · 1.20.6 1251 · 1.20.1 1186 · 1.19.4 1173 · 1.16.5 1027 · 1.12.2 779) stable history packs are extracted from the maven artifact via javap (the javadoc site has no version axis); every page carries sourceType: javap; no tutorial body (SpigotMC Wiki has no open licence) ⇒ use platform=paper for tutorials; GPL-3.0 derived-face boundaries in THIRD_PARTY_NOTICES.md

How MC 26.2 / 26.3 are supported (mod face): it depends on the loader. Fabric 26.2 is a complete pack: fabric/26.2 (11 rules + scaffold) plus the fabric-docs body in data/fabric_26.2 (list_fabric_versions includes 26.2). NeoForge 26.2 / 26.3 have rule trees (neoforge/26.2 / neoforge/26.3, 11 rules each), but the official main docs are not split per version and this repo has no corpus for either (list_neoforge_versions does not include them): the 00 engineering facts (plugin, neo_version, Java 25, runs, modMetadata) come from the official MDK and sources jar; 01–10 changes go through the 26.1 → 26.2 → 26.3 migration guide (get_migration_guide with route="26.1->26.2" / "26.2->26.3", sourced from the NeoForge Primer), together with analyze_porting_path. Fabric 26.3's upstream docs port PR has not merged yet, so it has neither a rule tree nor body; only a blog-level migration summary exists (data/fabric_porting/26.3.md, source=porting-extra) and it must not be used as a source for class signatures. Versioned docs will be added once upstream publishes them. The server face's 26.3 is a different line: paper/26.3/rules/ is the Paper server rule tree (carrier runServer), unrelated to the mod-face migration route above — do not cross-apply one to the other.

To list what is already indexed on this machine: node mcp-server/dist/cli.js activate_platform_pack --action=list; for docs: list_forge_versions / list_fabric_versions / list_neoforge_versions / list_doc_versions.

Quick start

Install (read this first)

see the top

For the AI (when opening an MC mod project):

Follow the root AGENTS.md to identify the platform and the exact version, then call activate_platform_pack action=session to load that version's rules / Skill index (do not read a neighbouring version's platform/<ver>/.cursor directly). For official docs, call list_*_versions first, then pin version to the project version for search_*_docs / search_docs. Creative design is the user's call; compatibility trade-offs and API choices default to the user as well, and the agent may decide when the user does not want to or cannot, but then it must explain using the template below (the template is also written into the root AGENTS.md under "Human in the loop", binding on agents). Writing files, running Gradle, copying jars, uploading — all require confirmation first (human in the loop, not an unattended pipeline).

Explanation template (mandatory format when deciding on the user's behalf)

The authoritative text is "Delegation explanation template" in the root AGENTS.md. This section is a copy with the same structure — change one of the three places and you must sync the other two (AGENTS.md, README.md, README.en.md; no gate checks this yet).

Judge the risk first; it decides when you speak:

What kind of decision When to state it Wait for a reply?
Low risk: an API style, a dependency version After acting, in the same reply No
High risk: switch loader platform, restructure packages, drop a dependency, edit build scripts Before acting Yes, wait for the user
The user already said "don't ask me, just do it" / "you decide" After acting No, but you must give the revert path

The explanation must carry five parts, in this order, one part per paragraph:

  1. What was chosen — name and version. Example: Forge 1.20.1's SimpleChannel.
  2. Why it was chosen — give only reasons tied to this version or this project. "Industry practice" is not a reason.
  3. The alternatives, and why not — one or two, one sentence each.
  4. Impact and risk — what the user must check or watch because of this.
  5. How to revert — which lines change back, and to what.

Start with this line:

I picked DeferredRegister for you; the reasoning is below.

Every reason must be checkable: cite a hit page id or URL from search_*_docs, a rule number, or an official doc link. If you cannot find one, write // TODO(未核实). Never fill a name from memory, and never write only "best practice".

Match the language to the user: when the user says "I'm not very technical" or "just decide", describe the outcome instead of stacking terms (example: "with this style you will have to touch two more places when Forge upgrades"). For a professional developer, give class names, method signatures, and doc links. Both styles must still carry the five parts and the sources above — what changes is the wording, not the content.

Worked example (keep the shape, re-check every fact for your version):

I picked SimpleChannel for you; the reasoning is below.

  1. Network packet registration uses Forge 1.20.1's SimpleChannel (NetworkRegistry.newSimpleChannel).
  2. Your loader is NeoForge 1.20.1, which is the Forge compatibility layer, and its official docs still only give SimpleChannel (source: search_neoforge_docs version=1.20.1, hit page 1.20.1/networking_simpleimpl, which contains the name verbatim).
  3. The other route is CustomPacketPayload + IPayloadRegistrar: that API has a doc page only from NeoForge 1.20.4 (networking/payload returns DOC_NOT_FOUND at 1.20.1), so it is not available to your version.
  4. Impact: the code depends on the net.minecraftforge package at compile time, so confirm your project carries that dependency.
  5. Revert: only your own network registration class changes (the official docs name it ModidPacketHandler); when you later move to 1.20.4+, swap the channel construction in that class for payload registration.

Using the scaffold for a new project:

Use scaffold/ under the matching platform version (e.g. forge/1.20.1/scaffold/) to generate a project skeleton that already carries the rules.

Syncing multiple IDEs:

After editing .cursor/, run sync-skills.ps1 in that version directory.

Configuring the local MCP server: see "Install (read this first)" above; the per-host config format and acceptance steps are authoritative in AUTO_SETUP.md (do not default to Cursor's mcp.json).

Mod testing loop: two halves

Real-machine testing is split into two loops with different coverage:

Half What the loop does Coverage Carried by
First half agent writes code → build → launch the game automatically → read the crash → fix the code → retest all platforms (Forge / Fabric / NeoForge / Quilt / LiteLoader / Rift / ModLoader / Bedrock) mc-build-mod, mc-ingame-iterate (step checklists, human in the loop); build/launch errors and crashes are read by inspect_runtime / analyze_log / crash_analyze from <gameDir>/logs/latest.log + crash-reports/; on Bedrock it reads the content log (analyze_bedrock_log)
Second half launch the game automatically → enter the world and operate it, testing by itself → bring the evidence back → fix the code → retest Java platforms on MC 1.20.1 and above (1.20.1 included): Fabric / Quilt / Forge / NeoForge generate_playtest_driver (no bridge: in-process temporary driver; with bridge: BlackBoxPro action sequences) + playtest_bridge / playtest_intent / inspect_playtest_evidence; workflow mc-ingame-playtest

Two routes:

  • No bridge (in-process driver): generate_playtest_driver driverMode=temporary_client_tick_driver (or in_jvm_player_agent: the LLM feeds intents one by one through the <evidenceDir>/intent.json mailbox). The driver is compiled into the project under test; once in the world it operates, asserts, and collects evidence by following a script (smoke / village / custom plan DSL); it is long-running with hot-loaded scripts (editing <evidenceDir>/plan.txt starts a new round inside the same process, no game restart). Evidence = state.json / exit-code.txt / qa.log / rounds.jsonl + screenshots.
  • With bridge (third-party bridge mod): a prebuilt bridge mod (currently BlackBoxPro, MIT) is installed into the game instance; playtest_bridge sends actions / queries / screenshots over 127.0.0.1:38081. Evidence = calls.jsonl + screenshots + query responses. Which MC versions the bridge covers is decided by the third party: the current BlackBoxPro build covers fabric/neoforge 1.21.1, 1.21.11 and forge 1.12.2; this repo only records combinations it actually measured (community_knowledge/authored/ingame-playtest-automation.md), so do not treat any other version as verified.

Single entry point for reading evidence: inspect_playtest_evidence (three states present|absent|unreadable; a missing item must never be read as "no failure"); for multiple clients (multiple sessions) use inspect_playtest_multi (per-client three states + joint pass judgement + anchors + rendezvous markers; if any client directory falls outside the authorized root, the whole reading is rejected). For execution rights and authorizations see "Human-in-the-loop exception: in-game playtest (three channels)" in the root AGENTS.md.

Testing requirement: how far you must test before delivering

The loop above is the mechanism; this section is the delivery gate. A change is not delivered because it compiles: it must be tested, and tested across dimensions. The full layer-by-layer table (which tool per layer, what a failure looks like) lives in "Playtest requirement (delivery gate)" in the root AGENTS.md; what follows is the summary for humans.

The ladder (a red lower layer blocks the higher ones): L0 build → L1 structure and static checks → L2 data side (recipes / loot tables / tags / block states / lang) → L3 GameTest automation → L4 in-game smoke → L5 scenario acceptance (the player-visible behaviour this change introduced) → L6 server and multiplayer → L7 regression and co-existence → pre-publish close-out.

The minimum level is the widest one that matches what you changed:

What changed Test at least up to
Logic / registration L3 (GameTest)
Player-visible behaviour (block / item / entity / GUI / recipe effect / worldgen) L4 + L5
Networking / world saves / server side L6
Loader or MC version upgrade L0–L7, all of it
Documentation / comments only L0

"Comprehensive" means spreading over dimensions, not running the same path several times: the surface you changed (code / resources / generated data / config / platform metadata); platform × version (test every target version — a green result on a neighbouring version does not count); both sides, client and dedicated server; a new world and an upgraded old save; permission profiles (survival / creative / operator); edge cases (empty and full inventory, a missing target block, unloaded chunks, death and rejoin, a player who is not the host); presentation (models and textures, GUI overflow and screen scaling, every lang key filled in both en_us and zh_cn); and logs (no new ERROR in latest.log, crash-reports/ empty; on Bedrock, the content log).

Judging a failure (fail-closed): no evidence means not passed. absent does not mean "no failure"; exit-code.txt other than 0, or missing from disk, is red. Real driver coverage is defined by PLAYTEST_VERIFIED_TIER in the generator (the single source of truth — prose does not count tiers), and a version outside that table is not exempt — use the bridge route or play by hand, and state honestly whether it was verified manually or not at all. If MC_SKILL_PLAYTEST_INTENT_E2E is unset, treat the intent route as unverified; never pass it silently.

Boundary with human-in-the-loop: the gate says testing is required, not that the agent gets to run anything. Gradle and launching the game still follow the three-channel authorization. Without authorization, write "not verified on a real machine" in the delivery report and hand the user the checklist above — never declare a pass on the user's behalf.

Second-half loop tutorial: three routes, end to end

This section covers how to get the game running from scratch, let the agent play inside it, and keep the evidence: the three routes step by step, plus the operational bits gathered in one place. The real-machine ledger and capability boundaries you must read before running anything are in the pointer table at the end of this file.

How to pick a route:

Route driverMode / tools Coverage Good for Main cost
① With bridge bridge mod + playtest_bridge BlackBoxPro prebuilt artifacts (fabric/neoforge 1.21.1 + 1.21.11, forge 1.12.2) or the minimal in-repo bridge (9 targets = forge 1.7.10–1.12.2 + rift 1.13 / 1.13.2 + modloader 1.6.4, shipped by generate_playtest_driver driverMode=external_bridge; both rift versions share one real template, modloader skeleton only) fastest to get running, large action set narrow version coverage; the in-repo bridge has 10 actions, fail-closed per version; the bridge has no auth ⇒ local, short sessions only
② No-bridge script generate_playtest_driver driverMode=temporary_client_tick_driver real driver on verified versions; structural shell elsewhere deterministic regression / CI reproduction you must install the driver and supply a world
③ No-bridge intent session driverMode=in_jvm_player_agent + playtest_intent real executor coverage = PLAYTEST_VERIFIED_TIER (the generator's internal table, widened as evidence comes in; the prose does not count versions; versions outside the table get only a menu contract + a structural shell) agent decides in real time, "wrong choice → red → switch intent" observation granularity = once per intent; v1 goto has no pathfinding

Capability split (read this first — do not conflate the routes): route ① (bridge) is command-level — it sends chat packets, not key presses ⇒ reading / observing plus /tp /setblock-style commands work (subject to the instance's op status); walking, jumping, mining time, collision and GUI clicking cannot be tested. Routes ② and ③ (driver) are player-level — real key-press primitives (forward / back / left / right / jump / sneak / sprint / attack / use) plus the move / goto / break / gui / look / scan / shot / assert steps ⇒ walking, jumping, mining and GUI interaction are all reachable. That "cannot be tested" line scopes to route ① only — it is not the ceiling of the whole chain.

Route ① With bridge (fastest)

  1. Authorize: MC_SKILL_PLAYTEST_ALLOW=1 + MC_SKILL_PLAYTEST_ROOT=<absolute path> (the three channels and the prohibitions are in the root AGENTS.md, "Human-in-the-loop exception: in-game playtest").
  2. Install the bridge: the BlackBoxPro jar for that side + dependencies (the fabric side needs fabric-api and FLK); record source / version / sha256; the jar only goes into the authorized root.
  3. Launch the game → probe: playtest_bridge action=status ⇒ ready=true is the bar for "in the world" (the actions list differs per version — take the bridge's /status self-report and never copy numbers from another version).
  4. Enter the world: execute create_world / join_world — creating a world takes tens of seconds, and a response timeout ≠ failure (measured: after the timeout the world actually existed).
  5. Drive: action sequences come from generate_playtest_driver driverMode=external_bridge (playtest/actions.json + postconditions + evidence contract); single steps use execute, compound actions use batch + delay, and "wait for a condition" uses await (the bridge has no wait_until; a timeout maps to PLAYTEST_TIMEOUT and must not collapse into "no failure").
  6. Read the result: inspect_playtest_evidence (three states present|absent|unreadable) + calls.jsonl + screenshots; on failure → fix the code → rebuild via mc-build-mod → re-run.

Route ② No-bridge script driver (widest coverage)

  1. Create the project: copy the matching version's scaffold to <ROOT>/<platform>-<version> — the project directory is the game root (run/ is the gameDir; do not change the runDir DSL). JDK split: JDK 17 for the 1.20.1 line, JDK 21 for the 1.21.x line, and JDK 25 for the 26.1+ line (diagnose_gradle hard-checks the 26.1 toolchain).
  2. Disable pause-on-lost-focus (mandatory): write pauseOnLostFocus:false in <gameDir>/options.txt — otherwise key-press movement is always 0.00 (when you force-kill the process MC does not write this file itself, so create it by hand).
  3. Generate the driver: generate_playtest_driver{platform, version, driverMode:"temporary_client_tick_driver", enterWorld:"<save name>" or leave empty, evidenceDir:"<absolute path inside the authorized root>", plan:[…] or scenario:"smoke"|"village"} ⇒ put PlaytestQaDriver.java in src/main/java/<pkg>/playtest/ and add one PlaytestQaDriver.register(); line to the client entry point.
  4. Supply a world: <gameDir>/saves/<save name>/level.dat must exist + allowCommands=1 (needed by /locate and other cmd steps) — see "operational bits" below.
  5. Run: gradlew build → gradlew runClient; log milestones [QA] driver registered → [QA] open world requested → [QA] ROUND 1 START → [QA] DONE :: / [QA] ERROR:.
  6. Hot load: to change actions / assertions / coordinates, edit only <evidenceDir>/plan.txt (a new round starts inside the same process, no game restart); rebuild and restart only when the driver's or the mod under test's Java source changed.
  7. Read the result and clean up: same as route ①; when done, delete the driver and the call line per playtest/REVERT.md (never commit).

Route ③ No-bridge intent session (the agent sends intents live; details)

How it relates to route ② (these are not two parallel systems): it is the same driver and the same interpreter; intents are just steps that "expand into a primitive sub-plan", and the outer script degenerates into a single waitintent guard loop. Only one plan runs per tick.

  1. Prerequisites: steps 1–2 of route ② plus a verified version (real executor coverage = PLAYTEST_VERIFIED_TIER, the single source of truth, widened as evidence comes in — the prose does not count versions; versions outside the table get only a menu contract + a structural shell and will not pretend to run).
  2. Enter the world: follow that version's recipe — the frozen family (fabric 1.20.4 / 1.21.1 / 1.21.3) uses vanilla quick play (add programArgs "--quickPlaySingleplayer", "<save name>" to the loom runs in build.gradle) and leaves enterWorld empty; the 1.21.11 line can use enterWorld:"<save name>" directly.
  3. Generate: generate_playtest_driver{platform:"quilt", version:"1.21.11", driverMode:"in_jvm_player_agent", capabilityProfile:"operator"|"creative"|"strict_survival", evidenceDir:"<absolute path inside the authorized root>", budgetTicks:36000} ⇒ five artifacts plus playtest/intent-menu.json (the menu contract); the default script = mark in_jvm:intent-session + waitintent max=6000.
  4. Install and run: same as route ②; by [QA] ROUND 1 START the first waitintent tick in the world seeds state.json (the observation surface).
  5. Observe (read): playtest_intent{action:"read", evidenceDir} ⇒ observation surface: intentState (profile / menu / mailbox / remaining budget / current intent), intents[], lastIntent, scan.nearest{found,id,x,y,z}, goto{x,z,arrived,arrivedDist}, plus menu and mailbox state and nextSteps (after a failure, the fallbacks from that intent's menu).
  6. Send an intent (write): playtest_intent{action:"write", evidenceDir, intent:"walk_to", params:{x:10,z:-20,tol:3}, confirmed:true} ⇒ writes <evidenceDir>/intent.json (flat JSON). Six checks on the write side: confirmed → forbidden list (kill/tnt/fill) → the 13-intent menu → parameter allowlist → required parameters → mailbox occupancy (occupied returns MAILBOX_BUSY unless overwrite=true); illegal intents are rejected on the write side and never reach the executor. Two usability boundaries (measured on fabric 26.1.2): ① the default menu lookup misses — the generator writes playtest/intent-menu.json at the project root, while the tool looks for <evidenceDir>/intent-menu.json and then <evidenceDir>/../playtest/intent-menu.json; when evidenceDir is (as recommended) outside the project (<authorized root>/instances/<tag>/evidence-intent) both miss ⇒ you must pass menuPath=<project root>/playtest/intent-menu.json explicitly, otherwise you get MENU_NOT_FOUND. ② observe needs entities= or blocks= — passing only radius= is judged red as observe_need_scan (v1: an empty scan has no criterion to judge); that is fail-closed design, not a bug.
  7. Session loop: read to observe → pick an intent (on failure switch per nextSteps) → write → the driver consumes it (renames intent.json to intent.done.json) → expands it into primitives → judges exactly one typed postcondition → appends to intents[] and refreshes state.json → back to guarding. Failures must not be retried automatically (retrying a one-shot intent would re-consume blocks or trigger side effects again); switch intents instead.
  8. Wrap up: write {"intent":"stop"} ⇒ ends the round (does not close the game); then clean up per playtest/REVERT.md.

Two operational rules (measured on fabric 26.1.2): the at field in state.json is the time of the last intent (not the file's write time) ⇒ judge whether the driver is alive by the process + the file mtime + intent.done.json, not by at; the screenshot PNG lands in <gameDir>/screenshots/ (the gameDir of runClient is run/), not at the project root. The default script's waitintent max=6000 (5 min) can expire before you send your first intent (the whole round is then judged red) — the driver does not exit, it falls back to the idle state guarding plan.txt, and rewriting plan.txt once starts a new round in the same process (max=30000 is steadier). Per-step readings for that chain (observe→walk_to→screenshot→stop, all five intents green, exit-code=0) are in the playtest single source of truth, community_knowledge/authored/ingame-playtest-automation.md, section "intent space → executor implementation surface" (entry row: the pointer table at the end of this file).

Failure semantics (the most important difference across the three routes): a failure at the mailbox level is data (intents[] records ok:false plus a failure field) and guarding continues (the session stays alive); protocol violations (forbidden list, not in menu, wrong profile) are rejected by the tool on the write side; failures in script form (an intent step inside plan.txt) are judged red and stop the round.

Budget and protocol: per-intent cap = the budgetTicks column in the menu (walk_to 1200 / find_and_goto 9000 / the rest 60–600); a single guard run is 5 min (waitintent max=6000); a full round defaults to 30 min (budgetTicks=36000); the mailbox is single-slot (while one intent is running, newly written intents wait in the mailbox and a second write is rejected). A wrong parameter (e.g. x=abc) is judged red as param_not_number; it never silently falls back to a default.

v1 implementation surface and known limits: implemented = walk_to / look_at(yaw|pos) / find_and_goto(structure|block|entity) / observe / open_gui / inventory / screenshot / wait(ticks) / tp(op/creative) / stop; mine/place/interact and wait until= are not implemented (a hit is judged red, never silent). goto has no pathfinding (straight line + fly + a cruise speed of 140 with anti-stuck; complex terrain times out → switch intent); the structure form needs cheats enabled in that world; the block form only samples a thin vertical layer of -4..+8 (start near the target height); entity only covers roughly the 48-block tracking range; if a village has no villagers in range, suspect an abandoned village first (try another one).

Four real-machine sessions (quilt 1.21.11 / operator): the intent-switch chain, entity / block positive cases, the screenshot ageMs freshness criterion and the walk_to{x:abc} negative case — all exit-code=0; per-item readings are in the same single source of truth; for the per-version matrix and the current criteria see the playtest row of the pointer table at the end of this file (its §真机台账 = current criteria T5 + archives T0–T4).

Second-half loop operational bits (scattered everywhere, gathered here)

Item How
JDK split 1.20.1 line = JDK 17; 1.21.x line = JDK 21; 26.1+ line = JDK 25 (point JAVA_HOME at the matching version; on older lines you can add -Porg.gradle.java.installations.paths=<jdk17>)
Authorization MC_SKILL_PLAYTEST_ALLOW=1 + MC_SKILL_PLAYTEST_ROOT=<absolute path>; evidence and driver files stay in that root only
Pause on lost focus write pauseOnLostFocus:false in <gameDir>/options.txt (MC does not write it after a force-kill; this single line is enough to run)
World supply create a world once with a vanilla server of the same MC version (eula=true + server.properties with level-name / gamemode=creative / online-mode=false) → wait for Done (…) → stop → copy saves/<name>/ into each version's <gameDir>/saves/ (same version works across loaders); enabling cheats = flip the allowCommands payload byte 0→1 in level.dat (gzip NBT, same-length rewrite; locate it by "the first 3 bytes are the tag type, the first 2 bytes are the length"); afterwards confirm no client still holds that world (otherwise the old client writes the value back to 0 on exit)
Entering the world (frozen family) for fabric 1.20.4 / 1.21.1 / 1.21.3 the driver must not call IntegratedServerLoader.start (it freezes the render thread in a Thread.sleep waiting for the server to load, proven by jstack) ⇒ use vanilla quick play (--quickPlaySingleplayer "<save name>") and leave enterWorld empty; the 1.21.11 line can use enterWorld
Assets stuck if the first :downloadAssets fails or produces no output for a long time: ForgeGradle and Loom asset caches can borrow from each other; find a missing object via the official manifest → assetIndex.id → indexes/<id>.json, then compare sizes; overwrite a corrupt (truncated) file using the real path assets/objects/xx/<hash> (content-addressed, same path)
First run dies at mixin prepare old clones of fabric 1.20.1 / 1.20.4 / 1.21.1: the scaffold's filesMatching needs examplemod.mixins.json added (already fixed in the library)
Closing the client kill the real JVM precisely (the java process whose command line contains -Dfabric.dli.config); do not kill only the gradlew wrapper — a leftover client holds the save's session.lock and the next world entry reports "another program has locked a part of the file"
Separate instances use a separate runId / instance per run (sharing a runDir silently overwrites screenshots)
Reading evidence inspect_playtest_evidence (three states; a missing item must not be read as "no failure"); rounds.jsonl must be one valid JSON object per line (entries {intent,params,ok,postcondition|failure,detail}); check screenshot freshness via ageMs (negative means clock jitter); qa.log must be a .log file (the reader takes the [QA] section from the tail of any .log in the directory)
Cleanup delete the driver file and the register() call line; evidence stays only in the authorized root; self-check with git status for zero hits — never commit

Community knowledge and library mods

Separate from the official Forge/Fabric/NeoForge docs under data/, this repo carries two more practical knowledge sets for the agent to use in publishing, crash triage, soft dependencies, library selection, and dependency-tree work. Neither replaces search_*_docs or query_api.

Community practice knowledge (community_knowledge/)

Directory Meaning Note for the agent
authored/ short essays written in this repo (editable) practice checklists and anti-patterns, not API specifications
permitted/ community posts distilled with the author's permission when still unsure, open the original URL
links/ title / summary / external link only forbidden to treat the web page body as ingested full text

Index: indexes/index-l0.json (per-source counts are in the file itself; rebuild: npm run community:index). MCP: list_community_sources → search_community_docs → get_community_doc_summary / get_community_doc_full. The environment variable MC_SKILL_COMMUNITY can change the root path.

Topic quick reference: publishing / crash triage / soft dependencies / machine GUI / localization / code patterns (patterns/), and so on. Library integration additionally has the authored/lib-*.md essay series plus the overview library-catalog-2026, the traps lib-traps-2026, and the recipe integration notes library-integration / library-integration-jei-emi.

Mandatory rule: before writing code from a community essay, if a method name or version detail is uncertain you must first check the original source or the official docs the essay points to.

Library mod knowledge system (knowledge/libs/ + the data chain)

Three layers (details in the MCP tool sections §7 / §7.5 below):

  1. Community essays — authored/lib-*.md, searchable through search_community_docs; each has a decompilation-verified section (the source of verifiedApi).
  2. Library Skill sources — knowledge/libs/<group>/mc-<name>/SKILL.md, not written into platform .cursor/skills; resolved per the "library Skill" rules in AGENTS.md: platform → group mapping (forge-only+all-platforms / fabric-only+all-platforms / neo-only+all-platforms / bedrock-only) plus a second filter on frontmatter. Unsure which library to use → read knowledge/libs/all-platforms/mc-lib-catalog/SKILL.md first.
  3. Data chain — essay frontmatter → mcp-server/scripts/build-library-catalog-from-authored.mjs → library-catalog.ts + lib-manifests/all.json + lib-api-summaries/ → check_dependencies recognizes dependencies and version windows. (Counting rules and measures: see the library-data-chain counting rules in CONTRIBUTING.md; script locations: see the table in §7.5)

Recommended agent path (library-related): check_dependencies (look at detectedLibraries) → search_community_docs (lib-<name> or library-catalog-2026) → read knowledge/libs/.../SKILL.md by skillId or name → if a signature is still missing, go to search_*_docs / query_loader_api.

Environment variables

Common (what most users touch)

Variable Meaning Example
MC_SKILL_DATA Root of the data directories (points at data/, not at a version subdirectory) <repo root>/data
MC_SKILL_COMMUNITY Root of the community knowledge base (defaults to the repo's community_knowledge/) <repo root>/community_knowledge
MC_SKILL_ALLOW_WRITE Set to 1 to let port_project write to disk 1
MC_SKILL_PROJECT_ROOT Project root allowed for writes (absolute path) <absolute path to your mod project>
MC_SKILL_STRICT Set to 1 to make MCP startup fail when data is invalid 1
MC_SKILL_DEBUG_PATHS Set to 1 to print path resolution steps (turn it on first when "can't find data/") 1
MC_SKILL_CACHE Cache root for decompilation / MDK / loader jars. Both MCP and the scripts read it; when unset, MCP defaults to APPDATA while the scripts default to os.tmpdir()/mc-skill-cache, so the two split apart (batch runs should set one explicit path) %APPDATA%/mc-skill-cache (scripts fall back to os.tmpdir()/mc-skill-cache)
JAVA_HOME Preferred JDK for decompilation / remap (needs 17+). When unset or pointing at <17 it falls back to java on PATH; whichever has the higher major wins, and only when neither is usable do you get TOOLCHAIN_MISSING <Temurin 17+ install dir>
MC_SKILL_PLAYTEST_ALLOW Set to 1 to open the authorization gate for the three playtest channels (must be paired with MC_SKILL_PLAYTEST_ROOT) 1
MC_SKILL_PLAYTEST_ROOT Playtest authorization root (absolute path; the target's real path must fall inside it) <authorized instance world root>
MC_SKILL_SKIP_DOWNLOAD Set to 1 to make the decompilation tools skip every download and fail honestly. It must be set to the literal 1 (the implementation compares === "1" strictly, see mcp-server/src/decompile/java/java-process.ts:168; leaving it unset or setting true does nothing). This repo's .github/workflows/ all four workflows set it. It only covers get_minecraft_source / decompile_mod_jar (download_official_mdk does not read it; it has its own pin gate) unset (download on demand by default)

Advanced / troubleshooting (set as needed; most cases don't need these)

Variable Meaning Default / example
MC_SKILL_JAVA_SCAN_MAX_FILES File cap for the Java source scan in validate_project and friends 300
MC_SKILL_JAVA_TIMEOUT_MS Timeout in ms for remap / decompile Java subprocesses. Non-numeric or ≤0 values are ignored and fall through (a typo never turns into a 0 ms instant kill); the java -version probe stays at a fixed 15 s and is unaffected 900000 (15 minutes)
MC_SKILL_SCRIPT_TIMEOUT_MS CLI-side script subprocess timeout in ms (unset = no timeout, so long runs aren't killed) unset
MC_SKILL_MAX_ENTRY_BYTES Max uncompressed size of a single entry when inflating (zip-bomb guard) 268435456 (256 MB)
MC_SKILL_MDK_CHECKSUMS Override path of the MDK checksum pin file mcp-server/data/mdk-checksums.json
MC_SKILL_BEDROCK_API_PIN Override path of the Bedrock Script API pin file mcp-server/data/bedrock-script-api-pin.json
MC_SKILL_FETCH_BACKEND Set to curl to route GitHub fetches through the system curl.exe (escape hatch when Node TLS fails) unset (try Node, fall back to curl)
MC_SKILL_GITHUB_API_BASE GitHub API mirror base (also added to the fetch host allowlist) unset (api.github.com)
MC_SKILL_GITHUB_TIMEOUT_MS GitHub request timeout in ms built-in fallback
MC_SKILL_GITHUB_TOKEN / GITHUB_TOKEN GitHub token for self-update / upstream queries (raises rate limit, avoids anonymous throttling) unset
MC_SKILL_UPDATE_REPO / MC_SKILL_UPDATE_REMOTE Self-update repo slug / forced git remote name guguzea/MC-AI-Coding-Assistant-Tool
MC_SKILL_UPDATE_CACHE_TTL_SEC Self-update check cache TTL (seconds) 3600
MC_SKILL_UPDATE_DOWNLOAD_TIMEOUT_MS Self-update download timeout in ms 600000
MC_SKILL_UPSTREAM_CACHE Set to 0 to disable the query_upstream_releases disk cache entirely unset (per-tier TTL)
HTTP_PROXY / HTTPS_PROXY / ALL_PROXY (and all-lowercase forms) Proxy for fetches unset
APPDATA Windows base for the default cache root (when MC_SKILL_CACHE is unset) system value
NODE_OPTIONS Node 22.5–22.12 / 23.0–23.3 need --experimental-sqlite in here unset (not needed on 22.13+ / 23.4+)
MCP_TIMEOUT_MS Test/CI-side timeout in ms (read by test-mcp.mjs / release-smoke.mjs / the four CI workflows; the MCP server process itself does not read it) 60000

The two tables above list the entire user-configurable surface. The server source reads 37 distinct environment-variable names when counted case-sensitively; the remainder are case aliases of the same switch plus process details (HTTP_PROXY / http_proxy, ComSpec / COMSPEC) and need no separate configuration. To get the full list, scan mcp-server/src/** for process.env.*.

Notes on using the MCP tools

The local MCP service is named MC-AI-Coding-Assistant-Tool (89 tools). Configure it with an absolute path and point MC_SKILL_DATA at this repo's data/. Requires Node.js >= 22.5 (the Yarn mappings use the built-in node:sqlite; 22.5–22.12 and 23.0–23.3 need --experimental-sqlite in NODE_OPTIONS or the launch arguments, 22.13+ / 23.4+ do not). The repo / Release does not include node_modules, so you must run npm ci && npm run build yourself (running npm run build:yarn-sqlite afterwards is recommended).

Tests: cd mcp-server && npm test (build + all unit suites: core / scripts / data audit / Wave BCD / localize / update / CLI / decompile / deep mixin / MCP protocol). CI semantics: the job env of all four workflows under .github/workflows/ sets MC_SKILL_SKIP_DOWNLOAD=1 uniformly, so download-based tools fail honestly in CI instead of silently hitting the network (that variable may only be relied on after node test-decompile.mjs passes inside mcp-server). The CLI also has two separate gates: npm run test:cli:quick (mcp-server/scripts/assert-cli-quick.mjs, fast tier, wired into the default gate chain) and npm run test:cli:full (mcp-server/scripts/assert-cli-full.mjs, full tier — the authoritative list is taken at run time: entry contract probes + real calls + per-item waiver reasons, not run by default).

Post-install acceptance and npm script reference

After installing (or on a fresh clone), run the four checks below; go no further until they are all green:

cd mcp-server && npm ci && npm run build     # dist/ is not committed, you must build it
node dist/cli.js --version                    # should print a version (matching `version` in `mcp-server/package.json`)
node dist/cli.js list-tools --names-only      # should return 89 tool names
node dist/cli.js activate_platform_pack --action=list   # should return the platform/versions built on this machine
node dist/cli.js diagnose_data_paths          # each platform should be found; empty / not_found = MC_SKILL_DATA is wrong

If the tools are all uncallable inside the MCP host, it is usually an unbuilt dist/ or an unreloaded host (installing new dist/ still requires reloading MCP). The checklist is in "Tool not working" below.

Common scripts after cd mcp-server (the full set of 35 lives in mcp-server/package.json):

Script Purpose When to run
npm run build tsc compile into dist/ after source changes; before MCP/CLI
npm ci install dependencies fresh clone (repo/Release ships no node_modules)
npm test full gate chain (build + unit suites + the assert-*.mjs gates) before committing
npm run test:core core unit tests (includes rule loading / compatibility-comment pins) changed core / rule loading
npm run test:cli CLI contract tests (arg parsing + envelope + exit codes) changed CLI entry / envelope / exit codes
npm run test:cli:quick / test:cli:full CLI fast tier (in the default chain) / full tier (not run by default) changed CLI
npm run test:scripts the mcp-server/scripts/** gate chain changed scripts / gates (must run before wrapping up)
npm run test:audit data-audit unit tests changed data/ or the auditor
npm run test:semantic semantic-index unit tests after rebuilding the semantic store
npm run test:decompile / test:deep-mixin decompilation / deep mixin unit tests (no JDK 17+ and no network needed: fixture jars/classes are built inside the tests, and the probe case only requires the probe's verdict to be honest) changed decompilation / bytecode checks
npm run test:update self-update unit tests changed src/update/
npm run build:yarn-sqlite rebuild the Yarn mappings SQLite (--all) first time / after a version change; before convert_mapping
npm run fetch:embedding-model download the local embedding model before first building the semantic index
npm run build:semantic-index rebuild the semantic index (npm run … -- --all) for offline / semantic retrieval
npm run build:vanilla-registries rebuild Vanilla registry data (-- --version=<v>) changed query_registry data
npm run audit:data full cross-platform data consistency audit (any ERROR = not publishable) before publishing the data pack
npm run audit:data:forge / :fabric / :neoforge / :fail-on-error single-platform / all-platform fail-on-error changed only one platform
npm run community:index rebuild the community L0 index (--write) after adding/removing community_knowledge/ entries
npm run smoke:release release smoke test before packaging

The rest (test:w3 / assert:no-yarn-slurp / build:yarn-named / repair:quilt-indexes / audit:quilt-indexes / fetch:quilt-docs / fetch:bedrock-docs / fetch:vanilla-registries, and others) can be looked up directly in mcp-server/package.json.

Two first-class entry points: MCP and CLI

One core, two adapters (neither forks): MCP (stdio, for AI hosts) and the CLI (terminal / scripts, for humans). Same prerequisites as MCP: Node ≥ 22.5 + cd mcp-server && npm ci && npm run build (the CLI runs from dist/).

Entry point one: the tool line (= the MCP tools, all callable)

node mcp-server/dist/cli.js --version
node mcp-server/dist/cli.js list-tools --names-only                    # list of tool names
node mcp-server/dist/cli.js list-tools --tool resolve_lib_skills       # schema for one tool
node mcp-server/dist/cli.js search_docs --platform fabric --version 1.21.1 --query registry
node mcp-server/dist/cli.js resolve_lib_skills --platform fabric --mcVersion 1.21.1
node mcp-server/dist/cli.js check_dependencies --project .
node mcp-server/dist/cli.js crash_analyze --crashReport @./crash-reports/latest.txt
  • Short aliases (5 in total; every other tool name dispatches directly): query→query_api, convert→convert_mapping, update→mc_skill_update, status→get_server_status, warmup→get_server_status (adds warmup=true).
  • Argument conventions: flags-only (--key value / --key=value / bare --flag → true); --file field=path, @path / @- (read a file / stdin), --stdin-json, --raw [field], --timeout <ms>, --quiet, --project <dir>, --output-format json. The complete global-flag list (including the --compact / --json / -h / -V edge cases) lives only in the "Standalone CLI" section below, not here. Parameter names follow each tool's schema (e.g. resolve_lib_skills uses --mcVersion; run … <tool name> --help when unsure).
  • Output: always a JSON wrapper {success, tool, result|error}; exit codes 0 = success / 1 = tool failure or timeout (errorKind: tool_failure | timeout) / 2 = usage error (usage | validation).
  • Project-scoped tools: --project <dir> maps to projectPath; --fail-on-error promotes found:false / a non-empty errors[] to exit code 1.

Entry point two: the repo line (maintenance-side script subcommands)

node mcp-server/bin/mc-skill-scripts.mjs --help                 # full command table
node mcp-server/bin/mc-skill-scripts.mjs lib resolve --platform fabric --version 1.21.1
node mcp-server/bin/mc-skill-scripts.mjs lib resolve --validate # resolution check per combination (the combination list follows VALIDATE_COMBOS inside the script; same gate as test-core §S15)
node mcp-server/bin/mc-skill-scripts.mjs lib summary --only libgui --write
node mcp-server/bin/mc-skill-scripts.mjs lib ownership          # G1 library-ownership gate
node mcp-server/bin/mc-skill-scripts.mjs corpus decompile --filter slug=cloth-config,jei
node mcp-server/bin/mc-skill-scripts.mjs corpus merge --input x.jsonl --dry-run
node mcp-server/bin/mc-skill-scripts.mjs cloth project          # injection marker ↔ versions.json check
node mcp-server/bin/mc-skill-scripts.mjs gate list
node mcp-server/bin/mc-skill-scripts.mjs gate run lib-ownership # run one gate (exit code passed through)
  • Nine commands = lib resolve|summary|ownership · corpus decompile|emit|merge · cloth project · gate list|run;
  • Thin shell: it forwards to the existing scripts under scripts/ and mcp-server/scripts/ with arguments and exit codes passed through unchanged; … <group> <command> --help prints the command's help (a script's own --help runs the script directly);
  • Boundary: the CLI must run inside the repo (the scripts live in the repo root scripts/ and mcp-server/scripts/); the repo line is maintenance-side work (batch decompilation / summary rebuilds / the G1 gate / injection write-back) and is not exposed on the MCP tool surface.
  • Smoke gate: mcp-server/scripts/assert-cli-smoke.mjs (both entry points' --version/--help + 8 × --help + gate list + lib resolve really run ×2) is wired into test-core §S16. After a global install (e.g. npm i -g ./mcp-server) both entry points appear as bins: mc-skill and mc-skill-scripts.

Library mod files stay directly readable by the AI: knowledge/libs/** is "the source is the usable file" — the AI reads the files directly per the "library Skill" rules in AGENTS.md; resolve_lib_skills (the same core behind the MCP tool and the CLI's lib resolve) only does resolution and ground-truth hints (returning repo-relative paths + versionsJson), and never replaces the file or caches the body.

Vector / semantic search (T1)

search_forge_docs / search_fabric_docs / search_neoforge_docs / search_docs are hybrid by default, not "L0 titles only". Implementation: L0 keyword ranking ∪ (FTS5 full text + MiniLM vector cosine), then RRF fusion; hits may carry matches[] (top-K from the chunks table: sectionHeading / snippet / score). A semantic: true in the response means that query used the semantic store.

Three degradation tiers (fall back one tier when something is missing; no errors, no invented data, and no remote model fetch at runtime — allowRemoteModels=false):

Tier Condition Behaviour
hybrid semantic/db.sqlite exists, embeddings are non-empty, and data/_models/Xenova/all-MiniLM-L6-v2 is ready L0 + vectors + FTS5, fused with RRF
fts5-only the semantic store exists but the embedding model is missing, or the embeddings table is empty full-text keyword search (FTS5), no vector scoring
l0-only that version/data source has no semantic store (semanticSearch returns null) matches L0 index fields only (label / id / url / tags); results carry semantic: false plus a warning

The global get_server_status.semanticIndex.modeHint is the machine-wide tier (any hybrid tree with a ready model → hybrid). A single query can still be L0: Forge 1.7.10 has no tutorial semantic store, for example. Read that query's own semantic and warning; do not rely on modeHint alone.

Missing model at build time: warn and degrade to fts5-only (no exit 1). diagnose_data_paths.semantic reports whether the db beside each doc tree exists.

Where the data and models live: semantic stores at data/{platform}_{ver}/{source}/{ver}/semantic/db.sqlite (forge_javadoc skipped — that tree gets no semantic store; db.sqlite.tmp-* / -journal are build leftovers), with data/semantic-index-manifest.json as the authoritative manifest; the embedding model at data/_models/Xenova/all-MiniLM-L6-v2 (transformers.js, the only place allowed to fetch a model remotely). Build: npm run fetch:embedding-model; npm run build:semantic-index -- --all (also accepts --platform / --version / --source / --no-embed / --force; interruptible and resumable). Artifact manifest: data/semantic-index-manifest.json.

How the agent calls it (two entry points, two steps, one field)

Entry A: the MCP tool (the proper route once the AI IDE has MC-AI-Coding-Assistant-Tool attached). Pick the tool by platform; the only parameters are version + query, and the semantic layer participates automatically — there is no switch:

  • Forge → search_forge_docs { version: "1.14.4", query: "entity goal" }
  • Fabric → search_fabric_docs { version: "1.21.4", query: "custom enchantment effect" } (run list_fabric_versions first to confirm the indexed version name)
  • NeoForge → search_neoforge_docs { version: "1.20.1", query: "..." } (1.20.1 falls back to the Forge corpus; that is expected)
  • General (quilt / liteloader / rift / modloader, etc.) → search_docs { platform: "...", version: "...", query: "..." }

Entry B: the standalone CLI (no MCP client, or you want to verify in a shell right away — also the way to test right after editing source without reloading the host):

node mcp-server/dist/cli.js search_forge_docs --version=1.14.4 --query="entity goal selector"

(MC_SKILL_DATA points at data/; tool output is always JSON, and --json does not change tool output.)

Two steps: take the id from the search_*_docs result (not the website URL) → read the body with get_*_doc_full / get_*_doc_summary. At most 2 pages at a time, so the context does not overflow.

Response contract: { ok, total, totalPool, truncated, semantic, results: [{ id, score, … }], matches? }. On the doc-search surface total is the number of rows returned this time (= results.length, which follows the limit you pass), not the total number of corpus hits; to judge "did I get everything", read the other two keys that are always in the payload: totalPool = how many candidates that surface had before windowing, truncated = (total < totalPool) (all eight emit sites covered; on most surfaces limitWindow.candidates is still the window, not the pool, and the bedrock surface has its window block under demotion). Residual caveat: totalPool only goes as deep as "what this surface can offer", not the whole corpus (fusion input and L0 retrieval each have their own caps). For query_loader_api / query_upstream_releases / search_mod_code, total is the full pool ⇒ the two families of formulas have opposite signs; do not copy one into the other. The agent must read the semantic field:

  • semantic: true = that query went through the semantic store (FTS5 BM25 + MiniLM vector cosine, RRF fused); hits can be treated as relevance-ordered coverage evidence;
  • semantic: false = degraded to L0 keywords (that tree has no semantic store / the embedding model is missing / semanticSearch returned null), with a warning — hits are then not exhaustive, and found:false proves nothing;
  • hits may carry matches[] (sectionHeading / snippet / score), and the snippet comes from real body text in the chunks table, so it can be quoted directly.

Agent-side rule (the "when uncertain" clause in the root AGENTS.md): when looking up APIs / docs / mechanisms, search semantically first; query_api / query_loader_api are compatibility tools (see the next section) and only serve as fallback.

The query_* compatibility tools and their index-coverage boundary

query_api / query_loader_api are marked as compatibility tools (class-name / signature indexes whose coverage varies by version and is limited). Every response now says so explicitly instead of staying silent:

  1. Every query_api response: the notes end with "query_api is a compatibility tool … prefer semantic search through search_forge_docs / search_docs for docs and semantics".
  2. query_api on 1.14.4 / 1.15.2: both versions have a real index (MCPConfig joined.tsrg → tsrg-extractor.js: 1.14.4 = 4,976 classes / 32,570 methods, 1.15.2 = 5,137 classes / 34,159 methods). Class names must use that version's SRG path (e.g. net.minecraft.item.Item) and member names are func_/field_, with no parameter names or javadoc. Only when extracted/api-index.json is missing or holds 0 classes does it fall back to the "empty index" warning; in that state found:false does not mean the class is absent, and search_forge_docs semantic search is the way in (the docs corpus and semantic store are complete for both versions and queries return semantic: true).
  3. Every query_loader_api response: notes gains a compatibility note (coverage bounded by the versions already ingested).
  4. Second-tier source nameIndex: when query_api misses in the api-index, or that version has no Parchment index at all (e.g. 1.21.x Fabric, or NeoForge versions without an extracted index), it queries the on-disk mapping index data/<platform>_<version>/mappings/yarn-mappings.sqlite and attaches the result as nameIndex: exists / matchKind (exact|simple-unique|ambiguous|contains|none) / named / memberCounts / memberSample / mappingEra + dbKind. Three boundary conditions, all required: found still stays false (existence never masquerades as a signature hit), mappingEra must be read (named for yarn-tiny is a Yarn name; for forge-srg/tsrg/mcp-csv it is the MCP func_/field_ name; for mcp-config-srg (the six Forge versions 1.16.5–1.20.4) it is an SRG class name plus m_N_/f_N_ member names), and when that version has no store or the table is empty the entire key is absent (no fabricated tier). Store selection follows the loader: this tool's api-index only reads data/forge_<ver>/extracted, so nameIndex also picks the store along the Forge line; the versions 1.16.5–1.20.4 that have stores in both trees no longer get answered by fabric's yarn-tiny (RenderCall lives in blaze3d/systems/ in Yarn but in blaze3d/pipeline/ in this pack; package names cannot be inferred across mapping layers); when Forge has no store it still falls back to fabric. For signatures, still use search_*_docs or get_minecraft_source on demand.

Pins: test-core.mjs (the 1.20.1 compatibility note / the real-index hit on 1.14.4 and 1.15.2 (Item must return a method list and no empty-index warning) / the 1.12.2 data-health pin / the nameIndex three legs: wiring (on 1.21.1 StatusEffect returns a nameIndex with found:false), falsification (an invented name must give exists:false), disclosure (all three notes required) + no nameIndex on the storeless version 26.1.2 or on the hit path 1.20.1**) and test-loader-api.mjs (the compatibility note).

Doc lookup (Forge / Fabric / NeoForge)

  1. The page ID must be the id from the search result, not a website URL path.
    • Right: get_fabric_doc_full({ id: "1.20.4/develop_items_first-item", version: "1.20.4" })
    • Wrong: id: "items/first-item"
  2. Recommended flow: search_*_docs → (optional) get_*_doc_summary → get_*_doc_full.
  3. Search defaults to hybrid (see the previous section). Only when it degrades to l0-only does it "match index fields only".
  4. Prefix query examples: class:Item, event:lifecycle.
  5. NeoForge 1.20.1 doc lookups fall back to the Forge 1.20.1 view (compatibility layer); that is expected.
  6. If a platform's data pack is not downloaded, the matching list/search returns PLATFORM_DATA_MISSING (use diagnose_data_paths to confirm).
  7. Run list_*_versions / list_doc_versions first and confirm the version exists locally before searching. search_forge_docs and search_docs({ platform: "forge" }) share one set of Forge indexes.
  8. Pick the tool by version (do not use query_api as a stand-in for the official docs):
Target Doc search Vanilla / mappings Platform API
Forge 1.12.2 search_forge_docs / search_docs (version=1.12.2). There is a data/forge_1.12.2/forge-docs tutorial tree (e.g. 1.12.2/blocks_blocks) Do not treat query_api as javadoc: that version only yields SRG class names with func_/field_ member names (no parameter names or javadoc). Use convert_mapping for mappings (MCP SRG) query_loader_api / search_loader_api (1.12.2-forge is indexed, about 1100 classes)
Forge 1.7.10–1.11.2 no tutorial rule tree; falls to forge_javadoc / search_docs, semantic: false same (SRG class names + func_/field_ member names, no javadoc); do not use it to check signatures no loader summaries (search_loader_api mode=list reports noIngest)
Forge 1.13.2 search_forge_docs / javadoc SRG class names and member names are listed (no Parchment javadoc) 1.13.2-forge is indexed
Forge 1.14.4 / 1.15.2 search_forge_docs (semantic store complete, queries return semantic: true) query_api has a real index (derived from MCPConfig joined.tsrg: 4,976 / 5,137 classes; class names use that version's SRG path, members are func_/field_, no parameter names or javadoc) *-forge is indexed
Forge 1.16.5–1.20.4 search_forge_docs Vanilla is available through query_api (real method signatures) query_loader_api or the docs
Fabric run list_fabric_versions first; never pass off a neighbouring version's wiki as this version's. 26.1.2 / 26.2 have fabric-docs only, no wiki 26.1+ has no query_api index search_loader_api mode=list: fabric-api for 1.14.4 / 1.16.5 / 1.17.1 / 1.18.2 / 1.19.4 / 1.20.1 / 1.20.4 / 1.21.1 / 1.21.3 / 1.21.11 / 26.1.2 / 26.2 is indexed (do not treat it as a maven 404; 12 versions = the 15 fabric/* rule trees minus the thin ones, 1.21.4 / 1.21.8 / 1.21.10)
Quilt search_docs({platform:"quilt"}); for QSL questions, a Fabric Registry hit is not a hit same-version Vanilla boundary as the left column QSL summaries via mode=list (e.g. 1.19.4-qsl / 1.21.1-qsl)
NeoForge run list_neoforge_versions first. 1.20.1 falls back to Forge docs (compatibility layer) 26.1+ has no query_api several *-neoforge versions are indexed
LiteLoader / Rift / ModLoader search_docs. LiteLoader/Rift have hybrid semantic stores from the official wiki; ModLoader is still L0-only convert_mapping / decompilation the in-repo verification tables remain the authority; not ingested → PLATFORM_SKIPPED. With your own jar use ingest_loader_api (dryRun by default)
Bedrock search_bedrock_docs (carries docsStatus) no Java query_api validate_addon_manifest / validate_bp_json, not validate_project
Paper / Paper API / Spigot (server-side) search_docs({platform:"paper"}) for the tutorial body (data/paper_stable/paper-docs/, 67 pages); {platform:"paper-api"} for the Paper API signature face (current pack paper-api_stable, 2116 classes, including Paper-only classes such as io.papermc.paper.*; history ×5); {platform:"spigot"} for the Bukkit/Spigot signature face (current pack spigot_stable, 1396 classes; history ×8). Version keys: all three platforms have the current-pack pseudo-version stable; paper-api also has 5 real MC versions, and spigot 8 more no Java query_api — plugins target the Bukkit abstraction layer and normal plugin code never touches net.minecraft.*; the per-version javap rewrite tables have zero applicability to the plugin side the real upstream version strings are in each page's asOfVersion (Paper 26.3.build.178-stable / Spigot 26.3-R0.1-SNAPSHOT). All signature packs have semantic stores (semantic/db.sqlite beside each pack, semantic: true); but signature pages only carry signature lines, so 0 body-term hits ≠ the API does not exist — for class / member lookups the L0 index fields of search_docs are steadier
  1. Query with a class name or a short term (Block, class:RegistryEvent). On failure, shorten the query or switch to search_docs; do not read a crash or an empty result as "this version has no docs".
  2. After editing mcp-server source: run npm run build, then reload MCP in the host. A running process in Cursor will not swap to the new dist/ by itself; use node mcp-server/dist/cli.js to verify immediately.

Tool pitfalls (measured, same class of problem)

These are not "the class does not exist in the game" but a wrong index / lookup, or stale docs:

Symptom What is actually happening What the agent should do
search_*_docs with constructor throws abbr is not iterable ABBREV_EXPAND[query] hits Object.prototype.constructor already changed to Object.hasOwn / ownGet. If MCP still crashes → reload the service
get_version_info({version:"constructor"}) returns undefined。注册流程:DeferredRegister… VERSION_DB["constructor"] is a Function an unknown version must report forgeVersion=unknown; never apply the 1.20 registration flow
get_migration_guide({route:"constructor"}) returns found:true free-string lookup in MIGRATION_GUIDES[key] hits a Function now ownGet; it must return found:false
get_workflow_template({name:"constructor"}) the MCP schema makes the workflow name an enum (Zod rejects it directly); the function layer still needs ownGet do not read a validation failure as "there is no workflow system"
query_api on 1.12.2 Block returns found:true 3344 class names, 3256 of which have members (func_/field_ obfuscated names, no parameter names/javadoc) read warning / notes; switch to search_forge_docs / query_loader_api
generate_datagen with platform=forge version=1.12.2 emits Java 1.12.2 has no DataGen; the old template even emitted 1.21's ResourceLocation.fromNamespaceAndPath Forge 1.20.1 (Consumer<FinishedRecipe>) and 1.20.4 (recipe only, buildRecipes(RecipeOutput)); NeoForge 1.20.1 → use search_neoforge_docs, 1.20.4/1.20.6 recipe only, 1.21.x and 26.1; Fabric 1.21.1/1.21.3/1.21.4/1.21.8/1.21.10/1.21.11 and 26.1 (no 1.21.5); Quilt has none (switch to search_docs platform=quilt + write it by hand over the Fabric overlay); other versions return an error
get_version_info 1.12.2 action=register still teaches DeferredRegister gotchas says "unsupported" but the recommendation forcibly appends the 1.20 flow 1.12.2 registration is RegistryEvent.Register<T>
search_loader_api returns empty for Fabric 1.14.4 etc. docs used to say maven 404 / LOADER_API_NOT_INDEXED trust mode=list; skipped-ingest.json's mavenNotIndexed is now an empty array
docs return semantic: false or a warning containing stale deliberately L0-only (ModLoader's three versions only), or sqlite lags behind processed/ read that query's JSON, not just get_server_status.semanticIndex.modeHint

This class of lookup always goes through ownGet (mcp-server/src/utils/own-record.ts); never write record[userString].

Rule pack loading (activate_platform_pack)

The forge/<ver>/.cursor tree in the knowledge base is not picked up by the IDE of a user's mod project. During coding, use MCP to deliver that version into the current conversation; do not copy the rules into the MC_skill repo root.

action What it does
list the platforms / versions already indexed
session writes nothing, does not depend on a project root. Returns that version's AGENTS.md, the rule bodies, and a Skill index (name / description / relPosix / absPath). By default only rules 00 / 01 / 09 are injected; topics and task are added to that base (union, never a replacement); skillNames and the names suggested by task are deduplicated and injected as skillBodies (8 entries max in total). topics never injects Skill bodies. Library Skills do not go into nextReads; only an explicit skillNames injects library bodies. includeAllRules=true pours in the full text of rules 00–10. ok=true with a "base only" warning means the pack is usable but the rules were not extended for the task (rulesMode=base, with a next object). If the pack exists but the 00/01/09 files are missing → ok:false + PACK_INCOMPLETE (not PACK_NOT_FOUND). Library Skills are still read from knowledge/libs/.
write writes into the user's mod project IDE directories. hosts is required (cursor / claude / … / dsh / all). DryRun by default. Do not use includeSkills any more; use writeSkillStubs instead (when neither is passed the default is true, which writes stubs pointing the agent at the knowledge-base path, not the full Skill text). includeSkillBodies writes full bodies. The target must not be this knowledge base (the entire repo tree is rejected, including version subdirectories). Breaking change: when MC_SKILL_PROJECT_ROOT is set it is a hard boundary — projectPath must fall inside it or the call is rejected (PATH_OUTSIDE_ALLOWLIST, with breakingChange: true and allowRoot in the response); before this, projectPath could override the env. Migration: point the env at a directory that contains the target project, or use a projectPath inside it.
deactivate removes what was written, per the manifest

You cannot toggle Cursor's / Claude's Skill scanner. Reloading MCP will not make entries appear in the settings page.

Tool boundaries

Doc vector search cannot replace Vanilla method signatures. When the index is missing, keep found:false / an empty result plus an explanation,

Situation What it looks like What the agent should use instead
query_api / get_method_params on MC 26.1+ that version's extracted data has 0 classes (no Parchment api-index) search_neoforge_docs (must pass version, run list_neoforge_versions first) / search_fabric_docs (run list_fabric_versions first, e.g. 26.1.2); or get_minecraft_source / decompilation. The mapping layer returns UNOBFUSCATED_NO_YARN
api-index.json on Forge 1.14.4 / 1.15.2 derived from MCPConfig joined.tsrg (4,976 / 5,137 classes), not a placeholder {}. Both class and member names are SRG (net/minecraft/item/Item + func_77658_a), with no parameter names or javadoc (Parchment only exists from about 1.16.5) for parameter names/javadoc switch to version=1.16.5+; within this version query by that version's SRG name, not the 1.17+ world/item/Item
Fabric 26.1.2 only fabric-docs (few pages), no fabric-wiki keep source at the default fabric-docs; do not pass off 1.21.x wiki as 26.1.2
Forge 1.12.2 list_forge_versions includes 1.12.2; there is a forge-docs tutorial tree. query_api yields SRG class names with func_/field_ member names (not a readable signature) search_forge_docs / search_docs({platform:"forge", version:"1.12.2"}) → get_forge_doc_full. For Forge classes use query_loader_api. Never treat func_/field_ names as a full signature
Forge 1.7.10–1.11.2 1.7.10 has a javadoc verification table plus short 00/01/09; other versions land on Javadoc class names with semantic: false treat it as a class-name index; search_forge_docs version=1.7.10 / search_docs({platform:"forge"}). Do not substitute the 1.12.2 / 1.20.1 rules, and do not pretend to pin a 1.7.10 MDK
diagnose_gradle / validate_project ForgeGradle + Loom + Neo/MDG; Rift / BaseMod / Bedrock still bail out early. validate_project does real checks for Fabric/Quilt/NeoForge (passed/failed); LiteLoader/Rift/ModLoader/Bedrock are skipped. Bedrock → validate_addon_manifest the Java scan limit defaults to 300 and can be raised with MC_SKILL_JAVA_SCAN_MAX_FILES (exceeding it produces a warning saying the check may be incomplete)
get_server_status.updateHint says an update is available the check cache may be stale trust mc_skill_update action=check; if git describe is already ahead of the Release there is no need to apply

Agents must not read "the tool returned empty / found:false / warning" as "it does not exist in the game or the docs", and must not query the wrong platform's tools and force an answer. For reference:

Misreading The actual boundary
query_api can look up DeferredRegister / Fabric API It cannot. It only holds Vanilla Parchment extracted data (roughly 1.16.5–1.20.4). Platform APIs → query_loader_api (platform + minecraftVersion required) or the matching search_*_docs
query_api can look up a Forge 1.12.2 Block constructor Not as javadoc. That version has no Parchment method entries, only SRG class names with func_/field_ member names. Switch to search_forge_docs / query_loader_api / convert_mapping
search_forge_docs erroring or returning empty = that version has no docs run list_forge_versions first. 1.12.2 does have a tutorial tree. The query term constructor used to crash on a prototype key; that is fixed, and if it still crashes, reload MCP. On failure, shorten the query or use search_docs({platform:"forge"})
query_api found:false = the class does not exist the index lacks that class, the short name is ambiguous (Handler will not match MouseHandler), or action.code=DATA_UNAVAILABLE (no extracted data for that version / the worker is not ready). 26.1+ holds 0 classes; 1.7.10–1.15.2 have an SRG class-name index (member names are func_/field_ obfuscated names; on 1.14.4/1.15.2 the class names are also that version's SRG paths). Switch to doc search or get_minecraft_source
get_method_params covers all MC versions it shares query_api's data source, so the boundaries are the same
get_version_info works for Fabric/NeoForge Forge only
diagnose_gradle can fix Loom / NeoGradle it covers ForgeGradle + Loom + NeoGradle/MDG; Rift / BaseMod / Bedrock still bail out early. The liteloader plugin takes the lightweight path
validate_project can check fabric.mod.json Fabric/Quilt/NeoForge are really checked; LiteLoader/Rift/ModLoader/Bedrock remain skipped. Use validate_addon_manifest for Bedrock
query_registry can look up a mod's registry names it only covers vanilla minecraft: resource IDs
an empty doc search = the data pack is broken it may be L0 degradation, wrong tags, or no wiki for that version. Check semantic / warning
using a website URL as the id for get_*_doc_full you must use the id from the search result
search_community_docs can stand in for official APIs It cannot. links entries do not fetch the page body
port_project will modify the user's project dryRun by default; a real write needs confirmed + MC_SKILL_ALLOW_WRITE + a path inside MC_SKILL_PROJECT_ROOT
workflows / MCP not running Gradle, not copying jars, not uploading = a missing unattended pipeline this is human-in-the-loop by design. Creativity, performance, and debugging are the user's calls; compatibility trade-offs and API choices may be delegated but must be explained with the "explanation template"; high-risk actions need confirmation first
analyze_porting_path gives a porting path for any folder a non-mod directory → NOT_A_MOD_PROJECT; LiteLoader / Rift / ModLoader / Bedrock → UNSUPPORTED_PORT
generate_* / generate_datagen will write files by default they only return a text skeleton plus suggestedPath. An optional write needs write=true + confirmed=true + MC_SKILL_ALLOW_WRITE=1 + an absolute MC_SKILL_PROJECT_ROOT; the path must be relative to the project root and free of ..; if any condition is missing you get text only, never a silent write. Three-state semantics: not passing write = dry-run (text only, always ok:true, resultKind:"ok", and ok promises nothing about writing); generation failure (e.g. unsupported version/platform) ⇒ ok:false + resultKind:"generation_failed" (reason in errors[]); skeleton produced but the write did not complete (missing confirmed, or the sandbox refused) ⇒ ok:false + resultKind:"write_blocked" (CLI success:false + exit 1, nothing written, the text preview stays in result, and the fine-grained reason is in writeError.code: CONFIRMATION_REQUIRED / PROJECT_ROOT_REQUIRED / PATH_OUTSIDE_ALLOWLIST / NOTHING_TO_WRITE / WRITE_FAILED). platform/loader and version (for datagen/config/capability/renderer) are required; defaulting to forge is forbidden. datagen: Forge 1.20.1 and 1.20.4 (1.20.4 recipe only), NeoForge 1.20.4/1.20.6 (recipe only)/1.21.x/26.1, Fabric 1.21.1/1.21.3/1.21.4/1.21.8/1.21.10/1.21.11 and 26.1 (no 1.21.5); Quilt has no generate_datagen (switch to search_docs platform=quilt); other Forge versions (including 1.12.2) error out. generate_capability: forge=Capability; neoforge 1.20.1 uses the same Capability shape and 1.20.4+ uses Attachment; fabric/quilt → error, switch to CCA
localize_mod translates to Chinese automatically there is no machine translation, it only marks needsTranslation
check_dependencies = a full Gradle resolution heuristics + the library catalog; libraries it does not know about will be missed
mixin_analyze deep:true downloads the MC jar it does not. Not cached → CACHE_MISS, run get_minecraft_source first
search_mod_code can search any jar you must run decompile_mod_jar first (or already have a decompiled directory): a jar that exists but was never decompiled ⇒ NOT_DECOMPILED, a missing jar ⇒ NOT_FOUND; neither means "no hits"
analyze_mod_jar returns method bodies it only parses metadata (toml/json/mixin lists); it does not decompile
convert_mapping / lookup_obfuscated work on 26.1 they return UNOBFUSCATED_NO_YARN (already deobfuscated)
validate_datapack_json covers every pack_format it is a trimmed schema, leaning towards 1.20.1 / 1.21.1
get_*_doc_full can pull many pages at once at most 2 pages, to avoid context overflow
updateHint.available = you must update the cache may be stale; run mc_skill_update check first
missing 26.2 / 26.1.2 wiki → copy a neighbouring version cloning to impersonate a version is forbidden
DOC_NOT_FOUND / an empty rule tree → copy a neighbouring version's API forbidden. Keep the unverified stub; this is not an oversight

Order of preference when writing a mod: platform rules (AGENTS.md) → search_*_docs (platform APIs) → query_api (only indexed Vanilla) → decompilation (when you really need source). Do not run query_api backwards to guess Forge event names.

Tool and network boundaries (boundaries only, no conclusions)

The two items below cannot be verified locally against the upstream itself (only the channel can be verified — see the table further down). What is registered here is "what must not be inferred", not "verified as no".

Boundary How far it was verified Inference that is forbidden
Public-internet reachability can only be verified at the level of this machine's channel; it is not a "reachable / not reachable" boolean the pinned commit of download_official_mdk, the Releases used by mc_skill_update, and the short example-mod commit hashes pinned in the rules / AGENTS can only be re-verified on a reachable network. Measured: Node fetch returns TLS_VERIFY_FAILED for both raw.githubusercontent.com and services.gradle.org (same ledger: $MC_SKILL_CACHE/loader-api-summaries/fetch-qsl-last.json); the same URL via curl.exe --ssl-no-revoke GET = 200 (719 B / 0.1s), and services.gradle.org/distributions/… = 307; a single git/trees?recursive=1 call to api.github.com timed out at 12s (not re-measured) "this machine cannot fetch it" ≠ "the upstream does not exist / the checksum is wrong / that commit is fake"; and TLS-class failures must not be recorded as NOT_FOUND or "version missing". Keep such entries marked "unverified", switch networks or ask the user to re-verify locally, and do not replace them with another set of guessed values
Bedrock description.identifier and other namespaced IDs: length limits and character set Microsoft Learn only says the ID must be namespaced and gives no length limit or allowed character set; the community only offers advice such as "lowercase, no spaces or special characters" and "path length is bounded by the host" do not treat advice as a hard limit, and do not assert "unrestricted" just because Learn is silent. validate_addon_manifest / validate_bp_json do not error on length or character set; when generating IDs take a conservative form per the advice and say that it is a convention, not an official constraint

Fetch channel matrix (when writing maintenance scripts, pick a leg from this table; do not copy "this machine has no network"):

Leg Measured locally Usage
Node fetch (github / gradle / maven domains) always TLS_VERIFY_FAILED must not be the primary leg; a failure must be classified as TLS-class, kept separate from 404 / rate limiting
curl.exe --ssl-no-revoke GET 200 / 307 (the only stable leg on this machine) the primary leg on win32. A cold first attempt may time out (measured once at 15s with zero bytes), so it must carry backoff retries
curl.exe --head the same URL returned both 502 and 200 across rounds never use HEAD to decide reachability; probe with GET
api.github.com git/trees?recursive=1 timed out in one round re-verify it on its own before relying on it; do not assume it shares the fate of raw

scripts/_lib/fetch-with-ua.mjs encodes this table: downloadWithFallback({ preferCurl: process.platform === "win32" }), where the curl leg always carries --ssl-no-revoke + a UA and the fetch leg always carries AbortSignal.timeout() + a UA; the failure categories in FETCH_FAILURE (TLS_VERIFY_FAILED / TLS_REVOCATION_CHECK_FAILED / TLS_HANDSHAKE_FAILED / RATE_LIMITED / NOT_FOUND) are never mixed.

Mapping conversion (convert_mapping + Yarn)

  1. It uses the prebuilt yarn-mappings.sqlite (current-batch schema v4, with fields; v2/v3 stores still readable) and does lazy point lookups; loading the whole yarn-mappings.json at runtime is forbidden.
  2. Support matrix (summary):
Version range Data source / era Class ↔ class Method ↔ method Field ↔ field Notes
1.16+ (with Fabric tiny) yarn-tiny ✅ ✅ needs ownerClass; for overloads prefer descriptor ✅ memberKind=field to=mojang = the short Tiny official name
1.13 Forge tsrg + MCP CSV ✅ ✅ may carry ownerClass ✅ + fields.csv joined.tsrg + CSV
1.7–1.12 Forge forge-srg + MCP CSV ✅ ✅ may carry ownerClass ✅ + fields.csv joined.srg + CSV
1.14–1.15 mcp-csv (partial) ❌ only the global searge↔named global field_* only do not pass ownerClass
  1. mcp↔parchment is an identity layer; use get_method_params for parameter names.
  2. obfuscated / intermediary layer (T5): obfuscated = the short Tiny official obfuscated name (er), intermediary = classes like method_6032; yarn/mcp→obfuscated has the same value as to=mojang, and obfuscated/intermediary→yarn/mcp supports ownerClass-free global reverse lookup (single tokens from crash logs). to=mojang keeps the old behaviour and the notes point you at to=obfuscated instead. 26.1+ has no obfuscation layer: obfuscated/intermediary requests return UNOBFUSCATED_NO_YARN (available only for 1.14–1.21.11).
  3. Field lookups: pass memberKind: "field" (with "auto" the naming style is inferred); passing ownerClass is recommended; 1.14–1.15 only has the global field_*/searge↔named. While the schema is still v2 it returns SCHEMA_FIELDS_UNAVAILABLE(the sqlite must be rebuilt). CLI:node mcp-server/dist/cli.js convert --kind field ...`.
  4. Failures default to found:false and converted:null; the transitional parameter allow_fallback can return the original name with fallbackUsed set (a fake success is forbidden).
  5. Build: cd mcp-server && npm run build:yarn-sqlite (writes to a local temp first and then copies, to avoid drive-letter I/O problems).
  6. from=mojang (looking things up by readable mojmap name) has two tiers of sources: the first tier is the official column in the table above, and for obfuscated classes that column holds the short Tiny obfuscated name — only the few classes that were never obfuscated carry a readable full path (under 1% readable paths, e.g. com/mojang/blaze3d/…) ⇒ looking up readable names like Container / Level will always give found:false, and that does not mean the class is missing in that version (the miss receipt states this). The second tier is the derived comparison table data/_yarn-mojmap-pairs/ (class-level obf / mojmap / yarn plus FQCNs on both sides, no intermediary column); it participates only when from=mojang and to is yarn / obfuscated, and a hit carries fallbackUsed:true while the notes name the table and its row count; to=intermediary is rejected outright and does not fall back to the first tier.

Workflow templates and knowledge resources (Prompts / Resources + tool fallback)

Cursor's main path is tools; the protocol layer still registers Prompts/Resources, and the tool fallback guarantees the same body text stays readable:

Capability Tool Notes
Workflow get_workflow_template The authoritative list is the one returned by get_workflow_template (including mc-new-block / mc-new-item / mc-new-blockentity / mc-mixin / mc-worldgen / mc-config / mc-gametest / mc-setup-env / mc-publish, same names as the Prompts); the orchestration skills mc-grill / mc-handoff / mc-router / mc-review / mc-spec / mc-retro / mc-breakdown / mc-wizard / mc-research / mc-glossary / mc-waitwhat / mc-prototype live in common_skill/ at the repo root (plain-doc treatment, outside the gated managed surfaces)
Knowledge list list_knowledge_resources lists the mcskill:// URIs
Knowledge read read_knowledge_resource reads the body for a URI

Common URIs: mcskill://patterns/README (→ community_knowledge/patterns/README.md), mcskill://schema/sqlite?version=<exact MC> (the bare URI is rejected), mcskill://matrix/mixin-support, mcskill://version-changes/1.21, mcskill://antipatterns/registry, mcskill://workflow/<template name>, mcskill://community/<authored-id>, mcskill://skill/<name> (reads the common_skill/ source bodies; the live list = the skill- prefixed entries of list_knowledge_resources, registered from disk).

Porting analysis (analyze_porting_path)

Platform detection combines source code with build and metadata files (build.gradle, mods.toml, fabric.mod.json, and so on). An empty directory, or one with neither build nor metadata → ok:false + NOT_A_MOD_PROJECT (not platform: unknown).

Output contract: targetPlatform is required (if unspecified → INVALID_INPUT, no silent default); routeSteps is always a human-readable string[]; the machine-readable hand-off is the parallel nextSteps[], each item { text, tool?, args? }, where tool + args must be directly callable (required parameters present, no placeholders) — if that cannot be satisfied, only text is given. port_project continues from nextSteps.

Write operations (port_project)

Read-only by default. A real write requires both MC_SKILL_ALLOW_WRITE=1 and MC_SKILL_PROJECT_ROOT=<the project root allowed for writes>, and the target path must fall under that root.

Data reproduction and distribution

The indexes and text under data/ are generated by mcp-server/scripts/. Large *.jar / *.zip files are excluded by .gitignore by default (with exception rules under data/**), so do not assume Git holds every binary.

  • Only rebuild data from the official sources the scripts declare.
  • Run cd mcp-server && npm run audit:data; any ERROR means the data pack is not fit for publishing.
  • The full data pack can be distributed through the GitHub Release assets mc-skill-data-full-*.zip + SHA256SUMS-*.txt + data-manifest.json.
  • If a local original package is lost, re-fetch it; never copy across versions and rename it.

Directory conventions

  • Platforms are split by platform/version/ (e.g. forge/1.20.1/, fabric/1.20.1/)
  • Rule files live in .cursor/rules/, numbered 00~10
  • Every rule contains constraints and a Decision Flow

Rule files

File Topic Notes
00-project-setup.mdc Project structure Java / Gradle / version numbers
01-registry.mdc Registries how to register, by version
02-block.mdc Blocks blocks / block entities / fluids
03-item.mdc Items items / tools / armor / food
04-entity.mdc Entities EntityType / Renderer / Goal
05-events.mdc Events picking the event class by scenario
06-networking.mdc Networking sync need → packet type
07-datagen.mdc DataGen choosing a Provider
08-client-server.mdc Client/server split which side the code goes on
09-anti-patterns.mdc Anti-patterns symptoms and the correct approach
10-gui.mdc GUI Menu / Screen / Container

Agent Skills

Path example: forge/1.20.1/.agents/skills/<name>/. Each version carries 8 host mirrors: .agents / .claude / .continue / .cursor / .opencode / .pi / .trae / .zcode (DSH shares .agents/skills with Codex and gets no separate directory; sync-skills.ps1 refreshes all of them at once). The Wave D skills were once synced with scripts/_oneoff/propagate-wave-d-skills.mjs (one-off, do not run again); for daily mirroring use scripts/sync-skills.ps1 -All.

Library Skills (mc-config / mc-geckolib / mc-curios / mc-patchouli, etc.) are not written to disk: the sources are in the root knowledge/libs/<group>/mc-<name>/SKILL.md (all-platforms / fabric-only / neo-only / forge-only / bedrock-only) and are used per the "library Skill" resolution rules in AGENTS.md; propagate-wave-d-skills.mjs and the platform .cursor/skills no longer contain library entries. Current library source file counts and unique skillId counts: read knowledge/libs/README.md §current scale (same measure there: files = the number of mc-*/SKILL.md per group; unique skillIds deduplicated by directory name / frontmatter name:, the difference coming from the mc-curios / mc-kotlin-for-forge dual-group mirrors). Consistent with the "② library Skill sources" row in §7.5 of this file.

Platform/version Count Structure Notes
forge/1.12.2–1.20.4 main versions 35 directories (one directory per skill) 15 core + 19 Wave D + mc-events (1.7.10 is an honest stub)
forge/1.15.2 / forge/1.17.1 35 / 35 directories 1.17.1 has mc-events and no mc-capability (a different set from 1.20.1)
forge/1.7.10 3 rules + 3 skills directories only 00/01/09 + mc-item / mc-registry / mc-events (stub: no rule 05, and the event API is unverified so nothing may be generated)
forge/1.8.9 · 1.9.4 · 1.10.2 · 1.11.2 3 rules + 0 skills rules/ only each of the four has 00/01/09, and .cursor/skills does not exist ⇒ 0 skills is by design (a short rule tree exists only to gate "do not copy modern APIs into early versions"), not an oversight. Measured (counting *.mdc in readdir <pack>/.cursor/rules, counting entries in .cursor/skills); substituting the 00–10 rules or the 35 skills of 1.12.2 is forbidden
forge/1.21.1 0 rules + 0 skills (draft) only AGENTS.md + pack.meta.json that directory has no .cursor/ at all ⇒ a session always returns PACK_NOT_FOUND, and it is not in list_forge_versions. Registered as by design; cloning a new tree to fill in a version number is forbidden, and so is standing in a NeoForge 1.21.1 or Forge 1.20.4 tree
fabric/* (15 versions, identical skeleton counts; 26.1.2 / 26.2 are Mojmap) 38 .md files (thin versions / 26.1.2 / 26.2 use a directory layout) 18 base per version (including mc-fabric-api / mc-kotlin / mc-cloth-config) + 19 Wave D + mc-events (including 1.21.3 and 26.1.2; 26.1.2 / 26.2 are Mojmap, Yarn is forbidden). The thin versions 1.21.4 / 1.21.8 / 1.21.10 have exactly the same counts — 11 rules + 38 skills — as the other 12 versions (measured (counting *.mdc in readdir <pack>/.cursor/rules, counting entries in .cursor/skills): all 15 fabric versions are 11/38, no exceptions), "thin" refers to the corpus, not the skeleton: those three versions scan 2 files under knowledge/ in reality (that version's common/verified-api-<ver>.md plus the version-changes/1.21.x.md shared by the three; the "1 file" in pack.meta.json counts only the version's own common/ page), while the 7 versions that have code-patterns/ have 12–13 files (also measured), and the thin versions do not ship code-patterns/. The status:"ready" in pack.meta.json does not contradict this self-description — the criterion is what is measured on disk, not what this sentence claims (the ruling "a thin pack is a declaration")
neoforge/<ver> session index follows the version directory directories the root neoforge/.agents/skills is not the session source; main and thin versions (1.20.6 / 1.21.5 / 1.21.10) have the same named skill set within the version (entity/datagen, etc.), no longer 6. neoforge/1.20.1 has only mc-registry in this version; the rest goes through the Forge 1.20.1 overlay
quilt/<ver> on-disk (rules 4 + skills 3) 3 directories only the QSL deltas mc-registry / mc-events / mc-networking; entity/gui and the rest continue over the Fabric overlay and are not counted in this version's on-disk numbers. Rules measured (counting *.mdc in readdir <pack>/.cursor/rules, counting entries in .cursor/skills): all 10 versions have exactly 4 rules (00-project-setup / 01-registry / 05-events / 06-networking), not the full 00–10 set; other topics read the same-version Fabric overlay
liteloader/<ver> (1.8.9 / 1.10.2 / 1.12.2) 3 directories mc-events / mc-gui / mc-networking (LiteLoader-specific wording, not Forge APIs)
rift/1.13.2 3 directories mc-events / mc-gui / mc-networking
modloader/1.6.4; modloader/1.2.5, 1.5.2 2; 1 directories 1.6.4: mc-item + mc-registry; the others only have mc-registry (emitting anything outside the safe-api table is forbidden)
bedrock 10 directories (×8 host mirrors) Script API / manifest / resource and behaviour packs, see bedrock/.cursor/skills/; no version pinning, live docsStatus
Category Skills
Core mc-registry, mc-block, mc-item, mc-blockentity, mc-entity, mc-mixin, mc-networking, mc-datagen, mc-capability, mc-gui
Content mc-fluid, mc-particle, mc-sound, mc-recipe, mc-enchantment, mc-potion, mc-effect, mc-command, mc-villager, mc-ai
Rendering / models mc-renderer, mc-model
World / data packs mc-worldgen, mc-structure, mc-advancement, mc-loottable, mc-datapack, mc-resourcepack, mc-dimension, mc-weather
Config / testing / energy mc-gametest, mc-energy, mc-multiblock
Compatibility / doc libraries mc-compat-jei (knowledge/libs source plus platform-owned copies in forge/1.20.1 and neoforge/26.1, not mirrors); library skills (mc-config / mc-cloth-config / mc-yacl / mc-geckolib / mc-architectury / mc-terrablender / mc-playeranimator / mc-pehkui / mc-kubejs / mc-balm / mc-modern-ui / mc-patchouli / mc-owo / mc-curios / mc-kotlin-for-forge / mc-trinkets / mc-cca / mc-polymer / mc-text-placeholder / mc-satin / mc-fabric-language-kotlin / mc-libgui / mc-lib-catalog / mc-author-shared-libs / mc-resourceful-lib / mc-moonlight-lib / mc-caelus / mc-spruceui / mc-player-ability-lib / mc-server-translations / mc-impersonate / mc-script-ui / mc-script-server ; file counts / the unique skillId measure: read knowledge/libs/README.md §current scale → knowledge/libs)

Fabric additionally has mc-fabric-api, mc-kotlin, mc-cloth-config; Forge 1.12.2–1.20.4 and the Fabric main versions all have mc-events (the thin versions backfilled through FABRIC_SKILL_DONORS carry a DONOR_SKILL banner). Code pattern samples live in community_knowledge/patterns/ (also readable via mcskill://patterns/README).

Textures and models

Modeling and texturing sit outside the MCP tool surface. Model JSON skeletons come from generate_model; textures go through the mc-texture skill.

Division of labour

Step What to use What this repo provides
Block models / blockstates / item items/ generate_model (requires version) cube and item/generated skeletons
Models with real shape, Bedrock .geo.json, GeckoLib animation External Blockbench MCP Placement rules (geo/, animations/, textures/)
Texture painting / texture animation / particle FX mc-texture Full procedure plus three zero-dependency scripts
Canvases above 32 px, character sprites pixel-art-upstream Upstream methodology plus grid.py
Reference integrity audit_resources Does not check pack_format

The model MCP is a GPL-3.0 standalone program, installed as an external tool and reached over MCP: https://github.com/jasonjgardner/blockbench-mcp-plugin

Skill entry

read_knowledge_resource uri=mcskill://skill/mc-texture; source in common_skill/mc-texture/SKILL.md. The warning from activate_platform_pack task=mc-texture points at both it and pixel-art-upstream.

Procedure: pick size → pick style → pick palette → layer the art → render → check at 1× → revise (≥3 rounds). A style, color budget or size given by the user outranks vanilla convention; otherwise use 16×16, tileable, 4–8 colors, light from the upper left. Layer order is flat silhouette → light → interior detail → outline → features.

Materials follow in-game states: copper has four oxidation stages (unoxidized / exposed / weathered / oxidized), with green spreading from the edges and inverting to teal at the last stage, and four texture sets are made together. Wood separates into log / stripped / planks, stone into stone / cobblestone / stone bricks, and metal uses highlight blocks rather than noise. Basis: the Minecraft Wiki "Oxidation" article and the corpus under data/.

Texture animation

A vertical frame strip plus a sibling .png.mcmeta (the file name keeps the .png). Fields frametime / interpolate / frames / width·height, defaulting to 1 / false / all frames in order / inferred from the shorter side. The atlas height must divide by the frame height; frames: [0,1,2,1] gives a back-and-forth loop.

Multiple frames go through the atlas mode of render-pixels.mjs: one grid file per frame, rendering a vertical PNG and writing the mcmeta in one pass. Preview with gif.mjs; frame-by-frame checking still reads the PNG atlas.

Particle effects

Computed per frame by rule: split into elements → seed the randomness → integrate with a fixed step → color by distance travelled. Structural patterns (faces, logos, text) use a raster; natural spread (balls, sparks) uses particles.

A firework shape has five legal values — small_ball / large_ball / star / creeper / burst (default small_ball) — plus trail and flicker. Source: data/neoforge_*/…/resources_server_loottables_lootfunctions.md.

Scripts

Three zero-dependency scripts; PNG and GIF are written over node:zlib.

Script Purpose Pre-write validation
render-pixels.mjs palette + pixel grid to a 1× PNG; with multiple files, stacks a vertical atlas and writes the mcmeta ragged rows, undefined color keys, size mismatch; warns on isolated pixels and semi-transparency
firework.mjs five-shape firework atlas + mcmeta argument validity, trailing empty frames trimmed
gif.mjs vertical atlas to GIF preview GIF89a structure
# single texture
node common_skill/mc-texture/tools/render-pixels.mjs sprite.txt --out out.png --size 16x16 --scale 16

# texture animation: stack frames into a vertical atlas and write the .png.mcmeta
node common_skill/mc-texture/tools/render-pixels.mjs f0.txt f1.txt f2.txt --atlas out/anim.png --frametime 3

# firework effects
node common_skill/mc-texture/tools/firework.mjs temp/firework --shape star --fps 12 --size 32 --trail --flicker

# GIF preview
node common_skill/mc-texture/tools/gif.mjs temp/firework/firework.png out.gif --delayCs 8 --scale 6

MCP/CLI TOOLS:89

Service name: MC-AI-Coding-Assistant-Tool.

Recommended general flow:

  1. diagnose_data_paths / list_*_versions / get_server_status to confirm data and versions
  2. Docs: search_* → get_*_summary → get_*_full (never load more than 2 full pages at once; the id must come from a search result)
  3. Platform APIs via query_loader_api / search_loader_api or search_*_docs; Vanilla signatures only via query_api / get_method_params (roughly 1.16.5–1.20.4; 1.12.2 is a class-name empty shell; 26.1+ has no index). Rule trees via activate_platform_pack action=session (00/01/09 + a Skill index by default, see "Rule pack loading" above)
  4. Mappings: convert_mapping / lookup_obfuscated (26.1+ has no obfuscation layer)
  5. Project work: diagnose_gradle / validate_project / generate_datagen / crash_analyze / analyze_build_log / inspect_runtime (log-based). Run the matching checks for Forge/Fabric/Quilt/NeoForge; validate_project remains skipped for LiteLoader/Rift/Bedrock
  6. Porting: analyze_porting_path → (after confirmation) port_project (dryRun by default)
  7. Community / library mods: for practice and library selection → search_community_docs (lib-* / library-catalog-2026; follow AGENT_USAGE.md) → read knowledge/libs/.../SKILL.md (start with mc-lib-catalog); check_dependencies shows detectedLibraries
  8. Workflows / knowledge: get_workflow_template / list_knowledge_resources → read_knowledge_resource

For tool limits and misreadings, see "Tool boundaries" above.


1. API, mappings, and status (6)

Tool What it does
query_api Looks up method signatures, parameter names, return types, and javadoc for Vanilla/Parchment classes (loads the extracted index by version, version required, defaulting to 1.20.1 is forbidden). It does not contain Forge-specific classes. Versions with an index = 1.7.10–1.20.4. On 1.7.10–1.15.2 you get SRG names (the class name is that version's SRG path, members are func_/field_) without parameter names or javadoc; 1.16.5–1.20.4 use Parchment; 26.1+ have no usable method index. found:true requires an exact FQCN or a unique simple name (e.g. Item), and rewrites carry autoCorrected; ambiguous substrings such as Handler return found:false plus suggestions. Use query_loader_api for platform loader APIs.
get_method_params Full parameter-name list for a class + method (an optional JNI descriptor distinguishes overloads). With several overloads and no descriptor → found:false + ambiguous + candidates. 26.1+ has no index → DATA_UNAVAILABLE.
convert_mapping Converts classes / methods / fields between mojang / mcp / yarn / parchment / obfuscated / intermediary (SQLite v4). memberKind=field; to=mojang gives the short Tiny official name (the same layer as obfuscated); failures default to converted:null (allow_fallback is optional). The six layers are not available on every version: yarn-tiny versions (fabric 1.14.4–1.21.x) have no MCP/Parchment readable layer, so to=mcp / to=parchment is rejected outright → YARN_TINY_NO_MCP_LAYER (use to=yarn, or query_api / get_method_params); mcp↔parchment is an identity layer. Batch (S3): pass up to 50 names in memberName separated by commas / semicolons / newlines and get results[] plus batch{requested,found,missing} in one call (over the limit → INVALID_INPUT, no silent truncation; with a single name the output shape is unchanged). Entry lines (S2): accessLines=true attaches paste-ready AT / AW lines, where the name layer forks by loader — Forge member lines must use SRG names, NeoForge uses readable names with glued descriptors, and Fabric/Quilt AW entry names and descriptors must sit in the same mapping layer as the project (the header follows to: named / intermediary / official); a missing name or descriptor ⇒ complete:false and an inline <TODO…>, and complete lines feed back into the same parser used by validate_at / validate_aw (selfCheckOk). The generation surface narrowed: on the AW side only accessible entries are produced; the extendable / mutable / transitive-* parallel forms and the two-operand instructions inject-interface / extend-enum that validate_aw accepts are not generated (validation ⊃ generation — write them by hand when needed). SRG member-layer coverage: the six versions Forge 1.16.5 / 1.17.1 / 1.18.2 / 1.19.4 / 1.20.1 / 1.20.4 now have stores built from the trimmed MCPConfig with mappingEra=mcp-config-srg (named = SRG names: hash-shaped m_/f_ from 1.17 on, the old func_/field_ form on 1.16.5), so Forge AT member lines on those six versions get real names; this store only participates when platform=forge. neoforge_* / quilt_* still have no member store ⇒ still <TODO…>. Two tiers of sources for from=mojang: the first tier is that version's official column, which for obfuscated classes holds short Tiny obfuscated names (a / fac / ccv) — only the few classes that were never obfuscated carry readable full paths (under 1% readable paths) ⇒ looking up a readable mojmap name such as Container / Level will always give found:false, and that must not be read as "the class is missing in that version"; the second tier is the derived comparison table data/_yarn-mojmap-pairs/ (class-level obf / mojmap / yarn plus FQCNs on both sides, no intermediary column), which participates only when from=mojang and to is yarn / obfuscated; hits carry fallbackUsed:true and the notes name the table and its row count, while to=intermediary is rejected outright without falling back to the first tier.
lookup_obfuscated Deobfuscates a single token from a crash log (method_6032 / er / func_110143_aJ / field_100013_f) → a readable Yarn name + ownerClass + descriptor. method → field → class; multiple hits give AMBIGUOUS; 26.1+ returns UNOBFUSCATED_NO_YARN.
get_server_status API index warm-up status, a diagnose_data_paths summary, a descriptor self-check, and updateHint; an optional warmup preloads a given version. It also returns a java probe (node / JAVA_HOME / version / ready / hint, needed by decompilation and remapping). It reports this machine's Java situation only and does not decide Gradle ↔ JDK matching (that is diagnose_gradle).
get_version_info [Forge only] Recommended approach, key changes, gotchas, and the official changelog link for an MC version plus an operation (e.g. "registering a block").

1b. Loader API and platform packages (5)

Tool What it does
query_loader_api Looks up classes and MethodInfo in the Forge / NeoForge / Fabric-API / QSL summaries. platform + minecraftVersion are required; there is no 1.20.1 default. It is not query_api. found:false does not mean the class is absent from the game. LiteLoader/Rift/ModLoader have no summaries → PLATFORM_SKIPPED (you can ingest_loader_api).
search_loader_api Substring search over fqcnIndex (limit defaults to 20, capped at 50 — over the cap it silently clamps instead of erroring). mode=list lists indexed versions / skipped ones / the cache overlay.
ingest_loader_api Extracts summaries from a jar you supply (LiteLoader/Rift/ModLoader, which the project does not download for you), writing only to the $MC_SKILL_CACHE/loader-api-summaries overlay; writing into the repo's data/ is forbidden. jarPath (absolute) + mappingsVersion are required. DryRun by default. Do not use --file. When a platform has several candidate artifacts, use library to pick the key: the candidate keys for platform=fabric are <ver>-fabric-api (the API library) and <ver>-fabric (the loader itself), and the write side used to take the first candidate unconditionally ⇒ passing a fabric-loader jar without library=fabric overwrites that version's API summary; a suffix that is not among the candidates ⇒ INVALID_INPUT listing the candidates, with no guessing and no new key names.
detect_mod_project Read-only detection of a mod project (Quilt is checked before Fabric). projectPath (CLI --project) takes precedence over MC_SKILL_PROJECT_ROOT. The knowledge base root, or a version's scaffold → KNOWLEDGE_REPO_NOT_MOD (Architectury's version-less forge/+fabric/ with no pack.meta.json is not a false positive). No matching rule tree → PACK_NOT_FOUND; a neighbouring version's 00–10 is forbidden.
activate_platform_pack list / session / write / deactivate. A session writes nothing and does not depend on a project root: rules 00/01/09 by default plus a Skill index (topics/task add to the union; skillNames injects bodies, 8 max; see "Rule pack loading" above). write is dryRun by default and hosts is required. Do not use includeSkills any more; use writeSkillStubs (default true, stubs only); includeSkillBodies writes full bodies. The target must be a user's mod project (the knowledge base root is rejected). You cannot toggle an IDE's scanner.

2. Project helpers (7)

Tool What it does
diagnose_gradle Checks build.gradle / gradle.properties: ForgeGradle + Fabric/Quilt Loom + NeoGradle/ModDevGradle. On 26.1, Loom must be net.fabricmc.fabric-loom, Java 25, and modImplementation is forbidden. The liteloader plugin takes the lightweight path. Rift / BaseMod / Bedrock still bail out early.
generate_datagen Emits DataGen Provider templates. Required providerType / modId / targetName / version / platform. Forge 1.20.1 and 1.20.4 (1.20.4 recipe only, buildRecipes(RecipeOutput)), NeoForge 1.20.4/1.20.6 (recipe only)/1.21.x/26.1, Fabric 1.21.1/1.21.3/1.21.4/1.21.8/1.21.10/1.21.11 and 26.1 (no 1.21.5). Quilt has no generate_datagen — switch to search_docs platform=quilt. Other Forge versions return an error.
crash_analyze Parses a full crash report (or reads a file via crashReportPath), infers crashKind (including fml / client / server / fabric / quilt / liteloader / rift / modloader), likely causes, missing prerequisites / version incompatibilities, and logHints. Prefer this over blind web searching; the practice classification can be combined with the community tool.
validate_project Forge: mods.toml / DeferredRegister. Fabric/Quilt: fabric.mod.json / quilt.mod.json + entrypoints. NeoForge: neoforge.mods.toml, @Mod + IEventBus. LiteLoader/Rift/ModLoader/Bedrock are skipped. Broken recipes only produce a warning. The Java scan limit is 300 by default (MC_SKILL_JAVA_SCAN_MAX_FILES).
check_publish_ready Pre-publish checklist: license/version, whether build/libs looks like a real release jar, and it reads the checklist in community_knowledge/authored/publishing.md (missing items only produce warnings). It does not upload and does not call CurseForge/Modrinth APIs.
inspect_runtime Log-based inspector: it prefers logsDir/crashReportsDir, otherwise it probes bounded paths such as run/logs. Whole-disk scans and JVM attach are forbidden. Reads file tails by default.
resolve_lib_skills Resolves the knowledge/libs library skill sources by platform + exact MC version (§3.6: group mapping + platforms/mcVersions filtering); it returns the repo-relative path and a versionsJson ground-truth hint (read the matching MC version slot before writing coordinates for that library). Same core as the CLI's lib resolve; it only resolves and never returns bodies — the AI still reads the source file directly (the file is the usable thing).

3. Forge official docs (5)

Tool What it does
list_forge_versions Lists the Forge doc versions available locally. Returns PLATFORM_DATA_MISSING when there is no data.
search_forge_docs Hybrid search (L0 + semantic RRF; pure L0 when there is no store). version is required (run list_forge_versions first). Equivalent to search_docs({platform:"forge"}). 1.12.2 uses the forge-docs tutorials, not query_api. Supports class: / event: / method: prefixes, | OR, stop-word removal, and tag filtering. Returns page id values for the follow-up tools.
get_forge_doc_summary L1 summary of a single page: the first paragraph plus section headings / short summaries, to decide whether reading the full text is worth it.
get_forge_doc_full Full L2/L2+ text of a single page; highlight_key=true by default highlights the 🔴🟠🟢 key passages. Never load more than 2 full pages at once.
get_forge_doc_related Related pages based on the path skeleton, tags, and section keywords. Returns {ok,id,version,results[]} on success (results is always an array).

4. Fabric official docs (5)

Tool What it does
list_fabric_versions Lists the local Fabric doc versions (a fabric-docs / fabric-wiki version counts when it has an index). No data → PLATFORM_DATA_MISSING.
search_fabric_docs Hybrid search; optional source: fabric-docs (default) / fabric-wiki / all. The wiki leans towards beginners; 26.1.2 has no wiki.
get_fabric_doc_summary L1 summary of a Fabric page (source selectable).
get_fabric_doc_full Full Fabric page text with key-passage highlighting (source selectable).
get_fabric_doc_related Related Fabric pages. Returns {ok,id,version,source,results[]} on success (results is always an array).

5. NeoForge official docs (5)

Tool What it does
list_neoforge_versions Lists the local NeoForge doc versions; the main docs default to 26.1 (the official main docs are not split per version and this repo has no 26.2 / 26.3 corpus ⇒ no cloning to impersonate one); 26.2 / 26.3 have rule trees but are not in this list (doc searches for them fall back with a warning); 1.20.1 can fall back to Forge data.
search_neoforge_docs Hybrid search (DeferredRegister, Data Components, Payload, …); pure L0 when there is no semantic store. You must pass version (run list_neoforge_versions first).
get_neoforge_doc_summary L1 summary of a NeoForge page.
get_neoforge_doc_full Full NeoForge page text with key-passage highlighting.
get_neoforge_doc_related Related NeoForge pages. Returns {ok,id,version,results[]} on success (results is always an array).

6. Cross-platform docs (5)

Mirrors the dedicated tools, behind one entry point taking platform (forge / fabric / neoforge / quilt / liteloader / rift / modloader, required). For Bedrock use search_bedrock_docs (see §6b).

Tool What it does
list_doc_versions Lists the versions available for the given platform (it never returns all three platforms at once).
search_docs Multi-platform hybrid search; source is accepted for Fabric. Pure L0 without a semantic store; PLATFORM_DATA_MISSING when the platform data is missing.
get_doc_summary Multi-platform L1 summary, for deciding whether a page contains what you need. A missing Quilt page falls back to Fabric (fallback=fabric); FAPI-only Registry/ItemGroup pages are rejected (ok=false).
get_doc_full Multi-platform full text. Useful for complete API steps, event lists, and config item lists; highlight_key highlights the 🔴🟠🟢 key passages by default. A missing Quilt page falls back to Fabric; FAPI-only pages are rejected and no Registry body is returned.
get_doc_related Related multi-platform pages, returning the other pages that share the most keywords. On success the root is an object {ok,platform,id,version,results[]}. A Quilt → Fabric fallback carries sourcePlatform:"fabric" / warning at both top level and entry level, and FAPI-only pages are dropped; FAPI-only ids are rejected (ok=false).

6b. Bedrock Add-Ons (9)

Separate from the Java search_*_docs / validate_project. Bedrock uses the Learn documentation and pack JSON — no Yarn, no Mixin, no query_api.

Tool What it does How to read the result Error codes
search_bedrock_docs Searches the Microsoft Learn Bedrock documentation (with a lagging docsStatus). limit may be raised per call (the default measure is unchanged; it only widens the window and does not change ranking or the release-notes demotion, and the difference between the pool size and the widened window is spelled out in demotion / warning). lookup: ok + results[]; empty ≠ the page does not exist — read docsStatus / demotion / warning first —
get_bedrock_doc_summary L1 summary of a Bedrock page. lookup: ok + summary; a missing page goes to ok:false + error —
get_bedrock_doc_full Full text of a Bedrock page. lookup: ok + full text; at most 2 pages at a time —
get_bedrock_doc_related Related Bedrock pages. lookup: ok + array; an empty array is not a failure —
validate_addon_manifest Validates an Add-On manifest.json (header/modules uuid and version). Not validate_project. validator: the verdict is in errors[]; this file records no dedicated three-state name for it, so trust the response's ok / error —
validate_bp_json Validates behaviour pack entity JSON, etc. validator: same as above —
generate_addon_manifest Emits manifest JSON text only, no disk writes. generator: resultKind three states, same as §10 (ok / generation_failed / write_blocked) —
generate_bp_entity Emits behaviour pack entity JSON text only, no disk writes. generator: same as above —
analyze_bedrock_log Triage of the Bedrock content log (content_log.txt). Not the Java crash_analyze. reader: no match ⇒ empty result ≠ no problem —

How to read the result: ok:true = you have a result; ok:false = the tool failed (reason in errors[] / error). For lookup tools, an empty result never means the target does not exist (a missing index, semantic degradation, or a tool boundary is always stated). Generators additionally have the resultKind three states, see §10. A — in the error-code column = this repo records no dedicated error code for that tool; the real error is whatever errors[] / error.code says, and filling it in from memory is forbidden.

7. Community knowledge base (4)

Separate from the official docs and not a replacement for search_*_docs. It suits practice work: publishing, crash classification, soft dependencies, machine GUI, library selection. The index holds 110 entries (authored 95 / links 11 / permitted 4, read live from community_knowledge/indexes/index-l0.json), of which 48 are lib-*.md library-integration notes. Usage rules: community_knowledge/AGENT_USAGE.md; topic id quick reference: community_knowledge/README.md.

Tool What it does
list_community_sources Lists the community_knowledge entries (permitted / authored / links) with source counts.
search_community_docs Searches the community library; hits carry sourceKind, url, summary. For libraries you can search lib-curios, library-catalog-2026, etc.
get_community_doc_summary Summary of a community entry (including attribution); links give metadata + external URL only.
get_community_doc_full permitted/authored return in-repo Markdown; links only give the URL and never fetch the page body.

7.5 Library mod knowledge system (essays + Skills + the data chain)

Three layers covering "what a library mod is → how to use it → where the data comes from":

① Community essays (under community_knowledge/authored/, searchable via search_community_docs)

  • lib-*.md essays, grouped by function: config (Cloth / YACL / Fzzy / owo / MidnightLib…), animation (GeckoLib / playerAnimator / Satin), cross-loader (Architectury / Balm / Resourceful / Moonlight), curios (Curios / Trinkets / Caelus), worldgen (TerraBlender), GUI (LibGui / ObsidianUI / Modern UI), data attachment (CCA / PAL), server-side network text (Polymer / Text Placeholder / Server Translations / Impersonate / Pehkui), scripting languages (KubeJS / Kotlin…), recipes (JEI / EMI / REI), and all-in-one packs (Collective / Bookshelf / MaLiLib, etc.)
  • The master catalog library-catalog-2026 (overview navigation), the dedicated traps file lib-traps-2026 (8 selection traps), and the recipe integration notes library-integration / library-integration-jei-emi
  • Each file has a decompilation-check section (its title carries that round's timestamp; follow the essay itself): the top-level API packages / entry points for the MC version × loader combinations that were decompiled and checked; details follow the official sources

② Library Skill sources (under knowledge/libs/, used per the "library Skill" rules in AGENTS.md, not written into platform directories)

  • Five groups: all-platforms / fabric-only / forge-only / neo-only / bedrock-only (per-group counts: read knowledge/libs/README.md §current scale; neo-only mirrors Curios, KFF and forge-only)
  • Resolution rules: platform → group mapping (forge→forge-only+all-platforms; fabric/quilt→fabric-only+all-platforms; neoforge→neo-only+all-platforms; bedrock→bedrock-only) plus a second filter on frontmatter platforms/mcVersions. Router hub: mc-lib-catalog

③ Data chain (essay frontmatter → script → MCP consumption)

authored/lib-*.md frontmatter (+ the library-integration / library-integration-jei-emi navigation notes)
  → mcp-server/scripts/build-library-catalog-from-authored.mjs → library-catalog.ts (catalog entries / verifiedApi keys / officialUrls)
  → scripts/build-lib-manifest.mjs (Modrinth API) → mcp-server/data/lib-manifests/all.json (slug / version entry matrix)
  → scripts/batch-decompile.mjs (batch decompilation, sources generated on demand into $MC_SKILL_CACHE, not committed)
  → scripts/merge-verified-api.mjs → write verifiedApi back
  → scripts/build-api-summaries.mjs → mcp-server/data/lib-api-summaries/ (API summaries by library × version group)
  → check_dependencies consumes the catalog + manifest (library recognition / version summary)

The scripts live in two places, both of them (do not look in only one):

Script Location
build-library-catalog-from-authored.mjs mcp-server/scripts/
build-lib-manifest.mjs scripts/ (repo root)
batch-decompile.mjs scripts/ (repo root)
merge-verified-api.mjs scripts/ (repo root)
build-api-summaries.mjs scripts/ (repo root)

For data locations see the Decompiled data artifacts section.

The definitions, live readings and re-compute discipline for the two counting rules (A verifiedApi keys / B the library API summary side) all live in CONTRIBUTING.md, "Counting rules for the library data chain"; the two denominators are different and must not substitute for each other. This section only describes the data-chain structure and does not copy the readings.

8. Porting, data diagnostics, and upstream availability (4)

Tool What it does
diagnose_data_paths Diagnoses the data directory configuration (advanced troubleshooting). Reports the resolved values of MC_SKILL_DATA / MC_SKILL_COMMUNITY, and whether forge/fabric/neoforge/quilt/liteloader/rift/modloader/bedrock/community are found / empty / not_found. The first stop for troubleshooting.
analyze_porting_path Scans the project, identifies the platform/version/mappings/Architectury, and outputs risks, routeSteps, reference links, and suggested query_api calls. On the schema only projectPath is required; targetPlatform is enforced by the handler (silently defaulting forge→neoforge is forbidden; missing → INVALID_INPUT). routeSteps is a human-readable string[]; the machine-readable hand-off is nextSteps[] (tool + directly callable args). LiteLoader / Rift / ModLoader / Bedrock → UNSUPPORTED_PORT.
port_project Executes porting steps: init_architectury / extract_common / apply_version_migration. dryRun by default; a real write needs dryRun=false + confirmed=true + MC_SKILL_ALLOW_WRITE=1 + a path inside MC_SKILL_PROJECT_ROOT.
query_upstream_releases Asks an upstream release source whether a loader / mapping / mod version exists at all, and what the latest build is. source has ten options: forge / neoforge (maven-metadata.xml, fully queryable), fabric-loader / fabric-yarn / quilt-loader / parchment / legacyfabric-loader (endpoints are split per MC version, so minecraftVersion is mandatory; parchment's artifact name is parchment-<mc> and its version string is a date such as 2023.09.03; legacyfabric filters through the ?game_version= query string because the path form /<mc> returns 400), modrinth (slug, any third-party mod or library), maven (slug=<alias>:<group>/<artifact>; the host alias table is pinned in mcp-server/src/upstream/releases.ts under MAVEN_HOST_ALIASES, so arbitrary hosts cannot be assembled), and mojang-manifest (the official version_manifest_v2; pass minecraftVersion to filter by versions[].id). Difference from list_*_versions: those list the doc versions already ingested by this repo, so not being on the list ≠ the upstream does not have it. The three states must be read: ok:false ⇒ nothing was found (network/HTTP/parse) and you must not conclude the upstream lacks it; ok:true + available:false ⇒ the upstream really does not have it. matchRule echoes the version-matching rule (e.g. for neoforge: MC 1.21.1 → prefix 21.1.). releases is truncated by version, descending, to limit (default 12); the total is in total; releases sort before same-number nightlies. Requires network access; when Node hits a TLS failure it falls back to curl.exe --ssl-no-revoke automatically and does not touch the system certificate store; both the entry point and the redirect landing point must pass the host allowlist (parchment's hosted backend ldtteam.jfrog.io is explicitly registered), and a landing point outside the allowlist reports URL_REJECTED without reading the body. The first tool in the repo with outputSchema + structuredContent. S4′ on-disk cache: TTL per state — 6 hours for available:true / 2 hours for available:false (a negative can be overturned by a new release, hence the short tier) / no caching for ok:false; the cache root may only be $MC_SKILL_CACHE/upstream-cache/ (a resolved path inside the repo is refused); the response carries cache{hit,tier,ttlMs,ageMs?,wrote?,note?}, refresh=true forces a refetch and MC_SKILL_UPSTREAM_CACHE=0 turns caching off entirely; the cache key includes source/minecraftVersion/slug/limit. outputSchema declares the cache slot in sync.

9. Registry / Mixin / resources (9)

Tool What it does How to read the result Error codes
query_registry Looks up vanilla resource IDs (nameLayer: registry_id); use convert_mapping for class/method names. lookup: ok + result; empty ≠ the ID does not exist (it only covers minecraft:) —
mixin_analyze Parses mixins.json and @Mixin injection targets (multiple mapping layers; high risk — see supportMatrix). With deep:true it runs bytecode-level verification against the cached remapped client jar (target class / selectors / @At call sites); if the jar is not cached you get a CACHE_MISS pointer (it never downloads on its own). validator: ok + verdict; a jar that is not cached = a CACHE_MISS pointer, not a failure (run get_minecraft_source first) CACHE_MISS
validate_at Bytecode-level validation of Forge/NeoForge *_at.cfg: class/member existence (inheritance chain / record / inner classes), mapping-layer mismatch suggestions, cross-file conflicts. validator: the verdict is in errors[]; this file records no dedicated three-state name, so trust the response's ok / error —
validate_aw Bytecode-level validation of Fabric .accesswidener: header/namespace, entry types, existence, transitive, cross-file conflicts. validator: same as above —
audit_resources Static checks of model texture references, orphan textures, modId naming, etc. validator: same as above (static surface, not bytecode-level) —
validate_datapack_json Trimmed JSON validation for recipe / loot_table / advancement / tag (on 1.21+ a recipe result may be an object; this is not the full pack_format schema). validator: trimmed schema ⇒ passing does not mean full pack_format compliance, only that the surfaces listed here were covered —
get_workflow_template Full workflow text (the get_workflow_template list is authoritative; same names as the MCP Prompts; a tools-only client such as Cursor uses the fallback). lookup: ok + full text; template names come from that tool's list, not from guessing —
list_knowledge_resources / read_knowledge_resource Lists / reads the mcskill:// URIs (patterns, schema, workflow, community, etc.). lookup: ok + URI list / body; a missing URI ⇒ ok:false —

How to read the result: ok:true = you have a result; ok:false = the tool failed (reason in errors[] / error). For lookup tools, an empty result never means the target does not exist. Generators additionally have the resultKind three states, see §10. A — in the error-code column = this repo records no dedicated error code for that tool; the real error is whatever errors[] / error.code says, and filling it in from memory is forbidden. The only confirmed code in this group is CACHE_MISS (the mixin_analyze deep pointer for an uncached jar — a "build the cache first" hint, not an error).

Counting rule: this group has 9 tools in 8 rows — the last row merges list_knowledge_resources and read_knowledge_resource, while the heading "(9)" counts tools.

Bytecode-level verification (mixin_analyze deep / validate_at / validate_aw) depends on the T2 cache pipeline: when the jar is not cached you get a CACHE_MISS pointer (run get_minecraft_source first), and it never starts a large download on its own.

10. Code generation templates (11)

The 11 tools in this group return text + suggestedPath only, no disk writes by default. An optional write requires all of: write=true + confirmed=true + the environment variable MC_SKILL_ALLOW_WRITE=1 + an absolute MC_SKILL_PROJECT_ROOT (missing ⇒ PROJECT_ROOT_REQUIRED); the write path must be relative to the project root and free of .., and going out of bounds reports PATH_OUTSIDE_ALLOWLIST. If any condition is missing you get text back and nothing is written silently. Three-state semantics: the default (no write) = dry-run, always ok:true + resultKind:"ok"; a generation failure ⇒ ok:false + resultKind:"generation_failed" (reason in errors[]); a write that did not complete ⇒ ok:false + resultKind:"write_blocked" (CLI success:false + exit 1, nothing written, the text preview still in result, fine-grained reason in writeError.code). Counting rule: this group is exactly the 11 items below; generate_datagen (DataGen Provider templates) belongs to §2 project helpers, not to this group.

Tool What it does
generate_model Block/item JSON models and blockstate templates. Required modId / blockName / version; kind defaults to block, and kind=item emits only the item model (no blockstates; the blockName slot then carries the item name). Item model paths fork by version: 1.21.4+ / 1.21.11 / 26.1 use assets/<mod>/items/ (Client Items), earlier versions use models/item/; an era upper-bound sentinel (eraUpperBoundError) rejects invented versions outright.
generate_lang en_us + zh_cn lang JSON skeletons. Required modId / entries / version; the skeleton does not change with pack_format. An empty entries is not silent (S6-③): it stays ok:true, but the response carries a disclosure warning plus a machine-readable emptyEntries:true ⇒ that is an empty skeleton, not a finished product.
generate_network_packet Network packet (C2S / S2C) skeletons, with registration and send/receive boilerplate per platform and version. Required modId / packetName / platform; version is optional, but version-specific shapes (payload vs SimpleChannel) are only emitted when it is passed.
generate_capability Capability / DataAttachment skeletons. Required modId / name / platform / version. forge 1.20.1 (and 1.18.2–1.20.4) Capability; neoforge 1.20.1 uses the same Capability shape, 1.20.4+ uses Data Attachment; fabric/quilt → error, switch to CCA.
generate_config Config skeletons. Required modId / loader / version; defaulting to forge is forbidden. neoforge 1.21+/26.1/1.20.4/1.20.6 use ModConfigSpec; 1.20.1 uses ForgeConfigSpec (Forge-compatible); the forge side only covers the ForgeConfigSpec era (1.13+, verified on 1.20.1; 1.12.2's Configuration is not generated); fabric/quilt emit a minimal Cloth Config skeleton plus a warning declaring the dependency (it is not a redirect to mc-config). The default for fabric/quilt is always Cloth; YACL is only an explicit opt-in (the library parameter is implemented: enum cloth | yacl, default cloth, and not passing it means Cloth; changing the default is forbidden). Passing library=yacl gives you a structural shell: apart from the class declaration and verified member names, everything is // TODO(未核实), and you must additionally run ingest_loader_api on your own yacl jar before it can compile. Cloth / YACL and other third-party config libraries are not loader APIs: to use their method names you must first ingest them with your own jar via ingest_loader_api (dryRun by default, writing only to the $MC_SKILL_CACHE overlay); until then query_loader_api only returns found:false and you must leave // TODO(未核实).
generate_entity_renderer Entity renderer skeletons. Required modId / entityName / platform / version; fabric/quilt error out directly.
generate_worldgen Worldgen JSON skeletons. Required modId / featureName / platform / version, and there are sentinels at both ends: 1.x only accepts 1.18.2–1.21.x and 26.x only accepts the 26.1.x this repo verified (upper bounds WORLDGEN_MAX_MINOR_1X / MC_MAX_MINOR_26X; an invented version such as 1.99.9, or an era outside the bound such as 26.2, is always rejected and the error names the sentinel to raise instead of generating quietly); platform=forge × 26.x is rejected outright (Forge has no 26.x). feature JSON for forge / neoforge; for fabric / quilt only configured_feature / placed_feature (forge's biome_modifier is forbidden). When there is no template, errors lists the supported versions.
localize_mod Localization: diff / draft_zh for your own mod, or extract / pack_draft for a third-party jar. There is no machine translation; unfilled items are marked needsTranslation; when there is no en_us, another language can be used as the source.
generate_playtest_driver Playtest skeletons (required platform / version): driverMode defaults to external_bridge (bridge action sequences + postconditions + evidence contract); in_jvm_player_agent produces a real executor on the versions listed in PLAYTEST_VERIFIED_TIER (the single source of truth; the list comes from the generator — the prose does not count versions) (intent menu + mailbox consumption + typed postconditions + per-intent budget), while versions outside that list get a contract + structural shell. It installs no bridge and launches no game.
generate_paper_plugin Generates a Paper plugin project skeleton — the server face, independent of the mod face (carrier gradlew runServer, not runClient; the API is the Bukkit/Paper abstraction layer, not net.minecraft.*; lifecycle plugin.yml+onEnable instead of @Mod+event bus; the per-version javap rewrite tables have zero applicability to this face). Text only, dry-run by default, with disk writes controlled by write=true — it never writes into the repo, never builds a platform tree, and never enters any mod-face scaffold gate. Boundaries: without paperApiVersion it generates a placeholder that fails loudly at dependency resolution (it never silently takes latest); plugin.yml's api-version defaults to TODO-未核实 (a wrong value gets the plugin rejected at load time); no binaries are produced (you must supply the gradle wrapper jar yourself); evidence level = structural shell, not built and not run. Illegal input: a pluginName that is not a legal Java identifier, or a packageName that is not a legal Java package name, is rejected outright.
generate_playtest_server_driver Generates a server-face (Paper/Bukkit) playtest driver (required evidenceDir) — usage (minimal closed loop / plan verbs / evidence contract / verdict patterns / unattended recipe / required launch configuration / BOM pitfalls) is in "How to use the server-face automatic test loop" in AGENTS.md. ⚠ Note: it reuses the client driver's evidence contract verbatim (state.json / exit-code.txt 0|1 only / qa.log / rounds.jsonl / plan.txt, same names, same directory ⇒ the reading side (inspect_playtest_evidence and inspect_playtest_multi) needs zero changes); the execution surface is newly built: there is no client on a server ⇒ player-level primitives such as move/goto/break/gui/jump/look/shot/scan are never generated. The injection point is new: JavaPlugin#onEnable + Bukkit.getScheduler().runTaskTimer (synchronous scheduling, main thread). Text only, dry-run by default. Step surface: only wait / mark / stop / touch / waitfile / cmd / assert are supported (assert only player_count / world_count / marker); client-only steps or unknown kinds are judged red, never silently skipped. Every Bukkit API name was checked against this repo's signature corpus (including dispatchCommand throws CommandException, already caught). It does not claim to enter PLAYTEST_VERIFIED_TIER — that entry carries mappings, and a server has no mappings. Evidence level = structural shell.

11. Log and dependency diagnostics (8)

Tool What it does How to read the result Error codes
analyze_log Parses game / crash log excerpts (reusing the crash_analyze classification). reader: ok + a classification; since it parses an excerpt, the verdict only covers the part you pasted —
analyze_build_log Parses pasted Gradle / javac build failures (it does not execute gradlew); returns the symbols/files and suggested tools. reader: ok + symbols/files + suggested tools; it does not run gradlew —
get_migration_guide Defaults to the Primer toc; section returns only that chapter; full=true gives the whole text (with url/license/loader). The route may contain a platform or from->to. lookup: the default is toc only (three modes: toc / section / full); not getting full text does not mean the chapter is missing —
check_dependencies Reports dependency problems from build.gradle / mods.toml / fabric.mod.json / quilt.mod.json / litemod.json / riftmod.json / Bedrock manifests: loader detection (quilt/fabric/forge/neoforge/liteloader/rift/modloader/bedrock), library recognition (catalog wiring), conflict / trap detection. It returns detectedLibraries (including the supportedVersions decompilation-verified version window and a manifestSummary version/loader summary, from library-catalog.ts + mcp-server/data/lib-manifests/all.json). lookup: ok + detectedLibraries; heuristics + catalog ⇒ libraries it does not know will be missed (this is not a full Gradle resolution) —
inspect_playtest_evidence Reads playtest evidence (exit-code / state.json / [QA] sections / calls.jsonl / screenshots), each item with the three states present|absent|unreadable; requires MC_SKILL_PLAYTEST_ALLOW=1 + MC_SKILL_PLAYTEST_ROOT (a realpath hard boundary). It can delegate to inspect_runtime to read logs. three states: present / absent / unreadable per item; a missing item must never be read as "no failure" —
inspect_playtest_multi Multi-client joint reading (multiple sessions): clients[] ({id,evidenceDir}) or evidenceRoot (scans direct subdirectories as clients; the reserved name sync/ is skipped and leaves a trace in autoSkipped). Per-client three states + joint pass judgement + anchors (state.json's at / plan.txt mtime / last rounds entry) + rendezvous markers. joint fail-closed: client count ≥1 ∧ every exit-code=0 ∧ both state and qa present ∧ the last rounds entry ok≠false ∧ (when expectMarkers is given) every marker present; if any client directory's realpath falls outside the authorized root, the whole reading is rejected NO_CLIENTS · CLIENT_NOT_GREEN · MARKERS_MISSING · OUTSIDE_AUTHORIZED_ROOT · DUPLICATE_CLIENT_ID
playtest_intent The playtest intent mailbox (the LLM-side wiring for the in_jvm_player_agent real executor): action=read|write; a write creates <evidenceDir>/intent.json (the driver's waitintent step consumes it and renames it to intent.done.json). Check order: confirmed → forbidden list (kill/tnt/fill) → the menu (intent-menu.json) → parameter allowlist → required parameters → mailbox occupancy (overwrite overrides it). Requires MC_SKILL_PLAYTEST_ALLOW=1 + MC_SKILL_PLAYTEST_ROOT. Failure codes: CONFIRMATION_REQUIRED / INTENT_FORBIDDEN / INTENT_NOT_IN_MENU / PARAM_NOT_DECLARED / MISSING_REQUIRED_PARAM / MAILBOX_BUSY / MENU_NOT_FOUND. six checks on the write side; illegal intents are rejected on the write side and never reach the executor. Three failure shapes: mailbox-level failure = data (guarding continues) / protocol violation = rejected on the write side / script form = judged red and the round stops CONFIRMATION_REQUIRED · INTENT_FORBIDDEN · INTENT_NOT_IN_MENU · PARAM_NOT_DECLARED · MISSING_REQUIRED_PARAM · MAILBOX_BUSY · MENU_NOT_FOUND
playtest_bridge Calls the BlackBoxPro bridge (host is always 127.0.0.1, default port 38081): status reads /status.ready (in the world); execute posts to /execute (the native timeout ⇒ PLAYTEST_TIMEOUT); await polls query_* for a condition (the bridge has no wait_until). execute/await require confirmed=true + authorization. The bridge has no authentication and binds to all interfaces — use it locally only. a timeout is not "no failure": the native timeout maps to PLAYTEST_TIMEOUT and must not collapse into "nothing failed". /status.ready is not trustworthy — judge "in a world" with query_player_state PLAYTEST_TIMEOUT

How to read the result: ok:true = you have a result; ok:false = the tool failed (reason in errors[] / error). For lookup tools, an empty result never means the target does not exist. The three genuine three-state surfaces in this section are inspect_playtest_evidence's present|absent|unreadable, playtest_intent's three failure shapes, and playtest_bridge's timeout semantics. A — in the error-code column = this repo records no dedicated error code for that tool; the real error is whatever errors[] / error.code says, and filling it in from memory is forbidden. The 13 codes written in this section are all named values from the repo docs.

12. Self-update (1)

Tool What it does
mc_skill_update Checks / applies tooling + data updates for this repo (GitHub Release). action=check|apply; scope=tooling|data|all; channel=stable by default (pre-releases ignored). apply is dryRun by default; a real write needs confirmed=true + MC_SKILL_ALLOW_WRITE=1 + MC_SKILL_PROJECT_ROOT=this repo's root. It returns filesToOverwrite / diskSpace / restartRequired. CLI: node mcp-server/dist/cli.js update --action check|apply (the old positional form check|apply still works, with a migration hint on stderr).

get_server_status also carries buildStatus (buildRequired=true when src is newer than dist, telling you to run npm run build again), updateHint (cached from the last check, default TTL 1h), and pendingRestart.

13. Decompilation and mod sources (5)

Zero downloads by default: no prewarming, no prefetching; downloads happen only on explicit calls, into $MC_SKILL_CACHE (MCP default %APPDATA%/mc-skill-cache or ~/.config/mc-skill-cache; repo scripts default os.tmpdir()/mc-skill-cache — those are different directories, so long batch runs should pin one path), and never into the project directory.

Cache and concurrency: the layout is <cache>/{jars,mappings,remapped,decompiled,decompiled-mods,registry,resources,locks}/ plus cache.db (node:sqlite; mdk/ is created on demand by the MDK tool). Lock granularity and the meta / artifacts table shapes are documented in mcp-server/README.md §T2; concurrent runs on the same version or output directory get CACHE_LOCK_BUSY / LOCK_BUSY immediately instead of queueing or reusing someone else's half-written tree.

Java 17+ prerequisite: VineFlower does the decompilation and tiny-remapper does the remap; both are Java 17+ tools downloaded on demand into <cache>/resources/. Their fixed versions and SHA256 live in the constants of mcp-server/src/decompile/downloaders/resources.ts (a byte mismatch fails instead of silently switching versions); the component list and licences are in THIRD_PARTY_NOTICES.md. The order is fixed: argument validation → the MC_SKILL_SKIP_DOWNLOAD gate → the Java probe, so in CI you see DOWNLOAD_DISABLED rather than TOOLCHAIN_MISSING. Both JAVA_HOME/bin/java and java on PATH are probed and the highest usable major wins; only when neither qualifies do you get TOOLCHAIN_MISSING (the process does not crash). MC_SKILL_SKIP_DOWNLOAD only covers the two downloading tools in this family; analyze_mod_jar / search_mod_code never download, and download_official_mdk does not read the variable.

Tool Arguments and behaviour Output / key boundaries
get_minecraft_source {version, className, mapping?: "auto"|"yarn"|"mojmap", lines?: [start,end], force?}. Missing version ⇒ VERSION_REQUIRED, missing className ⇒ MISSING_REQUIRED; className accepts dotted or slashed form; mapping defaults to auto: 1.14–1.21.11 → yarn, 26.1–26.3 → mojmap; lines is a 1-based closed range, default the first 120 lines, and an invalid range returns INVALID_INPUT (never silently clamped) Writes <cache>/decompiled/<version>/<mapping>/<class path>.java and returns totalLines / snippet[] / remap ∈ two-step-yarn | single-step-mojmap | none. Cache hit <1s, first run 3–10 minutes. VineFlower runs with --only=<class path> first and falls back to a full decompile if the target file is not produced. force only bypasses the class-file hit and forces a manifest / mappings re-download plus a remap re-run; an existing .java is not rewritten (delete the file to recompile it)
analyze_mod_jar {jarPath, version?}; pure Node reading of the zip central directory: quilt.mod.json / fabric.mod.json / mods.toml / neoforge.mods.toml / litemod.json / riftmod.json / Bedrock manifest.json, mixin references, entrypoints, dependencies, AW/AT. Passing version echoes requestedVersion / mcVersionConstraints[] / versionMatch ∈ match | mismatch | unknown No Java, zero downloads, no writes, no decompilation. versionMatch: unknown means the jar carries no decidable version constraint — not "incompatible"
decompile_mod_jar {jarPath, version?, mapping?: "yarn"|"mojmap", force?}. Remapping happens only when version is given and falls in 1.14–1.21.11 (mapping defaults to yarn, two-step official→intermediary→named); 26.1–26.3 skip the remap; without version the raw bytecode is decompiled directly Writes <cache>/decompiled-mods/<modId>/<modVersion>-<jar sha512 first 12>/. The identity segment comes from jar bytes (not mod metadata), so two different builds sharing a modId + modVersion never share a tree. modId must prove itself: jar metadata → a nested jar it declares (META-INF/jars|jarjar/*.jar, ambiguity returns candidates instead of guessing) → a caller label (only if that jar's own entry paths contain it). Otherwise MOD_ID_UNKNOWN, no fallback to a shared unknown-mod directory. The target subtree is cleared before writing (failure ⇒ CACHE_CLEAN_FAILED). A failed remap degrades to decompiling the original jar: remapped:false + degraded:true + warnings, and the names may still be obfuscated/intermediary. If the .mc-skill-decompiled.json completion marker cannot be written ⇒ partial:true (the tree is still usable and found stays true). Cache hits are judged from the marker's version/mapping; a mismatch ⇒ cacheStale:true plus a hint to add force:true. Returns the summary fileCount / javaFileCount / topLevelDirs / sampleFiles
search_mod_code {query, decompiledDir?, jarPath?, pattern?, maxResults?}. decompiledDir takes priority and must be absolute; jarPath is resolved through cache.db to an already decompiled directory. The default is a case-insensitive substring match; only pattern:true switches to regex (flags i only, never g/y; >512 characters or nested quantifiers return INVALID_INPUT) Scans .java / .txt / .json / .toml / .cfg by default; maxResults defaults to 100 with a 500 cap; a time and file-count budget applies, and hitting any limit sets truncated:true (truncated ≠ no hits). In pattern mode over-long lines are not searched and the response carries PARTIAL_SCAN. found:false only means zero hits; a jar that exists but was never decompiled ⇒ NOT_DECOMPILED, a missing jar ⇒ NOT_FOUND, neither entry point ⇒ INVALID_INPUT
download_official_mdk {platform, minecraftVersion, buildPlugin?, dryRun?, confirmed?, destPath?, allowCacheFallback?, allowUnpinned?}. dryRun by default (pin metadata only); dryRun:false downloads over the network and writes the cache even without a user project, so it also needs confirmed:true; writing a user project additionally needs destPath + MC_SKILL_ALLOW_WRITE=1 + MC_SKILL_PROJECT_ROOT Writes <cache>/mdk/<platform>/<version>/<buildPlugin>/, extracts into unpacked/, and parses entryClass / loaderVersion / mappings. Pin table: mcp-server/data/mdk-checksums.json (overridable with MC_SKILL_MDK_CHECKSUMS): for GitHub sources the ref must be a 40-hex commit SHA that appears in archiveUrl, and hosts must pass the allowlist; an empty sha256 fails closed with MDK_NOT_PINNED, and only an explicit allowUnpinned:true accepts an unverified download (and writes the hash back). Extraction uses unzip / 7z / bsdtar (Windows' bundled System32\tar.exe and default 7-Zip install locations are probed; GNU tar cannot read zip); there is also zip-slip rejection, an extraction-size budget, and a cross-check of the extracted tree against the central-directory listing. The two distribution shapes carry different data: the npm package (package.json's files includes data) ships the MCP-side small data — mdk-checksums.json / bedrock-script-api-pin.json / wrapper-jars.json / lib-api-summaries/ / lib-coords/ / lib-manifests/ / loader-api-summaries/ — so the pin chain works in the npm shape; the GitHub Release mcp-server-*.zip packs only dist/ plus metadata and does not contain those 7 items, so unpack mc-skill-data-full-*.zip over it (npm install --data merges the same way and keeps the packaged items). The platform corpus (forge_* etc.) is in neither package. The allowUnpinned write-back target is <pkg>/data/ and is overwritten by upgrades/reinstalls ⇒ for long-lived setups point MC_SKILL_MDK_CHECKSUMS at a pin table outside the package. LiteLoader / Rift have no official MDK (only the per-version scaffolds)

Version support surface (it only constrains MC source decompilation via get_minecraft_source; decompile_mod_jar has no version gate — any jar decompiles, and version only decides whether to remap and which mappings to use). The gate lives in the two released-ceiling tables in mcp-server/src/decompile/version-manager.ts (MAX_RELEASED_PATCH_BY_MINOR / MAX_RELEASED_PATCH_BY_26X_MINOR): minor/patch values outside those tables are rejected during argument validation, so invented versions like 1.21.999 and unreleased minors never pass.

Every currently released version is inside the support surface (the ceiling tables are topped up after each Minecraft release; anything outside them is rejected during argument validation):

Support surface Yarn Mojmap Notes
1.14 – 1.21.11 ✅ ✅ yarn by default (two-step official→intermediary→named); mojmap is single-step. Mojmap has client_mappings only from 1.14.4 onward: choosing it on 1.14–1.14.3 fails at the download stage with MAPPINGS_NOT_FOUND, so use the default yarn
26.1 – 26.3 (the complete 26.x release set) ❌ (Yarn discontinued) ✅ (no remap) Already deobfuscated, so the client jar carries readable names
Outside the surface — — 1.13.2 and earlier, snapshots, unreleased minors; INVALID_INPUT plus the supported range

Each mapping layer also has upstream gates (yarn's build metadata / checksum sidecar / three-column namespaces, mojmap's manifest download entry); missing any of them fails instead of degrading to an unverified download. Implementation and failure codes: mcp-server/src/decompile/downloaders/yarn.ts, mcp-server/src/decompile/services/java-pipeline.ts.

Failure codes in this family (all taken from the implementation; the actual value is whatever error.code / action.code says): TOOLCHAIN_MISSING (Java <17 or missing), DOWNLOAD_DISABLED (MC_SKILL_SKIP_DOWNLOAD=1), CACHE_LOCK_BUSY / LOCK_BUSY (concurrency), CLASS_NOT_FOUND (the decompile finished but that class is not in that namespace), MAPPINGS_NOT_FOUND / MAPPINGS_CHECKSUM_MISSING / MAPPINGS_EMPTY (missing mappings, missing sidecar checksum, empty parse), DISK_INSUFFICIENT, DECOMPILE_FAILED, MOD_ID_UNKNOWN, CACHE_CLEAN_FAILED, NOT_DECOMPILED, MDK_NOT_PINNED. found:false does not mean "the class/library does not exist": an empty result on a lookup tool only means nothing was found.

Division of labour with query_api: query_api / get_method_params give 1.16.5–1.20.4 Vanilla signatures (fast, offline); they do not include Forge/Fabric APIs and have no index for 26.x. The source-oriented tools in this section (get_minecraft_source / decompile_mod_jar / search_mod_code / download_official_mdk) should only be used when you really need full source or decompilation (they download a lot), and every tool description carries a ⚠️ boundary note.

14. Decompiled data artifacts

Decompiled data that is committed (consumed by check_dependencies and others, usable right after a clone):

Data Location Content
library-catalog.ts mcp-server/src/diagnostics/ catalog entries (lib-* essays + the integration navigation notes) / verifiedApi keys (gameVersion/loader → packages/entrypoints) + supportedVersions version windows (the Modrinth supported MC version list, decompilation-verified) + officialUrls. Counting rule A: see the library-data-chain counting rules in CONTRIBUTING.md
lib-api-summaries/*.json mcp-server/data/ public class / method signature summaries per library (split by library × version group). Counting rule B: same as above
lib-manifests/all.json mcp-server/data/ slug / version / URL / hash / loader matrix (generated from the Modrinth API). The root is an array, each item {slug, entries[]}; version entries live under entries, and reading a top-level versions computes 0

packages is a heuristic artifact and must not be used as an import reference: verifiedApi.<version/loader>.packages is derived by scripts/batch-decompile.mjs from the top-level directories of the decompiled output (the first 3 segments for common TLDs, the first 2 otherwise, and at each level only the first child directory in alphabetical order), so it only answers "which package roots does this library probably live under" and is not a copy-pasteable list of full class names. To get to a concrete class name you must go through query_loader_api (after the user ingests a jar via ingest_loader_api) or check with IDE completion. The ownership side already has a hard constraint: scripts/merge-verified-api.mjs rejects outright any package name whose root is already attested by another library entry (JiJ-bundled library leakage), and the self-check lives in §S3 of mcp-server/test-scripts.mjs.

Known gaps (measured, not fabricated): a few catalog entries have an empty verifiedApi object — 4 of them are third-party libraries whose jar cannot be fetched: lib-config-legacy, lib-libgui, lib-server-translations, lib-spruceui-obsidianui. The root cause: those 4 have an empty modrinthSlug in library-catalog.ts, and Modrinth project/libgui, project/spruceui, project/server-translations-api, and project/config-legacy all return 404 (no such project), so build-lib-manifest cannot fetch a version list and batch-decompile has no jar to decompile, leaving verifiedApi as {}. For these libraries, follow each one's officialUrls (the GitHub repository); cloning summaries from a neighbouring library or version is forbidden. Additionally, authored/lib-traps-2026 (role: "trap") and authored/library-integration (a compilation entry) carry no verifiedApi by design and are not gaps. Note: obsidianui in the lib-spruceui-obsidianui entry does exist on Modrinth (200). If a summary is added for it later, the right move is to add modrinthSlug to the frontmatter of community_knowledge/authored/lib-spruceui-obsidianui.md and re-run the data chain, not to hand-edit the generated library-catalog.ts.

The decompiled sources themselves are not committed (generated on demand into $MC_SKILL_CACHE; the scale depends on which libraries × versions have been decompiled, so the repo promises no fixed file count — read the cache directory when you need it). When the sources are missing search_mod_code returns NOT_DECOMPILED (jar exists but was never decompiled) or NOT_FOUND (the jar / directory itself is missing), plus a pointer to decompile_mod_jar. Related scripts: scripts/build-lib-manifest.mjs (manifest), scripts/build-api-summaries.mjs (API summaries), scripts/batch-decompile.mjs (batch decompilation), scripts/merge-verified-api.mjs (writing verifiedApi back into the catalog).

Also: registerPrompt / registerResource (workflow and knowledge URIs) are for clients that support prompts/resources; see mcp-server/docs/prompts-client-compat.md.

15. Workflow templates (MCP Prompts)

Workflow templates are registered through registerPrompt (usable by clients that support prompts); tools-only clients such as Cursor use the get_workflow_template tool to get the same full text. The authoritative list is the template names in get_workflow_template's enum (two families: development templates + orchestration skills; see also the mcskill://skill/ family on this page).

These templates are agent step checklists (human in the loop): once the creative direction and version trade-offs are settled, they give the retrieval / draft / validation order. There is no MCP tool for Gradle, for copying a jar into a game directory, or for uploading a release; mc-build-mod / mc-ingame-iterate only list steps, which the user runs locally after confirming. The agent does not run Gradle, does not copy mods automatically, and does not upload to stores — high-risk steps say "execute after user confirmation", by design.

Template name Title Flow highlights
mc-new-block New block workflow DeferredRegister registration → BlockItem → model (generate_model) → lang (generate_lang) → loot (generate_datagen) → optional tags/recipe
mc-new-entity New entity workflow EntityType + attributes → SpawnPlacement/spawn egg → renderer (generate_entity_renderer) → loot/sounds
mc-new-gui GUI workflow MenuType + AbstractContainerMenu → Screen registration → per-platform sync (Forge SimpleChannel / NeoForge Payload / Fabric ServerPlayNetworking)
mc-crash-triage Crash triage analyze_log/crash_analyze → search_community_docs → validate_project + mixin_analyze → diagnose_gradle
mc-port-mod Port a mod analyze_porting_path → confirm the target → port_project dryRun → get_migration_guide
mc-build-mod Mod build flow validate_project / diagnose_gradle → gradlew build after user confirmation → confirm the jar in build/libs; on failure analyse the log; can feed into the real-machine loop
mc-ingame-iterate Real-machine test and fix loop ask for and verify the launcher path (official / HMCL / PCL2 version isolation) → install the jar after user confirmation → reproduce → fix → retest. Path conventions are in the template body and in the HMCL isolation doc
mc-ingame-playtest In-game playtest (bridge) preflight (bridge jar/dependency accounting) → playtest_bridge (/execute + /status.ready + await) → screenshot/query evidence → inspect_playtest_evidence → fix and feed back; execution rights are in "Human-in-the-loop exception: in-game playtest (three channels)" in the root AGENTS.md
mc-localize-mod Mod localization decide own/third_party → localize_mod diff/draft or extract/pack_draft → the agent fills in Chinese → self-check; see authored/localization-lang
mc-decompile-mod Mod decompilation research locate the jar → analyze_mod_jar → decompile_mod_jar / get_minecraft_source → search_mod_code → locate the target class → change proposal → hand off to mc-build-mod / mc-ingame-iterate
mc-new-item New item workflow that version's 03-item registration → model/lang → crafting (generate_datagen only when a template exists)
mc-new-blockentity Block entity workflow BlockEntityType + block → rendering/sync; GUI hands off to mc-new-gui
mc-mixin Mixin workflow mixin_analyze → bucketing mixins.json → verify mappings
mc-worldgen Worldgen workflow configured/placed feature → biome injection for that version
mc-config Config workflow generate_config (loader+version required) or Cloth Config
mc-gametest GameTest workflow check the docs per platform; never assume Forge 1.20.1 from memory
mc-publish Publishing checklist metadata / build/libs / changelog / license; let the user upload where possible (human in the loop, no upload on their behalf)
mc-setup-env Dev environment setup detect_mod_project → MDK dryRun or the Loom/mapping list; genRuns is run after user confirmation
mc-full-mod Full chain for a brand-new mod only from scratch: setup-env → mc-new-* → build → ingame-iterate → optional localize/publish
mc-networking Networking checklist session task=mc-networking → generate_network_packet (with the version suffix)
mc-capability Capability / attachment checklist Forge/Neo 1.20.1 Capability; Neo 1.20.4+ Attachment
mc-recipe-data Recipes and data packs 07-datagen / mc-recipe / loot / advancement
mc-audio-vfx Sounds and particles mc-sound / mc-particle
mc-commands Commands mc-command
mc-dimension-structure Dimensions and structures mc-dimension / mc-structure
mc-access AT / AW validate_at / validate_aw
mc-bedrock-addon Bedrock Add-On search_bedrock_docs / validate_addon_manifest; no Java 02–10 injected
mc-fluid Fluids 02 + mc-fluid
mc-enchant-potion Enchantments / potions / effects mc-enchantment / mc-potion / mc-effect
mc-energy Energy mc-energy / mc-capability
mc-creative-tags Creative tab and tags 03
mc-kotlin Kotlin mods 00; check that version's docs
mc-jei JEI compatibility mc-compat-jei
mc-ci-publish-extra CI publishing extras 00; only emits step names (copyable YAML at community_knowledge/patterns/examples/mod-ci-github-actions.md), never runs CI and never uploads (human in the loop)
mc-villager Villager professions / trades session task=mc-villager → 04-entity; verify profession/trade signatures against that version's docs, never copy a neighbouring version
mc-multiblock Multiblock structures session task=mc-multiblock → 02-block / 07-datagen; no template means writing the docs by hand
mc-ai Entity AI / goals session task=mc-ai → 04-entity; verify Goal/Brain class names against that version's docs, never copy the 1.12 AI task table into 1.20+
mc-events-forge Forge event system checklist session task=mc-events-forge → 05-events / mc-events; take the registration-time vs runtime subscription split from that version's 05-events.mdc (≤1.17 onwards); verify class names with search_forge_docs
mc-events-neoforge NeoForge event system checklist session task=mc-events-neoforge → 05-events / mc-events; mod bus (registration time) vs game bus (runtime) per version from that version's 05-events.mdc; verify class names with search_neoforge_docs
mc-events-fabric Fabric / Quilt event system checklist session task=mc-events-fabric → 05-events / mc-events; "register a callback at init vs run runtime logic inside the callback" per version from that version's 05-events.mdc (the thin versions 1.21.4/1.21.8/1.21.10 only have a pointer sentence); the Quilt branch only goes through quilt//05-events (QSL has no stable artifact, so a Fabric callback must not be passed off as QSL); verify class names with search_fabric_docs
mc-rendering Rendering workflow (BER / custom model loaders / shaders) The render registration entry point forks by platform + version; a single API name must not be used to cover every version. Confirm platform and exact version first → session (optionally task=mc-new-blockentity / mc-new-entity); presentation layer hands off to mc-audio-vfx
mc-profiling Profiling workflow A standalone profiling surface for stutter / memory / time cost; principle "measure before optimizing". This is the full version of mc-crash-triage step 5 and mc-build-mod step 7
mc-save-migration Save-data structure migration workflow Mandatory first step: before changing save schema, make the user back up the whole world directory and report the backup path. Covers SavedData .dat, block-entity / entity / chunk read-write formats, and cross-version old-world compatibility
mc-server-multiplayer-test Dedicated server and multiplayer test workflow Multiplayer-side verification: dedicated server, several clients in one world, state sync, behavior under permissions and latency. Building goes through mc-build-mod; single-player real-machine testing through mc-ingame-iterate
mc-combat-attribute Damage / attributes / combat workflow Damage types, entity attributes and modifiers, combat numbers. Enchantments / potions / effects go to mc-enchant-potion; loot goes to mc-recipe-data
mc-multi-loader Multi-loader (Architectury) workflow One source producing Fabric / NeoForge (or Forge) multi-loader builds; build and debug cost doubles, which is a trade-off to confirm with the user first. Changing code in an existing project goes through that platform's session
mc-modpack Modpack integration workflow Turn third-party mods into a runnable pack: dependency closure, load order, conflict triage. No automatic publishing, no downloading or uploading mod files on your behalf
mc-datapack-standalone Standalone datapack workflow (no Java code) Pure datapack: a world datapacks/ directory or a standalone zip, no build.gradle, no Java source. Recipes / loot shipped inside a mod go to mc-recipe-data and that platform's session
mc-resourcepack-standalone Standalone resource pack workflow Pure resource pack: resourcepacks/ or a standalone zip (models / blockstates / textures / lang / sounds / GUI textures). In-mod resources go through that platform's session and rules

16. Knowledge exposure (MCP Resources)

mcskill:// URIs are registered through registerResource (for clients that support resources); the list_knowledge_resources / read_knowledge_resource tools are the fallback.

293 resources measured (counted live via list_knowledge_resources; recompute: node mcp-server/dist/cli.js list_knowledge_resources). By URI family:

⚠ 293 entries ≠ all 293 go through registerResource — three delivery paths, kept separate; do not read this as "all of them are visible in the client's Resources panel":

Delivery path Count Notes
registerResource (MCP Resources) 133 code-patterns 116 + skill 12 + fixed 5
registerPrompt (MCP Prompts) 61 mcskill://workflow/* goes through the prompt face instead
tool-only, not registered 99 mcskill://community/* has neither a resource nor a prompt; it is only reachable through list_knowledge_resources / read_knowledge_resource
URI family Count Content
mcskill://code-patterns/<platform>/<version>/NN-<topic>-patterns.md 116 (forge 61 / fabric 49 / neoforge 6) Code pattern library bodies, split by platform + version; snippet-level patterns the agent reads directly
mcskill://community/<sourceKind>/<id> 99 Readable community_knowledge/ entries = authored 95 + permitted 4; the 11 links entries carry metadata + external URL only and are not readable entries (the 110-entry index is described under "Community practice knowledge")
mcskill://workflow/<template> 61 Workflow bodies with the same names as the Prompts (same set as get_workflow_template; 49 development templates + 12 orchestration skills)
mcskill://skill/<name> 12 Orchestration skill bodies (common_skill/mc-*/SKILL.md; same names as the trailing 12 orchestration skills of get_workflow_template)
mcskill://matrix/mixin-support 1 the mixin_analyze support matrix (SRG/Yarn/Mojang/readable/descriptor shapes)
mcskill://schema/sqlite 1 yarn-mappings.sqlite v2/v3/current-batch v4 field reference (must carry ?version=<exact MC>; a bare URI is refused)
mcskill://version-changes/1.21 1 the dedicated 1.21 changes chapter (knowledge base)
mcskill://antipatterns/registry 1 the registry anti-pattern essay
mcskill://patterns/README 1 the code pattern library index (community_knowledge/patterns/)

code-patterns only covers the forge / fabric / neoforge trees (quilt / liteloader / rift / modloader / bedrock have no code-patterns/ → 0 for that family); 6 of them are archived legacy entries — registered by name, but read_knowledge_resource returns found:false plus an archive note instead of a body.

17. Standalone CLI (node mcp-server/dist/cli.js, all 89 tools available)

Flags-only (--key value / --key=value / bare --flag → true), output always wrapped as JSON {success, tool, result|error}, exit codes 0 = success / 1 = tool error / 2 = usage error. Global flags (not part of any tool schema): --help/-h, --version/-V (printed before the tool name, or when the whole command has no tool name; when --version follows the tool name it is the tool's own field, while -V in that position is parsed as a boolean version ⇒ schema validation fails and it exits 2), --json (does not change tool output, kept only for compatibility; it affects how --help is rendered in an interactive terminal), --compact, --fail-on-error, --quiet (silences progress lines and heartbeats; errors / warnings / migration hints still print), --timeout <ms> (exits 1 on expiry with errorKind:"timeout", and the exit code still stays within 0/1/2), --project <dir>, --file field=path, --raw [field] (that field is passed completely literally; writing it bare disables the global @ expansion), --output-format json (the canonical way to express an output-format intent; the only legal value today, anything else exits 2), --stdin-json (reads a whole argument object from stdin as a base, with same-named command-line fields always winning; under a TTY, and when it appears together with @- / =- / --file f=-, it always exits 2); every string field supports file input — --crashReport @./latest.txt reads a file, --crashReport=- / @- reads stdin (once per process), and --file crashReport=./latest.txt is equivalent, with single files and --stdin-json payloads sharing an ~8MB limit. With --fail-on-error, found:false and a non-empty errors[] are also promoted to exit code 1. --fail-on-error=false turns that behaviour off (do not read writing =false as enabling it). Boolean flags only accept true/false/1/0/yes/no/on/off; --flag=junk is rejected.

⚠️ Windows PowerShell 5.1 console pitfall (E-7): under a GBK code page, PS 5.1 capturing this CLI's UTF-8 JSON through a pipeline introduces bad control characters that break JSON.parse; plain Node spawnSync pipeline parsing of the same output is perfectly fine. Consume it from scripts through a Node child process, or run chcp 65001 first.

node mcp-server/dist/cli.js status --version 1.20.1            # server status (incl. buildStatus)
node mcp-server/dist/cli.js query --className net.minecraft.world.entity.LivingEntity --methodName getMaxHealth --version 1.20.1
node mcp-server/dist/cli.js convert --from mcp --to mojang --version 1.20.1 --name getHealth --owner net.minecraft.world.entity.LivingEntity '--descriptor=()F'
node mcp-server/dist/cli.js update --action check
node mcp-server/dist/cli.js list-tools                          # schemas for all 89 tools

Generic dispatch (v0.2+): besides the commands above, any MCP tool name can be called directly (handlers are collected automatically, and missing arguments return the zod validation message):

node mcp-server/dist/cli.js search_docs --platform forge --query DeferredRegister --version 1.20.1
node mcp-server/dist/cli.js check_dependencies --buildGradle "..." --fabricModJson "{...}"
node mcp-server/dist/cli.js analyze_mod_jar --jarPath <path>
node mcp-server/dist/cli.js get_community_doc_summary --id authored/lib-curios

The old positional forms (query <className> / convert ... <memberName>, etc.) still work; wrap in single quotes in PowerShell when parentheses are involved (e.g. '--descriptor=()F').


Troubleshooting and FAQ

The troubleshooting data lives in the dedicated tables below; this section is an index into them.

Four high-frequency symptoms

Symptom Check first Where
All tools uncallable inside the MCP host Is dist/ built? Has the host been reloaded? "Tool not working" below
PLATFORM_DATA_MISSING / a platform's data is empty Does MC_SKILL_DATA point at this repo's data/? diagnose_data_paths, or set MC_SKILL_DEBUG_PATHS=1
Can't find some API / class It is outside index coverage or the simple name is ambiguous, not a proof the class is missing from the game the misreading table in "Tool boundaries" above
The game launched but the driver does nothing the authorization pair / focus pause / the world's session.lock being held "Second-half loop operational bits" above

Jump to the matching dedicated table

  • Tool returns odd results, crashes, args misread → "Tool pitfalls (measured, same class of problem)"
  • Unsure what found:false / CACHE_MISS / empty methods means → the misreading table in "Tool boundaries"
  • Fetch / upstream query failures (TLS, timeout, 404, proxy) → "Tool and network boundaries"
  • An update installed but nothing changed → mc_skill_update's updateHint (TTL 1h) + get_server_status.buildStatus (buildRequired)
  • CLI garbled output / MODULE_NOT_FOUND (non-ASCII path) → the PowerShell 5.1 pitfall in "Standalone CLI"
  • Playtest: bridge timeout / scan=0 / world won't load / can't close the client → "operational bits" above

Tool not working (read after cloning)

  • Every MCP tool call fails (server not started): mcp-server/dist/ is unbuilt (dist is not committed). Run cd mcp-server && npm ci && npm run build (Node >= 22.5; for Yarn lookups also npm run build:yarn-sqlite).
  • get_server_status reports buildStatus.buildRequired=true: src is newer than dist; rebuild with npm run build, then reload MCP in the host (compiling dist alone is not enough — the host process still runs the old code).
  • A decompilation tool returns TOOLCHAIN_MISSING: Java 17+ is required (VineFlower / tiny-remapper); install Temurin 17+ and restart MCP, or set JAVA_HOME per the returned instructions.
  • search_mod_code returns NOT_DECOMPILED: the sources have not been decompiled yet (not committed by design); follow the returned instructions to call decompile_mod_jar / get_minecraft_source first.
  • No MCP client: use the standalone CLI node mcp-server/dist/cli.js <tool> --key=value (all 89 tools are callable).

Glossary

Term Meaning
Human in the loop (HITL) High-risk steps stop at a checklist / dryRun for user confirmation; see the "What it is" section
dryRun / the three write states preview (no write) / real write (write+confirmed + env vars) / blocked (write_blocked)
The three evidence states present / absent / unreadable; a missing file must not be read as "no failure"
resultKind machine-readable outcome for generator tools: ok / generation_failed / write_blocked (the two failures must not be conflated)
total the number of results returned this call, varies with the limit you pass; not the total corpus hit count
totalPool / truncated candidates this facet had before the output window / whether more pages remain
semantic whether this retrieval used the semantic index; false = degraded to keywords (stale = index out of date)
verbatim whether a hit is "this identifier appears verbatim in the page body"; a missing field = undetermined
sourceKind community entry source: authored / permitted / links
verifiedApi per-entry API keys (gameVersion/loader) verified in the library catalog
fallback / source_version on doc fallback: which version the result actually came from / whether fallback occurred
first / second half loop first half = code→build→auto-launch→triage; second half = play in-game→gather evidence→feed back
test ladder (L0–L7) the minimum testing gate before delivery: L0 build → L1 structure and static checks → L2 data → L3 GameTest → L4 in-game smoke → L5 scenario → L6 server / multiplayer → L7 regression; a red lower layer blocks the higher ones, and the floor is the widest one matching what you changed (no evidence means red — see the three evidence states). See "Playtest requirement (delivery gate)" in the root AGENTS.md
version outside the table a version not in PLAYTEST_VERIFIED_TIER: no real driver is generated for it, but it still has to be tested — use the bridge route or play by hand, and state honestly whether it was verified manually or not at all
three channels the authorization channels for playtest execution rights (A repo sandbox / B user dev instance / C third-party bridge)

Uninstall and rollback

  • Remove rules / Skills written into a user project: activate_platform_pack action=deactivate (rewrites back per the write manifest); run the action=write dryRun preview first to see planned / willDelete.
  • Remove a playtest driver: delete the driver files plus the PlaytestQaDriver.register(); call line in the target project per the generated playtest/REVERT.md; git status should show zero hits (the driver is never committed).
  • Remove the CLI / MCP install: npm uninstall -g mc-ai-coding-assistant-tool (the package name; the bins are mc-skill / mc-skill-scripts, and you can also just delete the bin symlinks); the repo's mcp-server/ and data/ can simply be deleted (both live inside the repo and do not touch the user's mod project).
  • Roll back a self-update: mc_skill_update only does git ff-only merges, so roll back with git reset --hard <previous commit> (tooling) or restore the previous data zip; uncommitted changes block the update (optionally allowDirty / stashDirty).
  • Cache and temp artifacts: decompilation / MDK / semantic-model artifacts live in $MC_SKILL_CACHE (default %APPDATA%/mc-skill-cache); deleting it affects neither the repo nor the user project.

Phase milestones

Phase Status Content
Phase 1 ✅ done rule sets for Forge / Fabric / NeoForge plus multi-version expansion
Phase 1.5 ✅ done mod scaffold + validation CLI
Phase 2 ✅ done Agent Skills + the code pattern library
Phase 3 ✅ done MCP Server (docs + mappings + porting + community + Wave B/C/D extensions + five platforms; the tool count is whatever list-tools says)
Phase 4 ✅ done knowledge base / anti-patterns / data audit and Release distribution
Phase 4.5 ✅ done Full library mod coverage: the lib-* essay series + the library Skill source system (read knowledge/libs/README.md §current scale) + an enhanced check_dependencies + the decompilation data chain (artifacts generated on demand into $MC_SKILL_CACHE, not committed; the verifiedApi key counting rule is in CONTRIBUTING.md) + API summaries + manifest + generic CLI dispatch
Phase 5 📋 partial inspect_runtime is a log-based inspector (not JVM attach); the fine-tuning dataset is still on hold

Pointer table (external landing spots)

Every external landing spot this file refers to is listed here (cross-references inside this file are not). Usage: find the row by topic; the third column gives the trigger and how to read it.

What Landing spot When to read it / how
Standing rules (human-in-the-loop / testing gate / tool boundaries) AGENTS.md before starting any round; the "verified boundaries" under its in-game-playtest exception decide "can this version run / what can the bridge test"
MCP installation and host configuration (the one and only manual) AUTO_SETUP.md follow its steps when installing or fixing MCP (Step 0-pre path check → Step 6 install Skills); its opening "Agent must-read: execution order" is a hard constraint
Tool error codes: measured failures + full coverage list doc/tool-error-codes.md read it when you get a code / errorKind; never write a code you did not measure
Per-batch implementation history (gates and baselines) mcp-server/CHANGELOG.md "which batch changed what, and why"
Corpus provenance / re-sourcing / per-version re-test history CORPUS_PROVENANCE.md before quoting version coverage or corpus counts
In-game playtest: criteria / pitfalls / per-round evidence (its §真机台账 = current criteria T5 + archives T0–T4) community_knowledge/authored/ingame-playtest-automation.md read before running any playtest; if your combo is not in the ledger, treat it as unverified — do not extrapolate from a neighbouring version
Per-round delivery drafts (numbered blocks, rolling, newest on top) DELIVERY_LOG.md handoff / overnight runs / spot checks; append-only
Delivery report form (tier judging + main 4 blocks + maintenance 6 blocks + managed-surface list) REPORT-FORMAT.md before writing a delivery draft; if it is unreadable, answer with the three human-facing items from AGENTS.md and name the missing form
Maintenance night-batch receipts (rolling) NIGHT_BATCH.md night-batch queue and morning spot checks
Debt and decision ledger (batches / unplanned items) CONTRIBUTING_LIST.md "decided but not done / waiting on a decision"
Release-increment ledger (V1.0.4..HEAD, item by item) root CHANGELOG.md / bugfix_list.md moved into the Release body when publishing
Contribution / verification discipline / data-chain rules CONTRIBUTING.md before touching gates, scripts, or managed-surface docs
Authoring rules (writing docs for agents) WRITING-FOR-AGENTS.md before writing or editing any agent-facing doc
Community-essay usage discipline (essays are not API specs) community_knowledge/AGENT_USAGE.md before writing code from an essay; when unsure, open the original URL it cites
Community knowledge index (full topic table) community_knowledge/README.md finding essays: publishing / crash triage / soft dependencies / machine GUI / localization …
Library-mod Skill sources (read directly per group mapping; not projected) knowledge/libs/<group>/mc-<name>/SKILL.md (overview: knowledge/libs/README.md) library selection / usage; unsure which → read all-platforms/mc-lib-catalog first
Full tool semantics (global flag table / Standalone CLI section / tool index / install config) mcp-server/README.md CLI details, npm run scripts, the MCP tool surface
mcp-server additional docs (mixin-support / vanilla-registries / registry-data-source / mc-skill-update / prompts-client-compat) mcp-server/docs/ bytecode-verification matrix / registry sources / self-update / prompt compatibility
Human-facing README (multi-IDE sync list, plain-language start) README_human.md the entry for people; English: README_human.en.md
Third-party documentation and mapping licenses THIRD_PARTY_NOTICES.md distribution / licensing questions