@xenolithengine/graph-mcp-server 0.7.0-beta.0

package/dist/resources.d.ts

@@ -0,0 +1,14 @@
+export interface ResourceDef {
+    /** Stable URI shown to MCP clients (e.g. Claude Desktop attachment pane). */
+    uri: string;
+    /** Short display name in the client. */
+    name: string;
+    /** One-line description for the LLM picking the right resource. */
+    description: string;
+    /** MIME type of the returned content. */
+    mimeType: string;
+    /** Existing remote tool name to call via the WS bridge to fetch content. */
+    remoteTool: string;
+}
+export declare const RESOURCES: ReadonlyArray<ResourceDef>;
+//# sourceMappingURL=resources.d.ts.map

package/dist/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAA;IACX,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAA;IACnB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAA;IAChB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,eAAO,MAAM,SAAS,EAAE,aAAa,CAAC,WAAW,CAehD,CAAA"}

package/dist/resources.js

@@ -0,0 +1,22 @@
+// MCP **resources** — read-only context the AI client can attach to its prompt without spending
+// a tool call per read. Each entry binds a stable URI (the spec calls these "resources") to a
+// fetcher; the fetcher calls back into the editor via the existing WS bridge using the SAME
+// remote tool name we already ship — `get_graph`, `list_node_types`, etc. — so there's no new
+// editor surface, just a different MCP-side exposure (resource vs tool).
+export const RESOURCES = [
+    {
+        uri: 'graph://current',
+        name: 'Current graph',
+        description: 'The live editor graph as xenolith.v1 JSON — nodes, edges, comments. Attach this to ask the AI about the current state without forcing it to call get_graph.',
+        mimeType: 'application/json',
+        remoteTool: 'get_graph',
+    },
+    {
+        uri: 'schema://types',
+        name: 'Node type schemas',
+        description: 'Every registered node type with its pins (label/direction/data type) and widgets. Attach this so the AI knows the available types before designing a graph — saves a list_node_types call per session.',
+        mimeType: 'application/json',
+        remoteTool: 'list_node_types',
+    },
+];
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,8FAA8F;AAC9F,4FAA4F;AAC5F,8FAA8F;AAC9F,yEAAyE;AAezE,MAAM,CAAC,MAAM,SAAS,GAA+B;IACnD;QACE,GAAG,EAAE,iBAAiB;QACtB,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,6JAA6J;QAC1K,QAAQ,EAAE,kBAAkB;QAC5B,UAAU,EAAE,WAAW;KACxB;IACD;QACE,GAAG,EAAE,gBAAgB;QACrB,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE,wMAAwM;QACrN,QAAQ,EAAE,kBAAkB;QAC5B,UAAU,EAAE,iBAAiB;KAC9B;CACF,CAAA"}

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { EditorBridge } from './bridge.js';
+/** Build the MCP server: advertise our tools, and on each tool call forward args to the connected
+ *  editor over the WS bridge. The MCP SDK handles stdio framing + JSON-RPC. */
+export declare function createMcpServer(bridge: EditorBridge): McpServer;
+export declare function startStdio(mcp: McpServer): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAEnE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAI1C;+EAC+E;AAC/E,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CAuD/D;AAED,wBAAsB,UAAU,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAG9D"}

package/dist/server.js

