breakpoint-mcp 1.77.0 → 1.78.0

package/dist/csdap.js

@@ -53,10 +53,61 @@ export class CsDapClient extends EventEmitter {
      * being emitted as an unlistened `error` event (which throws).
      */
     startFailure = null;
+    /**
+     * Whether a launch/attach this client sent was accepted. Tracked SEPARATELY from
+     * `state` for the reason `DapClient` tracks it separately, measured here on this
+     * plane against a real netcoredbg: `cs_dbg_continue` on a client that had never
+     * launched anything left `state = "running"` behind — `resume()` assigns it
+     * optimistically before it waits — so every call after it read as a live session.
+     * A guard built on `state` alone would be poisoned by the very call it exists to
+     * refuse.
+     */
+    sessionStarted = false;
     capabilities = null;
     state = "disconnected";
     lastStoppedThreadId = null;
     lastStoppedReason = null;
+    /**
+     * Whether a launch/attach the adapter accepted is still in force. The `cs_dbg_*`
+     * tools that can only answer from a live session consult this instead of asking
+     * netcoredbg and reporting whatever came back.
+     *
+     * 🔴 Measured against a real netcoredbg 3.2.0-1092 on a client that had never
+     * launched anything: seven of the nine readers answered with a raw hex code —
+     * `Failed command 'stackTrace' : 0x80004005` (E_FAIL), `0x80070057` (E_INVALIDARG)
+     * — `cs_dbg_set_variable` reported "the debug adapter reported a failure with no
+     * message", and `cs_dbg_watch` answered `isError:false` with every entry carrying
+     * `error: "error: 0x80004005"`. Only `cs_dbg_restart` refused, and only because it
+     * happens to read `lastStartMode`. That is the same single exception session 259
+     * measured one plane over, for the same accidental reason.
+     */
+    get hasSession() {
+        return this.sessionStarted && this.state !== "terminated" && this.state !== "disconnected";
+    }
+    /**
+     * Whether the adapter has reported a stop, read through a call so TypeScript's
+     * control-flow narrowing does not collapse it — `state` is mutated by the event
+     * handler across every `await` in `start()`, so a literal comparison after an
+     * assignment is (wrongly) an impossible one to tsc. `DapClient.stoppedNow()`
+     * carries the same note for the same reason.
+     */
+    stoppedNow() {
+        return this.state === "stopped";
+    }
+    /**
+     * Whether there is a FRAME to answer from — the public half of `stoppedNow()`.
+     *
+     * 🔴 `hasSession` IS NOT THIS, and session 262 spent a whole session on the
+     * difference on the GDScript plane. Measured here with a session live and the
+     * program merely RUNNING: `stackTrace` 0x80070057, `scopes` / `variables` /
+     * `step` 0x80004005, `evaluate` 0x80070057, `set_variable` blaming the adapter,
+     * `watch` an `isError:false` answer whose every entry carried a hex code, and
+     * `cs_dbg_continue` waiting the full 15 s to answer `{"state":"running"}` —
+     * about 45 s of adapter round trips for a question answerable here in none.
+     */
+    get isStopped() {
+        return this.stoppedNow();
+    }
     constructor(channel, timeoutMs) {
         super();
         this.channel = channel;
@@ -65,6 +116,7 @@ export class CsDapClient extends EventEmitter {
         this.channel.onClose((cause) => {
             this.state = "terminated";
             this.configured = false;
+            this.sessionStarted = false;
             const detail = cause ? ` (${cause.message})` : "";
             for (const [, p] of this.pending) {
                 clearTimeout(p.timer);
@@ -262,6 +314,7 @@ export class CsDapClient extends EventEmitter {
     async start(mode, args) {
         this.lastStartMode = mode;
         this.lastStartArgs = args;
+        this.sessionStarted = false;
         // Listen for `initialized` before we ask, so we cannot miss it.
         const onInit = this.waitEvent("initialized", Math.min(this.timeoutMs, 5000));
         this.capabilities = await this.request("initialize", {
@@ -287,6 +340,9 @@ export class CsDapClient extends EventEmitter {
         const startReq = this.request(mode, args).then(() => undefined, (err) => {
             this.startFailure = err;
             this.configured = false;
+            // A rejection arriving after `start()` returned ends the session, so the
+            // tools' session guard refuses from then on rather than reading `running`.
+            this.sessionStarted = false;
             this.state = "terminated";
             // A DISTINCT event name, deliberately: `error` is special-cased by
             // EventEmitter and throws when unlistened. This one is safe to ignore.
@@ -313,6 +369,7 @@ export class CsDapClient extends EventEmitter {
         const fatal = this.startFailure ?? (configureDoneAdvertised ? configureFailure : null);
         if (fatal) {
             this.configured = false;
+            this.sessionStarted = false;
             this.state = "terminated";
             void startReq;
             const detail = fatal?.message ?? String(fatal);
@@ -321,6 +378,7 @@ export class CsDapClient extends EventEmitter {
                 `${JSON.stringify(args).slice(0, 200)}).`);
         }
         this.configured = true;
+        this.sessionStarted = true;
         // 🔴 ONLY from `initialized`, never unconditionally. The adapter can emit `stopped`
         // (or `terminated`) between the configurationDone RESPONSE and this line, and the
         // event handler has already moved the state — a blind `= "running"` clobbers it and
@@ -430,6 +488,7 @@ export class CsDapClient extends EventEmitter {
         this.channel.close();
         this.state = "disconnected";
         this.configured = false;
+        this.sessionStarted = false;
     }
 }
 //# sourceMappingURL=csdap.js.map

package/dist/index.js

@@ -50,7 +50,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.77.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.78.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
     // 208 §7.1 — delete from the wire what the protocol already says: the SDK's
     // draft-07 `$schema` inside every input/output schema (MCP's default dialect is
     // 2020-12, and declaring another is an explicit switch a peer may reject), and

package/dist/tools/csdap.js

@@ -105,6 +105,67 @@ const CS_DAP_PATHS = {
 };
 export function registerCsDapTools(server, dap, cfg) {
     const root = cfg.csDapProjectPath;
+    /**
+     * Refuse when no launch/attach the adapter accepted is in force.
+     *
+     * 🔴 Measured against a real netcoredbg 3.2.0-1092 on a client that had never
+     * launched anything. Nine readers, and the only one that refused did so by
+     * accident:
+     *
+     * ```
+     * cs_dbg_stack_trace   11ms  Failed command 'stackTrace' : 0x80004005
+     * cs_dbg_scopes         1ms  Failed command 'scopes' : 0x80004005
+     * cs_dbg_variables      1ms  Failed command 'variables' : 0x80004005
+     * cs_dbg_evaluate       1ms  error: 0x80004005
+     * cs_dbg_watch          1ms  isError:FALSE, every entry error "error: 0x80004005"
+     * cs_dbg_set_variable   1ms  "the debug adapter reported a failure with no message"
+     * cs_dbg_step           1ms  Failed command 'next' : 0x80004005
+     * cs_dbg_continue       0ms  Failed command 'continue' : 0x80004005
+     * cs_dbg_restart        1ms  refuses — because it reads `lastStartMode`
+     * ```
+     *
+     * `0x80004005` is E_FAIL and `0x80070057` is E_INVALIDARG: hex for "no", naming
+     * nothing the caller can act on and pointing at the adapter for a state the host
+     * already knew. The refusal names the two ways to open a session instead.
+     */
+    const requireSession = (tool) => {
+        if (dap.hasSession)
+            return;
+        refuse(`${tool} needs a C# debug session: call cs_dbg_launch or cs_dbg_attach first. ` +
+            `There is none, so any state, frame or scope reported here would be invented — ` +
+            `this call previously answered with the adapter's raw failure code.`, "no_session");
+    };
+    /**
+     * Refuse when the session is live but the program is not AT A STOP.
+     *
+     * 🔴 THE SAME PROXY, ONE PLANE OVER — session 262 §1's whole finding, ported after
+     * measuring it here rather than assumed. A session existing is a proxy for a frame
+     * existing, and the two part company the moment the program runs on. Measured with
+     * a launched session and nothing stopped:
+     *
+     * ```
+     * cs_dbg_stack_trace      2ms  Failed command 'stackTrace' : 0x80070057
+     * cs_dbg_scopes           1ms  Failed command 'scopes' : 0x80004005
+     * cs_dbg_variables        1ms  Failed command 'variables' : 0x80004005
+     * cs_dbg_evaluate         1ms  error: 0x80070057
+     * cs_dbg_set_variable     1ms  "the debug adapter reported a failure with no message"
+     * cs_dbg_step             1ms  Failed command 'next' : 0x80004005
+     * cs_dbg_continue    15,000ms  isError:FALSE  {"state":"running"}
+     * ```
+     *
+     * 🔴 RAISED BEFORE THE ADAPTER ROUND TRIP, which is most of the point: that 15 s —
+     * with `cs_dbg_restart`'s 30 s beside it — is time the caller spent being told
+     * nothing, for a question `dap.isStopped` answers in none. The refusal names the
+     * state it READ rather than the state it assumed, and names both ways to reach a
+     * stop, because "not stopped" is not itself an instruction.
+     */
+    const requireStopped = (tool) => {
+        if (dap.isStopped)
+            return;
+        refuse(`${tool} needs the program stopped at a breakpoint: the C# debug session is live but the program is ${dap.state}. ` +
+            `Arm a line with cs_dbg_set_breakpoints and trigger that code path, or step from a stop you already have — ` +
+            `nothing here can be read from a program that is still running.`, "not_stopped");
+    };
     /**
      * Resolve a breakpoint source path and REFUSE one that cannot carry a breakpoint.
      *
@@ -272,6 +333,8 @@ export function registerCsDapTools(server, dap, cfg) {
         inputSchema: {},
     }, async () => {
         try {
+            requireSession("cs_dbg_continue");
+            requireStopped("cs_dbg_continue");
             const r = await dap.resume("continue", { threadId: dap.threadId() }, RESUME_WAIT_MS);
             return ok({ state: r.state, stopped_reason: r.reason });
         }
@@ -286,6 +349,8 @@ export function registerCsDapTools(server, dap, cfg) {
         inputSchema: { kind: z.enum(["in", "over", "out"]).describe("Step kind") },
     }, async ({ kind }) => {
         try {
+            requireSession("cs_dbg_step");
+            requireStopped("cs_dbg_step");
             const command = kind === "in" ? "stepIn" : kind === "out" ? "stepOut" : "next";
             const r = await dap.resume(command, { threadId: dap.threadId() }, RESUME_WAIT_MS);
             return ok({ state: r.state, stopped_reason: r.reason });
@@ -300,6 +365,8 @@ export function registerCsDapTools(server, dap, cfg) {
         inputSchema: { levels: z.number().int().positive().optional().describe("Max frames (default 20)") },
     }, async ({ levels }) => {
         try {
+            requireSession("cs_dbg_stack_trace");
+            requireStopped("cs_dbg_stack_trace");
             const body = await dap.request("stackTrace", { threadId: dap.threadId(), startFrame: 0, levels: levels ?? 20 });
             const frames = Array.isArray(body["stackFrames"])
                 ? body["stackFrames"].map((f) => ({
@@ -318,6 +385,8 @@ export function registerCsDapTools(server, dap, cfg) {
         inputSchema: { frame_id: z.number().int().describe("Frame id from cs_dbg_stack_trace") },
     }, async ({ frame_id }) => {
         try {
+            requireSession("cs_dbg_scopes");
+            requireStopped("cs_dbg_scopes");
             const body = await dap.request("scopes", { frameId: frame_id });
             const scopes = Array.isArray(body["scopes"])
                 ? body["scopes"].map((s) => ({ name: s.name ?? "", variables_ref: s.variablesReference ?? 0 }))
@@ -334,6 +403,8 @@ export function registerCsDapTools(server, dap, cfg) {
         inputSchema: { variables_ref: z.number().int().describe("variablesReference from cs_dbg_scopes or a parent variable") },
     }, async ({ variables_ref }) => {
         try {
+            requireSession("cs_dbg_variables");
+            requireStopped("cs_dbg_variables");
             const body = await dap.request("variables", { variablesReference: variables_ref });
             const variables = Array.isArray(body["variables"])
                 ? body["variables"].map((v) => ({
@@ -357,6 +428,11 @@ export function registerCsDapTools(server, dap, cfg) {
         },
     }, async ({ expression, frame_id, confirm }) => {
         try {
+            // 🔴 BEFORE the confirmation prompt, not after. Asking the operator to approve
+            // an evaluate that cannot run — and that previously answered `0x80070057` when
+            // they approved it — spends their attention on a call already known to fail.
+            requireSession("cs_dbg_evaluate");
+            requireStopped("cs_dbg_evaluate");
             const blocked = await gate(server, confirm, `Evaluate C# expression in the running game: ${expression}`);
             if (blocked)
                 return blocked;
@@ -393,6 +469,11 @@ export function registerCsDapTools(server, dap, cfg) {
         },
     }, async ({ variables_ref, name, value, confirm }) => {
         try {
+            // Before the capability read as well as before the prompt: `capabilities` is
+            // null until `initialize`, so with no session the check below is a question
+            // asked of nobody.
+            requireSession("cs_dbg_set_variable");
+            requireStopped("cs_dbg_set_variable");
             if (dap.capabilities && dap.capabilities["supportsSetVariable"] === false) {
                 return {
                     isError: true,
@@ -436,12 +517,37 @@ export function registerCsDapTools(server, dap, cfg) {
         },
     }, async ({ add, remove, clear, frame_id }) => {
         try {
+            requireSession("cs_dbg_watch");
+            // 🔴 THE ONE READER HERE NOT REFUSED WHILE THE PROGRAM RUNS, ON PURPOSE — the
+            // same deliberate divergence session 262 made on the GDScript plane, for the
+            // same reason. `cs_dbg_watch` is two things at once: it MANAGES a persistent
+            // set and it evaluates that set, and this tool's own description teaches
+            // arming the set and re-reading it "after a step/continue". Refusing the
+            // mutation while the program runs would refuse the documented workflow.
+            // The set change is applied; only the VALUES are unavailable, and the entry's
+            // own `error` field says which.
             if (clear)
                 dap.clearWatches();
             if (remove && remove.length)
                 dap.removeWatches(remove);
             if (add && add.length)
                 dap.addWatches(add);
+            if (!dap.isStopped) {
+                // 🔴 What this replaces was worse than empty. Measured against a real
+                // netcoredbg with no session and again with the program running: an
+                // `isError:false` answer whose every entry carried `error: "error:
+                // 0x80004005"` — a hex code offered to the caller as the reason their watch
+                // has no value. The reason is that the program is not stopped, the host
+                // knows it, and it costs no round trip to say so.
+                return ok({
+                    watches: dap.listWatches().map((expression) => ({
+                        expression,
+                        value: "",
+                        type: "",
+                        error: `not stopped (${dap.state}) — a watch is evaluated in a stopped frame, so values arrive at the next stop`,
+                    })),
+                });
+            }
             // Bound each watch's evaluate to the short deadline (mirrors cs_dbg_evaluate): a watch
             // the adapter never answers fails fast on that entry instead of hanging the full DAP
             // timeout at every stop, while other watches still resolve normally.
@@ -468,6 +574,21 @@ export function registerCsDapTools(server, dap, cfg) {
             // Per the DAP spec a client should only send setExceptionBreakpoints when the adapter
             // advertised at least one exception filter. Short-circuit with a clear "unsupported"
             // message otherwise, matching the GDScript dbg_set_exception_breakpoints discipline.
+            // 🔴 "THE CONNECTED ADAPTER" MUST FIRST BE ONE. `capabilities` is null until
+            // `initialize`, so with no session this read found nothing and the tool told
+            // the caller their debugger advertises no exception filters. Measured against
+            // a real netcoredbg 3.2.0-1092: with no session it answered "unsupported by
+            // the connected C# debug adapter (it advertises no exceptionBreakpointFilters)"
+            // — while that same adapter advertises `all` and `user-unhandled`, which the
+            // cs-dap cohort asserts on every CI leg. A capability read is a question for
+            // somebody, and there was nobody. Session 262 §2 fixed this shape one plane
+            // over, where the message blamed the user's engine BUILD; here it blamed their
+            // debugger for a handshake that never happened.
+            //
+            // NOT `requireStopped`: exception filters are armed for the FUTURE, so a live
+            // running session is a legitimate caller — the same call `dbg_data_breakpoints`
+            // gets on the GDScript plane, and for the same reason.
+            requireSession("cs_dbg_set_exception_breakpoints");
             const advertised = dap.capabilities?.["exceptionBreakpointFilters"];
             const available_filters = Array.isArray(advertised)
                 ? advertised.map((f) => ({ filter: f.filter ?? "", label: f.label ?? "" }))

package/package.json

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