breakpoint-mcp 1.2.0 → 1.3.0

package/README.md

@@ -3,7 +3,7 @@
 The MCP **host** for [Breakpoint MCP](https://github.com/jlivingston-Cipher/godot-breakpoint-mcp) —
 a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
 Godot game engine to AI coding assistants across four planes: headless CLI, the live
-editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **242 tools
+editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **244 tools
 + 5 MCP resources**, built against the stable `@modelcontextprotocol/sdk` 1.x API.
 Developed and tested with **Claude**; because MCP is an open protocol, other clients can
 connect too (currently untested — reports welcome).
@@ -15,10 +15,28 @@ architecture.
 
 ## Install
 
+The fastest path — from your Godot project folder, one command installs and enables the
+editor addon (bundled in this package) and prints your MCP-client config:
+
+```bash
+npx breakpoint-mcp init
+```
+
+Then open the project in Godot and verify the setup:
+
+```bash
+npx breakpoint-mcp doctor
+```
+
+`init` copies the addon into `addons/breakpoint_mcp/`, enables it in `project.godot`, and
+prints — or, with `--client claude-code|claude-desktop|cursor|windsurf|vscode`, writes —
+the client config. `doctor` checks the Godot binary, the addon, and the four bridges
+(add `--require-live` once the editor is open; `--json` for a machine-readable report).
+
+To install the `breakpoint-mcp` command globally instead of invoking it via `npx`:
+
 ```bash
-npx breakpoint-mcp          # run on demand
-# or
-npm i -g breakpoint-mcp     # install the `breakpoint-mcp` command
+npm i -g breakpoint-mcp
 ```
 
 Requires **Node ≥ 18**. The host targets the `@modelcontextprotocol/sdk` `1.x` line
@@ -60,10 +78,11 @@ section for each client's config file and format.
 
 ## The addon (required for the editor / runtime planes)
 
-Install the `breakpoint_mcp` editor addon into your Godot project (drop
-`addons/breakpoint_mcp/` in and enable it under Project Settings → Plugins). It opens the
-loopback servers this host connects to and auto-registers the in-game runtime bridge.
-Without it, only the headless-CLI (`godot_*`) plane works.
+`breakpoint-mcp init` installs and enables this for you — the editor addon ships **inside
+this package**, so you don't need the repository to get it. To do it by hand instead, copy
+`addons/breakpoint_mcp/` into your project and enable it under Project Settings → Plugins.
+Either way it opens the loopback servers this host connects to and auto-registers the
+in-game runtime bridge; without it, only the headless-CLI (`godot_*`) plane works.
 
 ## Local-first
 

package/addon/breakpoint_mcp/plugin.cfg

@@ -3,5 +3,5 @@
 name="Breakpoint MCP"
 description="Exposes the live Godot editor and the running game to an MCP host so an AI assistant can drive them: scene/node/resource CRUD with full undo/redo, project settings, ClassDB, editor + in-game screenshots, and an in-game runtime bridge (live SceneTree, property get/set, method calls, signals, input injection, Performance monitors). Pairs with the breakpoint-mcp MCP host."
 author="James Livingston"
-version="1.2.0"
+version="1.3.0"
 script="plugin.gd"

package/dist/index.js

@@ -43,7 +43,7 @@ async function main() {
     // so long jobs (export/import/headless script) support poll/await/cancel.
     // D3: also advertise resources.subscribe so clients can subscribe to
     // godot://… resources and receive notifications/resources/updated.
-    const server = new McpServer({ name: "breakpoint-mcp", version: "1.2.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.3.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
     // B1: enforce frozen output schemas on every structured tool. Must run before
     // the register*Tools calls below — it wraps server.registerTool.
     applyOutputSchemas(server);

package/dist/schemas.js

@@ -326,6 +326,22 @@ export const outputSchemas = {
             red: z.number(), green: z.number(), blue: z.number(), alpha: z.number(), hex: z.string(),
         })),
     },
+    gd_call_hierarchy: {
+        direction: z.string(),
+        items: z.array(z.object({
+            name: z.string(), kind: z.string(), uri: z.string(), line: z.number(), character: z.number(), detail: z.string(),
+            calls: z.array(z.object({
+                name: z.string(), kind: z.string(), uri: z.string(), line: z.number(), character: z.number(), detail: z.string(),
+                ranges: z.array(z.object({ line: z.number(), character: z.number(), end_line: z.number(), end_character: z.number() })),
+            })),
+        })),
+    },
+    gd_semantic_tokens: {
+        token_count: z.number(),
+        tokens: z.array(z.object({
+            line: z.number(), character: z.number(), length: z.number(), type: z.string(), modifiers: z.array(z.string()),
+        })),
+    },
     // ---- Plane D: C# semantic / OmniSharp LSP (tools/cslsp.ts) ----
     cs_completion: { items: z.array(z.object({ label: z.string(), kind: z.string(), detail: z.string(), insertText: z.string() })) },
     cs_hover: { contents: z.string() },

package/dist/tools/lsp.js

@@ -117,6 +117,52 @@ function normalizeColors(result) {
         };
     });
 }
