muninn-mcp

Read-only Model Context Protocol server for one Muninn Minecraft backend.

One process always represents exactly one game backend. It has one Muninn base URL, one backend bearer token, and one discovered server_id. Run a separate process for each backend because installed plugins and capabilities can differ.

The default MCP transport is the official stateful Streamable HTTP transport from the MCP TypeScript SDK. Stdio remains available as a fallback.

Requirements

• Node.js 20 or newer

• a reachable Muninn plugin HTTP API

• the backend bearer token from plugins/Muninn/config.yml

This implementation targets Muninn plugin API 0.1.0 at plugin commit 6ef77aafb1cb0f634020d48ca5621885bb103940.

Related MCP server: Discord Message Finder MCP

HTTP-first start

npm ci
npm run build

MUNINN_BASE_URL=http://127.0.0.1:8781 \
MUNINN_AUTH_TOKEN='<Muninn backend token>' \
MUNINN_EXPECTED_SERVER_ID=survival \
MUNINN_MCP_AUTH_TOKEN='<separate MCP client token>' \
npm start

Defaults:

• transport: http

• bind: 127.0.0.1

• port: 3000

• MCP endpoint: http://127.0.0.1:3000/mcp

• readiness endpoint: http://127.0.0.1:3000/healthz

The incoming MUNINN_MCP_AUTH_TOKEN is deliberately separate from MUNINN_AUTH_TOKEN. The first protects MCP clients → this process; the second protects this process → the Minecraft backend. Never reuse them.

An HTTP MCP client connects to the URL and supplies the static token:

{
  "mcpServers": {
    "muninn-survival": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer <MUNINN_MCP_AUTH_TOKEN>"
      }
    }
  }
}

The exact client configuration envelope is client-specific; the URL, standard Authorization header, and Streamable HTTP protocol are not.

Readiness needs no token and exposes no configuration secrets:

curl http://127.0.0.1:3000/healthz

The process first discovers the backend through /health and /capabilities. It only starts listening after backend identity and capabilities have passed fail-fast validation.

Stdio fallback

MUNINN_TRANSPORT=stdio \
MUNINN_BASE_URL=http://127.0.0.1:8781 \
MUNINN_AUTH_TOKEN='<Muninn backend token>' \
MUNINN_EXPECTED_SERVER_ID=survival \
npm start

Example stdio client entry:

{
  "mcpServers": {
    "muninn-survival": {
      "command": "node",
      "args": ["/absolute/path/to/muninn-mcp/dist/index.js"],
      "env": {
        "MUNINN_TRANSPORT": "stdio",
        "MUNINN_BASE_URL": "http://127.0.0.1:8781",
        "MUNINN_AUTH_TOKEN": "<Muninn backend token>",
        "MUNINN_EXPECTED_SERVER_ID": "survival"
      }
    }
  }
}

Configuration

MCP transport

For a private-network listener:

MUNINN_MCP_BIND=0.0.0.0 \
MUNINN_MCP_ALLOWED_HOSTS=minecraft-admin.internal,192.0.2.20 \
MUNINN_MCP_AUTH_TOKEN='<high-entropy token>' \
npm start

The built-in listener is plain HTTP. Do not expose it directly to the public internet. Keep it on loopback/private networking or place TLS and appropriate network controls in front of it.

Muninn backend

Backend limits remain authoritative and may be stricter.

HTTP security and lifecycle

• Host validation is port-independent and deny-by-default.

• Browser requests with an Origin header are denied unless the exact origin is allowlisted. CORS never uses * and never enables credentials.

• Incoming auth uses constant-time comparison of SHA-256 token digests.

• Request bodies are parsed only after MCP authentication and are capped at 256 KiB.

• Neither backend nor incoming bearer values are logged or returned in errors, including nested backend payloads.

• Each initialize request gets a cryptographically random stateful MCP session, its own official StreamableHTTPServerTransport, and its own McpServer.

• Subsequent POST/GET/DELETE requests require a valid Mcp-Session-Id.

• HTTP DELETE terminates a session. SIGINT/SIGTERM stop accepting requests, close all active transports/SSE streams, and close the HTTP server.

• Sessions are in memory and are not resumable across process restarts; clients initialize again after a restart.

Capability-aware tools

Only tools whose endpoint is present in an enabled module's capability report are registered. CoreProtect tools also require the corresponding feature flag. Restart the process after backend plugin/capability changes to refresh tools/list.

