minecraft-bedrock-mcp-server 0.1.0

package/dist/tools/tool-definition.js

@@ -0,0 +1,40 @@
+import { toCallToolResult } from "./tool-result.js";
+/**
+ * Defines a tool whose handler validates input, enqueues a command whose
+ * `kind` is the tool name, awaits the behavior pack's result, and returns it
+ * as a consistent tool envelope.
+ */
+export function defineQueuedTool(config) {
+    return {
+        name: config.name,
+        title: config.title,
+        description: config.description,
+        inputShape: config.inputShape,
+        annotations: config.annotations,
+        handler: async (input, context) => {
+            const payload = config.toPayload === undefined ? input : config.toPayload(input);
+            const result = await context.queue.enqueueAndAwait({
+                kind: config.name,
+                payload,
+                correlationId: context.correlationId,
+                timeoutMs: context.commandTimeoutMs,
+            });
+            return toCallToolResult(result);
+        },
+    };
+}
+/**
+ * Defines a tool whose handler runs locally — filesystem operations, or tools
+ * that work directly with the subscription registry.
+ */
+export function defineLocalTool(config) {
+    return {
+        name: config.name,
+        title: config.title,
+        description: config.description,
+        inputShape: config.inputShape,
+        annotations: config.annotations,
+        handler: config.handler,
+    };
+}
+//# sourceMappingURL=tool-definition.js.map

package/dist/tools/tool-definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-definition.js","sourceRoot":"","sources":["../../src/tools/tool-definition.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AA+CpD;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAA+B;IAE/B,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YAChC,MAAM,OAAO,GACX,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,KAAuB,CAAC,CAAC;YACrF,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC;gBACjD,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,OAAO;gBACP,aAAa,EAAE,OAAO,CAAC,aAAa;gBACpC,SAAS,EAAE,OAAO,CAAC,gBAAgB;aACpC,CAAC,CAAC;YACH,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;KACF,CAAC;AACJ,CAAC;AAYD;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,MAA8B;IAE9B,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAoC;KACrD,CAAC;AACJ,CAAC"}

package/dist/tools/tool-result.d.ts

@@ -0,0 +1,17 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { CommandResult } from "../protocol/index.js";
+/**
+ * Builds a successful tool result.
+ *
+ * The payload is carried once, as a TOON text block. Tools declare no
+ * `outputSchema`, so no redundant `structuredContent` copy is emitted — the
+ * text block is the single machine- and human-readable representation.
+ */
+export declare function toolSuccess(data: unknown): CallToolResult;
+/** Builds a failed tool result carrying a stable error code. */
+export declare function toolError(code: string, message: string, details?: unknown): CallToolResult;
+/** Maps a behavior-pack {@link CommandResult} to a tool envelope. */
+export declare function toCallToolResult(result: CommandResult): CallToolResult;
+/** Maps an error thrown by a tool handler to a tool envelope. */
+export declare function toErrorResult(error: unknown): CallToolResult;
+//# sourceMappingURL=tool-result.d.ts.map

package/dist/tools/tool-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result.d.ts","sourceRoot":"","sources":["../../src/tools/tool-result.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAiB1D;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAKzD;AAED,gEAAgE;AAChE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,cAAc,CAM1F;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CAItE;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAK5D"}

package/dist/tools/tool-result.js

@@ -0,0 +1,52 @@
+import { encode } from "@toon-format/toon";
+import { BridgeError } from "../errors/bridge-error.js";
+/**
+ * Serializes a tool payload as TOON (Token-Oriented Object Notation).
+ *
+ * TOON is a compact, LLM-oriented encoding of the JSON data model: it drops
+ * JSON's braces, quotes, and repeated keys, and renders uniform object arrays
+ * as a single header plus CSV-style rows. For the tabular results this server
+ * produces — block volumes, entity component dumps, player and event lists —
+ * that is materially fewer tokens than JSON, and never more than the
+ * pretty-printed JSON this previously emitted.
+ */
+function serialize(data) {
+    if (data === undefined)
+        return "(no content)";
+    return encode(data);
+}
+/**
+ * Builds a successful tool result.
+ *
+ * The payload is carried once, as a TOON text block. Tools declare no
+ * `outputSchema`, so no redundant `structuredContent` copy is emitted — the
+ * text block is the single machine- and human-readable representation.
+ */
+export function toolSuccess(data) {
+    return {
+        content: [{ type: "text", text: serialize(data) }],
+        isError: false,
+    };
+}
+/** Builds a failed tool result carrying a stable error code. */
+export function toolError(code, message, details) {
+    const error = { code, message, ...(details === undefined ? {} : { details }) };
+    return {
+        content: [{ type: "text", text: encode({ error }) }],
+        isError: true,
+    };
+}
+/** Maps a behavior-pack {@link CommandResult} to a tool envelope. */
+export function toCallToolResult(result) {
+    return result.status === "ok"
+        ? toolSuccess(result.result)
+        : toolError(result.error.code, result.error.message, result.error.details);
+}
+/** Maps an error thrown by a tool handler to a tool envelope. */
+export function toErrorResult(error) {
+    if (BridgeError.is(error)) {
+        return toolError(error.code, error.message, error.details);
+    }
+    return toolError("INTERNAL", error instanceof Error ? error.message : "unexpected error");
+}
+//# sourceMappingURL=tool-result.js.map