+// textDocument/prepareCallHierarchy + callHierarchy/{incoming,outgoing}Calls.
+// A CallHierarchyItem carries a SymbolKind and a selectionRange (the name range);
+// surface the selectionRange start (falling back to the full range) so a caller
+// gets the caret position of each symbol.
+function normalizeCallItem(item) {
+    const it = (item ?? {});
+    const r = it.selectionRange ?? it.range ?? {};
+    return {
+        name: it.name ?? "",
+        kind: it.kind ? SYMBOL_KIND[it.kind] ?? String(it.kind) : "",
+        uri: it.uri ?? "",
+        line: r.start?.line ?? 0,
+        character: r.start?.character ?? 0,
+        detail: it.detail ?? "",
+    };
+}
+// The call-site ranges (fromRanges) an incoming/outgoing call reports, within the
+// file that makes the call.
+function normalizeCallRanges(ranges) {
+    const arr = Array.isArray(ranges) ? ranges : [];
+    return arr.map((rr) => {
+        const r = (rr ?? {});
+        return {
+            line: r.start?.line ?? 0, character: r.start?.character ?? 0,
+            end_line: r.end?.line ?? 0, end_character: r.end?.character ?? 0,
+        };
+    });
+}
+function decodeSemanticTokens(data, legend) {
+    const d = Array.isArray(data) ? data : [];
+    const types = legend?.tokenTypes ?? [];
+    const mods = legend?.tokenModifiers ?? [];
+    const out = [];
+    let line = 0, char = 0;
+    for (let i = 0; i + 4 < d.length; i += 5) {
+        const dLine = d[i] ?? 0, dChar = d[i + 1] ?? 0, len = d[i + 2] ?? 0, typeIdx = d[i + 3] ?? 0, modBits = d[i + 4] ?? 0;
+        line += dLine;
+        char = dLine === 0 ? char + dChar : dChar;
+        const modifiers = [];
+        for (let b = 0; b < 32; b++)
+            if (modBits & (1 << b))
+                modifiers.push(mods[b] ?? String(b));
+        out.push({ line, character: char, length: len, type: types[typeIdx] ?? String(typeIdx), modifiers });
+    }
+    return out;
+}
 // offsetOf / applyTextEdits now live in ./lsp-common.js (shared with the C#
 // rename mutator, cs_rename). Imported above.
 export function registerLspTools(server, lsp, cfg) {
@@ -572,5 +618,72 @@ export function registerLspTools(server, lsp, cfg) {
             return fail(err);
         }
     });
