breakpoint-mcp 1.72.7 → 1.73.2

package/addon/breakpoint_mcp/runtime_bridge.gd

@@ -14,6 +14,11 @@ extends Node
 const Codec := preload("res://addons/breakpoint_mcp/variant_json.gd")
 const DEFAULT_PORT := 9081
 const LOG_CAP := 1000
+# D1a: how many error/warning entries one response may carry. A cap and not the
+# whole ring: a call that provokes a thousand warnings must not turn a 200-byte
+# reply into a 100 KB one. The `total` beside the list is what stops the cap
+# lying about how many there were.
+const ENGINE_LOG_CAP := 20
 # D6: source for the runtime-compiled Logger subclass (Godot 4.5+). Kept as a
 # string so `extends Logger` is only ever compiled where the class exists — the
 # addon stays parse-clean on Godot 4.3/4.4 (no Logger class).
@@ -235,9 +240,17 @@ func _handle_line(c: Dictionary, line: String) -> void:
 	if method in ASYNC_METHODS:
 		_dispatch_async(c, id, method, params)
 		return
+	# D1a: the engine-error echo. The ring already receives every push_error /
+	# push_warning and every engine message (via the 4.5+ Logger capture), but
+	# nothing tied one to the CALL that provoked it — a caller had to notice
+	# something was wrong, then go and read runtime.get_log, then guess which
+	# entries were its own. Reading _log_seq either side of the dispatch answers
+	# that by construction: everything appended in between belongs to this call.
+	var seq_before := _log_seq
 	var result := _dispatch(method, params)
 	var response := {"id": id}
 	response.merge(result)
+	_attach_engine_log(response, seq_before)
 	_send(peer, response)
 
 
@@ -306,6 +319,51 @@ func _on_captured_log(level: String, message: String) -> void:
 	_in_capture = false
 
 
+## D1a: every `error`/`warning` ring entry appended AFTER `seq_before`, i.e. during
+## the dispatch this response belongs to. Written into `result` and not beside it:
+## the host resolves a reply as `msg.result`, so a sibling key is dropped on the
+## floor — and `structuredContent` must match the tool's `outputSchema` or a
+## conforming client throws, which is why `engine_log` is declared on all 26
+## runtime output schemas rather than smuggled in.
+##
+## `isError` IS DELIBERATELY UNTOUCHED. A push_error during a call that returned
+## what it was asked for is a DIAGNOSTIC, not a failed call; promoting it would
+## make every noisy frame look like a broken tool and would change the meaning of
+## a field callers already branch on.
+##
+## Absent when there is nothing, never `[]`: an optional field that is always
+## present carries no information, and 208 §4's finding is that absent and
+## explicitly-empty are NOT the same value to a client that never materialises
+## defaults.
+func _attach_engine_log(response: Dictionary, seq_before: int) -> void:
+	if not response.get("ok", false):
+		return  # a failed call already carries its own error; see the note above
+	var result: Variant = response.get("result")
+	if typeof(result) != TYPE_DICTIONARY:
+		return
+	var entries: Array = []
+	for e in _log:
+		if entries.size() >= ENGINE_LOG_CAP:
+			break
+		if int(e.get("seq", 0)) <= seq_before:
+			continue
+		var lvl := String(e.get("level", ""))
+		if lvl == "error" or lvl == "warning":
+			entries.append(e)
+	if entries.is_empty():
+		return
+	# 🔴 THE COUNT IS SEPARATE FROM THE LIST, because the list is CAPPED. A caller
+	# reading twenty entries cannot tell "twenty happened" from "hundreds happened
+	# and you are seeing the first twenty", and the second is the case that matters.
+	var total := 0
+	for e in _log:
+		if int(e.get("seq", 0)) > seq_before:
+			var lvl2 := String(e.get("level", ""))
+			if lvl2 == "error" or lvl2 == "warning":
+				total += 1
+	result["engine_log"] = {"entries": entries, "total": total, "since_seq": seq_before}
+
+
 # ----------------------------------------------------------- dispatch --------
 
 func _dispatch(method: String, params: Dictionary) -> Dictionary:
@@ -972,6 +1030,12 @@ func _node_remove(params: Dictionary) -> Dictionary:
 ## as a bare (un-awaited) call from _handle_line so _process never blocks; it resumes on the
 ## engine's frame signals and sends when complete.
 func _dispatch_async(c: Dictionary, id: Variant, method: String, params: Dictionary) -> void:
