breakpoint-mcp 1.4.0 → 1.12.0

package/README.md

@@ -3,7 +3,7 @@
 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. **244 tools
+editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **258 tools
 + 5 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).
@@ -30,7 +30,9 @@ 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
+the client config. By default it uses the addon bundled in this package; add
+`--from-github [ref]` to fetch the addon from GitHub instead (e.g. `--from-github main`).
+`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`:

package/addon/breakpoint_mcp/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Livingston and breakpoint-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/addon/breakpoint_mcp/bridge_server.gd

@@ -18,6 +18,11 @@ var _server: TCPServer
 var _ops: Operations
 var _clients: Array = [] # Array of {peer: StreamPeerTCP, buf: String}
 var _port: int = DEFAULT_PORT
+## Re-entrancy guard for `_process` (Finding D). True while a request dispatch is
+## on the stack, so a handler that pumps the editor main loop (e.g. `scene.save`
+## 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
 
 
 func setup(plugin: EditorPlugin) -> void:
@@ -64,6 +69,16 @@ func get_status() -> Dictionary:
 func _process(_delta: float) -> void:
 	if _server == null:
 		return
+	# Finding D: a request handler can pump the editor main loop (e.g. scene.save
+	# runs a filesystem rescan/reimport), which makes the engine call _process
+	# again *inside* the current dispatch. A client's line is only cleared from
+	# c["buf"] after _drain_lines returns, so a re-entrant tick would re-read and
+	# re-dispatch the SAME line, recursing until the stack overflows
+	# (operations.gd:512 _scene_save <-> _drain_lines/_handle_line here). Skip
+	# re-entrant ticks; buffered bytes are serviced on the next top-level tick.
+	if _dispatching:
+		return
+	_dispatching = true
 	# Accept new connections.
 	while _server.is_connection_available():
 		var peer := _server.take_connection()
@@ -86,6 +101,7 @@ func _process(_delta: float) -> void:
 		_drain_lines(c)
 		still_alive.append(c)
 	_clients = still_alive
+	_dispatching = false
 
 
 func _drain_lines(c: Dictionary) -> void:

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.0"
+const ADDON_VERSION := "1.4.2"
 
 var _plugin: EditorPlugin
 

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

package/dist/cli/github.js