+    // ---- Phase 2 LSP-depth: call hierarchy + semantic tokens -----------------
+    // Two heavier semantic providers. Godot's GDScript language server does not
+    // advertise callHierarchyProvider or semanticTokensProvider on current builds
+    // (observed through 4.7), so both feature-detect and return a clear
+    // "unsupported" message, keeping the D7 -32601 belt-and-suspenders in case a
+    // future build advertises one but still answers "method not found".
+    server.registerTool("gd_call_hierarchy", {
+        title: "GDScript call hierarchy",
+        description: "Find the callers (direction=incoming, the default) or callees (direction=outgoing) of the function at a position. " +
+            "Resolves the symbol with textDocument/prepareCallHierarchy, then callHierarchy/incomingCalls or outgoingCalls, and " +
+            "returns each related function with the call-site ranges. Read-only. " +
+            "Godot's GDScript language server does not advertise callHierarchyProvider through 4.7; feature-detected.",
+        inputSchema: {
+            ...posSchema,
+            direction: z.enum(["incoming", "outgoing"]).optional().describe("incoming = who calls this (default); outgoing = what this calls"),
+        },
+    }, async ({ path, line, character, direction }) => {
+        const dir = direction ?? "incoming";
+        const alt = "Use gd_references to find where a symbol is used, or gd_definition to jump to it.";
+        try {
+            const caps = await lsp.getServerCapabilities();
+            if (!caps.callHierarchyProvider)
+                return unsupportedLsp("gd_call_hierarchy", "textDocument/prepareCallHierarchy", "callHierarchyProvider", alt);
+            const uri = await openAndPos(path);
+            const prepared = (await lsp.request("textDocument/prepareCallHierarchy", { textDocument: { uri }, position: { line, character } }));
+            const method = dir === "outgoing" ? "callHierarchy/outgoingCalls" : "callHierarchy/incomingCalls";
+            const items = await Promise.all((prepared ?? []).map(async (prep) => {
+                const calls = (await lsp.request(method, { item: prep }));
+                const related = (calls ?? []).map((c) => {
+                    const cc = (c ?? {});
+                    const peer = dir === "outgoing" ? cc.to : cc.from;
+                    return { ...normalizeCallItem(peer), ranges: normalizeCallRanges(cc.fromRanges) };
+                });
+                return { ...normalizeCallItem(prep), calls: related };
+            }));
+            return ok({ direction: dir, items });
+        }
+        catch (err) {
+            if (isMethodNotFound(err))
+                return unsupportedLsp("gd_call_hierarchy", "textDocument/prepareCallHierarchy", "callHierarchyProvider", alt);
+            return fail(err);
+        }
+    });
+    server.registerTool("gd_semantic_tokens", {
+        title: "GDScript semantic tokens",
+        description: "Return the semantic-highlighting tokens for a whole script — each token's position, length, type (e.g. function, " +
+            "variable, keyword) and modifiers — decoded from the LSP packed-integer form through the server's advertised legend. " +
+            "Read-only. Godot's GDScript language server does not advertise semanticTokensProvider through 4.7; feature-detected.",
+        inputSchema: { path: z.string().describe("Script path (res://..., absolute, or project-relative)") },
+    }, async ({ path }) => {
+        const alt = "Use gd_document_symbols for a structural outline of the file.";
+        try {
+            const caps = await lsp.getServerCapabilities();
+            const provider = caps.semanticTokensProvider;
+            if (!provider)
+                return unsupportedLsp("gd_semantic_tokens", "textDocument/semanticTokens/full", "semanticTokensProvider", alt);
+            const uri = await openAndPos(path);
+            const result = (await lsp.request("textDocument/semanticTokens/full", { textDocument: { uri } }));
+            const tokens = decodeSemanticTokens(result?.data ?? [], provider.legend);
+            return ok({ token_count: tokens.length, tokens });
+        }
+        catch (err) {
+            if (isMethodNotFound(err))
+                return unsupportedLsp("gd_semantic_tokens", "textDocument/semanticTokens/full", "semanticTokensProvider", alt);
+            return fail(err);
+        }
+    });
 }
 //# sourceMappingURL=lsp.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakpoint-mcp",
-  "version": "1.2.0",
+  "version": "1.3.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",