+	# D1a: the async lane echoes too, and it is the lane that needs it MOST — a
+	# step_frames call runs the game for N frames, so it is the one dispatch here
+	# that can provoke errors from code the caller never named. Handing it the
+	# synchronous version's treatment is not symmetry for its own sake: a caller
+	# stepping frames to reproduce a bug is exactly the caller this feature is for.
+	var seq_before := _log_seq
 	var result: Dictionary
 	match method:
 		"runtime.step_frames":
@@ -982,6 +1046,7 @@ func _dispatch_async(c: Dictionary, id: Variant, method: String, params: Diction
 	if peer != null and peer.get_status() == StreamPeerTCP.STATUS_CONNECTED:
 		var response := {"id": id}
 		response.merge(result)
+		_attach_engine_log(response, seq_before)
 		_send(peer, response)
 
 

package/dist/index.js

@@ -11,6 +11,7 @@ import { StdioChannel } from "./stdio.js";
 import { DapClient } from "./dap.js";
 import { buildToolsets } from "./toolsets.js";
 import { registerRecipes } from "./recipes.js";
+import { applyWireDefaults } from "./wire-defaults.js";
 import { applyOutputSchemas } from "./schemas.js";
 import { applyAnnotations } from "./annotations.js";
 import { applyTimeoutCaveat } from "./timeout-caveat.js";
@@ -41,7 +42,16 @@ 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.72.7" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.73.2" }, { 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
+    // `execution: {taskSupport:"forbidden"}` on the 288 non-task tools (the spec's own
+    // value for an ABSENT field, in a field revision 2026-07-28 deletes outright).
+    // Neither is authored here; both are SDK output. 🔴 FIRST of the apply* family and
+    // not merely early: McpServer installs its tools/list handler from inside the FIRST
+    // registerTool, so a wrapper added after any registration wraps nothing.
+    applyWireDefaults(server);
     // B1: enforce frozen output schemas on every structured tool. Must run before
     // any register*Tools call — it wraps server.registerTool.
     applyOutputSchemas(server);

package/dist/schemas.js

@@ -44,6 +44,30 @@ const runtimeNode = z.lazy(() => z.object({
     visible: z.boolean().optional(),
     children: z.array(runtimeNode).optional(),
 }));
+/**
+ * D1a — the engine-error echo, declared once and spread into the 22 runtime
+ * tools whose `structuredContent` IS the bridge reply verbatim.
+ *
+ * 🔴 DECLARED RATHER THAN SMUGGLED. `structuredContent` is validated against
+ * `outputSchema` by both SDK clients, which THROW on a mismatch (208 §4), so a
+ * field the addon adds and this file does not declare breaks every conforming
+ * caller. The blast radius is the price of the feature, not an accident of it.
+ *
+ * 🔴 AND OPTIONAL, WITH THE ADDON OMITTING IT RATHER THAN SENDING `[]`. 208 §4
+ * measured that no SDK materialises a documented default, so absent and
+ * explicitly-empty are different values to a client — and "nothing went wrong"
+ * is worth saying with silence.
+ */
+const engineLog = {
+    engine_log: z
+        .object({
+        entries: z.array(z.object({ seq: z.number(), level: z.string(), message: z.string() })),
+        // The list is CAPPED at 20; this is how many there actually were.
+        total: z.number(),
+        since_seq: z.number(),
+    })
+        .optional(),
+};
 /** name -> ZodRawShape describing that tool's structuredContent. */
 export const outputSchemas = {
     // ---- Plane B: headless CLI (tools/cli.ts) ----
@@ -469,7 +493,7 @@ export const outputSchemas = {
     // C# sessions have no scene, so — unlike dbg_restart — no `scene` field here.
     cs_dbg_restart: { session_id: z.string(), method: z.string(), state: z.string() },
     // ---- Plane C: runtime bridge (tools/runtime.ts -> runtime_bridge.gd) ----
-    runtime_get_tree: {
+    runtime_get_tree: { ...engineLog,
         name: z.string(),
         type: z.string(),
         path: z.string(),
@@ -477,26 +501,26 @@ export const outputSchemas = {
         visible: z.boolean().optional(),
         children: z.array(runtimeNode).optional(),
     },
-    runtime_get_property: { path: z.string(), property: z.string(), value: encodedValue },
-    runtime_set_property: { path: z.string(), property: z.string(), value: encodedValue },
-    runtime_call_method: { return: encodedValue },
-    runtime_emit_signal: { emitted: z.boolean() },
-    runtime_inject_input: { injected: z.boolean(), kind: z.string() },
-    runtime_get_monitors: { monitors: z.record(z.number()) },
-    runtime_get_log: {
+    runtime_get_property: { ...engineLog, path: z.string(), property: z.string(), value: encodedValue },
+    runtime_set_property: { ...engineLog, path: z.string(), property: z.string(), value: encodedValue },
+    runtime_call_method: { ...engineLog, return: encodedValue },
+    runtime_emit_signal: { ...engineLog, emitted: z.boolean() },
+    runtime_inject_input: { ...engineLog, injected: z.boolean(), kind: z.string() },
+    runtime_get_monitors: { ...engineLog, monitors: z.record(z.number()) },
+    runtime_get_log: { ...engineLog,
         entries: z.array(z.object({ seq: z.number(), level: z.string(), message: z.string() })),
         latest_seq: z.number(),
         // D6: true when the Godot 4.5+ Logger capture is active (zero-config print()
         // capture, no managed parent). Optional so older addons still validate.
         capture: z.boolean().optional(),
     },
-    runtime_assert_node_state: {
+    runtime_assert_node_state: { ...engineLog,
         path: z.string(),
         ok: z.boolean(),
         checked: z.number(),
         mismatches: z.array(z.object({ property: z.string(), expected: encodedValue, actual: encodedValue })),
     },
-    runtime_assert_scene_structure: {
+    runtime_assert_scene_structure: { ...engineLog,
         ok: z.boolean(),
         checked: z.number(),
         failures: z.array(z.object({
@@ -506,7 +530,7 @@ export const outputSchemas = {
             actual: encodedValue.optional(),
         })),
     },
-    runtime_assert_perf: {
+    runtime_assert_perf: { ...engineLog,
         ok: z.boolean(),
         checked: z.number(),
         regressions: z.array(z.object({
@@ -517,13 +541,13 @@ export const outputSchemas = {
         })),
         monitors: z.record(z.number()),
     },
-    runtime_assert_screen_text: {
+    runtime_assert_screen_text: { ...engineLog,
         ok: z.boolean(),
         matches: z.number(),
         present: z.boolean(),
         samples: z.array(z.object({ path: z.string(), text: z.string() })),
     },
-    runtime_screenshot_diff: {
+    runtime_screenshot_diff: { ...engineLog,
         ok: z.boolean(),
         diff_ratio: z.number(),
         differing_pixels: z.number(),
@@ -535,9 +559,9 @@ export const outputSchemas = {
     },
     // F8 additions: await/animation/node-lifecycle over the runtime bridge.
     runtime_await_condition: { met: z.boolean(), polls: z.number(), elapsed_ms: z.number(), value: encodedValue },
-    runtime_anim_play: { playing: z.boolean(), current_animation: z.string(), speed_scale: z.number() },
-    runtime_anim_stop: { playing: z.boolean(), current_animation: z.string(), position: z.number() },
-    runtime_anim_get_state: {
+    runtime_anim_play: { ...engineLog, playing: z.boolean(), current_animation: z.string(), speed_scale: z.number() },
+    runtime_anim_stop: { ...engineLog, playing: z.boolean(), current_animation: z.string(), position: z.number() },
+    runtime_anim_get_state: { ...engineLog,
         playing: z.boolean(),
         current_animation: z.string(),
         position: z.number(),
@@ -545,13 +569,13 @@ export const outputSchemas = {
         speed_scale: z.number(),
         animations: z.array(z.string()),
     },
-    runtime_node_add: { added: z.boolean(), path: z.string(), type: z.string() },
-    runtime_node_remove: { removed: z.boolean(), path: z.string() },
+    runtime_node_add: { ...engineLog, added: z.boolean(), path: z.string(), type: z.string() },
+    runtime_node_remove: { ...engineLog, removed: z.boolean(), path: z.string() },
     // F4 additions: deterministic playtesting (time control / frame stepping / state digest / RNG seed).
-    runtime_time_scale: { previous: z.number(), current: z.number() },
-    runtime_step_frames: { frames_advanced: z.number(), frame_index: z.number() },
-    runtime_state_digest: { digest: z.record(z.record(encodedValue)), node_count: z.number() },
-    runtime_seed_rng: { seed: z.number() },
+    runtime_time_scale: { ...engineLog, previous: z.number(), current: z.number() },
+    runtime_step_frames: { ...engineLog, frames_advanced: z.number(), frame_index: z.number() },
+    runtime_state_digest: { ...engineLog, digest: z.record(z.record(encodedValue)), node_count: z.number() },
+    runtime_seed_rng: { ...engineLog, seed: z.number() },
     // F6 additions: multi-peer deterministic playtesting (spawn / stop / converge).
     runtime_spawn_peers: {
         peers: z.array(z.object({

package/dist/wire-defaults.js

@@ -0,0 +1,161 @@
+import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * 208 §7.1 — WHAT THE PROTOCOL ALREADY SAYS, DELETED FROM THE WIRE.
+ *
+ * Two fields on every tool in `tools/list` were not authored here and say nothing a
+ * conforming peer does not already assume. Both are removed on the way out.
+ *
+ *  1. 🔴 `"$schema": "http://json-schema.org/draft-07/schema#"`, inside EVERY input and
+ *     output schema. Nobody in this repo writes it: the SDK converts our Zod through
+ *     `zod-to-json-schema`, which defaults to draft-07, and offers no target knob on the
+ *     Zod-v3 path (`server/zod-json-schema-compat.js` — the `target` option is read only
+ *     by the Zod-v4 branch). MCP fixes the DEFAULT dialect at JSON Schema 2020-12 and
+ *     requires every implementation to support it; a `$schema` field is an EXPLICIT
+ *     SWITCH to a dialect nobody is obliged to support and which a peer MUST reject
+ *     gracefully if it does not. So this is not decoration and it is not a trim:
+ *     **580 of our 580 schemas fail to compile under a strict 2020-12 validator as
+ *     shipped, and 580 of 580 compile with the declaration removed, with zero semantic
+ *     disagreement across 2,320 probe instances.** The bytes (30,160 — 7.7% of the
+ *     surface) are the smaller half of the finding.
+ *
+ *  2. `execution: { taskSupport: "forbidden" }`, on the 288 tools that are not task
+ *     tools. Also not authored here — `McpServer.registerTool` hardcodes it. The spec
+ *     defines `"forbidden"` as the value when the field is ABSENT ("clients MUST NOT
+ *     attempt to invoke the tool as a task... This is the default behavior"), and the
+ *     field does not exist AT ALL on `Tool` in revision 2026-07-28, which moved tasks to
+ *     an extension with no per-tool flag. The three real task tools keep `"optional"`.
+ *
+ * 🔴 THE DIALECT STRIP IS FAIL-SAFE BY CONSTRUCTION, AND THAT IS THE WHOLE DESIGN.
+ * Removing `$schema` is only meaning-preserving while the schema stays inside the
+ * draft-07 ∩ 2020-12 intersection. `dialectSensitive()` walks for the keywords where the
+ * two dialects disagree and the declaration is KEPT if it finds one — so a future schema
+ * that actually needs draft-07 silently keeps working instead of silently changing
+ * meaning. `token-cost.mjs` then refuses on any surviving declaration, which turns the
+ * fail-safe from a quiet fallback into a red gate. **The transform never guesses; the
+ * gate makes the one case it declines to handle impossible to miss.**
+ */
+/**
+ * Keywords whose FORM or MEANING differs between draft-07 and 2020-12. Presence of any
+ * one of them means the dialect label is load-bearing and must not be dropped.
+ *
+ * 🔴 `exclusiveMinimum`/`exclusiveMaximum` are listed for their BOOLEAN form only —
+ * draft-04's. Both draft-07 and 2020-12 take a number there, and 65 of ours do, so
+ * matching on the key alone would keep the declaration on a third of the surface for a
+ * difference that does not exist. The predicate reads the value, not just the key.
+ */
+export const DIALECT_SENSITIVE = [
+    ["items", (v) => Array.isArray(v)], //            tuple form; 2020-12 spells it prefixItems
+    ["additionalItems", () => true], //               2020-12 folds this into items
+    ["exclusiveMinimum", (v) => typeof v === "boolean"], // draft-04 form
+    ["exclusiveMaximum", (v) => typeof v === "boolean"], // draft-04 form
+    ["dependencies", () => true], //                  split into dependentSchemas/dependentRequired
+    ["definitions", () => true], //                   $defs in 2020-12
+    ["$defs", () => true], //                         2020-12 only — the label would be wrong already
+    ["prefixItems", () => true], //                   2020-12 only
+    ["unevaluatedProperties", () => true], //         2020-12 only
+    ["unevaluatedItems", () => true], //              2020-12 only
+];
+/** Keys under these keywords are AUTHOR-CHOSEN NAMES, not schema vocabulary. */
+const NAME_BEARING = new Set(["properties", "patternProperties", "definitions", "$defs"]);
+/**
+ * Does this schema depend on which dialect validates it?
+ *
+ * 🔴 THE `properties` SKIP IS NOT A REFINEMENT, IT IS THE DIFFERENCE BETWEEN A TRUE AND A
+ * FALSE ANSWER. A first pass over this surface reported one `dependencies` hit and would
+ * have kept the declaration on the whole surface; the hit was `scene_get_dependencies`'s
+ * output field, a property NAMED dependencies. A walker that cannot tell a keyword from a
+ * key reads an author's vocabulary as the protocol's.
+ */
+export function dialectSensitive(node, inNamePosition = false) {
+    if (node === null || typeof node !== "object")
+        return false;
+    if (Array.isArray(node))
+        return node.some((v) => dialectSensitive(v, false));
+    const obj = node;
+    // draft-07 ignores keywords adjacent to $ref; 2020-12 applies them.
+    if (obj.$ref !== undefined && Object.keys(obj).length > 1)
+        return true;
+    for (const [k, v] of Object.entries(obj)) {
+        if (!inNamePosition) {
+            for (const [key, matches] of DIALECT_SENSITIVE)
+                if (k === key && matches(v))
+                    return true;
+        }
+        if (dialectSensitive(v, NAME_BEARING.has(k)))
+            return true;
+    }
+    return false;
+}
+/** The declaration the SDK emits, and the only one this strips. */
+export const SDK_DIALECT = "http://json-schema.org/draft-07/schema#";
+/**
+ * Drop `$schema` iff it is the SDK's draft-07 default AND nothing in the schema needs it.
+ * Any other declaration is somebody's deliberate choice and is left alone.
+ */
+export function stripDialect(schema) {
+    if (schema === null || typeof schema !== "object" || Array.isArray(schema))
+        return schema;
+    const obj = schema;
+    if (obj.$schema !== SDK_DIALECT)
+        return schema;
+    if (dialectSensitive({ ...obj, $schema: undefined }))
+        return schema;
+    const { $schema: _dropped, ...rest } = obj;
+    return rest;
+}
+/** Drop `execution` iff it carries nothing but the spec's own default. */
+export function stripDefaultExecution(tool) {
+    const ex = tool.execution;
+    if (ex === null || typeof ex !== "object")
+        return tool;
+    const keys = Object.keys(ex);
+    if (keys.length !== 1 || keys[0] !== "taskSupport")
+        return tool;
+    if (ex.taskSupport !== "forbidden")
+        return tool;
+    const { execution: _dropped, ...rest } = tool;
+    return rest;
+}
+/** Both transforms over one tool. Pure, so the refusal proofs can drive it directly. */
+export function normalizeTool(tool) {
+    let out = tool;
+    if (out.inputSchema !== undefined) {
+        const s = stripDialect(out.inputSchema);
+        if (s !== out.inputSchema)
+            out = { ...out, inputSchema: s };
+    }
+    if (out.outputSchema !== undefined) {
+        const s = stripDialect(out.outputSchema);
+        if (s !== out.outputSchema)
+            out = { ...out, outputSchema: s };
+    }
+    return stripDefaultExecution(out);
+}
+/** The `tools/list` result, normalized. Shape-preserving: cursors and extras survive. */
+export function normalizeToolList(result) {
+    if (!result || !Array.isArray(result.tools))
+        return result;
+    return { ...result, tools: result.tools.map((t) => normalizeTool(t)) };
+}
+/**
+ * Wrap the low-level `tools/list` handler so every listing leaves normalized.
+ *
+ * 🔴 MUST RUN BEFORE THE FIRST `registerTool`. `McpServer` installs its tools/list
+ * handler lazily, from inside the first registration (`setToolRequestHandlers`), so a
+ * wrapper added afterwards has nothing to wrap and would silently do nothing. It is
+ * therefore the FIRST of the apply* family, not merely an early one.
+ *
+ * 🔴 AND IT WRAPS THE HANDLER, NOT THE REGISTRY. The alternative — stripping at
+ * registration — cannot work for the dialect: the Zod-to-JSON-Schema conversion happens
+ * at LIST time, so at registration there is no `$schema` to remove yet.
+ */
+export function applyWireDefaults(server) {
+    const low = server.server;
+    const raw = low.setRequestHandler.bind(low);
+    low.setRequestHandler = (schema, handler) => {
+        if (schema !== ListToolsRequestSchema)
+            return raw(schema, handler);
+        return raw(schema, async (...args) => normalizeToolList((await handler(...args))));
+    };
+}
+//# sourceMappingURL=wire-defaults.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakpoint-mcp",
-  "version": "1.72.7",
+  "version": "1.73.2",
   "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",
@@ -60,6 +60,7 @@
   },
   "devDependencies": {
     "@types/node": "^20.14.0",
+    "ajv": "^8.20.0",
     "typescript": "^5.5.0"
   }
 }