breakpoint-mcp 1.14.1 → 1.19.0

package/README.md

@@ -3,8 +3,8 @@
 The MCP **host** for [Breakpoint MCP](https://github.com/jlivingston-Cipher/godot-breakpoint-mcp) —
 a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
 Godot game engine to AI coding assistants across four planes: headless CLI, the live
-editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **271 tools
-+ 5 MCP resources**, built against the stable `@modelcontextprotocol/sdk` 1.x API.
+editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **276 tools
++ 6 MCP resources**, built against the stable `@modelcontextprotocol/sdk` 1.x API.
 Developed and tested with **Claude**; because MCP is an open protocol, other clients can
 connect too (currently untested — reports welcome).
 

package/addon/breakpoint_mcp/bridge_secret.gd

@@ -0,0 +1,61 @@
+@tool
+extends RefCounted
+## Shared loopback-bridge auth: a per-project secret + a constant-time compare.
+##
+## The secret is a 64-char hex string minted once per project and stored at
+## res://.godot/breakpoint_mcp.secret. The .godot dir is engine-managed and, by
+## Godot convention, git-ignored — so the secret never lands in version control.
+## Both bridges in a project (the editor bridge_server and the runtime autoload)
+## read the SAME file, and the Node host reads it too, from
+## <projectPath>/.godot/breakpoint_mcp.secret — so all three agree with ZERO user
+## configuration. Host-side an env override (BREAKPOINT_BRIDGE_SECRET /
+## BREAKPOINT_RUNTIME_SECRET) wins, for advanced / host-launched-child cases.
+##
+## Why: the loopback bind (127.0.0.1) is the only access control otherwise, so any
+## OTHER local process on a shared machine could drive the bridge — including the
+## destructive editor ops that are elicitation-gated in the HOST. A direct socket
+## bypasses that host gate; requiring this handshake moves the gate's teeth to the
+## addon. Defense-in-depth, not a remote-RCE fix (loopback already blocks the net).
+
+const SECRET_PATH := "res://.godot/breakpoint_mcp.secret"
+
+
+## Return the shared secret, minting + persisting a fresh one if none exists.
+## Returns "" ONLY on an unrecoverable IO error — the caller then runs WITHOUT
+## auth (logging a warning) rather than bricking the bridge.
+static func load_or_mint() -> String:
+	if FileAccess.file_exists(SECRET_PATH):
+		var rf := FileAccess.open(SECRET_PATH, FileAccess.READ)
+		if rf != null:
+			var existing := rf.get_as_text().strip_edges()
+			rf = null
+			if existing.length() > 0:
+				return existing
+	# Mint 32 cryptographically-random bytes -> 64 hex chars.
+	var crypto := Crypto.new()
+	var hex := crypto.generate_random_bytes(32).hex_encode()
+	var godot_dir := ProjectSettings.globalize_path("res://.godot")
+	if not DirAccess.dir_exists_absolute(godot_dir):
+		DirAccess.make_dir_recursive_absolute(godot_dir)
+	var wf := FileAccess.open(SECRET_PATH, FileAccess.WRITE)
+	if wf == null:
+		return ""
+	wf.store_string(hex)
+	wf = null
+	return hex
+
+
+## Constant-time equality over the UTF-8 bytes of two strings. Folds any length
+## difference into the result and always scans the longer input, so it never
+## short-circuits on the first differing byte (no timing side channel on the
+## secret's content). The secret's length is fixed (64) and not itself sensitive.
+static func const_time_eq(a: String, b: String) -> bool:
+	var ab := a.to_utf8_buffer()
+	var bb := b.to_utf8_buffer()
+	var diff: int = ab.size() ^ bb.size()
+	var n: int = ab.size() if ab.size() > bb.size() else bb.size()
+	for i in n:
+		var x: int = ab[i] if i < ab.size() else 0
+		var y: int = bb[i] if i < bb.size() else 0
+		diff |= x ^ y
+	return diff == 0

package/addon/breakpoint_mcp/bridge_server.gd

@@ -13,6 +13,8 @@ extends Node
 
 const Operations := preload("res://addons/breakpoint_mcp/operations.gd")
 const DEFAULT_PORT := 9080
+const BridgeSecret := preload("res://addons/breakpoint_mcp/bridge_secret.gd")
+const PauseLatch := preload("res://addons/breakpoint_mcp/pause_latch.gd")
 
 var _server: TCPServer
 var _ops: Operations
@@ -23,6 +25,11 @@ var _port: int = DEFAULT_PORT
 ## triggers a filesystem rescan/reimport) cannot re-enter `_process` and re-drain
 ## the same still-buffered line, which would recurse until the stack overflows.
 var _dispatching: bool = false
+## Loopback-auth handshake state (default-on; see bridge_secret.gd). `_secret` is
+## the shared per-project secret; `_auth_required` is false only when auth is
+## explicitly disabled (BREAKPOINT_BRIDGE_INSECURE) or the secret can't be minted.
+var _secret: String = ""
+var _auth_required: bool = false
 
 
 func setup(plugin: EditorPlugin) -> void:
@@ -34,6 +41,7 @@ func _ready() -> void:
 	var env_port := OS.get_environment("BREAKPOINT_BRIDGE_PORT")
 	if env_port != "" and env_port.is_valid_int():
 		_port = int(env_port)
+	_setup_auth()
 	_server = TCPServer.new()
 	var err := _server.listen(_port, "127.0.0.1")
 	if err != OK:
@@ -42,6 +50,22 @@ func _ready() -> void:
 		print("[breakpoint_mcp] listening on 127.0.0.1:%d" % _port)
 
 
+## Establish the loopback-auth secret unless explicitly disabled. Default-on:
+## BREAKPOINT_BRIDGE_INSECURE=1 (or =true) turns auth OFF (documented escape
+## hatch, not recommended). If the secret can't be persisted, run WITHOUT auth
+## rather than bricking the bridge (a broken mint must not lock out the host).
+func _setup_auth() -> void:
+	var insecure := OS.get_environment("BREAKPOINT_BRIDGE_INSECURE").to_lower()
+	if insecure == "1" or insecure == "true":
+		_auth_required = false
+		push_warning("[breakpoint_mcp] BREAKPOINT_BRIDGE_INSECURE set — loopback bridge auth DISABLED")
+		return
+	_secret = BridgeSecret.load_or_mint()
+	_auth_required = _secret != ""
+	if not _auth_required:
+		push_error("[breakpoint_mcp] could not establish bridge secret — running WITHOUT auth")
+
+
 func shutdown() -> void:
 	for c in _clients:
 		var peer: StreamPeerTCP = c["peer"]
@@ -83,7 +107,7 @@ func _process(_delta: float) -> void:
 	while _server.is_connection_available():
 		var peer := _server.take_connection()
 		if peer:
-			_clients.append({"peer": peer, "buf": ""})
+			_clients.append({"peer": peer, "buf": "", "authed": not _auth_required})
 	# Service existing connections.
 	var still_alive: Array = []
 	for c in _clients:
@@ -99,6 +123,10 @@ func _process(_delta: float) -> void:
 				var bytes: PackedByteArray = chunk[1]
 				c["buf"] += bytes.get_string_from_utf8()
 		_drain_lines(c)
+		if c.get("close", false):
+			peer.poll()
+			peer.disconnect_from_host()
+			continue
 		still_alive.append(c)
 	_clients = still_alive
 	_dispatching = false
@@ -114,19 +142,45 @@ func _drain_lines(c: Dictionary) -> void:
 		buf = buf.substr(nl + 1)
 		line = line.strip_edges()
 		if line != "":
-			_handle_line(c["peer"], line)
+			_handle_line(c, line)
+			if c.get("close", false):
+				break
 	c["buf"] = buf
 
 
-func _handle_line(peer: StreamPeerTCP, line: String) -> void:
+func _handle_line(c: Dictionary, line: String) -> void:
+	var peer: StreamPeerTCP = c["peer"]
 	var parsed: Variant = JSON.parse_string(line)
 	if typeof(parsed) != TYPE_DICTIONARY:
+		# Pre-auth we don't even echo a parse error (no-echo discipline) — deny + close.
+		if not c.get("authed", false):
+			_deny_unauth(c)
+			return
 		_send(peer, {"id": null, "ok": false, "error": {"code": "bad_json", "message": "Could not parse request line"}})
 		return
 	var req: Dictionary = parsed
 	var id: Variant = req.get("id", null)
 	var method := String(req.get("method", ""))
 	var params: Dictionary = req.get("params", {}) if typeof(req.get("params")) == TYPE_DICTIONARY else {}
+	# Handshake gate: an unauthenticated peer may ONLY authenticate. Anything else
+	# is denied with a generic code and the connection is closed.
+	if not c.get("authed", false):
+		if method == "auth" and BridgeSecret.const_time_eq(String(params.get("secret", "")), _secret):
+			c["authed"] = true
+			_send(peer, {"id": id, "ok": true})
+		else:
+			_deny_unauth(c)
+		return
+	# Pause latch (addon "Pause Agent" control): while a human has the agent paused
+	# from the editor dock, HOLD every new command except a liveness `ping` — reject
+	# without dispatching, so the host re-issues after resume. An op already running
+	# finishes (one line per tick). This is the coarse editor+runtime-plane stop,
+	# distinct from the host signal latch's finer, whole-surface, mutating-only hold.
+	if method != "ping" and PauseLatch.is_paused():
+		var held := {"id": id}
+		held.merge(PauseLatch.held_response(method))
+		_send(peer, held)
+		return
 	var result: Dictionary
 	# Handlers never throw in normal operation; guard anyway.
 	result = _ops.dispatch(method, params)
@@ -135,6 +189,14 @@ func _handle_line(peer: StreamPeerTCP, line: String) -> void:
 	_send(peer, response)
 
 
+## Generic, no-echo denial for an unauthenticated peer; marks the connection for
+## closing. Never reveals the expected secret, the received value, the failing
+## method, or any engine detail — only a fixed `unauthorized` code.
+func _deny_unauth(c: Dictionary) -> void:
+	_send(c["peer"], {"id": null, "ok": false, "error": {"code": "unauthorized"}})
+	c["close"] = true
+
+
 func _send(peer: StreamPeerTCP, obj: Dictionary) -> void:
 	var text := JSON.stringify(obj) + "\n"
 	peer.put_data(text.to_utf8_buffer())
@@ -146,5 +208,5 @@ func _send(peer: StreamPeerTCP, obj: Dictionary) -> void:
 func broadcast_event(uri: String) -> void:
 	for c in _clients:
 		var peer: StreamPeerTCP = c["peer"]
-		if peer and peer.get_status() == StreamPeerTCP.STATUS_CONNECTED:
+		if peer and c.get("authed", false) and peer.get_status() == StreamPeerTCP.STATUS_CONNECTED:
 			_send(peer, {"event": "resource.changed", "uri": uri})

package/addon/breakpoint_mcp/operations.gd

@@ -7,7 +7,7 @@ extends RefCounted
 ## wrapped in the EditorUndoRedoManager so a human can Ctrl-Z anything the assistant did.
 
 const Codec := preload("res://addons/breakpoint_mcp/variant_json.gd")
-const ADDON_VERSION := "1.4.3"
+const ADDON_VERSION := "1.7.0"
 
 var _plugin: EditorPlugin
 

package/addon/breakpoint_mcp/pause_latch.gd

@@ -0,0 +1,65 @@
+@tool
+extends RefCounted
+## Shared "Pause Agent" latch — the addon's human-facing control surface.
+##
+## The in-editor status dock's "Pause Agent" toggle engages this latch; both the
+## editor bridge (bridge_server.gd) and the runtime bridge (runtime_bridge.gd)
+## honor it. While paused they REJECT new agent commands on the editor + runtime
+## planes; an op already running finishes, and a bare `ping` still answers so the
+## host can see the bridge is alive. It is the visible companion to the host-side
+## signal latch (SIGUSR1/SIGUSR2): the host latch is the finer instrument (it
+## holds only MUTATING actions, across the WHOLE surface); this addon latch is the
+## coarse, one-click stop scoped to the two engine-facing bridges.
+##
+## Cross-process by design. The toggle lives in the EDITOR while the runtime bridge
+## lives in the RUNNING GAME (a separate OS process), so an in-memory flag can't be
+## shared. State is a flag FILE in the engine-managed, git-ignored res://.godot/ —
+## the same directory and the same reason bridge_secret.gd uses one: it is the one
+## place both the editor and an editor-launched game can reach. File present =
+## paused. Only the editor writes it; both bridges read it.
+##
+## NOT an emergency stop: it holds ENTRY to a new command and never interrupts an
+## in-flight op, and (unlike the queuing host latch) it does not hold the caller —
+## it rejects, so the host re-issues after resume.
+
+const FLAG_PATH := "res://.godot/breakpoint_mcp.pause"
+
+
+## True while the agent is paused (the flag file exists). One stat per call —
+## cheap enough for the dispatch seam — and always reflects the latest state
+## written by the editor, even from the separate game process.
+static func is_paused() -> bool:
+	return FileAccess.file_exists(FLAG_PATH)
+
+
+## Engage (paused=true) or clear (paused=false) the latch. Engaging writes a tiny
+## JSON marker (for legibility — presence is what the bridges read); clearing
+## removes the file. Best-effort: a failed write/remove logs a warning rather than
+## throwing, so the toggle can never brick the editor (mirrors bridge_secret's
+## mint-or-warn posture). Called only in the editor process, where res:// is
+## writable; the runtime bridge only ever reads via is_paused().
+static func set_paused(paused: bool) -> void:
+	if paused:
+		var f := FileAccess.open(FLAG_PATH, FileAccess.WRITE)
+		if f == null:
+			push_warning("[breakpoint_mcp] could not write pause flag %s" % FLAG_PATH)
+			return
+		f.store_string(JSON.stringify({"paused": true, "at": int(Time.get_unix_time_from_system())}))
+		f.close()
+	elif FileAccess.file_exists(FLAG_PATH):
+		var err := DirAccess.remove_absolute(ProjectSettings.globalize_path(FLAG_PATH))
+		if err != OK:
+			push_warning("[breakpoint_mcp] could not clear pause flag %s" % FLAG_PATH)
+
+
+## The standard "held" response a bridge returns for a command received while
+## paused — no dispatch happened. Mirrors the host confirm.ts blocking wording so
+## the agent gets a clear, actionable reason instead of a silent drop.
+static func held_response(method: String) -> Dictionary:
+	return {
+		"ok": false,
+		"error": {
+			"code": "paused",
+			"message": "Agent paused from the Breakpoint editor dock — \"%s\" was held and NOT executed. Resume from the dock, then re-issue." % method,
+		},
+	}

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

package/addon/breakpoint_mcp/plugin.gd

@@ -13,6 +13,7 @@ extends EditorPlugin
 
 const BridgeServer := preload("res://addons/breakpoint_mcp/bridge_server.gd")
 const StatusDock := preload("res://addons/breakpoint_mcp/status_dock.gd")
+const PauseLatch := preload("res://addons/breakpoint_mcp/pause_latch.gd")
 const RUNTIME_AUTOLOAD := "BreakpointRuntimeBridge"
 const RUNTIME_SCRIPT := "res://addons/breakpoint_mcp/runtime_bridge.gd"
 
@@ -43,6 +44,9 @@ func _enter_tree() -> void:
 		_selection.selection_changed.connect(_on_selection_changed)
 	if not scene_changed.is_connected(_on_scene_changed):
 		scene_changed.connect(_on_scene_changed)
+	# Pause is a session control: clear any flag left over from a prior session so a
+	# fresh editor always starts running (never silently paused by a stale file).
+	PauseLatch.set_paused(false)
 	print("[breakpoint_mcp] plugin enabled")
 
 
@@ -61,6 +65,8 @@ func _exit_tree() -> void:
 		_server.shutdown()
 		_server.queue_free()
 		_server = null
+	# Don't leave the agent latched paused once the plugin (and its dock) are gone.
+	PauseLatch.set_paused(false)
 	print("[breakpoint_mcp] plugin disabled")