All tools are annotated read-only, non-destructive, and idempotent. The Paper batch endpoint uses HTTP POST but does not mutate game state.

Core and composite

• server_status

• investigate_block — bounded Paper/CoreProtect/WorldGuard context with independent probe results

CoreProtect primitives

• coreprotect_block_lookup

• coreprotect_container_lookup

• coreprotect_item_lookup

• coreprotect_inventory_lookup

• coreprotect_chat_lookup

• coreprotect_command_lookup

• coreprotect_session_lookup

• coreprotect_sign_lookup

• coreprotect_username_lookup

• coreprotect_queue_lookup

Paper primitives

• paper_get_container

• paper_batch_containers (1–64 locations)

• paper_get_player_inventory

• paper_get_player_ender_chest

• paper_get_player_state

• paper_get_player_stats

• paper_list_players

• paper_get_server_info

• paper_list_entities

• paper_get_block

CMI primitives

• cmi_list_players

• cmi_get_player

• cmi_get_player_homes

• cmi_list_warps

• cmi_list_jails

WorldGuard primitives

• worldguard_list_regions

• worldguard_get_region

• worldguard_regions_at

• worldguard_flags_at

Paginated tools always send explicit bounded offset/limit values and return the backend's has_more marker for deliberate follow-up.

Errors

Muninn envelopes become readable MCP tool errors with stable codes, safe details, HTTP status, backend ID, guidance, and retryability where applicable: UNAUTHORIZED, NOT_FOUND, BAD_REQUEST, SYNC_TIMEOUT, MODULE_DISABLED, FEATURE_UNAVAILABLE, LIMIT_EXCEEDED, PLAYER_OFFLINE, and INTERNAL.

Transport-side errors include TIMEOUT, NETWORK_ERROR, CANCELLED, INVALID_RESPONSE, and SERVER_ID_MISMATCH.

HTTP routing/auth errors use bounded JSON/JSON-RPC bodies and never echo Host, Origin, authorization values, request bodies, or internal exceptions.

Verification

npm ci
npm run check
npm test

The suite covers:

• HTTP-default and stdio process startup/shutdown;

• official StreamableHTTPClientTransport initialize, initialized notification, tools/list, tools/call, SSE, and DELETE lifecycle;

• incoming auth 401, Host/Origin/CORS policy, invalid methods and sessions;

• non-zero invalid configuration;

• recursive secret redaction;

• all 29 atomic tool-to-endpoint mappings and capability filtering.

Real plugin Docker harness

The cross-project test starts the adjacent real Paper+CoreProtect+CMI+WorldGuard fixture, starts the built HTTP MCP process, connects through the official Streamable HTTP client, calls paper_get_server_info, and removes all temporary processes/containers:

npm run test:e2e:harness

By default the plugin checkout is expected at ../muninn-plugin:

MUNINN_PLUGIN_DIR=/absolute/path/to/muninn-plugin npm run test:e2e:harness

An already-running backend can be tested directly:

MUNINN_E2E_BASE_URL=http://127.0.0.1:8781 \
MUNINN_E2E_AUTH_TOKEN='<backend token>' \
MUNINN_E2E_SERVER_ID=survival \
npm run test:e2e

The stdio fallback remains covered by the normal test suite.

Releases and npm publication

Release Please watches conventional commits on main, maintains a release PR, updates CHANGELOG.md, package.json, package-lock.json, and the release manifest, then creates a vX.Y.Z GitHub Release when that release PR is merged. The same workflow checks and tests the released commit before publishing @vanilla-game/muninn-mcp as a public npm package with provenance.

The package is not published yet, so the first release needs a short-lived npm granular access token with permission to create packages in the vanilla-game scope. Store it as the NPM_TOKEN GitHub Actions secret. After the bootstrap publish succeeds, configure npm Trusted Publishing for:

• GitHub organization: Vanilla-Game

• repository: muninn-mcp

• workflow filename: release-please.yml

• allowed action: npm publish

Then remove the NPM_TOKEN repository secret. Future releases use GitHub OIDC through the workflow's id-token: write permission instead of a long-lived npm credential. The npm package's repository URL must continue to match this GitHub repository exactly.

By default Release Please uses the workflow's GITHUB_TOKEN. An optional RELEASE_PLEASE_TOKEN GitHub secret can supply a GitHub App or fine-grained PAT when repository policy requires release PR events to trigger other workflows.

License

MIT