breakpoint-mcp 1.0.0

package/dist/stdio.js

@@ -0,0 +1,101 @@
+import { spawn } from "node:child_process";
+import { FrameDecoder, encodeFrame } from "./framing.js";
+import { log } from "./logger.js";
+/**
+ * A `JsonRpcChannel` backed by a spawned subprocess speaking LSP over stdio —
+ * the transport OmniSharp (and other CLI language servers) use, unlike Godot's
+ * TCP LSP. Frames are `Content-Length`-delimited on the child's stdin/stdout
+ * (reusing `FrameDecoder`/`encodeFrame`), so a protocol client written against
+ * `JsonRpcChannel` works over stdio exactly as it does over TCP.
+ *
+ * The process is spawned LAZILY on the first `send()` — like `FramedConnection`
+ * connects lazily — so a host with no C# language server installed pays nothing
+ * and never fails at startup; only a cs_* tool call actually launches it. A spawn
+ * failure (e.g. the binary isn't on PATH) rejects the send with an actionable
+ * hint rather than hanging.
+ */
+export class StdioChannel {
+    command;
+    args;
+    cwd;
+    label;
+    unavailableHint;
+    child = null;
+    starting = null;
+    decoder;
+    messageCb = () => { };
+    closeCb = () => { };
+    constructor(command, args, cwd, label, unavailableHint) {
+        this.command = command;
+        this.args = args;
+        this.cwd = cwd;
+        this.label = label;
+        this.unavailableHint = unavailableHint;
+        this.decoder = new FrameDecoder((m) => this.messageCb(m), label);
+    }
+    onMessage(cb) {
+        this.messageCb = cb;
+    }
+    onClose(cb) {
+        this.closeCb = cb;
+    }
+    start() {
+        if (this.child && this.child.exitCode === null && !this.child.killed)
+            return Promise.resolve(this.child);
+        if (this.starting)
+            return this.starting;
+        this.starting = new Promise((resolve, reject) => {
+            let child;
+            try {
+                child = spawn(this.command, this.args, { cwd: this.cwd, stdio: ["pipe", "pipe", "pipe"] });
+            }
+            catch (err) {
+                this.starting = null;
+                reject(new Error(`${this.label} could not spawn '${this.command}'. ${this.unavailableHint} (${err.message})`));
+                return;
+            }
+            child.once("spawn", () => {
+                this.child = child;
+                this.starting = null;
+                log(`${this.label} spawned '${this.command} ${this.args.join(" ")}' (cwd=${this.cwd})`);
+                resolve(child);
+            });
+            child.once("error", (err) => {
+                this.starting = null;
+                this.child = null;
+                reject(new Error(`${this.label} could not spawn '${this.command}'. ${this.unavailableHint} (${err.message})`));
+            });
+            child.stdout.on("data", (chunk) => this.decoder.push(chunk));
+            // The server's own logging goes to stderr (LSP frames are stdout-only); surface
+            // it in the host log, trimmed, so a misbehaving server is diagnosable.
+            child.stderr.on("data", (chunk) => {
+                const text = chunk.toString("utf8").trimEnd();
+                if (text)
+                    log(`${this.label} stderr: ${text.length > 500 ? text.slice(0, 500) + "…" : text}`);
+            });
+            child.on("exit", (code, signal) => {
+                log(`${this.label} exited (code=${code ?? "null"} signal=${signal ?? "null"})`);
+                this.child = null;
+                this.decoder.reset();
+                this.closeCb();
+            });
+        });
+        return this.starting;
+    }
+    async send(msg) {
+        const child = await this.start();
+        child.stdin.write(encodeFrame(msg));
+    }
+    close() {
+        if (this.child) {
+            try {
+                this.child.kill();
+            }
+            catch {
+                /* already gone */
+            }
+        }
+        this.child = null;
+    }
+}
+//# sourceMappingURL=stdio.js.map

package/dist/subscriptions.js

