minecraft-developing-mcp

License: PolyForm Noncommercial 1.0.0 Node.js >=22.5.0 MCP stdio

MCP server for AI-assisted Minecraft development.

It helps an AI agent inspect real project evidence before writing Minecraft modding code. It is meant for Java mod projects, KubeJS modpacks, datapacks, resource packs, Gradle workspaces, crash logs, local mod jars, nested JarJar dependencies, mappings, and optional offline documentation packages.

The public tool surface is intentionally small: clients normally run the mc-developing-mcp binary and call one MCP tool, mc_develop.

Why Use It?

Generic coding agents often waste context on Minecraft projects because the useful information is scattered across Gradle files, generated ProbeJS declarations, local jars, crash logs, datapack JSON, resource-pack assets, and version-specific APIs.

minecraft-developing-mcp gives the agent a focused way to ask:

You are trying to do this	What the MCP can check first
Fix a modpack crash	Logs, missing classes, mixin targets, metadata, owner jars, nested JarJar content.
Write or fix KubeJS	KubeJS folders, ProbeJS .d.ts, snippets, registries, items, events, and diagnostics.
Work on a Java mod	Gradle dependencies, Maven repositories, source jars, Java diagnostics, mappings, and local source indexes.
Edit datapacks	Pack roots, resource locations, version profiles, migration warnings, and vanilla datapack profiles.
Edit resource packs/client visuals	Assets, models, item references, resource paths, client rendering hints, and shader reference hooks.
Use offline docs	Explicitly installed MDM resource packages and SQLite indexes in a local cache.

The goal is not to replace the coding agent. The goal is to make the agent stop guessing and start from project evidence.

Installation

Stable install:

npm install -g minecraft-developing-mcp

Run the server:

mc-developing-mcp

For MCP clients, prefer npx so the project stays easy to update:

{
  "mcpServers": {
    "minecraft-developing": {
      "command": "npx",
      "args": ["-y", "--package", "minecraft-developing-mcp@latest", "mc-developing-mcp"]
    }
  }
}

Optional agent Skill:

npx skills add PickAID/mc-developing-mcp --skill mc-develop-first -g -a codex -y

This installs skills/mc-develop-first, a pluggable operating guide for agents. It makes mc_develop the first evidence step for Minecraft APIs, schemas, loader behavior, crash causes, KubeJS/ProbeJS context, datapack/resource-pack version details, local jar ownership, docs/version resources, and runtime environment handling. The Skill includes task-specific playbooks under references/ so agents can route KubeJS, crashes, Java/Gradle mods, datapacks/resource packs, docs resources, and runtime root questions without adding rules to AGENTS.md.

To remove it:

npx skills remove mc-develop-first -g -a codex -y

The older singular skill CLI currently uses npx skill skills/<name> and does not support an add subcommand in skill@1.0.2. If you specifically use that CLI, install from this repository by setting its base URL to the GitHub tree:

SKILL_BASE_URL=https://github.com/PickAID/mc-developing-mcp/tree/main npx skill skills/mc-develop-first

Requirements:

• Node.js >=22.5.0
• An MCP client that supports stdio servers
• A Minecraft project or modpack root when you want workspace-specific evidence
• A local Java JDK when you want Gradle, Java LSP/JDTLS, ForgeGradle/NeoForgeGradle, source generation, or Minecraft mod project diagnostics. The MCP can inspect some files without Java, but real Java mod evidence needs the same kind of JDK the project itself needs.

Recommended JDK baselines for Minecraft development:

Minecraft target	Typical JDK
1.18.2 to 1.20.1	JDK 17
1.20.5 to current modern releases	JDK 21 unless the loader/project says otherwise

Set JAVA_HOME or use the JDK selected by your Gradle toolchain. If Java diagnostics or Gradle evidence looks incomplete, first verify:

java -version
./gradlew --version

Basic Use

Ask your MCP client to use mc_develop before it writes code or diagnoses a Minecraft issue.

Example request:

{
  "requestText": "This modpack crashes during startup. Find the likely missing class owner before suggesting a fix.",
  "workspaceRoot": "/path/to/minecraft-or-project"
}

KubeJS example:

{
  "requestText": "Inspect ProbeJS/KubeJS context, then help fix this recipe script.",
  "workspaceRoot": "/path/to/PrismLauncher/instances/Example/minecraft"
}

Datapack/resource-pack example:

{
  "requestText": "Check whether this resource location and model path are valid for this pack before editing assets.",
  "workspaceRoot": "/path/to/resourcepack-or-modpack"
}

The response is compact evidence for the agent: detected workspace facts, relevant files, package status, route decisions, warnings, and follow-up actions.

Structured Output

mc_develop returns both human-readable text and structuredContent. The structured output is meant for agents and MCP clients that need reliable fields instead of parsing prose.

Top-level summaries currently include:

Field	What it gives the agent
workspacePreparation	Route readiness, detected workspace shape, missing prerequisites, and next call patterns.
crashSignals	Compact crash/log signals such as exception classes, owner hints, resource paths, and FTB-related errors.
javaDiagnostics	Java/LSP diagnostic counts and representative diagnostics when a Java diagnostics route runs.
kubeJsQuality	KubeJS script quality warnings and evidence gathered from KubeJS/ProbeJS routes.
clientVisualVerifier	Client visual proof-chain status for assets, models, rendering, UI, and shader-oriented work.

These summaries are intentionally shallow entry points. When an agent needs details, it should follow the referenced evidence blocks and suggested nextCallPatterns instead of guessing or issuing unrelated searches.

