breakpoint-mcp 1.81.0 → 1.82.1

package/addon/breakpoint_mcp/error_remedies.gd

@@ -54,6 +54,8 @@ const EDITOR_REMEDIES := {
 	"create_failed": "Check the parent and the name in the message, then call again.",
 	"mkdir_failed": "Check the parent directory is inside the project and writable; `filesystem_create_dir` creates intermediate directories, and the number is a Godot Error code.",
 	"bad_source": "Create an atlas source first with `tileset_add_source`; the id above is not one.",
+	"set_mismatch": "Send the value tagged — `{\"__type__\": \"Vector2\", \"x\": .., \"y\": ..}` — then call again; `node_get_property` reports the type the property currently holds.",
+	"set_ignored": "Check the property exists on this node with `node_get_property`, and that its setter accepts the value — nothing changed.",
 	"unknown_method": "Re-run `breakpoint-mcp init --force`, then reopen the project — the addon installed here is older than the host and plain `init` skips an addon that is already present.",
 	"bad_request": "Send the request again with the field the message names — it was empty or unparseable.",
 	"no_viewport": "Switch the editor to the tab that owns that viewport with `main_screen_set`, then call again.",
@@ -100,6 +102,10 @@ const RUNTIME_REMEDIES := {
 	"instantiate_failed": "Check the class or scene loads in the editor first — it would not instantiate in the running game.",
 	"cannot_remove_root": "Call `runtime_node_remove` on a child instead, or `godot_stop` to end the run — the running scene root cannot be removed.",
 	"no_tree": "Call `godot_run_project` and wait for it to bind, then call again — the game is not running.",
+	"set_mismatch": "Send the value tagged — `{\"__type__\": \"Vector2\", \"x\": .., \"y\": ..}` — then call again; `runtime_get_property` reports the type the property currently holds.",
+	"set_ignored": "Check the property exists on this node with `runtime_get_property`, and that its setter accepts the value — nothing changed.",
+	"bad_event_field": "Send the field tagged — `{\"__type__\": \"Vector2\", \"x\": .., \"y\": ..}` — or omit it and let the event land at its default position.",
+	"bad_params": "Fix the parameter named above and call again — the message carries the accepted shape.",
 }
 
 

package/addon/breakpoint_mcp/operations.gd

@@ -8,7 +8,7 @@ extends RefCounted
 
 const Codec := preload("res://addons/breakpoint_mcp/variant_json.gd")
 const Remedies := preload("res://addons/breakpoint_mcp/error_remedies.gd")
-const ADDON_VERSION := "1.11.0"
+const ADDON_VERSION := "1.12.0"
 
 var _plugin: EditorPlugin
 
@@ -648,14 +648,77 @@ func _node_set_property(params: Dictionary) -> Dictionary:
 	var prop := String(params.get("property", ""))
 	if prop == "":
 		return _err("bad_params", "Missing 'property'")
-	var old_value: Variant = node.get(prop)
-	var new_value: Variant = Codec.decode(params.get("value"))
-	var ur := _plugin.get_undo_redo()
-	ur.create_action("Breakpoint: set %s.%s" % [node.name, prop])
-	ur.add_do_property(node, prop, new_value)
-	ur.add_undo_property(node, prop, old_value)
-	ur.commit_action()
-	return _ok({"path": _path_of(root, node), "property": prop, "value": Codec.encode(node.get(prop))})
+	# 🔴 SAME FAMILY AS THE RUNTIME PLANE'S `_set_property` (issue #327) — an absent
+	# `value` is not a null one, and letting it through wrote the property type's zero
+	# over whatever was there, under a success envelope. See runtime_bridge.gd for the
+	# measurement; this plane reached it by the same route and through UndoRedo, so the
+	# wipe landed in the undo history looking like a deliberate edit.
+	if not params.has("value"):
+		return _err(
+			"bad_params",
+			"Missing 'value'. Pass it explicitly — an absent value is not the same request as a null one, and writing null here would set %s to its type's zero." % prop
+		)
+	var old_value: Variant = Codec.read_property(node, prop)
+	var new_value: Variant = Codec.decode(params["value"])
+	# 🔴 TRIAL FIRST, HISTORY ONLY IF IT LANDS. The engine coerces at the moment of the
+	# write, so the outcome cannot be known before it happens — and a refused write must
+	# leave neither a changed property NOR an undo entry. Committing first and undoing
+	# afterwards would put a "Breakpoint: set .." action in the editor's history for an
+	# edit that never took, which is a worse artifact than the one being fixed.
+	Codec.write_property(node, prop, new_value)
+	var after: Variant = Codec.read_property(node, prop)
+	var outcome := _set_outcome(new_value, old_value, after)
+	Codec.write_property(node, prop, old_value)
+	if outcome == "applied" or outcome == "coerced":
+		var ur := _plugin.get_undo_redo()
+		ur.create_action("Breakpoint: set %s.%s" % [node.name, prop])
+		if Codec.is_indexed(prop):
+			# UndoRedo's property methods take a property NAME; a sub-property has to go
+			# through the indexed setter as a method call, or the action records an edit
+			# to a property called "position:x" that no node has.
+			ur.add_do_method(node, "set_indexed", NodePath(prop), new_value)
+			ur.add_undo_method(node, "set_indexed", NodePath(prop), old_value)
+		else:
+			ur.add_do_property(node, prop, new_value)
+			ur.add_undo_property(node, prop, old_value)
+		ur.commit_action()
+		after = Codec.read_property(node, prop)
+	if outcome == "mismatch":
+		return _err(
+			"set_mismatch",
+			"%s.%s holds %s after the write and %s was asked for. Nothing the caller wrote survived: rich types cross this wire as {\"__type__\": \"Vector2\", \"x\": .., \"y\": ..} and a bare map, array or string is not that."
+				% [_path_of(root, node), prop, _describe(after), _describe(new_value)]
+		)
+	if outcome == "ignored":
+		return _err(
+			"set_ignored",
+			"%s.%s is unchanged at %s after being asked for %s. The property may not exist on this node, or its setter refused the value."
+				% [_path_of(root, node), prop, _describe(after), _describe(new_value)]
+		)
+	var out := {"path": _path_of(root, node), "property": prop, "value": Codec.encode(after)}
+	if outcome == "coerced":
+		out["coerced"] = true
+		out["requested"] = Codec.encode(new_value)
+	return _ok(out)
+
+
+## The three outcomes of a write. Deliberately duplicated across the two planes rather
+## than hoisted into the codec: 254's per-plane split is the house rule and these two
+## scripts have separate lifetimes. See `runtime_bridge.gd::_set_outcome` for the
+## argument the three names carry.
+static func _set_outcome(asked: Variant, before: Variant, after: Variant) -> String:
+	if Codec.values_equal(asked, after):
+		return "applied"
+	if not Codec.types_compatible(typeof(asked), typeof(after)):
+		return "mismatch"
+	if Codec.values_equal(before, after):
+		return "ignored"
+	return "coerced"
+
+
+## `type_string(typeof(v))` plus the value, for a message a reader can act on.
+static func _describe(v: Variant) -> String:
+	return "%s %s" % [type_string(typeof(v)), JSON.stringify(Codec.encode(v))]
 
 
 func _node_get_property(params: Dictionary) -> Dictionary:
@@ -668,7 +731,7 @@ func _node_get_property(params: Dictionary) -> Dictionary:
 	var prop := String(params.get("property", ""))
 	if prop == "":
 		return _err("bad_params", "Missing 'property'")
-	return _ok({"path": _path_of(root, node), "property": prop, "value": Codec.encode(node.get(prop))})
+	return _ok({"path": _path_of(root, node), "property": prop, "value": Codec.encode(Codec.read_property(node, prop))})
 
 
 func _selection_get() -> Dictionary:

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.11.0"
+version="1.12.0"
 script="plugin.gd"

package/addon/breakpoint_mcp/runtime_bridge.gd

@@ -20,7 +20,7 @@ extends Node
 ## and the process that is already running keeps the addon it loaded. Held in lockstep
 ## with `plugin.cfg` and with `operations.gd`'s copy by contract_check check 14, which
 ## exists because two of those literals disagreed for two releases.
-const ADDON_VERSION := "1.11.0"
+const ADDON_VERSION := "1.12.0"
 const Codec := preload("res://addons/breakpoint_mcp/variant_json.gd")
 const Remedies := preload("res://addons/breakpoint_mcp/error_remedies.gd")
 const DEFAULT_PORT := 9081
@@ -502,7 +502,35 @@ func _get_property(params: Dictionary) -> Dictionary:
 	if node == null:
 		return _err("bad_path", "Node not found: %s" % params.get("path", ""))
 	var prop := String(params.get("property", ""))
-	return _ok({"path": _path_of(node), "property": prop, "value": Codec.encode(node.get(prop))})
+	if prop == "":
+		return _err("bad_params", "Missing 'property'")
+	return _ok({"path": _path_of(node), "property": prop, "value": Codec.encode(Codec.read_property(node, prop))})
+
+
+## 🔴 THIS FUNCTION USED TO ANSWER WITH A READ-BACK IT NEVER COMPARED TO WHAT IT WAS
+## ASKED FOR (issue #327). Every way a write can fail to land — a String coerced into
+## a bool, an untagged `{"x":..,"y":..}` landing in a Vector2 as (0,0), an indexed path
+## read with the wrong method, a `value` key that never arrived — produced the same
+## `ok` envelope carrying the value the property ALREADY HAD. The caller's next action
+## was therefore taken against a state it believed it had set, arbitrarily far from the
+## point where nothing happened.
+##
+## 🔴 THE THREE OUTCOMES, AND ONLY ONE OF THEM IS A FAILURE OF THE WRITE:
+##
+##   APPLIED    the engine holds what was asked for                    -> ok
+##   COERCED    same type, different value — a setter clamped, snapped
+##              or normalised it. Ordinary and its own business, but the
+##              caller must be TOLD, because it is not what it asked for -> ok, coerced
+##   REFUSED    the property is unchanged, or holds an incompatible
+##              type: nothing the caller wrote survived                  -> error
+static func _set_outcome(asked: Variant, before: Variant, after: Variant) -> String:
+	if Codec.values_equal(asked, after):
+		return "applied"
+	if not Codec.types_compatible(typeof(asked), typeof(after)):
+		return "mismatch"
+	if Codec.values_equal(before, after):
+		return "ignored"
+	return "coerced"
 
 
 func _set_property(params: Dictionary) -> Dictionary:
@@ -510,8 +538,57 @@ func _set_property(params: Dictionary) -> Dictionary:
 	if node == null:
 		return _err("bad_path", "Node not found: %s" % params.get("path", ""))
 	var prop := String(params.get("property", ""))
-	node.set(prop, Codec.decode(params.get("value")))
-	return _ok({"path": _path_of(node), "property": prop, "value": Codec.encode(node.get(prop))})
+	if prop == "":
+		return _err("bad_params", "Missing 'property'")
+	# 🔴 A MISSING `value` IS NOT A NULL VALUE, and conflating them WIPED PROPERTIES.
+	# `Dictionary.get("value")` answers null for a key that is not there, and
+	# `Object.set(prop, null)` does not refuse — the engine coerces null to the
+	# property type's zero. Measured on 4.7: rotation 1.25 -> 0.0, position
+	# (123, 456) -> (0, 0), reported as success both times. The host's own published
+	# input schema left `value` OPTIONAL (`z.any()` is optional in zod), so a client
+	# omitting it was doing exactly what it was told it could do.
+	if not params.has("value"):
+		return _err(
+			"bad_params",
+			"Missing 'value'. Pass it explicitly — an absent value is not the same request as a null one, and writing null here would set %s to its type's zero." % prop
+		)
+	var asked: Variant = Codec.decode(params["value"])
+	var before: Variant = Codec.read_property(node, prop)
+	Codec.write_property(node, prop, asked)
+	var after: Variant = Codec.read_property(node, prop)
+	var outcome := _set_outcome(asked, before, after)
+	# 🔴 A REFUSED WRITE PUTS THE PROPERTY BACK, and the first draft of this fix did not.
+	# The engine has already coerced by the time we can compare, so `{"x":.., "y":..}`
+	# landing in a Vector2 had ALREADY overwritten (123, 456) with (0, 0) — and reporting
+	# that honestly would have left the caller with an accurate message and a broken
+	# scene. An error the tool raises about its own write must not also BE a write.
+	if outcome == "mismatch" or outcome == "ignored":
+		Codec.write_property(node, prop, before)
+	if outcome == "mismatch":
+		return _err(
+			"set_mismatch",
+			"%s.%s holds %s after the write and %s was asked for. Nothing the caller wrote survived: rich types cross this wire as {\"__type__\": \"Vector2\", \"x\": .., \"y\": ..} and a bare map, array or string is not that."
+				% [_path_of(node), prop, _describe(after), _describe(asked)]
+		)
+	if outcome == "ignored":
+		return _err(
+			"set_ignored",
+			"%s.%s is unchanged at %s after being asked for %s. The property may not exist on this node, or its setter refused the value."
+				% [_path_of(node), prop, _describe(after), _describe(asked)]
+		)
+	var out := {"path": _path_of(node), "property": prop, "value": Codec.encode(after)}
+	if outcome == "coerced":
+		# The write LANDED and the engine changed it — a clamp, a snap, a normalise.
+		# Saying so is the difference between a tool that is honest about what it did
+		# and one that lets the caller assume.
+		out["coerced"] = true
+		out["requested"] = Codec.encode(asked)
+	return _ok(out)
+
+
+## `type_string(typeof(v))` plus the value, for a message a reader can act on.
+static func _describe(v: Variant) -> String:
+	return "%s %s" % [type_string(typeof(v)), JSON.stringify(Codec.encode(v))]
 
 
 func _call_method(params: Dictionary) -> Dictionary:
@@ -600,25 +677,52 @@ func _inject_input(params: Dictionary) -> Dictionary:
 			var mb := InputEventMouseButton.new()
 			mb.button_index = int(ev.get("button", 1))
 			mb.pressed = bool(ev.get("pressed", true))
-			var pos: Variant = Codec.decode(ev.get("position"))
-			if pos is Vector2:
-				mb.position = pos
+			var pos_err := _apply_vector2(ev, "position", func(v: Vector2) -> void: mb.position = v)
+			if not pos_err.is_empty():
+				return pos_err
 			Input.parse_input_event(mb)
 			return _ok({"injected": true, "kind": kind})
 		"mouse_motion":
 			var mm := InputEventMouseMotion.new()
-			var mpos: Variant = Codec.decode(ev.get("position"))
-			if mpos is Vector2:
-				mm.position = mpos
-			var rel: Variant = Codec.decode(ev.get("relative"))
-			if rel is Vector2:
-				mm.relative = rel
+			var mpos_err := _apply_vector2(ev, "position", func(v: Vector2) -> void: mm.position = v)
+			if not mpos_err.is_empty():
+				return mpos_err
+			var rel_err := _apply_vector2(ev, "relative", func(v: Vector2) -> void: mm.relative = v)
+			if not rel_err.is_empty():
+				return rel_err
 			Input.parse_input_event(mm)
 			return _ok({"injected": true, "kind": kind})
 		_:
 			return _err("bad_kind", "Unknown input kind: %s" % kind)
 
 
+## Apply an OPTIONAL Vector2 field of a synthetic input event, or say why not.
+##
+## 🔴 THIS WAS `if pos is Vector2:` WITH NO ELSE, and it is the one place in the addon
+## where something really did discard silently — the shape issue #327 reported as
+## *Vector2 in mouse-motion events makes mouse-driven controls unreachable*. An
+## untagged `{"x": .., "y": ..}` decodes to a Dictionary, fails the type test, and the
+## event was injected AT THE ORIGIN with `{"injected": true}` on the way back. The
+## caller then read a game that had been clicked at (0, 0).
+##
+## Absent stays absent — these fields are genuinely optional and an omitted position
+## means *wherever the event lands by default*. PRESENT AND UNUSABLE is the error:
+## the caller aimed at something and missed by the width of the screen.
+## Returns {} when there is nothing to report, an `_err` envelope otherwise.
+func _apply_vector2(ev: Dictionary, field: String, apply: Callable) -> Dictionary:
+	if not ev.has(field):
+		return {}
+	var decoded: Variant = Codec.decode(ev[field])
+	if decoded is Vector2:
+		apply.call(decoded as Vector2)
+		return {}
+	return _err(
+		"bad_event_field",
+		"event.%s is %s and a Vector2 is required. Rich types cross this wire tagged: {\"__type__\": \"Vector2\", \"x\": .., \"y\": ..} — a bare map, array or string is not that, and injecting the event without it would have aimed at the origin."
+			% [field, _describe(decoded)]
+	)
+
+
 func _get_monitors(params: Dictionary) -> Dictionary:
 	var out := {}
 	var keys: Array = params.get("keys", [])

package/addon/breakpoint_mcp/variant_json.gd

@@ -106,3 +106,93 @@ static func decode(j: Variant) -> Variant:
 			arr.append(decode(item))
 		return arr
 	return j
+
+
+## 🔴 WHY THE FOUR MEMBERS BELOW EXIST — issue #327, and the reporter's own diagnosis
+## was wrong in a way worth writing down. They read *vectors dropped, falsy scalars
+## dropped, indexed paths null* as one truthiness guard in this file's decode path.
+## Measured live on Godot 4.7, both sides of the wire driven separately: real `false`,
+## `0` and `0.0` round-trip correctly and always have. What they actually hit was a
+## String reaching a bool property — Godot coerces any non-empty String to `true`, so
+## `"false"` reads back as `true` — and `set_property` had no way to notice, because it
+## answered with a FRESH READ-BACK it never compared to what was asked.
+##
+## 🔴 SO THE REPAIR IS A COMPARISON AND NOT A GUARD. A guard has to enumerate the ways
+## a write can fail to land; a comparison asks the only question that matters — is the
+## value the caller asked for the value the engine now holds — and is therefore correct
+## for the failure modes nobody has met yet.
+
+
+## True when `prop` names a SUB-property rather than a property: `position:x`,
+## `material_override:shader_parameter/albedo`.
+##
+## 🔴 THE COLON FORM IS `get_indexed`'s VOCABULARY, NOT `get`'s, and the two are
+## different methods rather than two spellings of one. `Object.get("position:x")`
+## answers `null` — not an error, not a warning — which is why #327 read this as the
+## property being unreadable rather than as the wrong method being called.
+static func is_indexed(prop: String) -> bool:
+	return prop.contains(":")
+
+
+## Read a property that may or may not be indexed.
+static func read_property(o: Object, prop: String) -> Variant:
+	if is_indexed(prop):
+		return o.get_indexed(NodePath(prop))
+	return o.get(prop)
+
+
+## Write a property that may or may not be indexed.
+static func write_property(o: Object, prop: String, v: Variant) -> void:
+	if is_indexed(prop):
+		o.set_indexed(NodePath(prop), v)
+	else:
+		o.set(prop, v)
+
+
+## Could a value of type `asked` ever be what the engine STORED as type `got`?
+##
+## 🔴 THIS IS THE LINE BETWEEN A COERCION AND A MISTAKE, and it is drawn at the type
+## rather than at the value on purpose. A setter that clamps, snaps or normalises
+## stores a DIFFERENT VALUE OF THE SAME TYPE and is doing its job — refusing that
+## would break every `Range.value` in every project. A String that lands in a bool,
+## or a Dictionary that lands in a Vector2, is a different kind of event: nothing the
+## caller wrote survived, and the engine says nothing about it.
+##
+## The three promotions below are Godot's own and are never mistakes: int <-> float,
+## String <-> StringName, and a plain Array into any of the packed array types (JSON
+## has one array and the engine has ten).
+static func types_compatible(asked: int, got: int) -> bool:
+	if asked == got:
+		return true
+	if _is_numeric(asked) and _is_numeric(got):
+		return true
+	if _is_stringy(asked) and _is_stringy(got):
+		return true
+	if asked == TYPE_ARRAY and _is_packed_array(got):
+		return true
+	return false
+
+
+static func _is_numeric(t: int) -> bool:
+	return t == TYPE_INT or t == TYPE_FLOAT
+
+
+static func _is_stringy(t: int) -> bool:
+	return t == TYPE_STRING or t == TYPE_STRING_NAME
+
+
+static func _is_packed_array(t: int) -> bool:
+	return t in [
+		TYPE_PACKED_BYTE_ARRAY, TYPE_PACKED_INT32_ARRAY, TYPE_PACKED_INT64_ARRAY,
+		TYPE_PACKED_FLOAT32_ARRAY, TYPE_PACKED_FLOAT64_ARRAY, TYPE_PACKED_STRING_ARRAY,
+		TYPE_PACKED_VECTOR2_ARRAY, TYPE_PACKED_VECTOR3_ARRAY, TYPE_PACKED_COLOR_ARRAY,
+	]
+
+
+## Did the engine store the value that was asked for? Numeric pairs are compared
+## approximately, because an int asked of a float property stores a float and the two
+## are the same answer.
+static func values_equal(asked: Variant, got: Variant) -> bool:
+	if _is_numeric(typeof(asked)) and _is_numeric(typeof(got)):
+		return is_equal_approx(float(asked), float(got))
+	return asked == got

package/dist/dap.js

@@ -120,9 +120,15 @@ export function unorderedHandshakeWarning(waitedMs) {
 export const DAP_RESTART_REMEDY = "Call `dbg_launch` or `dbg_attach` first — a restart reuses the parameters of a launch that already happened, and none has.";
 /**
  * Per-line breakpoint modifier fields, each gated by an adapter capability. Godot
- * advertises all three false AND ignores them — a "conditional" breakpoint halts
+ * advertises none of the three AND ignores them — a "conditional" breakpoint halts
  * unconditionally (measured live on 4.3 and 4.7), so an undropped modifier is not a
  * no-op, it is the opposite of what the caller asked for.
+ *
+ * 🔴 278 — THE KEYS ARE ABSENT, NOT `false`, AND THIS PARAGRAPH SAID `false` FOR AS LONG
+ * AS IT HAS EXISTED. Both read the same way through `!== true`, which is why nothing ever
+ * caught it; they are different facts about the adapter, and `docs/dap_capability_ledger.json`
+ * is where the difference is now recorded rather than described. The ledger carries the run
+ * the reading came from, so the next reader can check it instead of believing this comment.
  */
 export const BREAKPOINT_MODIFIER_CAPS = {
     condition: "supportsConditionalBreakpoints",

package/dist/index.js

@@ -17,6 +17,7 @@ import { applyWireDefaults } from "./wire-defaults.js";
 import { applyOutputSchemas } from "./schemas.js";
 import { applyAnnotations } from "./annotations.js";
 import { applyTimeoutCaveat } from "./timeout-caveat.js";
+import { packageVersion } from "./version.js";
 import { applyCapabilities, applyDroppedToolRefusal, droppedTools, registerCapabilitiesResource, selectPrivilegedGroups, } from "./capabilities.js";
 import { taskStore, TASK_CAPABILITIES } from "./tasks.js";
 import { RESOURCE_CAPABILITIES, registerResourceSubscriptions } from "./subscriptions.js";
@@ -52,7 +53,14 @@ 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.81.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    // 🔴 READ, NEVER WRITTEN HERE (#248, twenty-eight sessions). This is the version every
+    // connected client is told at `initialize`, and it was the ONE place in host/src where
+    // a version was a literal — while `--version`, `lsp.ts`'s clientInfo and `cslsp.ts`'s
+    // all call `packageVersion()`. `version.ts` says why in its own words: the best
+    // outcome is not a gated literal but no literal at all, and the incident it documents
+    // is this exact field — twenty-odd releases announcing 0.2.0 to every language server
+    // they met, because a literal nobody compares to anything cannot go stale loudly.
+    const server = new McpServer({ name: "breakpoint-mcp", version: packageVersion() }, { 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/schemas.js

@@ -19,6 +19,32 @@ import { z } from "zod";
  *    scalar, array, or a {"__type__": ...}-tagged object — so it stays `any`.
  */
 const encodedValue = z.any();
+/**
+ * The same Variant, on the way IN — and REQUIRED, which `z.any()` cannot be.
+ *
+ * 🔴 ISSUE #327, AND THE HALF OF IT NOBODY HAD REPORTED. `z.any()` answers true to
+ * zod's `isOptional()`, so every input key spelled that way was published to clients
+ * OUTSIDE the JSON Schema's `required` list — including `value` on seven shipped
+ * tools whose own descriptions call it "New value". A client omitting it was doing
+ * exactly what our schema told it it could do, and the addon then read
+ * `params.get("value")` as null and wrote the property type's ZERO over whatever was
+ * there. Measured on Godot 4.7: `rotation` 1.25 -> 0.0, `position` (123, 456) ->
+ * (0, 0), reported as success both times.
+ *
+ * 🔴 THE UNION IS THE POINT, NOT A NARROWING. It admits everything JSON can carry,
+ * including an explicit `null` — which is a real request (`material_override = null`)
+ * and is NOT the same request as sending nothing. What it stops admitting is
+ * ABSENCE. The addon refuses a missing key on its own side as well: a schema is the
+ * client's contract, and a direct socket has never had one.
+ */
+export const requiredEncodedValue = z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(z.any()),
+    z.record(z.string(), z.any()),
+]);
 const capturedRaw = z.object({
     code: z.number().nullable(),
     stdout: z.string(),
@@ -184,7 +210,11 @@ export const outputSchemas = {
     node_delete: { deleted: z.string() },
     node_rename: { path: z.string(), name: z.string() },
     node_reparent: { path: z.string() },
-    node_set_property: { path: z.string(), property: z.string(), value: encodedValue },
+    // `coerced`/`requested` appear only when the engine STORED something other than what
+    // was asked for and the type still matched — a clamp, a snap, a normalise (issue #327).
+    // Optional because the ordinary answer carries neither, and declared because a field the
+    // wire can carry and the schema cannot name is a field a strict client rejects.
+    node_set_property: { path: z.string(), property: z.string(), value: encodedValue, coerced: z.boolean().optional(), requested: encodedValue.optional() },
     node_get_property: { path: z.string(), property: z.string(), value: encodedValue },
     node_duplicate: { path: z.string(), name: z.string(), type: z.string() },
     node_get_children: { path: z.string(), children: z.array(z.object({ name: z.string(), type: z.string(), path: z.string() })) },
@@ -540,7 +570,7 @@ export const outputSchemas = {
         children: z.array(runtimeNode).optional(),
     },
     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_set_property: { ...engineLog, path: z.string(), property: z.string(), value: encodedValue, coerced: z.boolean().optional(), requested: encodedValue.optional() },
     runtime_call_method: { ...engineLog, return: encodedValue },
     runtime_emit_signal: { ...engineLog, emitted: z.boolean() },
     runtime_inject_input: { ...engineLog, injected: z.boolean(), kind: z.string() },

package/dist/tools/dap.js

@@ -398,17 +398,18 @@ export function registerDapTools(server, dap, cfg) {
             "or a path resolving outside the Godot project root — Godot binds breakpoints only to scripts in the project it runs, so " +
             "unlike cs_dbg_set_breakpoints an absolute path outside the root is refused here too. " +
             "Feature-detected: the per-line conditions / hit_conditions / log_messages modifiers are only sent when the connected adapter " +
-            "advertises support (supportsConditionalBreakpoints / supportsHitConditionalBreakpoints / supportsLogPoints). On an adapter that " +
-            "advertises them unsupported (Godot advertises all three false and IGNORES them, so the breakpoint would halt unconditionally) the " +
-            "modifier is dropped and the result includes `unsupported_modifiers` plus a `warning`. Detection happens when the breakpoints are " +
+            "advertises support (supportsConditionalBreakpoints / supportsHitConditionalBreakpoints / supportsLogPoints). Measured: no Godot " +
+            "build this project tests advertises it — 4.3-stable and 4.7-stable advertise none of the three (the keys are ABSENT rather than " +
+            "false) and IGNORE the modifiers, so such a breakpoint would halt unconditionally; see docs/dap_capability_ledger.json. All three " +
+            "are therefore dropped on every build measured, and the result includes `unsupported_modifiers` plus a `warning`. Detection happens when the breakpoints are " +
             "applied, so it covers buffered ones too: setting modifiers before a session exists returns `modifier_detection: \"deferred\"` with a " +
             "warning, and dbg_launch then reports the `unsupported_modifiers` actually dropped during the handshake.",
         inputSchema: {
             path: z.string().describe("Script path (res://..., absolute, or project-relative)"),
             lines: z.array(z.number().int().positive()).describe("1-based line numbers"),
-            conditions: z.array(z.string().nullable()).optional().describe("Optional per-line condition expressions (aligned to lines, use null to skip a line); break only when the expression is true"),
-            hit_conditions: z.array(z.string().nullable()).optional().describe("Optional per-line hit expressions aligned to lines, e.g. '>3' or '%5' — break based on hit count (null to skip)"),
-            log_messages: z.array(z.string().nullable()).optional().describe("Optional per-line log messages aligned to lines; a message turns that breakpoint into a LOGPOINT (logs and continues, never halts). {expr} interpolates (null to skip)."),
+            conditions: z.array(z.string().nullable()).optional().describe("Optional per-line condition expressions (aligned to lines, use null to skip a line); break only when the expression is true. Gated on supportsConditionalBreakpoints — Measured: no Godot build this project tests advertises it, so this is dropped and reported on every build measured."),
+            hit_conditions: z.array(z.string().nullable()).optional().describe("Optional per-line hit expressions aligned to lines, e.g. '>3' or '%5' — break based on hit count (null to skip). Gated on supportsHitConditionalBreakpoints — Measured: no Godot build this project tests advertises it, so this is dropped and reported on every build measured."),
+            log_messages: z.array(z.string().nullable()).optional().describe("Optional per-line log messages aligned to lines; a message turns that breakpoint into a LOGPOINT (logs and continues, never halts). {expr} interpolates (null to skip). Gated on supportsLogPoints — Measured: no Godot build this project tests advertises it, so this is dropped and reported on every build measured."),
         },
     }, async ({ path, lines, conditions, hit_conditions, log_messages }) => {
         try {
@@ -641,8 +642,11 @@ export function registerDapTools(server, dap, cfg) {
             "(DAP setExceptionBreakpoints). Pass the filter IDs to enable; call with no filters (or []) to clear them. The result echoes the " +
             "active filters and lists `available_filters` — the exception filters the connected adapter actually advertises. " +
             "Requires a running debug session. Not gated (it only configures the debugger). " +
-            "Feature-detected: on an adapter that advertises no exceptionBreakpointFilters (e.g. Godot 4.3, which also does not answer " +
-            "the request — it would otherwise time out) it returns a clear \"unsupported\" message WITHOUT sending anything.",
+            "Feature-detected: on an adapter that advertises no exceptionBreakpointFilters (which also does not answer the request — it would " +
+            "otherwise time out) it returns a clear \"unsupported\" message WITHOUT sending anything. Measured: no Godot build this project " +
+            "tests advertises it — 4.3-stable AND 4.7-stable both advertise no filters, so on a shipped engine it is unsupported surface today " +
+            "rather than a feature you can reach; see docs/dap_capability_ledger.json. This sentence used to name 4.3 alone as the example, " +
+            "which read as though a newer build had filters. None does.",
         inputSchema: {
             filters: z.array(z.string()).optional().describe("Exception filter IDs to enable (default none = clear). Choose from available_filters in the result."),
         },
@@ -782,6 +786,9 @@ export function registerDapTools(server, dap, cfg) {
             "list the valid goto targets on that line; when the line has exactly one target (or you pass `target_id`) it jumps there. " +
             "DESTRUCTIVE: skips or repeats code by moving execution — confirm with the user and keep this gated. " +
             "Feature-detected: on an adapter that does not advertise `supportsGotoTargetsRequest` it returns a clear \"unsupported\" message WITHOUT prompting. " +
+            "Measured: no Godot build this project tests advertises it — 4.3-stable and 4.7-stable both refuse this tool, so on a shipped engine it " +
+            "is unsupported surface today rather than a feature you can reach; see docs/dap_capability_ledger.json. It is kept, and kept guarded, " +
+            "because a capability is not a boundary and a build can start advertising it. " +
             "Refuses a source that can never carry a target — a missing file, a directory, an empty path (which resolves to the project root), " +
             "or a path resolving outside the Godot project root — the same guard dbg_set_breakpoints applies. " +
             "Only meaningful while stopped at a breakpoint.",
@@ -854,7 +861,9 @@ export function registerDapTools(server, dap, cfg) {
             "resolvable id is armed in one setDataBreakpoints call. Call with no `watch` (or []) to clear all data breakpoints. The result reports the " +
             "armed `breakpoints` (each with its resolved data_id and verified flag) and any `unresolved` variables the adapter cannot watch. " +
             "Requires a running session; NOT gated (it only configures the debugger). Feature-detected: on an adapter that does not advertise " +
-            "`supportsDataBreakpoints` it returns a clear \"unsupported\" message without sending any request.",
+            "`supportsDataBreakpoints` it returns a clear \"unsupported\" message without sending any request. Measured: no Godot build this " +
+            "project tests advertises it — 4.3-stable and 4.7-stable both refuse this tool, so on a shipped engine it is unsupported surface " +
+            "today rather than a feature you can reach; see docs/dap_capability_ledger.json.",
         inputSchema: {
             watch: z.array(z.object({
                 name: z.string().describe("Variable name to watch"),

package/dist/tools/editor/animation.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { requiredEncodedValue } from "../../schemas.js";
 import { gate } from "../../confirm.js";
 /** AnimationPlayer / Animation authoring + AnimationTree state machines. */
 export function registerAnimationTools(server, call) {
@@ -56,7 +57,7 @@ export function registerAnimationTools(server, call) {
             name: z.string().describe("Animation name"),
             track: z.number().int().describe("Track index"),
             time: z.number().describe("Key time in seconds"),
-            value: z.any().describe("Key value (JSON scalar, array, object, or a __type__-tagged Variant matching the track type)"),
+            value: requiredEncodedValue.describe("Key value (JSON scalar, array, object, or a __type__-tagged Variant matching the track type)"),
             transition: z.number().optional().describe("Transition curve exponent (default 1.0)"),
             library: z.string().optional().describe("Animation library name (default \"\")"),
         },

package/dist/tools/editor/core.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { requiredEncodedValue } from "../../schemas.js";
 import { gate } from "../../confirm.js";
 /** Editor session + core project settings (editor_* / project get/set). */
 export function registerCoreTools(server, call) {
@@ -35,7 +36,7 @@ export function registerCoreTools(server, call) {
         description: "Write a ProjectSettings value. Set save=true to persist to project.godot. DESTRUCTIVE — gated by confirmation.",
         inputSchema: {
             name: z.string().describe("ProjectSettings key"),
-            value: z.any().describe("New value; rich types use the {\"__type__\":...} tagging convention"),
+            value: requiredEncodedValue.describe("New value; rich types use the {\"__type__\":...} tagging convention"),
             save: z.boolean().optional().describe("Persist to disk (default false)"),
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },

package/dist/tools/editor/node.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { requiredEncodedValue } from "../../schemas.js";
 import { gate } from "../../confirm.js";
 /** Scene-tree node authoring: add / delete / reparent / property / group ops. */
 export function registerNodeTools(server, call, guard) {
@@ -48,7 +49,7 @@ export function registerNodeTools(server, call, guard) {
         inputSchema: {
             path: z.string().describe("Node path relative to the scene root"),
             property: z.string().describe("Property name, e.g. position, modulate, text"),
-            value: z.any().describe("New value (JSON scalar, array, object, or a __type__-tagged Variant)"),
+            value: requiredEncodedValue.describe("New value (JSON scalar, array, object, or a __type__-tagged Variant)"),
         },
     }, async ({ path, property, value }) => call("node.set_property", { path, property, value }));
     server.registerTool("node_get_property", {

package/dist/tools/editor/resource.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { requiredEncodedValue } from "../../schemas.js";
 import { gate } from "../../confirm.js";
 /**
  * Resource (.tres/.res) create / load / save / property / import ops.
@@ -100,7 +101,7 @@ export function registerResourceTools(server, call, guard) {
         inputSchema: {
             path: z.string().describe("Resource res:// path"),
             property: z.string().describe("Property name"),
-            value: z.any().describe("New value (JSON scalar or __type__-tagged Variant)"),
+            value: requiredEncodedValue.describe("New value (JSON scalar or __type__-tagged Variant)"),
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ path, property, value, confirm }) => {

package/dist/tools/editor/shader.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { requiredEncodedValue } from "../../schemas.js";
 import { gate } from "../../confirm.js";
 /** Shader + ShaderMaterial authoring. */
 export function registerShaderTools(server, call, guard) {
@@ -68,7 +69,7 @@ export function registerShaderTools(server, call, guard) {
         inputSchema: {
             path: z.string().describe("Node path relative to the scene root"),
             param: z.string().describe("Shader uniform name"),
-            value: z.any().describe("New value (JSON scalar or __type__-tagged Variant)"),
+            value: requiredEncodedValue.describe("New value (JSON scalar or __type__-tagged Variant)"),
         },
     }, async ({ path, param, value }) => call("shadermaterial.set_param", { path, param, value }));
 }

package/dist/tools/runtime.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { requiredEncodedValue } from "../schemas.js";
 import { isTransportUnavailable, remedyClause } from "../bridge.js";
 import { MAX_PEERS } from "../peers.js";
 import { gate } from "../confirm.js";
@@ -134,7 +135,7 @@ export function registerRuntimeTools(server, runtime, peers, config) {
     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, ...peerField },
+        inputSchema: { path: z.string(), property: z.string(), value: requiredEncodedValue, ...confirmField, ...peerField },
     }, async ({ path, property, value, confirm, peer }) => {
         const blocked = await gate(server, confirm, `Set live property ${path}.${property} on ${target(peer)}`);
         if (blocked)
@@ -371,7 +372,7 @@ export function registerRuntimeTools(server, runtime, peers, config) {
         inputSchema: {
             path: z.string().describe("Node path (relative to the current scene; '/root/...' absolute allowed)"),
             property: z.string().describe("Property to read on each poll"),
-            value: z.any().describe("Value to compare the property against (tagged-Variant form for complex types)"),
+            value: requiredEncodedValue.describe("Value to compare the property against (tagged-Variant form for complex types)"),
             op: z.enum(["eq", "ne", "gt", "ge", "lt", "le"]).optional().describe("Comparison operator (default eq)"),
             timeout_ms: z.number().int().positive().optional().describe("Maximum time to wait, in ms (default 5000)"),
             poll_interval_ms: z.number().int().positive().optional().describe("Delay between polls, in ms (default 100)"),

package/package.json

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