@@ -0,0 +1,141 @@
+import { SubscribeRequestSchema, UnsubscribeRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { log } from "./logger.js";
+/**
+ * D3 — resource subscriptions.
+ *
+ * Adds the MCP resources/subscribe + resources/unsubscribe requests and pushes
+ * notifications/resources/updated when a subscribed `godot://…` resource
+ * changes. The change signal originates in the editor addon (selection / edited
+ * scene changed) or the in-game runtime autoload (live SceneTree changed),
+ * travels over the same bridge socket D2's request path uses as an unsolicited
+ * "resource.changed" event, and is fanned out here — but only for URIs a client
+ * has actually subscribed to. Non-subscribers keep the unchanged pull-only
+ * behavior.
+ */
+/**
+ * Default trailing window (ms) for coalescing rapid resource.changed events into
+ * fewer notifications/resources/updated. Override via BREAKPOINT_RESOURCE_COALESCE_MS.
+ * Multiple `updated` are spec-harmless (the client just re-reads), so this only
+ * trims volume; 0 disables coalescing entirely.
+ */
+export const DEFAULT_COALESCE_MS = 50;
+/**
+ * Server capability advertising resources/subscribe (and, by extension, the
+ * notifications/resources/updated the SDK gates on `capabilities.resources`).
+ * Merged with the task capabilities in index.ts.
+ */
+export const RESOURCE_CAPABILITIES = {
+    resources: { subscribe: true },
+};
+/** Tracks which `godot://…` resource URIs the connected client is subscribed to. */
+export class ResourceSubscriptions {
+    uris = new Set();
+    subscribe(uri) {
+        this.uris.add(uri);
+    }
+    unsubscribe(uri) {
+        this.uris.delete(uri);
+    }
+    has(uri) {
+        return this.uris.has(uri);
+    }
+    get size() {
+        return this.uris.size;
+    }
+}
+/** Runtime-bridge resources live under godot://runtime/; the rest are editor-served. */
+function isRuntimeUri(uri) {
+    return uri.startsWith("godot://runtime/");
+}
+/**
+ * Install resources/subscribe + resources/unsubscribe on the low-level server,
+ * hold the relevant bridge connected so the addon's push events flow, and
+ * forward each "resource.changed" event to notifications/resources/updated for
+ * exactly the subscribed URIs.
+ *
+ * Rapid changes are coalesced per-URI with a leading-edge + trailing-flush
+ * throttle: the first change pushes immediately (responsive), then further
+ * changes inside a `coalesceMs` window collapse into at most one trailing push.
+ * This keeps a burst — e.g. many SceneTree mutations in one frame — from fanning
+ * out as a flood of notifications. Set coalesceMs to 0 to disable.
+ *
+ * The subscribe/unsubscribe methods are not capability-gated by the SDK's
+ * request-handler assertion, but sendResourceUpdated is gated on the `resources`
+ * capability — hence RESOURCE_CAPABILITIES must be advertised at construction.
+ */
+export function registerResourceSubscriptions(server, editor, runtime, subs = new ResourceSubscriptions(), opts = {}) {
+    const low = server.server;
+    const coalesceMs = opts.coalesceMs ?? DEFAULT_COALESCE_MS;
+    low.setRequestHandler(SubscribeRequestSchema, async (request) => {
+        const uri = request.params.uri;
+        subs.subscribe(uri);
+        // Keep the push channel open so the addon can deliver change events even if
+        // the host never issued a pull request for this resource.
+        const source = isRuntimeUri(uri) ? runtime : editor;
+        void source.ensureConnected();
+        log(`resources/subscribe ${uri} (${subs.size} active)`);
+        return {};
+    });
+    const throttles = new Map();
+    const push = (uri) => {
+        void low.sendResourceUpdated({ uri }).catch((err) => {
+            log(`sendResourceUpdated ${uri} failed: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    };
+    const clearThrottle = (uri) => {
+        const t = throttles.get(uri);
+        if (t) {
+            clearTimeout(t.timer);
+            throttles.delete(uri);
+        }
+    };
+    const arm = (uri) => {
+        const timer = setTimeout(() => onWindowEnd(uri), coalesceMs);
+        // Never keep the event loop alive just for a coalescing window.
+        timer.unref?.();
+        throttles.set(uri, { timer, pending: false });
+    };
+    const onWindowEnd = (uri) => {
+        const t = throttles.get(uri);
+        if (!t)
+            return;
+        if (t.pending && subs.has(uri)) {
+            // A change landed during the window — flush it and hold the window open so
+            // a sustained stream stays capped at ~one push per window instead of starving.
+            push(uri);
+            arm(uri);
+        }
+        else {
+            throttles.delete(uri);
+        }
+    };
+    const forward = (uri) => {
+        if (!subs.has(uri))
+            return;
+        if (coalesceMs <= 0) {
+            push(uri);
+            return;
+        }
+        const t = throttles.get(uri);
+        if (t) {
+            // Inside an open window — collapse into the eventual trailing flush.
+            t.pending = true;
+        }
+        else {
+            // Leading edge — push now and open a coalescing window.
+            push(uri);
+            arm(uri);
+        }
+    };
+    low.setRequestHandler(UnsubscribeRequestSchema, async (request) => {
+        const uri = request.params.uri;
+        subs.unsubscribe(uri);
+        clearThrottle(uri);
+        log(`resources/unsubscribe ${uri} (${subs.size} active)`);
+        return {};
+    });
+    editor.onResourceChanged(forward);
+    runtime.onResourceChanged(forward);
+    return subs;
+}
+//# sourceMappingURL=subscriptions.js.map

package/dist/tasks.js

@@ -0,0 +1,146 @@
+import { InMemoryTaskStore, isTerminal } from "@modelcontextprotocol/sdk/experimental/tasks";
+import { z } from "zod";
+import { outputSchemas } from "./schemas.js";
+import { log } from "./logger.js";
+/**
+ * D2 — the formal MCP task-execution model for long-running Godot jobs.
+ *
+ * Long, run-to-completion tools (headless export / import / script runs) used to
+ * emit ad-hoc `notifications/progress`. They now register under the spec's task
+ * model: a call creates a task, returns a handle immediately, and the client
+ * drives it with tasks/get (poll), tasks/result (await), and tasks/cancel
+ * (stop). Plain, non-task clients are unaffected — the SDK auto-creates a task,
+ * polls it to completion, and returns the result synchronously.
+ */
+/** How long a finished task's status + result stay retrievable (ms). */
+export const TASK_TTL_MS = 15 * 60 * 1000;
+/** Default poll cadence (ms); also the added latency of the synchronous path. */
+export const TASK_POLL_INTERVAL_MS = 500;
+/**
+ * Server capabilities advertising the task-execution model for tools/call.
+ * Passed to the McpServer constructor so the SDK installs the tasks/get,
+ * tasks/result, tasks/list and tasks/cancel request handlers.
+ */
+export const TASK_CAPABILITIES = {
+    tasks: { requests: { tools: { call: {} } } },
+};
+/**
+ * A TaskStore whose cancellation actually STOPS the running job.
+ *
+ * The SDK's Protocol handles `tasks/cancel` by calling `updateTaskStatus(id,
+ * 'cancelled')` on this store — which only records the status, it does not
+ * interrupt the in-flight work. We keep a per-task AbortController and trip it
+ * the instant a task transitions to 'cancelled', so a headless Godot run is
+ * really killed rather than left orphaned.
+ */
+export class GodotTaskStore extends InMemoryTaskStore {
+    aborters = new Map();
+    /** Bind a running job's AbortController to its task id (call in createTask). */
+    registerJob(taskId, controller) {
+        this.aborters.set(taskId, controller);
+    }
+    /** Test/introspection helper: is a job still tracked as cancellable? */
+    isTracked(taskId) {
+        return this.aborters.has(taskId);
+    }
+    async updateTaskStatus(taskId, status, statusMessage, sessionId) {
+        // Abort BEFORE recording the terminal status so the worker's own
+        // signal.aborted guard trips ahead of any late storeTaskResult().
+        if (status === "cancelled") {
+            const c = this.aborters.get(taskId);
+            if (c && !c.signal.aborted)
+                c.abort();
+        }
+        await super.updateTaskStatus(taskId, status, statusMessage, sessionId);
+        if (isTerminal(status))
+            this.aborters.delete(taskId);
+    }
+    async storeTaskResult(taskId, status, result, sessionId) {
+        await super.storeTaskResult(taskId, status, result, sessionId);
+        this.aborters.delete(taskId);
+    }
+}
+/** The one store the server and every task tool share. */
+export const taskStore = new GodotTaskStore();
+function errorResult(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+/**
+ * Wrap a plain worker into the SDK's { createTask, getTask, getTaskResult }
+ * ToolTaskHandler. createTask registers the task, launches the work in the
+ * background, and returns the handle immediately; the background settle stores
+ * the result — which the SDK turns into a notifications/tasks/status update and
+ * uses to satisfy any pending tasks/result long-poll.
+ */
+function makeTaskHandler(name, worker) {
+    const shape = outputSchemas[name];
+    const outSchema = shape ? z.object(shape) : undefined;
+    return {
+        createTask: async (args, extra) => {
+            const task = await extra.taskStore.createTask({
+                ttl: TASK_TTL_MS,
+                pollInterval: TASK_POLL_INTERVAL_MS,
+            });
+            const taskId = task.taskId;
+            const controller = new AbortController();
+            taskStore.registerJob(taskId, controller);
+            void (async () => {
+                let settled;
+                try {
+                    const result = await worker(args, controller.signal);
+                    if (controller.signal.aborted)
+                        return; // cancelled: store already terminal
+                    // Preserve the B1 invariant the SDK skips for task results: a
+                    // successful structured result must match its frozen output schema.
+                    if (outSchema && !result.isError) {
+                        if (!result.structuredContent) {
+                            throw new Error(`tool ${name} produced no structuredContent`);
+                        }
+                        outSchema.parse(result.structuredContent);
+                    }
+                    settled = {
+                        status: result.isError ? "failed" : "completed",
+                        result: result,
+                    };
+                }
+                catch (err) {
+                    if (controller.signal.aborted)
+                        return;
+                    const msg = err instanceof Error ? err.message : String(err);
+                    settled = { status: "failed", result: errorResult(`Error: ${msg}`) };
+                }
+                try {
+                    await extra.taskStore.storeTaskResult(taskId, settled.status, settled.result);
+                }
+                catch (storeErr) {
+                    // Benign if the task was cancelled in the same tick (terminal guard).
+                    const m = storeErr instanceof Error ? storeErr.message : String(storeErr);
+                    log(`task ${taskId} (${name}) result store skipped: ${m}`);
+                }
+            })();
+            return { task };
+        },
+        getTask: async (_args, extra) => extra.taskStore.getTask(extra.taskId),
+        getTaskResult: async (_args, extra) => extra.taskStore.getTaskResult(extra.taskId),
+    };
+}
+/**
+ * Register a long-running tool under the formal MCP task model.
+ *
+ * With `taskSupport: 'optional'`, task-aware clients get the full
+ * create -> poll -> await -> cancel lifecycle, while plain clients keep today's
+ * blocking semantics (the SDK auto-creates a task, polls to completion, and
+ * returns the result synchronously). The frozen output schema in schemas.ts is
+ * applied here, mirroring applyOutputSchemas' handling of registerTool.
+ */
+export function registerTaskTool(server, name, config, worker) {
+    const shape = outputSchemas[name];
+    server.experimental.tasks.registerToolTask(name, {
+        title: config.title,
+        description: config.description,
+        inputSchema: config.inputSchema,
+        ...(shape ? { outputSchema: shape } : {}),
+        execution: { taskSupport: "optional" },
+    }, makeTaskHandler(name, worker));
+}
+//# sourceMappingURL=tasks.js.map