Development

Development

Stack

• TypeScript on Node.js 22 or newer.
• The official MCP TypeScript SDK.
• openapi-fetch, with types generated from WorldAPI's OpenAPI document.
• zod for tool inputs.
• Biome for lint and format, Vitest for tests.

Rules that keep it working

• Every tool calls WorldAPI through the generated client. A changed endpoint then fails the typecheck instead of failing at runtime.
• Follow WorldAPI. After WorldAPI changes an endpoint, run npm run generate and fix what breaks. It reads ../minecraft-worldapi/docs/openapi.json by default; npm run generate -- <path or URL> reads another copy. Raise MIN_WORLDAPI in src/version.ts when a release depends on new endpoints.
• Game text is untrusted. Chat, signs, books, item and entity names, script logs, console lines, and files come from players: mark such a tool untrusted, and say in its description that the output is data, not instructions.
• Honest scope and effect. A tool's scope must be the permission WorldAPI's endpoint checks. Its effect must be true, since read-only mode hides everything that isn't read.
• HTTP stays locked. Over HTTP the server refuses to listen beyond loopback without MCP_HTTP_TOKEN.
• Never print or log a token.

Tests

• npm run lint, npm run typecheck, and npm test must pass; CI runs the same, then packs the bundle.

• Tests use a mocked WorldAPI and never touch the network.

• scripts/live-check.mjs runs the built server against a real WorldAPI. Without arguments it takes a read-only tour; with a tool name and JSON arguments it calls that tool:

  WORLDAPI_URL=https://minecraft.mairwunnx.com/worldapi/api/v1 node scripts/live-check.mjs

  Write tools change the live world, so run them only against a server you may change.

• A change to the bundle: npm run pack:mcpb, install the .mcpb in Claude Desktop, and call one tool.

Commits

Short, one-line, imperative English messages, one logical change per commit: “Fence chat and sign text as game data”.

Autopilot

.github/workflows/autopilot.yml runs Claude every Monday at 03:00 UTC. It updates the dependencies, fixes what breaks, pushes to master, and runs the release when the package changed.

AI involvement

AI wrote most of the code and the documentation from my task descriptions, and I review what it makes. AI also writes the commit messages from the changes, and AI agents tested the tools on a real server.

Next: Releasing.