breakpoint-mcp 1.1.0 → 1.2.1

package/README.md

@@ -15,10 +15,28 @@ architecture.
 
 ## Install
 
+The fastest path — from your Godot project folder, one command installs and enables the
+editor addon (bundled in this package) and prints your MCP-client config:
+
+```bash
+npx breakpoint-mcp init
+```
+
+Then open the project in Godot and verify the setup:
+
+```bash
+npx breakpoint-mcp doctor
+```
+
+`init` copies the addon into `addons/breakpoint_mcp/`, enables it in `project.godot`, and
+prints — or, with `--client claude-code|claude-desktop|cursor|windsurf|vscode`, writes —
+the client config. `doctor` checks the Godot binary, the addon, and the four bridges
+(add `--require-live` once the editor is open; `--json` for a machine-readable report).
+
+To install the `breakpoint-mcp` command globally instead of invoking it via `npx`:
+
 ```bash
-npx breakpoint-mcp          # run on demand
-# or
-npm i -g breakpoint-mcp     # install the `breakpoint-mcp` command
+npm i -g breakpoint-mcp
 ```
 
 Requires **Node ≥ 18**. The host targets the `@modelcontextprotocol/sdk` `1.x` line
@@ -60,10 +78,11 @@ section for each client's config file and format.
 
 ## The addon (required for the editor / runtime planes)
 
-Install the `breakpoint_mcp` editor addon into your Godot project (drop
-`addons/breakpoint_mcp/` in and enable it under Project Settings → Plugins). It opens the
-loopback servers this host connects to and auto-registers the in-game runtime bridge.
-Without it, only the headless-CLI (`godot_*`) plane works.
+`breakpoint-mcp init` installs and enables this for you — the editor addon ships **inside
+this package**, so you don't need the repository to get it. To do it by hand instead, copy
+`addons/breakpoint_mcp/` into your project and enable it under Project Settings → Plugins.
+Either way it opens the loopback servers this host connects to and auto-registers the
+in-game runtime bridge; without it, only the headless-CLI (`godot_*`) plane works.
 
 ## Local-first
 

package/addon/breakpoint_mcp/README.md

@@ -0,0 +1,28 @@
+# Breakpoint MCP (Godot editor addon)
+
+Loopback TCP/JSON bridge that exposes the live Godot editor (and, via the runtime autoload, the running game) to an MCP host so an AI assistant can drive it. Part of [breakpoint-mcp](../../../README.md).
+
+## Install
+1. Copy this `breakpoint_mcp/` folder into your project's `addons/` directory so the path is `res://addons/breakpoint_mcp/`.
+2. Enable it under **Project → Project Settings → Plugins → Breakpoint MCP**.
+3. On enable it listens on `127.0.0.1:9080`. Override the port by setting the `BREAKPOINT_BRIDGE_PORT` environment variable *before* launching Godot.
+
+Requires **Godot 4.2+** (uses the `EditorInterface` singleton; 4.4+ recommended).
+
+## Files
+- `plugin.gd` — `EditorPlugin` entry point; starts/stops the server.
+- `bridge_server.gd` — `TCPServer` polled from `_process`; newline-delimited JSON framing.
+- `operations.gd` — request handlers; every mutation is wrapped in `EditorUndoRedoManager`.
+- `variant_json.gd` — Variant ⇄ JSON codec (tagged rich types).
+
+## Protocol
+One JSON object per line (`\n`-terminated), both directions:
+```
+→ {"id":"<string>","method":"node.add","params":{"parent_path":".","type":"Sprite2D"}}
+← {"id":"<string>","ok":true,"result":{"path":"Sprite2D","name":"Sprite2D","type":"Sprite2D"}}
+← {"id":"<string>","ok":false,"error":{"code":"no_scene","message":"No scene is open"}}
+```
+Method names and payloads correspond 1:1 to the `editor_*` / `scene_*` / `node_*` tools in [`docs/TOOL_CATALOG.md`](../../../docs/TOOL_CATALOG.md).
+
+## Security
+Binds to loopback only. Handlers execute on the editor main thread. Treat the port as a local trust boundary — do not expose it beyond `127.0.0.1`.

package/addon/breakpoint_mcp/bridge_server.gd

