Development

Development

The full guide is CONTRIBUTING.md. This page is the short version. AI coding agents should read AGENTS.md too.

Layout

Path	What
src/main/java	shared code: bridge, handlers, config, events
src/client/java	client-only code: control, vision, navigation
mcp-server/	the MCP server and agent runtime (TypeScript)
versions/<node>/gradle.properties	per-node Minecraft and loader versions
settings.gradle	declares the nodes (Minecraft version by loader)

One source tree is built for every supported version with Stonecutter. Fabric nodes are named after the version (1.21.8), NeoForge nodes <version>-neoforge.

Build and test

./gradlew ":1.21.1:build"            # one Fabric node
./gradlew ":1.21.1-neoforge:build"   # one NeoForge node
./gradlew ":1.21.1:test" ":1.21.1-neoforge:test"
./gradlew chiseledBuild              # every node, what CI runs

cd mcp-server && npm ci && npm run typecheck && npm test

chiseledBuild needs Gradle on JDK 25 (with JDK 21 installed) and a lot of memory. On a small machine build one node of each loader and let CI do the rest. Jars land in versions/<node>/build/libs/.

Rules that matter

• Loader isolation. Shared code talks to vanilla Minecraft only. Fabric and NeoForge APIs live in packages named after the loader (dev.mcpfabric.fabric, ...neoforge, ...client.fabric, ...client.neoforge); each node compiles only its own.
• Every RPC method is gated by the capability lock of its group, and info.capabilities must report the group the same way.
• New or renamed RPC method: update mcp-server/src/tools.ts, the README tool list, the contract test and the CHANGELOG.
• Game state is touched on the game thread only. Bridge handlers that wait hold a bridge thread, so waits need a bound.
• Version-specific code uses Stonecutter comments; keep the active branch on the newest API.

Adding a Minecraft version

1. Add it to the versions(...) list in settings.gradle.
2. Create versions/<mc>/gradle.properties (copy a neighbour).
3. Run the build and add Stonecutter conditionals for compile errors.

NeoForge nodes use build.neoforge.gradle; see CONTRIBUTING.md.

Pull requests

main is protected: open a pull request, keep it to one logical change, use conventional commit messages (feat:, fix:, docs:, chore:) and make sure CI is green. Say which versions you tested.

Releases

Maintainers only. Pushing vX.Y.Z releases Fabric and neoforge-vX.Y.Z releases NeoForge, each to Modrinth and as a GitHub Release. Steps: docs/RELEASING.md.