package/dist/tools/tool-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result.js","sourceRoot":"","sources":["../../src/tools/tool-result.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGxD;;;;;;;;;GASG;AACH,SAAS,SAAS,CAAC,IAAa;IAC9B,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,cAAc,CAAC;IAC9C,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAa;IACvC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QAClD,OAAO,EAAE,KAAK;KACf,CAAC;AACJ,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,OAAe,EAAE,OAAiB;IACxE,MAAM,KAAK,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAC/E,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QACpD,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,gBAAgB,CAAC,MAAqB;IACpD,OAAO,MAAM,CAAC,MAAM,KAAK,IAAI;QAC3B,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC;QAC5B,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC/E,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,WAAW,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,SAAS,CAAC,UAAU,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC;AAC5F,CAAC"}

package/dist/tools/world-tools.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from "./tool-definition.js";
+/** World queries and world-level mutations. */
+export declare const worldTools: readonly ToolDefinition[];
+//# sourceMappingURL=world-tools.d.ts.map

package/dist/tools/world-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-tools.d.ts","sourceRoot":"","sources":["../../src/tools/world-tools.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAS7E,+CAA+C;AAC/C,eAAO,MAAM,UAAU,EAAE,SAAS,cAAc,EAuF/C,CAAC"}

package/dist/tools/world-tools.js

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import { DimensionSchema, MessageSchema, Vector3Schema } from "./common-schemas.js";
+import { defineQueuedTool } from "./tool-definition.js";
+const READ_ONLY = { readOnlyHint: true };
+const SoundOptionsSchema = z.object({
+    volume: z.number().nonnegative().optional(),
+    pitch: z.number().positive().optional(),
+});
+/** World queries and world-level mutations. */
+export const worldTools = [
+    defineQueuedTool({
+        name: "mc_world_get_info",
+        title: "Get world info",
+        description: "Returns the world name, Minecraft version, online player count, current " +
+            "tick, and day count.",
+        inputShape: {},
+        annotations: READ_ONLY,
+    }),
+    defineQueuedTool({
+        name: "mc_world_get_time",
+        title: "Get world time",
+        description: "Returns the absolute time and the time of day.",
+        inputShape: {},
+        annotations: READ_ONLY,
+    }),
+    defineQueuedTool({
+        name: "mc_world_get_weather",
+        title: "Get weather",
+        description: "Returns the current weather in a dimension.",
+        inputShape: { dimension: DimensionSchema },
+        annotations: READ_ONLY,
+    }),
+    defineQueuedTool({
+        name: "mc_world_get_dimensions",
+        title: "List dimensions",
+        description: "Returns the identifiers of every dimension.",
+        inputShape: {},
+        annotations: READ_ONLY,
+    }),
+    defineQueuedTool({
+        name: "mc_world_get_dimension_info",
+        title: "Get dimension info",
+        description: "Returns details for a dimension, such as its height range.",
+        inputShape: { dimension: DimensionSchema },
+        annotations: READ_ONLY,
+    }),
+    defineQueuedTool({
+        name: "mc_world_set_time",
+        title: "Set world time",
+        description: "Sets the time of day.",
+        inputShape: {
+            value: z.number().int().min(0).describe("Time of day in ticks (0-24000)."),
+        },
+    }),
+    defineQueuedTool({
+        name: "mc_world_set_weather",
+        title: "Set weather",
+        description: "Sets the weather in a dimension.",
+        inputShape: {
+            dimension: DimensionSchema,
+            type: z.enum(["Clear", "Rain", "Thunder"]),
+            duration: z.number().int().positive().optional().describe("Duration in ticks."),
+        },
+    }),
+    defineQueuedTool({
+        name: "mc_world_send_message",
+        title: "Send a chat message",
+        description: "Sends a chat message to all players or to a specific player.",
+        inputShape: {
+            target: z.string().min(1).describe("A player name, or 'all' for everyone."),
+            message: MessageSchema,
+        },
+    }),
+    defineQueuedTool({
+        name: "mc_world_play_sound",
+        title: "Play a sound",
+        description: "Plays a sound at a location in a dimension.",
+        inputShape: {
+            dimension: DimensionSchema,
+            sound: z.string().min(1),
+            location: Vector3Schema,
+            options: SoundOptionsSchema.optional(),
+        },
+    }),
+    defineQueuedTool({
+        name: "mc_world_spawn_particle",
+        title: "Spawn a particle",
+        description: "Spawns a particle effect at a location in a dimension.",
+        inputShape: {
+            dimension: DimensionSchema,
+            name: z.string().min(1).describe("Particle type id, e.g. minecraft:basic_flame_particle."),
+            location: Vector3Schema,
+            molang_variables: z.record(z.number()).optional(),
+        },
+    }),
+];
+//# sourceMappingURL=world-tools.js.map

package/dist/tools/world-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-tools.js","sourceRoot":"","sources":["../../src/tools/world-tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "minecraft-bedrock-mcp-server",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server that bridges MCP clients to a Minecraft Bedrock Dedicated Server.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "minecraft",
+    "minecraft-bedrock",
+    "bedrock-dedicated-server",
+    "bds",
+    "ai-agents"
+  ],
+  "license": "MIT",
+  "author": "John Chapman",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chapmanjw/minecraft-bedrock-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chapmanjw/minecraft-bedrock-mcp-server/issues"
+  },
+  "homepage": "https://github.com/chapmanjw/minecraft-bedrock-mcp-server#readme",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "minecraft-bedrock-mcp-server": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "dependencies": {
+    "@fastify/cors": "^10.0.0",
+    "@fastify/rate-limit": "^10.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@toon-format/toon": "^2.2.0",
+    "fastify": "^5.0.0",
+    "pino": "^9.0.0",
+    "prom-client": "^15.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.13.0",
+    "@types/node": "^20.17.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "eslint": "^9.13.0",
+    "pino-pretty": "^13.0.0",
+    "prettier": "^3.3.3",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.3",
+    "typescript-eslint": "^8.12.0",
+    "vitest": "^3.0.0"
+  }
+}