@@ -0,0 +1,121 @@
+@tool
+extends Node
+## Loopback TCP server speaking newline-delimited JSON-RPC-ish messages.
+##
+## Wire format (both directions), one JSON object per line ("\n" terminated):
+##   request:  {"id": "<string>", "method": "<name>", "params": { ... }}
+##   response: {"id": "<string>", "ok": true,  "result": { ... }}
+##             {"id": "<string>", "ok": false, "error": {"code": ..., "message": ...}}
+##
+## Binds to 127.0.0.1 only. The port comes from the BREAKPOINT_BRIDGE_PORT env
+## var (default 9080). The socket is polled from `_process`, so all request
+## handlers run on the editor's main thread.
+
+const Operations := preload("res://addons/breakpoint_mcp/operations.gd")
+const DEFAULT_PORT := 9080
+
+var _server: TCPServer
+var _ops: Operations
+var _clients: Array = [] # Array of {peer: StreamPeerTCP, buf: String}
+var _port: int = DEFAULT_PORT
+
+
+func setup(plugin: EditorPlugin) -> void:
+	_ops = Operations.new()
+	_ops.setup(plugin)
+
+
+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)
+	_server = TCPServer.new()
+	var err := _server.listen(_port, "127.0.0.1")
+	if err != OK:
+		push_error("[breakpoint_mcp] could not listen on 127.0.0.1:%d (error %d)" % [_port, err])
+	else:
+		print("[breakpoint_mcp] listening on 127.0.0.1:%d" % _port)
+
+
+func shutdown() -> void:
+	for c in _clients:
+		var peer: StreamPeerTCP = c["peer"]
+		if peer:
+			peer.disconnect_from_host()
+	_clients.clear()
+	if _server:
+		_server.stop()
+		_server = null
+
+
+func _process(_delta: float) -> void:
+	if _server == null:
+		return
+	# Accept new connections.
+	while _server.is_connection_available():
+		var peer := _server.take_connection()
+		if peer:
+			_clients.append({"peer": peer, "buf": ""})
+	# Service existing connections.
+	var still_alive: Array = []
+	for c in _clients:
+		var peer: StreamPeerTCP = c["peer"]
+		peer.poll()
+		var status := peer.get_status()
+		if status == StreamPeerTCP.STATUS_ERROR or status == StreamPeerTCP.STATUS_NONE:
+			continue
+		var available := peer.get_available_bytes()
+		if available > 0:
+			var chunk := peer.get_data(available)
+			if chunk[0] == OK:
+				var bytes: PackedByteArray = chunk[1]
+				c["buf"] += bytes.get_string_from_utf8()
+		_drain_lines(c)
+		still_alive.append(c)
+	_clients = still_alive
+
+
+func _drain_lines(c: Dictionary) -> void:
+	var buf: String = c["buf"]
+	while true:
+		var nl := buf.find("\n")
+		if nl == -1:
+			break
+		var line := buf.substr(0, nl)
+		buf = buf.substr(nl + 1)
+		line = line.strip_edges()
+		if line != "":
+			_handle_line(c["peer"], line)
+	c["buf"] = buf
+
+
+func _handle_line(peer: StreamPeerTCP, line: String) -> void:
+	var parsed: Variant = JSON.parse_string(line)
+	if typeof(parsed) != TYPE_DICTIONARY:
+		_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 {}
+	var result: Dictionary
+	# Handlers never throw in normal operation; guard anyway.
+	result = _ops.dispatch(method, params)
+	var response := {"id": id}
+	response.merge(result)
+	_send(peer, response)
+
+
+func _send(peer: StreamPeerTCP, obj: Dictionary) -> void:
+	var text := JSON.stringify(obj) + "\n"
+	peer.put_data(text.to_utf8_buffer())
+
+
+## D3: push an unsolicited "resource changed" event to every connected client
+## so a subscribed MCP host can emit notifications/resources/updated. Events carry
+## no "id" (they are not responses); the host routes them by the "event" field.
+func broadcast_event(uri: String) -> void:
+	for c in _clients:
+		var peer: StreamPeerTCP = c["peer"]
+		if peer and peer.get_status() == StreamPeerTCP.STATUS_CONNECTED:
+			_send(peer, {"event": "resource.changed", "uri": uri})