Architecture

Architecture

minecraft-mcp sits between an MCP client and WorldAPI. The client talks MCP over stdio or Streamable HTTP; minecraft-mcp turns each tool call into a WorldAPI REST call and listens to WorldAPI's WebSocket for live events.

Code map

Path	What it does
src/index.ts	Flags and transport: stdio, or Streamable HTTP at /mcp with a bearer token.
src/config.ts	Reads the environment and blanks the token out of any text.
src/server.ts	Builds the MCP server: tools, resources, prompts, and the instructions the agent reads first.
src/tool.ts	Registers a tool with the permission it needs and its MCP annotations; untrusted tools fence game text as data.
src/tools/	One file per group: server, worlds, blocks, entities, players, stats, files, scripts, extensions.
src/scopes.ts	WorldAPI's permissions; asks the WebSocket hello which ones the token has.
src/events.ts	The live event feed behind the events and console resources.
src/resources.ts, src/prompts.ts	MCP resources and prompts.
src/client.ts	The typed WorldAPI client and its errors.
src/version.ts	This package's version and MIN_WORLDAPI, the oldest WorldAPI it supports.
src/generated/worldapi.ts	Types generated from openapi/worldapi.json; never edit by hand.
manifest.json	The Claude Desktop bundle's manifest.
server.json	The MCP Registry entry.

Start-up

1. configFromEnv reads and checks the environment.
2. discoverScopes opens WorldAPI's WebSocket, sends the token in the first message, and reads the permissions from the answer. If that fails, it assumes what anonymous clients get.
3. checkWorldApi warns when WorldAPI is older than MIN_WORLDAPI.
4. buildServer registers each tool whose permission the token has. In read-only mode it skips every tool whose effect isn't read.

A tool

Each tool declares:

• scope: the permission WorldAPI's endpoint checks, as openapi.json states it. It can be one permission, { all: [...] }, or { any: [...] }.
• effect: read, write, idempotent, or destructive. It sets the MCP hints readOnlyHint, destructiveHint, and idempotentHint.
• untrusted: set when the result can hold text players wrote. The result then sits in a <game-data> fence.

Every result passes through the token redaction, and errors carry WorldAPI's error code.

Next: Development.