Optional Offline Resources

The npm package does not bundle large generated datasets. Offline documentation and version profiles are distributed separately through MDM resource releases and are installed only when explicitly requested.

Current public resource manifest:

https://github.com/PickAID/mdm-sources/releases/download/mdm-resources-v0.2.0/mdm-release-manifest.json

Start with a discovery call that does not download anything:

{
  "requestText": "Check whether an offline docs package would help this task."
}

After structuredContent.resourceActions.actions suggests a package and the user confirms the download, call again with the suggested patch and downloadPolicy: "allowed":

{
  "requestText": "Install the compact offline docs index and use it for this task.",
  "mdmReleaseInstall": {
    "manifestUrl": "https://github.com/PickAID/mdm-sources/releases/download/mdm-resources-v0.2.0/mdm-release-manifest.json",
    "packageId": "core-docs-search-sqlite",
    "downloadPolicy": "allowed"
  }
}

Recommended progressive flow:

1. Ask mc_develop for the task without mdmReleaseInstall.
2. Inspect structuredContent.resourceActions.actions.
3. If the suggested package is appropriate, call mc_develop again with that action's inputPatch.mdmReleaseInstall, changing downloadPolicy from disabled to allowed only after user confirmation.
4. The next result can reuse the installed docs/source index artifacts from the local runtime cache.

Common resource package types:

Type	Example
Docs index	core-docs-search-sqlite
Datapack profile	minecraft-1.20.1-vanilla-datapack-profile
Resource-pack profile	minecraft-1.20.1-vanilla-resourcepack-profile
Vanilla schema docs	vanilla-schema-docs
Mapping profile	minecraft-1.20.1-yarn-mapping-profile
Source profile/index	minecraft-1.20.1-vanilla-source-profile

The npm package does not include MDM bundles. A release bundle is only a transport and verification container; the runtime cache stores the requested package artifact and local private indexes under MC_DEVELOPING_MCP_RUNTIME_ROOT. Vanilla datapack/resource-pack data is generated from Mojang distribution metadata on demand. Private modpack caches, generated Minecraft source, ProbeJS outputs, local jar indexes, and user jar-derived bundles should not be committed to this repository.

Vanilla datapack/resource-pack explanation docs are generated in mdm-sources from SpyglassMC/vanilla-mcdoc and misode/misode.github.io. The vanilla-schema-docs bundle internalizes compact mcdoc schema previews, upstream hashes, and misode generator/interpreter references, then refreshes through a scheduled upstream-update workflow before release.

Configuration

Environment variables:

Variable	Purpose
MC_DEVELOPING_MCP_WORKSPACE_ROOT	Default workspace or modpack root if the request does not pass workspaceRoot.
MC_DEVELOPING_MCP_RUNTIME_ROOT	Runtime/cache root. Defaults to ~/.cache/mc-developing-mcp/runtime.
MC_DEVELOPING_MCP_PRISM_ROOT	Optional PrismLauncher root hint. The MCP must not assume Prism metadata exists.
MC_DEVELOPING_MCP_YARN_MAPPING_URL_TEMPLATE	Optional Tiny v2 Yarn mapping URL template. Supports {version}, {minecraftVersion}, and {family}.
MC_DEVELOPING_MCP_YARN_MAVEN_BASE_URL	Optional Fabric Maven base URL for Yarn mapping artifact discovery.
MC_DEVELOPING_MCP_MOJANG_VERSION_MANIFEST_URL	Optional Mojang version manifest URL for Mojmap mapping acquisition.
MC_DEVELOPING_MCP_PARCHMENT_MAVEN_BASE_URL	Optional Parchment Maven base URL for Parchment metadata acquisition.
MDM_SOURCES_ROOT	Optional local mdm-sources checkout for resource development.
CURSEFORGE_API_KEY	Optional CurseForge API key. Create one at https://console.curseforge.com/?#/api-keys.
SHADERTOY_APP_KEY	Optional ShaderToy API key. Without it, use browser-based fallback and compact summaries.

Only MC_DEVELOPING_MCP_* environment names are supported for current setup.

Developer Setup

pnpm install
pnpm build
pnpm test

Targeted server tests:

pnpm --filter minecraft-developing-mcp test

Publish checks:

pnpm publish:check
pnpm publish:dry-run
pnpm publish:install-smoke
pnpm publish:release-check

The publish dry-run and install smoke are important. They verify that the public package does not expose internal workspace dependencies and that the installed mc-developing-mcp binary can initialize and expose mc_develop.

Architecture

This is a TypeScript monorepo.

apps/mcp-server/          Public stdio MCP server package.
apps/agent-runtime/       Private runtime app for local experiments.
packages/*                Internal libraries bundled into the public server package.
docs/architecture/        Runtime and routing design notes.
docs/specs/               Package/resource/source acquisition specs.
docs/standards/           KubeJS and client visual standards.
scripts/                  Publish guards, pack dry-run, and install smoke scripts.

The public MCP API should stay progressive and small. New capabilities should normally be added behind mc_develop routing rather than exposed as many unrelated MCP tools.

Naming And Package Policy

The public package name is intended to be:

minecraft-developing-mcp

The binary remains:

mc-developing-mcp

Older scoped prerelease packages are not the recommended public install path. Use the unscoped stable package above.

License

This project is licensed under the PolyForm Noncommercial License 1.0.0.

Commercial use is not granted by this license. Contact the copyright holder if you need commercial terms.