breakpoint-mcp 1.0.0

package/dist/tools/runtime.js

@@ -0,0 +1,125 @@
+import { z } from "zod";
+import { gate } from "../confirm.js";
+import { ok } from "./lsp-common.js";
+const confirmField = {
+    confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
+};
+/**
+ * Runtime-bridge tools (Plane C). Each forwards to the in-game autoload
+ * (BreakpointRuntimeBridge) over TCP. These only work while the project is running.
+ */
+function fail(err) {
+    const be = err;
+    return {
+        isError: true,
+        content: [{ type: "text", text: `Runtime error [${be?.code ?? "error"}]: ${be?.message ?? String(err)}` }],
+    };
+}
+export function registerRuntimeTools(server, runtime) {
+    const call = async (method, params = {}) => {
+        try {
+            return ok(await runtime.request(method, params));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    };
+    server.registerTool("runtime_get_tree", {
+        title: "Runtime scene tree",
+        description: "Traverse the LIVE SceneTree of the running game (name, type, path, visibility, children).",
+        inputSchema: { max_depth: z.number().int().positive().optional().describe("Max recursion depth (default 64)") },
+    }, async ({ max_depth }) => call("runtime.get_tree", max_depth ? { max_depth } : {}));
+    server.registerTool("runtime_get_property", {
+        title: "Runtime get property",
+        description: "Read a property from a live node (path relative to the current scene; '/root/...' absolute allowed).",
+        inputSchema: { path: z.string(), property: z.string() },
+    }, async ({ path, property }) => call("runtime.get_property", { path, property }));
+    server.registerTool("runtime_set_property", {
+        title: "Runtime set property",
+        description: "Set a property on a live node. DESTRUCTIVE (mutates running game state) — gated by confirmation. Rich types use the {\"__type__\":...} convention.",
+        inputSchema: { path: z.string(), property: z.string(), value: z.any(), ...confirmField },
+    }, async ({ path, property, value, confirm }) => {
+        const blocked = await gate(server, confirm, `Set live property ${path}.${property}`);
+        if (blocked)
+            return blocked;
+        return call("runtime.set_property", { path, property, value });
+    });
+    server.registerTool("runtime_call_method", {
+        title: "Runtime call method",
+        description: "Invoke a method on a live node. DESTRUCTIVE (arbitrary invocation) — gated by confirmation. Args use the tagged-Variant convention.",
+        inputSchema: { path: z.string(), method: z.string(), args: z.array(z.any()).optional(), ...confirmField },
+    }, async ({ path, method, args, confirm }) => {
+        const blocked = await gate(server, confirm, `Call ${path}.${method}() on the running game`);
+        if (blocked)
+            return blocked;
+        return call("runtime.call_method", { path, method, args: args ?? [] });
+    });
+    server.registerTool("runtime_emit_signal", {
+        title: "Runtime emit signal",
+        description: "Emit a signal from a live node. DESTRUCTIVE — gated by confirmation.",
+        inputSchema: { path: z.string(), signal: z.string(), args: z.array(z.any()).optional(), ...confirmField },
+    }, async ({ path, signal, args, confirm }) => {
+        const blocked = await gate(server, confirm, `Emit signal "${signal}" from ${path}`);
+        if (blocked)
+            return blocked;
+        return call("runtime.emit_signal", { path, signal, args: args ?? [] });
+    });
+    server.registerTool("runtime_inject_input", {
+        title: "Runtime inject input",
+        description: "Inject a synthetic input event for automated play-testing. DESTRUCTIVE. " +
+            "event.kind is 'action' | 'key' | 'mouse_button' | 'mouse_motion'. " +
+            "Example: {\"kind\":\"action\",\"action\":\"jump\",\"pressed\":true}.",
+        inputSchema: {
+            event: z.object({
+                kind: z.enum(["action", "key", "mouse_button", "mouse_motion"]),
+                action: z.string().optional(),
+                strength: z.number().optional(),
+                keycode: z.number().int().optional(),
+                button: z.number().int().optional(),
+                pressed: z.boolean().optional(),
+                position: z.any().optional(),
+                relative: z.any().optional(),
+            }),
+            ...confirmField,
+        },
+    }, async ({ event, confirm }) => {
+        const blocked = await gate(server, confirm, `Inject ${event.kind} input event into the running game`);
+        if (blocked)
+            return blocked;
+        return call("runtime.inject_input", { event });
+    });
+    server.registerTool("runtime_get_monitors", {
+        title: "Runtime performance monitors",
+        description: "Read live Performance monitors (FPS, draw calls, node count, physics, audio output latency, ...). " +
+            "Pass specific keys or omit for all. Keys include time/fps, render/total_draw_calls, audio/output_latency.",
+        inputSchema: { keys: z.array(z.string()).optional() },
+    }, async ({ keys }) => call("runtime.get_monitors", keys ? { keys } : {}));
+    server.registerTool("runtime_screenshot", {
+        title: "Runtime screenshot",
+        description: "Capture the current game frame as a PNG and return it as image content so the assistant can see the running game.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const r = (await runtime.request("runtime.screenshot", {}));
+            return {
+                content: [
+                    { type: "image", data: r.base64, mimeType: r.mime },
+                    { type: "text", text: `Captured game frame (${r.width}x${r.height}).` },
+                ],
+            };
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("runtime_get_log", {
+        title: "Runtime log",
+        description: "Read the runtime log ring buffer (entries game code pushed via BreakpointRuntimeBridge.push_log). " +
+            "Use since_seq for incremental reads.",
+        inputSchema: {
+            since_seq: z.number().int().optional().describe("Return only entries with seq greater than this (default 0)"),
+            levels: z.array(z.string()).optional().describe("Filter to these levels, e.g. [\"error\",\"warning\"]"),
+        },
+    }, async ({ since_seq, levels }) => call("runtime.get_log", { since_seq: since_seq ?? 0, levels: levels ?? [] }));
+}
+//# sourceMappingURL=runtime.js.map

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "breakpoint-mcp",
+  "version": "1.0.0",
+  "description": "MCP server exposing Godot to AI coding assistants over the Model Context Protocol — developed and tested with Claude — across four planes (CLI, live editor, LSP+DAP, runtime) with elicitation-gated destructive tools, long jobs on the formal MCP task model, captured console output, and MCP resources.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "James Livingston",
+    "url": "https://github.com/jlivingston-Cipher"
+  },
+  "homepage": "https://github.com/jlivingston-Cipher/godot-breakpoint-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jlivingston-Cipher/godot-breakpoint-mcp.git",
+    "directory": "host"
+  },
+  "bugs": {
+    "url": "https://github.com/jlivingston-Cipher/godot-breakpoint-mcp/issues"
+  },
+  "keywords": [
+    "godot",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "gdscript",
+    "game-development",
+    "lsp",
+    "dap"
+  ],
+  "bin": {
+    "breakpoint-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc -p tsconfig.test.json && node --test dist-test/test/*.test.js",
+    "start": "node dist/index.js",
+    "dev": "tsc && node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  }
+}