@@ -0,0 +1,58 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { EditorBridge } from './bridge.js';
+import { TOOLS } from './tools.js';
+import { RESOURCES } from './resources.js';
+/** Build the MCP server: advertise our tools, and on each tool call forward args to the connected
+ *  editor over the WS bridge. The MCP SDK handles stdio framing + JSON-RPC. */
+export function createMcpServer(bridge) {
+    const mcp = new McpServer({ name: 'xenolith-graph', version: '0.7.0-beta.0' });
+    // Resources — read-only context. Each one forwards to an existing remote tool over the WS
+    // bridge so the editor needs no separate code path. MCP clients (Claude Desktop / Cursor)
+    // list these alongside tools and let the user attach them as context.
+    for (const r of RESOURCES) {
+        mcp.registerResource(r.name, r.uri, { description: r.description, mimeType: r.mimeType }, async (uri) => {
+            try {
+                const data = await bridge.current().call(r.remoteTool, {});
+                return { contents: [{ uri: uri.href, mimeType: r.mimeType, text: JSON.stringify(data, null, 2) }] };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return { contents: [{ uri: uri.href, mimeType: 'text/plain', text: `error: ${message}` }] };
+            }
+        });
+    }
+    for (const def of Object.values(TOOLS)) {
+        mcp.registerTool(def.name, { description: def.description, inputSchema: def.schema.shape }, async (args) => {
+            try {
+                const result = await bridge.current().call(def.name, args);
+                // Screenshot tools return a data-URI in `dataUri`. Re-wrap as MCP ImageContent so clients
+                // (Claude Desktop / Cursor / etc.) actually render the picture instead of dumping the
+                // base64 string into chat. Everything else is JSON text content.
+                const r = (result ?? null);
+                if (r && typeof r.dataUri === 'string') {
+                    const match = r.dataUri.match(/^data:([^;]+);base64,(.*)$/s);
+                    if (match) {
+                        return {
+                            content: [
+                                { type: 'image', data: match[2], mimeType: match[1] },
+                                { type: 'text', text: JSON.stringify({ ...r, dataUri: '<image>' }) },
+                            ],
+                        };
+                    }
+                }
+                return { content: [{ type: 'text', text: JSON.stringify(result ?? null) }] };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return { content: [{ type: 'text', text: `error: ${message}` }], isError: true };
+            }
+        });
+    }
+    return mcp;
+}
+export async function startStdio(mcp) {
+    const transport = new StdioServerTransport();
+    await mcp.connect(transport);
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/tools.d.ts

@@ -0,0 +1,452 @@
+import { z, type ZodTypeAny } from 'zod';
+/** A declarative MCP tool. The server registers each one with the MCP SDK and routes the call to
+ *  the connected editor via the WS bridge by name. Tools are intentionally thin — the editor owns
+ *  validation and command semantics; the server just shapes the request and forwards it. */
+export interface ToolDef<Schema extends ZodTypeAny> {
+    /** Stable tool name. MCP clients invoke by this; the WS protocol forwards by this. */
+    name: string;
+    /** Free-text description shown to the LLM. */
+    description: string;
+    /** Input schema (zod). Becomes JSON-Schema for the MCP advertisement. */
+    schema: Schema;
+}
+export declare const TOOLS: {
+    readonly list_node_types: {
+        readonly name: "list_node_types";
+        readonly description: "List every node type registered in the editor with its pins (direction/label/type). ALWAYS call this before add_node and connect_pins so you can use the real type names and pin labels — otherwise pins will not match.";
+        readonly schema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    };
+    readonly get_graph: {
+        readonly name: "get_graph";
+        readonly description: "Return the current graph as xenolith.v1 JSON (nodes, edges, comments). Read-only snapshot.";
+        readonly schema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    };
+    readonly add_node: {
+        readonly name: "add_node";
+        readonly description: "Insert a node of the given type. Coordinates are OPTIONAL: if omitted the editor drops it just to the right of the existing graph (or at the origin if empty). Prefer adding all nodes without coordinates, then calling auto_layout once to tidy the whole picture — the LLM has no idea about node sizes/spacing, so manual coords almost always overlap.";
+        readonly schema: z.ZodObject<{
+            type: z.ZodString;
+            x: z.ZodOptional<z.ZodNumber>;
+            y: z.ZodOptional<z.ZodNumber>;
+            state: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "strict", z.ZodTypeAny, {
+            type: string;
+            x?: number | undefined;
+            y?: number | undefined;
+            state?: Record<string, unknown> | undefined;
+        }, {
+            type: string;
+            x?: number | undefined;
+            y?: number | undefined;
+            state?: Record<string, unknown> | undefined;
+        }>;
+    };
+    readonly connect_pins: {
+        readonly name: "connect_pins";
+        readonly description: "Connect an output pin (from) to a compatible input pin (to). Pin types must match (float→float, object→object). The `pin` field accepts the pin LABEL (\"Output\", \"In\") as returned by list_node_types, OR a numeric index (\"0\", \"1\"), OR the literal \"in\"/\"out\" for simple single-pin nodes — pick whatever is easiest. Never invent uuids. On error the response lists the available pins so you can retry.";
+        readonly schema: z.ZodObject<{
+            from: z.ZodObject<{
+                node: z.ZodString;
+                pin: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+            }, "strip", z.ZodTypeAny, {
+                node: string;
+                pin: string | number;
+            }, {
+                node: string;
+                pin: string | number;
+            }>;
+            to: z.ZodObject<{
+                node: z.ZodString;
+                pin: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+            }, "strip", z.ZodTypeAny, {
+                node: string;
+                pin: string | number;
+            }, {
+                node: string;
+                pin: string | number;
+            }>;
+        }, "strict", z.ZodTypeAny, {
+            from: {
+                node: string;
+                pin: string | number;
+            };
+            to: {
+                node: string;
+                pin: string | number;
+            };
+        }, {
+            from: {
+                node: string;
+                pin: string | number;
+            };
+            to: {
+                node: string;
+                pin: string | number;
+            };
+        }>;
+    };
+    readonly fit_view: {
+        readonly name: "fit_view";
+        readonly description: "Frame the whole graph (or a specific node subset) in the viewport with padding. No return value.";
+        readonly schema: z.ZodObject<{
+            nodeIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            padding: z.ZodOptional<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            nodeIds?: string[] | undefined;
+            padding?: number | undefined;
+        }, {
+            nodeIds?: string[] | undefined;
+            padding?: number | undefined;
+        }>;
+    };
+    readonly set_widget_value: {
+        readonly name: "set_widget_value";
+        readonly description: "Set the value of a widget on a node (slider/number/toggle/combo/text/color/custom). Value type must match the widget type (number for slider/number, boolean for toggle, string for combo/text/color, arbitrary JSON for custom). Undoable.";
+        readonly schema: z.ZodObject<{
+            nodeId: z.ZodString;
+            widget: z.ZodString;
+            value: z.ZodUnknown;
+        }, "strict", z.ZodTypeAny, {
+            nodeId: string;
+            widget: string;
+            value?: unknown;
+        }, {
+            nodeId: string;
+            widget: string;
+            value?: unknown;
+        }>;
+    };
+    readonly remove_node: {
+        readonly name: "remove_node";
+        readonly description: "Delete a node by id. Incident edges are removed automatically. Undoable.";
+        readonly schema: z.ZodObject<{
+            nodeId: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            nodeId: string;
+        }, {
+            nodeId: string;
+        }>;
+    };
+    readonly disconnect_edge: {
+        readonly name: "disconnect_edge";
+        readonly description: "Remove an edge by id (as returned by connect_pins or get_graph).";
+        readonly schema: z.ZodObject<{
+            edgeId: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            edgeId: string;
+        }, {
+            edgeId: string;
+        }>;
+    };
+    readonly create_macro: {
+        readonly name: "create_macro";
+        readonly description: "Wrap a set of nodes into a collapsed Macro (group). External edges touching the selection become proxy pins on the macro, so the macro behaves like a single node from the outside. Returns the macro id.";
+        readonly schema: z.ZodObject<{
+            nodeIds: z.ZodArray<z.ZodString, "many">;
+            title: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            nodeIds: string[];
+            title?: string | undefined;
+        }, {
+            nodeIds: string[];
+            title?: string | undefined;
+        }>;
+    };
+    readonly expand_macro: {
+        readonly name: "expand_macro";
+        readonly description: "Open a collapsed macro inline — members become visible again. Camera animates to fit the group automatically.";
+        readonly schema: z.ZodObject<{
+            macroId: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            macroId: string;
+        }, {
+            macroId: string;
+        }>;
+    };
+    readonly collapse_macro: {
+        readonly name: "collapse_macro";
+        readonly description: "Re-collapse an expanded macro back into a single node with proxy pins.";
+        readonly schema: z.ZodObject<{
+            macroId: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            macroId: string;
+        }, {
+            macroId: string;
+        }>;
+    };
+    readonly auto_layout: {
+        readonly name: "auto_layout";
+        readonly description: "Tidy the entire graph: re-position every node using a layered left-to-right layout based on edge topology (sources on the left, sinks on the right). Call this AFTER adding nodes/edges so the result looks like a hand-arranged graph instead of overlapping boxes. Safe to call multiple times.";
+        readonly schema: z.ZodObject<{
+            direction: z.ZodOptional<z.ZodEnum<["LR", "TB"]>>;
+            spacing: z.ZodOptional<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            direction?: "LR" | "TB" | undefined;
+            spacing?: number | undefined;
+        }, {
+            direction?: "LR" | "TB" | undefined;
+            spacing?: number | undefined;
+        }>;
+    };
+    readonly set_category_palette: {
+        readonly name: "set_category_palette";
+        readonly description: "Recolour every node by category. Pass a map of category id → CSS colour. Categories come from node schemas — the values returned by list_node_types under `category` (e.g. \"logic\", \"data\", \"macro\", \"utility\", or whatever the host registered). Each entry can be (a) a plain \"#RRGGBB\" / rgba(...) / CSS-named colour for a solid pill, or (b) an object `{start, end}` for a two-stop gradient header. Pass an empty object to reset to the theme defaults.";
+        readonly schema: z.ZodObject<{
+            palette: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, "strict", z.ZodTypeAny, {
+            palette: Record<string, unknown>;
+        }, {
+            palette: Record<string, unknown>;
+        }>;
+    };
+    readonly set_theme: {
+        readonly name: "set_theme";
+        readonly description: "Override a subset of theme tokens (colours, gradients, geometry) at runtime. Pass a partial token object — anything you do not specify keeps its current value. The shape mirrors the editor's theme tokens; the most common subset is `color.accent`, `color.surface.*`, `color.text.*`, `geometry.node.radius`. Use this to make AI-driven recolours visible without uploading a whole new theme.";
+        readonly schema: z.ZodObject<{
+            tokens: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, "strict", z.ZodTypeAny, {
+            tokens: Record<string, unknown>;
+        }, {
+            tokens: Record<string, unknown>;
+        }>;
+    };
+    readonly register_node_schema: {
+        readonly name: "register_node_schema";
+        readonly description: "Define a brand-new node type the user can then instantiate via add_node. The schema must include `type` (unique identifier), `title`, optional `category`, and a `pins` array (each pin has `kind`, `direction`, `type`, optional `label`). Optional `widgets` array describes inline controls — for `combo` widgets you MUST pass a `values` array; `slider`/`number` accept `min`/`max`/`step`. If list_node_types already shows a type with the name you want, prefer add_node on the existing type rather than registering a variant with a different name.";
+        readonly schema: z.ZodObject<{
+            type: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+            category: z.ZodOptional<z.ZodString>;
+            pins: z.ZodArray<z.ZodObject<{
+                kind: z.ZodDefault<z.ZodEnum<["data", "exec"]>>;
+                direction: z.ZodEnum<["in", "out"]>;
+                type: z.ZodString;
+                label: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                kind: "data" | "exec";
+                type: string;
+                direction: "in" | "out";
+                label?: string | undefined;
+            }, {
+                type: string;
+                direction: "in" | "out";
+                kind?: "data" | "exec" | undefined;
+                label?: string | undefined;
+            }>, "many">;
+            widgets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                key: z.ZodOptional<z.ZodString>;
+                type: z.ZodEnum<["number", "slider", "toggle", "combo", "text", "color", "button"]>;
+                label: z.ZodOptional<z.ZodString>;
+                values: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+                    label: z.ZodString;
+                    value: z.ZodString;
+                }, "strip", z.ZodTypeAny, {
+                    value: string;
+                    label: string;
+                }, {
+                    value: string;
+                    label: string;
+                }>]>, "many">>;
+                min: z.ZodOptional<z.ZodNumber>;
+                max: z.ZodOptional<z.ZodNumber>;
+                step: z.ZodOptional<z.ZodNumber>;
+            }, "strip", z.ZodTypeAny, {
+                id: string;
+                type: "number" | "slider" | "toggle" | "combo" | "text" | "color" | "button";
+                values?: (string | {
+                    value: string;
+                    label: string;
+                })[] | undefined;
+                label?: string | undefined;
+                key?: string | undefined;
+                min?: number | undefined;
+                max?: number | undefined;
+                step?: number | undefined;
+            }, {
+                id: string;
+                type: "number" | "slider" | "toggle" | "combo" | "text" | "color" | "button";
+                values?: (string | {
+                    value: string;
+                    label: string;
+                })[] | undefined;
+                label?: string | undefined;
+                key?: string | undefined;
+                min?: number | undefined;
+                max?: number | undefined;
+                step?: number | undefined;
+            }>, "many">>;
+        }, "strict", z.ZodTypeAny, {
+            type: string;
+            pins: {
+                kind: "data" | "exec";
+                type: string;
+                direction: "in" | "out";
+                label?: string | undefined;
+            }[];
+            title?: string | undefined;
+            category?: string | undefined;
+            widgets?: {
+                id: string;
+                type: "number" | "slider" | "toggle" | "combo" | "text" | "color" | "button";
+                values?: (string | {
+                    value: string;
+                    label: string;
+                })[] | undefined;
+                label?: string | undefined;
+                key?: string | undefined;
+                min?: number | undefined;
+                max?: number | undefined;
+                step?: number | undefined;
+            }[] | undefined;
+        }, {
+            type: string;
+            pins: {
+                type: string;
+                direction: "in" | "out";
+                kind?: "data" | "exec" | undefined;
+                label?: string | undefined;
+            }[];
+            title?: string | undefined;
+            category?: string | undefined;
+            widgets?: {
+                id: string;
+                type: "number" | "slider" | "toggle" | "combo" | "text" | "color" | "button";
+                values?: (string | {
+                    value: string;
+                    label: string;
+                })[] | undefined;
+                label?: string | undefined;
+                key?: string | undefined;
+                min?: number | undefined;
+                max?: number | undefined;
+                step?: number | undefined;
+            }[] | undefined;
+        }>;
+    };
+    readonly select_nodes: {
+        readonly name: "select_nodes";
+        readonly description: "Set the editor selection to exactly the listed node ids. Use to draw the user's attention to nodes the AI just changed, or to scope a follow-up operation visually.";
+        readonly schema: z.ZodObject<{
+            nodeIds: z.ZodArray<z.ZodString, "many">;
+        }, "strict", z.ZodTypeAny, {
+            nodeIds: string[];
+        }, {
+            nodeIds: string[];
+        }>;
+    };
+    readonly clear_selection: {
+        readonly name: "clear_selection";
+        readonly description: "Deselect every node.";
+        readonly schema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    };
+    readonly dive_into_template: {
+        readonly name: "dive_into_template";
+        readonly description: "Open a template-instance node to edit its inner subgraph. Pass the instance node id (as listed by get_graph). The breadcrumb in the editor updates so the user can see where they are.";
+        readonly schema: z.ZodObject<{
+            instanceId: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            instanceId: string;
+        }, {
+            instanceId: string;
+        }>;
+    };
+    readonly dive_out: {
+        readonly name: "dive_out";
+        readonly description: "Pop out of the current subgraph back to its parent. Optional `toDepth` jumps multiple levels at once (0 = back to Root).";
+        readonly schema: z.ZodObject<{
+            toDepth: z.ZodOptional<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            toDepth?: number | undefined;
+        }, {
+            toDepth?: number | undefined;
+        }>;
+    };
+    readonly find_nodes: {
+        readonly name: "find_nodes";
+        readonly description: "Search the current graph for nodes matching a predicate. Returns ids + types + labels. Combine fields with AND. Use this instead of pulling the whole graph when you only need a subset.";
+        readonly schema: z.ZodObject<{
+            type: z.ZodOptional<z.ZodString>;
+            category: z.ZodOptional<z.ZodString>;
+            titleContains: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            type?: string | undefined;
+            category?: string | undefined;
+            titleContains?: string | undefined;
+        }, {
+            type?: string | undefined;
+            category?: string | undefined;
+            titleContains?: string | undefined;
+        }>;
+    };
+    readonly describe_node: {
+        readonly name: "describe_node";
+        readonly description: "Return a detailed snapshot of one node: type, title, category, position, all pins (with live connections), and all widgets (with current values). Use before reasoning about a node — get_graph returns a thinner shape.";
+        readonly schema: z.ZodObject<{
+            nodeId: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            nodeId: string;
+        }, {
+            nodeId: string;
+        }>;
+    };
+    readonly screenshot: {
+        readonly name: "screenshot";
+        readonly description: "Render the entire graph (NOT just the viewport — every node, padded) to a base64-encoded PNG/JPEG. Use to verify what the user is seeing after a series of edits. The response is large — only call when you need to \"see\" the result.";
+        readonly schema: z.ZodObject<{
+            format: z.ZodOptional<z.ZodEnum<["png", "jpeg"]>>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            padding: z.ZodOptional<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            padding?: number | undefined;
+            format?: "png" | "jpeg" | undefined;
+            scale?: number | undefined;
+        }, {
+            padding?: number | undefined;
+            format?: "png" | "jpeg" | undefined;
+            scale?: number | undefined;
+        }>;
+    };
+    readonly node_screenshot: {
+        readonly name: "node_screenshot";
+        readonly description: "Render a single node's current view (with its widget values, status ring, the lot) to a base64-encoded image. Much smaller than full `screenshot`. Use when you want to inspect or show ONE node — e.g. \"did my set_widget_value land?\".";
+        readonly schema: z.ZodObject<{
+            nodeId: z.ZodString;
+            format: z.ZodOptional<z.ZodEnum<["png", "jpeg"]>>;
+            scale: z.ZodOptional<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            nodeId: string;
+            format?: "png" | "jpeg" | undefined;
+            scale?: number | undefined;
+        }, {
+            nodeId: string;
+            format?: "png" | "jpeg" | undefined;
+            scale?: number | undefined;
+        }>;
+    };
+    readonly list_recipes: {
+        readonly name: "list_recipes";
+        readonly description: "Return the named subgraph templates the editor knows about. Each entry has `id`, `title`, `description`, `category`, and `requires` (the schema types the recipe assumes exist). Use this BEFORE instantiate_recipe so you know which recipes are available and what types you may need to register_node_schema first.";
+        readonly schema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    };
+    readonly instantiate_recipe: {
+        readonly name: "instantiate_recipe";
+        readonly description: "Drop a named recipe into the current graph in one call. Creates every node + every edge, returns the map of recipe-local id → real node id (so you can describe_node / connect_pins to additional nodes after). If the recipe needs schemas that aren't registered, the call fails with a list of missing types — register them with register_node_schema and retry. Nodes are stacked at the origin; call auto_layout afterwards to tidy.";
+        readonly schema: z.ZodObject<{
+            id: z.ZodString;
+            x: z.ZodOptional<z.ZodNumber>;
+            y: z.ZodOptional<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            id: string;
+            x?: number | undefined;
+            y?: number | undefined;
+        }, {
+            id: string;
+            x?: number | undefined;
+            y?: number | undefined;
+        }>;
+    };
+};
+export type ToolName = keyof typeof TOOLS;
+export declare const TOOL_NAMES: ToolName[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,KAAK,UAAU,EAAE,MAAM,KAAK,CAAA;AAExC;;4FAE4F;AAC5F,MAAM,WAAW,OAAO,CAAC,MAAM,SAAS,UAAU;IAChD,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAA;IACnB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAA;CACf;AAED,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6LsC,CAAA;AAExD,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,KAAK,CAAA;AACzC,eAAO,MAAM,UAAU,EAAyB,QAAQ,EAAE,CAAA"}