@@ -0,0 +1,97 @@
+/**
+ * `--from-github` escape hatch for `breakpoint-mcp init`: fetch the editor addon
+ * (addons/breakpoint_mcp/**) straight from the GitHub repo at a chosen ref, as an
+ * alternative to the copy bundled in the npm tarball. Used when the bundled addon
+ * is missing/corrupt, or to install a different ref (e.g. `main`, or an older tag)
+ * than the one that shipped with the installed package.
+ *
+ * Dependency-free: one GitHub git/trees API call lists the addon's blobs at the ref,
+ * then each file is downloaded from raw.githubusercontent.com (a CDN that does not
+ * count against the REST rate limit). The fetch-shaped dependency is injectable, so
+ * the whole path is unit-testable offline.
+ */
+import fs from "node:fs";
+import path from "node:path";
+export const DEFAULT_REPO = "jlivingston-Cipher/godot-breakpoint-mcp";
+const ADDON_PREFIX = "addons/breakpoint_mcp/";
+const USER_AGENT = "breakpoint-mcp-cli";
+function defaultFetch() {
+    const f = globalThis.fetch;
+    if (typeof f !== "function") {
+        throw new Error("global fetch is unavailable — Node 18+ is required for --from-github.");
+    }
+    return f;
+}
+/** Validate and split an `owner/repo` slug; throws on anything else. */
+export function parseRepo(repo) {
+    const m = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(repo.trim());
+    if (!m)
+        throw new Error(`invalid --repo '${repo}' (expected owner/repo).`);
+    return { owner: m[1], name: m[2] };
+}
+function authHeaders() {
+    const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN;
+    const h = { "User-Agent": USER_AGENT };
+    if (token)
+        h.Authorization = `Bearer ${token}`;
+    return h;
+}
+/**
+ * Fetch addons/breakpoint_mcp/** from `repo` at `ref` into `dest` (created if
+ * needed). Returns the written relative paths. Throws a clear Error on a bad
+ * repo/ref, a missing addon, rate-limiting, or a network failure.
+ */
+export async function fetchAddonFromGitHub(opts, fetchFn) {
+    const doFetch = fetchFn ?? defaultFetch();
+    const { owner, name } = parseRepo(opts.repo);
+    const ref = opts.ref;
+    const treeUrl = `https://api.github.com/repos/${owner}/${name}/git/trees/${ref}?recursive=1`;
+    let treeRes;
+    try {
+        treeRes = await doFetch(treeUrl, {
+            headers: { ...authHeaders(), Accept: "application/vnd.github+json" },
+        });
+    }
+    catch (err) {
+        throw new Error(`could not reach GitHub: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (treeRes.status === 404) {
+        throw new Error(`GitHub returned 404 for ${owner}/${name}@${ref} — check the repo and ref.`);
+    }
+    if (treeRes.status === 403) {
+        throw new Error("GitHub returned 403 (rate-limited or forbidden). Set GITHUB_TOKEN to raise the limit, or retry later.");
+    }
+    if (!treeRes.ok) {
+        throw new Error(`GitHub git/trees request failed (HTTP ${treeRes.status}).`);
+    }
+    const body = (await treeRes.json());
+    if (body.truncated) {
+        throw new Error(`the repository tree at ${ref} was too large to list in one request; --from-github can't be used for this ref.`);
+    }
+    const entries = Array.isArray(body.tree) ? body.tree : [];
+    const files = entries.filter((e) => e.type === "blob" && e.path.startsWith(ADDON_PREFIX));
+    if (files.length === 0) {
+        throw new Error(`no ${ADDON_PREFIX} found in ${owner}/${name}@${ref}.`);
+    }
+    const written = [];
+    for (const f of files) {
+        const rawUrl = `https://raw.githubusercontent.com/${owner}/${name}/${ref}/${f.path}`;
+        let res;
+        try {
+            res = await doFetch(rawUrl, { headers: { "User-Agent": USER_AGENT } });
+        }
+        catch (err) {
+            throw new Error(`could not download ${f.path}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!res.ok) {
+            throw new Error(`could not download ${f.path} (HTTP ${res.status}).`);
+        }
+        const rel = f.path.slice(ADDON_PREFIX.length);
+        const outPath = path.join(opts.dest, rel);
+        fs.mkdirSync(path.dirname(outPath), { recursive: true });
+        fs.writeFileSync(outPath, Buffer.from(await res.arrayBuffer()));
+        written.push(rel);
+    }
+    return written;
+}
+//# sourceMappingURL=github.js.map

package/dist/cli/init.js

@@ -9,10 +9,12 @@
  * it into that client's config file (see clients.ts for the id list + paths).
  */
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "./args.js";
 import { CLIENT_IDS, clientInfo, mergeClientConfig, serverEntry, snippet } from "./clients.js";
+import { DEFAULT_REPO, fetchAddonFromGitHub } from "./github.js";
 const PLUGIN_REL = "addons/breakpoint_mcp";
 const PLUGIN_CFG_RES = "res://addons/breakpoint_mcp/plugin.cfg";
 const SERVER_NAME = "godot";
@@ -39,6 +41,23 @@ export function resolveBundledAddon() {
     }
     return null;
 }
+/** This package's own version, read from its package.json (null if unreadable). */
+function packageVersion() {
+    try {
+        const pkgRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", ".."); // dist/cli -> pkg
+        const v = JSON.parse(fs.readFileSync(path.join(pkgRoot, "package.json"), "utf8"))
+            .version;
+        return typeof v === "string" ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Default ref for --from-github: this package's version tag (vX.Y.Z), else main. */
+function defaultGitHubRef() {
+    const v = packageVersion();
+    return v ? `v${v}` : "main";
+}
 /**
  * Add `res://addons/breakpoint_mcp/plugin.cfg` to project.godot's
  * `[editor_plugins] enabled=PackedStringArray(...)`, creating the section or the
@@ -102,7 +121,7 @@ function claudeCodeCommand(projectPath) {
     return `claude mcp add godot --env GODOT_PROJECT=${projectPath} -- npx -y breakpoint-mcp`;
 }
 /** Entry point for `breakpoint-mcp init`. Returns the process exit code. */
-export async function runInit(argv) {
+export async function runInit(argv, deps = {}) {
     const { flags } = parseArgs(argv, ["force", "dry-run"]);
     const projectPath = typeof flags.project === "string"
         ? path.resolve(flags.project)
@@ -111,30 +130,69 @@ export async function runInit(argv) {
     const force = flags.force === true;
     const client = typeof flags.client === "string" ? flags.client : "none";
     const godotBin = process.env.GODOT_BIN ?? "godot";
+    // --from-github [ref]: source the addon from GitHub instead of the bundled copy.
+    const fromGitHub = "from-github" in flags;
+    const fgVal = flags["from-github"];
+    const ref = typeof fgVal === "string" && fgVal.length > 0 ? fgVal : defaultGitHubRef();
+    const repo = typeof flags.repo === "string" && flags.repo.length > 0 ? flags.repo : DEFAULT_REPO;
     const projGodot = path.join(projectPath, "project.godot");
     if (!fs.existsSync(projGodot)) {
         process.stderr.write(`init: no project.godot at ${projectPath}\n` +
             "  Pass --project <dir> pointing at your Godot project (the folder with project.godot).\n");
         return 1;
     }
-    const addonSource = resolveBundledAddon();
-    if (!addonSource) {
-        process.stderr.write("init: could not locate the bundled editor addon inside the package.\n");
-        return 1;
-    }
     const out = [];
     const say = (s = "") => {
         out.push(s);
     };
     say(`Project: ${projectPath}${dryRun ? "  (dry run — no changes written)" : ""}`);
+    // Resolve the addon source: the bundled copy, or (--from-github) a temp dir
+    // fetched from GitHub. The temp dir is removed once the addon is installed.
+    let addonSource = null;
+    let tmpFetchDir = null;
+    if (fromGitHub) {
+        if (dryRun) {
+            say(`  addon source: would fetch ${repo}@${ref} from GitHub`);
+        }
+        else {
+            say(`  addon source: fetching ${repo}@${ref} from GitHub…`);
+            tmpFetchDir = fs.mkdtempSync(path.join(os.tmpdir(), "bpmcp-gh-"));
+            try {
+                const written = await fetchAddonFromGitHub({ repo, ref, dest: tmpFetchDir }, deps.fetchFn);
+                say(`  addon source: fetched ${written.length} file(s) from ${repo}@${ref}`);
+                addonSource = tmpFetchDir;
+            }
+            catch (err) {
+                fs.rmSync(tmpFetchDir, { recursive: true, force: true });
+                process.stderr.write(`init: --from-github failed: ${err instanceof Error ? err.message : String(err)}\n` +
+                    "  Omit --from-github to install the addon bundled with this package.\n");
+                return 1;
+            }
+        }
+    }
+    else {
+        addonSource = resolveBundledAddon();
+        if (!addonSource) {
+            process.stderr.write("init: could not locate the bundled editor addon inside the package.\n" +
+                "  Reinstall breakpoint-mcp, or pass --from-github to fetch the addon from GitHub.\n");
+            return 1;
+        }
+    }
     // 1. Install the addon.
     const destHasAddon = fs.existsSync(path.join(projectPath, PLUGIN_REL, "plugin.cfg"));
     if (dryRun) {
         const verb = destHasAddon ? (force ? "overwrite" : "skip (already present; --force to overwrite)") : "install";
-        say(`  addon: would ${verb} → ${PLUGIN_REL}/`);
+        const srcNote = fromGitHub ? ` (from ${repo}@${ref})` : "";
+        say(`  addon: would ${verb} → ${PLUGIN_REL}/${srcNote}`);
     }
     else {
+        if (!addonSource) {
+            process.stderr.write("init: internal error — no addon source resolved.\n");
+            return 1;
+        }
         const r = installAddon(addonSource, projectPath, { force });
+        if (tmpFetchDir)
+            fs.rmSync(tmpFetchDir, { recursive: true, force: true });
         say(`  addon: ${r.action} → ${PLUGIN_REL}/`);
     }
     // 2. Enable it in project.godot.

package/dist/index.js

@@ -17,9 +17,11 @@ import { registerCsDapTools } from "./tools/csdap.js";
 import { registerRuntimeTools } from "./tools/runtime.js";
 import { registerProcessTools } from "./tools/processes.js";
 import { registerKnowledgeTools } from "./tools/knowledge.js";
+import { registerVcsTools } from "./tools/vcs.js";
 import { registerAssetGenTools } from "./tools/assetgen.js";
 import { registerNetcodeTools } from "./tools/netcode.js";
 import { registerBackendTools } from "./tools/backend.js";
+import { registerTabletopTools } from "./tools/tabletop.js";
 import { registerResources } from "./tools/resources.js";
 import { applyOutputSchemas } from "./schemas.js";
 import { taskStore, TASK_CAPABILITIES } from "./tasks.js";
@@ -43,7 +45,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.4.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.11.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
     // B1: enforce frozen output schemas on every structured tool. Must run before
     // the register*Tools calls below — it wraps server.registerTool.
     applyOutputSchemas(server);
@@ -65,6 +67,11 @@ async function main() {
     const processes = registerProcessTools(server, config);
     // Group K: host-side knowledge & search (project grep, symbol/usage index, idiom lookup).
     registerKnowledgeTools(server, config);
+    // Group L: host-side version control (vcs_*). Read-only core over the `git` binary
+    // (status/log/diff/show/branches/blame) rooted at the project path — no editor, no
+    // language server, so it answers whenever the project is a git work tree. Mutating
+    // git tools are deferred pending a scope steer and will reuse the elicitation gate.
+    registerVcsTools(server, config);
     // Group J: AI asset generation (delegated backend / connected client; degrades
     // to a request spec when no backend is configured). Writes + imports via the bridge.
     registerAssetGenTools(server, bridge, config);
@@ -76,6 +83,11 @@ async function main() {
     // Detects the installed SDK (SilentWolf/Nakama/PlayFab/Photon) and generates gated
     // GDScript against it; degrades cleanly when the SDK is absent or lacks the feature.
     registerBackendTools(server, bridge, config);
+    // Group N: card/board/piece authoring composites (card_*). Host-side scripted
+    // sequences of existing editor-bridge primitives (scene/control/node/theme/
+    // resource) — they build + data-bind scenes, add no addon method, and invent
+    // no game rules or data.
+    registerTabletopTools(server, bridge, config);
     // Phase 4: MCP resources (scene tree, editor state, runtime tree/log, ClassDB docs).
     registerResources(server, bridge, runtime);
     // D3: resource subscriptions — push notifications/resources/updated when a
@@ -118,6 +130,8 @@ function printUsage() {
         "  --client <id>       Write the MCP config for a client: claude-code | claude-desktop | cursor | windsurf | vscode.",
         "  --force             Overwrite an addon that is already installed.",
         "  --dry-run           Print what would change without writing anything.",
+        "  --from-github [ref] Fetch the editor addon from GitHub at [ref] (default: this package's version tag) instead of the bundled copy.",
+        "  --repo <owner/repo> With --from-github, the source repo (default: jlivingston-Cipher/godot-breakpoint-mcp).",
         "",
         "doctor options:",
         "  --project <dir>     Project to check (default: $GODOT_PROJECT or the current directory).",

package/dist/schemas.js

@@ -480,6 +480,95 @@ export const outputSchemas = {
         })),
         available: z.array(z.string()),
     },
+    // Group L — version control (tools/vcs.ts). Read-only git wrappers; shapes frozen
+    // from the host reshaping in vcs.ts (git status --porcelain=v2 / log / diff / show
+    // / branch / blame --line-porcelain).
+    vcs_status: {
+        branch: z.string().nullable(),
+        oid: z.string().nullable(),
+        upstream: z.string().nullable(),
+        ahead: z.number(),
+        behind: z.number(),
+        staged: z.array(z.object({ path: z.string(), status: z.string() })),
+        unstaged: z.array(z.object({ path: z.string(), status: z.string() })),
+        untracked: z.array(z.string()),
+        unmerged: z.array(z.string()),
+        clean: z.boolean(),
+    },
+    vcs_log: {
+        commits: z.array(z.object({
+            hash: z.string(), short: z.string(), author: z.string(), date: z.string(), subject: z.string(),
+        })),
+        count: z.number(),
+    },
+    vcs_diff: {
+        staged: z.boolean(),
+        path: z.string().nullable(),
+        files: z.array(z.string()),
+        patch: z.string(),
+        truncated: z.boolean(),
+    },
+    // vcs_show has two modes (commit vs file-at-ref); only `ref` is always present, the
+    // rest are populated per mode, so all but `ref` are optional.
+    vcs_show: {
+        ref: z.string(),
+        hash: z.string().optional(),
+        short: z.string().optional(),
+        author: z.string().optional(),
+        date: z.string().optional(),
+        subject: z.string().optional(),
+        body: z.string().optional(),
+        patch: z.string().optional(),
+        path: z.string().optional(),
+        content: z.string().optional(),
+        truncated: z.boolean(),
+    },
+    vcs_branch_list: {
+        current: z.string().nullable(),
+        branches: z.array(z.object({
+            name: z.string(), short_sha: z.string(), current: z.boolean(), remote: z.boolean(),
+        })),
+        count: z.number(),
+    },
+    vcs_blame: {
+        path: z.string(),
+        lines: z.array(z.object({
+            line: z.number(), commit: z.string(), author: z.string(), date: z.string(), text: z.string(),
+        })),
+        count: z.number(),
+        truncated: z.boolean(),
+    },
+    // Group L mutating tools (Tier A). Success shapes only; gated tools that are
+    // blocked/declined return isError (exempt from output-schema validation).
+    vcs_add: {
+        staged: z.array(z.object({ path: z.string(), status: z.string() })),
+        count: z.number(),
+    },
+    vcs_commit: {
+        committed: z.boolean(),
+        hash: z.string(),
+        short: z.string(),
+        summary: z.string(),
+    },
+    vcs_restore: {
+        restored: z.array(z.string()),
+        count: z.number(),
+    },
+    vcs_stash: {
+        op: z.string(),
+        message: z.string(),
+        stashes: z.array(z.object({ ref: z.string(), description: z.string() })),
+    },
+    vcs_branch_create: {
+        created: z.boolean(),
+        name: z.string(),
+        from: z.string().nullable(),
+        switched: z.boolean(),
+    },
+    vcs_switch: {
+        switched: z.boolean(),
+        branch: z.string(),
+    },
     // ClassDB-backed reference tools (tools/editor.ts -> operations.gd _classdb_reference / _docs_search).
     class_reference: {
         class: z.string(),
@@ -582,6 +671,132 @@ export const outputSchemas = {
             auth_scaffold: backendScaffold,
         };
     })(),
+    // ---- Group N: card/board/piece authoring composites (tools/tabletop.ts) ----
+    card_template_create: {
+        scene_path: z.string(),
+        script_path: z.string(),
+        root_type: z.string(),
+        has_back: z.boolean(),
+        node_count: z.number(),
+        saved: z.boolean(),
+        slots: z.array(z.object({ name: z.string(), node_path: z.string(), kind: z.string() })),
+    },
+    card_instance: {
+        instance_path: z.string(),
+        face_up: z.boolean(),
+        bound: z.array(z.string()),
+        unbound: z.array(z.string()),
+    },
+    card_hand_layout: {
+        container_path: z.string(),
+        mode: z.string(),
+        count: z.number(),
+        instances: z.array(z.object({ index: z.number(), instance_path: z.string() })),
+    },
+    card_deck_from_table: {
+        deck_container: z.string(),
+        count: z.number(),
+        rows_read: z.number(),
+        rows_skipped: z.number(),
+        unmapped_columns: z.array(z.string()),
+        instances: z.array(z.object({ row_index: z.number(), instance_path: z.string() })),
+    },
+    card_set_face: {
+        node_path: z.string(),
+        face_up: z.boolean(),
+        method: z.string(),
+        animated: z.boolean(),
+        player_path: z.string().nullable(),
+        anim: z.string().nullable(),
+    },
+    board_create: {
+        scene_path: z.string(),
+        root_type: z.string(),
+        cell_kind: z.string(),
+        layout_mode: z.string(),
+        cell_count: z.number(),
+        node_count: z.number(),
+        saved: z.boolean(),
+        cells: z.array(z.object({ id: z.string(), node_path: z.string(), x: z.number(), y: z.number() })),
+    },
+    board_place: {
+        placed: z.boolean(),
+        cell: z.string(),
+        cell_path: z.string(),
+        node_path: z.string(),
+        align: z.object({ x: z.number(), y: z.number() }),
+    },
+    board_tile_create: {
+        scene_path: z.string(),
+        layer_path: z.string(),
+        layer_name: z.string(),
+        rows: z.number(),
+        cols: z.number(),
+        tile_size: z.array(z.number()),
+        tileset_path: z.string(),
+        tileset_created: z.boolean(),
+        cell_count: z.number(),
+        painted: z.boolean(),
+        node_count: z.number(),
+        saved: z.boolean(),
+    },
+    board_tile_place: {
+        placed: z.boolean(),
+        coord: z.array(z.number()),
+        layer_path: z.string(),
+        node_path: z.string(),
+        local_pos: z.object({ x: z.number(), y: z.number() }),
+        tile_size: z.array(z.number()),
+        anchor: z.string(),
+        align: z.object({ x: z.number(), y: z.number() }),
+        reparented: z.boolean(),
+    },
+    piece_template_create: {
+        scene_path: z.string(),
+        script_path: z.string(),
+        root_type: z.string(),
+        has_label: z.boolean(),
+        has_hit_area: z.boolean(),
+        has_back: z.boolean(),
+        node_count: z.number(),
+        saved: z.boolean(),
+        nodes: z.array(z.object({ name: z.string(), node_path: z.string(), type: z.string() })),
+    },
+    piece_instance: {
+        instance_path: z.string(),
+        face_up: z.boolean(),
+        bound: z.array(z.string()),
+        unbound: z.array(z.string()),
+        placed: z.boolean(),
+        cell: z.string().nullable(),
+    },
+    piece_move: {
+        moved: z.boolean(),
+        from: z.string().nullable(),
+        to: z.string(),
+        node_path: z.string(),
+        animated: z.boolean(),
+    },
+    interact_make_draggable: {
+        node_path: z.string(),
+        mode: z.string(),
+        script_path: z.string(),
+        payload_keys: z.array(z.string()),
+        action: z.string().nullable(),
+        connected: z.boolean(),
+        composed: z.boolean(),
+        base_script: z.string().nullable(),
+    },
+    interact_add_drop_zone: {
+        node_path: z.string(),
+        mode: z.string(),
+        script_path: z.string(),
+        on_drop: z.string(),
+        accepts_key: z.string(),
+        accepts_values: z.array(z.string()),
+        notified: z.boolean(),
+        area_path: z.string().nullable(),
+    },
 };
 /**
  * Inject the frozen output schemas into every matching tool at registration