@tensor-cad/mcp 0.1.0

package/README.md

@@ -0,0 +1,217 @@
+# @tensor-cad/mcp
+
+An MCP server that lets an assistant design transformer language models and find out what they would cost, before anyone writes a training script.
+
+It wraps [`@tensor-cad/engine`](../engine), the analysis compiled from Go to WebAssembly: a typed block graph, symbolic shape inference, a design-rule check, the parameter/FLOPs/memory/cost model, and a PyTorch emitter. The server is headless — it works on `.tensorcad.json` files and the built-in reference architectures, with no editor running.
+
+Built on the official TypeScript SDK v2 (`@modelcontextprotocol/server` 2.0.0), served over stdio.
+
+## Install
+
+### Claude Code
+
+```bash
+# from a checkout, during development
+claude mcp add --transport stdio tensorcad -- bun packages/mcp/src/stdio.ts
+
+# published
+claude mcp add --transport stdio tensorcad -- npx -y @tensor-cad/mcp
+```
+
+Add `--scope project` to write a committed `.mcp.json` for everyone on the repo. Resources then surface as `@tensorcad:tensorcad://...` mentions and prompts as `/mcp__tensorcad__design_model`.
+
+### Cursor
+
+`.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project:
+
+```json
+{
+  "mcpServers": {
+    "tensorcad": {
+      "command": "npx",
+      "args": ["-y", "@tensor-cad/mcp"]
+    }
+  }
+}
+```
+
+Cursor keeps a limited number of tools active across all servers, which is why this one ships eighteen rather than forty.
+
+### Claude Desktop, in one click
+
+Download `tensorcad.mcpb` from a release and open it. Claude Desktop installs it
+as an extension and asks once for a folder to keep designs in.
+
+The bundle is the server built for Node — which Claude Desktop ships and this
+repository does not use — with the WebAssembly engine beside it. `bun run
+build:mcpb` builds one and starts it under Node before it is done, because the
+two things that have broken it were both differences between Bun and Node rather
+than anything in the server.
+
+### Claude Desktop, by hand
+
+`claude_desktop_config.json` (Settings, Developer, Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "tensorcad": {
+      "command": "npx",
+      "args": ["-y", "@tensor-cad/mcp"],
+      "env": { "TENSORCAD_ROOT": "/absolute/path/to/your/designs" }
+    }
+  }
+}
+```
+
+### Any client
+
+[`mcp.example.json`](./mcp.example.json) is the repo-relative development form: `bun packages/mcp/src/stdio.ts`, run from the repository root.
+
+`TENSORCAD_ROOT` sets the directory `tensorcad_list_designs` scans for `.tensorcad.json` files and that relative paths resolve against. It defaults to the process working directory.
+
+## Tools
+
+Eighteen, all namespaced `tensorcad_`. Every one declares an `inputSchema` and an `outputSchema` and returns `structuredContent` alongside a readable text mirror; reads are annotated `readOnlyHint` and `idempotentHint`, and the two that overwrite something are annotated `destructiveHint`.
+
+| Tool | What it does |
+|---|---|
+| `tensorcad_list_designs` | Open designs, the built-in reference architectures, and `.tensorcad.json` files on disk |
+| `tensorcad_new_design` | Start from a preset or from nothing; returns a `design_id` |
+| `tensorcad_open_design` | Load a `.tensorcad.json`; opening the same path twice returns the same handle |
+| `tensorcad_save_design` | Write a design back to disk |
+| `tensorcad_get_design` | `format: "outline"` (default) or `"full"` |
+| `tensorcad_get_block` | One block: parameters as written and as resolved, port shapes, wiring, parameter count |
+| `tensorcad_search_catalog` | The block catalog with parameter schemas, port patterns and docs |
+| `tensorcad_apply_ops` | Batched edits with optimistic concurrency |
+| `tensorcad_validate` | Every design rule, each finding with a fix hint |
+| `tensorcad_analyze` | Parameters, FLOPs, KV cache, memory, throughput, cost, Chinchilla |
+| `tensorcad_generate_code` | PyTorch module and config, inline or written to a directory |
+| `tensorcad_checkpoint` | Named snapshot |
+| `tensorcad_restore` | Back to a checkpoint, or undo the last batch |
+| `tensorcad_explain` | One block: what it contributes, and why it is the size it is |
+| `tensorcad_scale` | Shrink a design to a parameter budget, keeping its proportions |
+| `tensorcad_plan` | Every way to split the training across a cluster, and which of them fit |
+| `tensorcad_diff` | What changed between two designs, structurally and numerically |
+| `tensorcad_import_hf` | Read a Hugging Face `config.json` into a design |
+
+### Five that answer questions the others cannot
+
+`analyze` says what a design costs; it does not say *why*. `explain` takes one
+path and answers that — the parameters as written and as evaluated, the shape on
+every port, the share of the model's weights and compute — without the agent
+reading the whole document to work it out.
+
+`diff` is the other half of editing. An agent that has just applied four
+operations can ask what they moved, structurally and numerically, against the
+design it started from. `plan` answers the question that decides whether any of
+it matters: would this train on the machines available, and how would it have to
+be split.
+
+`scale` and `import_hf` both produce a design rather than a report, and both save
+it in the session, so the result can be analysed, diffed and generated from like
+any other. That is why the store gained `adopt`: `create` builds a design from a
+preset or from nothing, and these arrive whole.
+
+### Handles, not sessions
+
+`tensorcad_new_design` and `tensorcad_open_design` mint a `design_id`; everything else takes it as an argument. That is what the 2026-07-28 revision asks for — cross-call state travels as an explicit handle rather than as connection state — and it means a client can restart the server mid-conversation without losing the thread of *which* design is meant.
+
+Each design carries a `revision` that increments on every change. Pass `expected_revision` to `tensorcad_apply_ops` and a concurrent edit becomes a clear error naming the current revision, instead of a silent overwrite.
+
+### One patch tool, not thirty setters
+
+`tensorcad_apply_ops` takes a list of operations and applies them in order to a copy. The first rejected operation aborts the batch and the design is left exactly as it was, so a half-applied edit is never observable.
+
+| Op | Fields |
+|---|---|
+| `add_node` | `parent?`, `id`, `type`, `params?`, `label?` |
+| `remove_node` | `path` (its edges go with it) |
+| `set_param` | `path`, `key`, `value` |
+| `connect` | `graph?`, `from`, `to` |
+| `disconnect` | `graph?`, `from`, `to` |
+| `set_symbol` | `name`, `value` (number, expression, or `null` to delete), `doc?`, `runtime?` |
+| `rename` | `path`, `id` (edges are rewritten) |
+| `set_label` | `path`, `label` |
+
+A `path` is slash-separated (`layers/block`), and endpoints are `blockId:port` local to their own graph. Most designs are parameterised by symbols — `L` layers, `D` width, `H` heads, `Hkv` key/value heads, `dh` head dimension, `F` feed-forward width, `V` vocabulary — so `set_symbol` is usually the right edit rather than touching individual blocks.
+
+## Resources
+
+| URI | Contents |
+|---|---|
+| `tensorcad://designs/{id}` | The document plus its outline |
+| `tensorcad://designs/{id}/validation` | Every finding |
+| `tensorcad://designs/{id}/analysis` | Every number, at the document's own defaults |
+| `tensorcad://catalog` | Every block type with parameter schemas and port patterns |
+| `tensorcad://catalog/{type}` | One block type |
+| `tensorcad://schema/design` | JSON Schema for the `.tensorcad.json` format |
+
+The templated ones support argument completion, and the design and catalog templates enumerate their instances, so a client can offer them without guessing an id.
+
+## Prompts
+
+`design_model` (target parameter count, context length, family), `review_design`, `scale_design`, `explain_costs`.
+
+## A typical session
+
+```
+tensorcad_new_design { preset: "llama-3-8b" }        -> dsn_1, revision 1
+tensorcad_get_design { design_id: "dsn_1" }          -> the outline: symbols, blocks, edge shapes
+tensorcad_checkpoint { design_id: "dsn_1" }          -> ckpt_1
+tensorcad_apply_ops  { design_id: "dsn_1", expected_revision: 1,
+                    ops: [{ op: "set_symbol", name: "D", value: 5120 },
+                          { op: "set_symbol", name: "L", value: 40 }] }
+                                                  -> revision 2, parameters and a validation summary
+tensorcad_validate   { design_id: "dsn_1" }          -> findings with fix hints
+tensorcad_analyze    { design_id: "dsn_1", T: 8192, hardware: "h100-sxm", gpus: 8, zero: 3 }
+tensorcad_generate_code { design_id: "dsn_1", out_dir: "out/my-model" }
+tensorcad_restore    { design_id: "dsn_1", checkpoint_id: "ckpt_1" }   # if it did not work out
+```
+
+## The live editor bridge
+
+Start the server with `TENSORCAD_BRIDGE=1` and a running TensorCAD editor attaches to it. The agent's edits appear on the canvas as it makes them, and the human's edits come back the other way.
+
+```bash
+TENSORCAD_BRIDGE=1 bun run packages/mcp/src/stdio.ts
+```
+
+Then open the editor (`bun run --cwd packages/ui dev`, or the desktop build). The status bar's rightmost cell says `agent`, and pressing it detaches.
+
+What happens, in order: the editor finds the bridge, publishes the design on screen — so the agent works on *that*, not on a file that resembles it — and the agent sees it in `tensorcad_list_designs`. From then on `tensorcad_apply_ops` lands on the canvas, and what the human does lands in the agent's store, at which point the client is told through `notifications/resources/updated` that the design's resources moved. An edit that arrives from the agent goes onto the editor's undo stack, so the person watching can take it back.
+
+There is no second document. An earlier design had a `LiveStore` beside the `FileStore`, both behind `DocumentStore`; that gives a design two homes and no rule for which one is right when they differ. The bridge observes the one store the tools already write to, and an editor's edit goes through the same `apply` a tool call does — same revision check, same undo log.
+
+**Off unless asked for.** Without the environment variable the server opens no port and is exactly as headless as it was, which is what keeps it usable in CI.
+
+**Who can connect.** It binds 127.0.0.1, so nothing off the machine reaches it. It refuses an upgrade whose `Origin` is not a localhost one, because the same-origin policy does *not* stop a page on the internet opening a WebSocket to your loopback address. And it requires a token, written to `~/.tensorcad/session.json` with owner-only permissions and served to loopback callers of `GET /session` — a browser cannot read the file, which is the only reason that endpoint exists. Anything already running on this machine as you can read the file anyway; the token is not a defence against that and is not meant to be.
+
+`TENSORCAD_BRIDGE_PORT` moves it off 7357. The editor probes that port and the three above it, which is also the range the bridge falls back through when one is taken.
+
+Also deliberately absent: `tensorcad_render_preview` (a canvas image needs the editor) and `tensorcad_run_script` (a scripting escape hatch, which wants a sandbox and an opt-in environment variable before it is worth shipping). Both are in the research notes as future tools; leaving them out keeps the count where clients are happy.
+
+## Publishing
+
+`server.json` beside this README is the [MCP registry][registry] manifest:
+the namespace (`io.github.filip-pajalic/tensorcad`, which matches `mcpName` in
+`package.json`), the npm package it points at, and the one environment variable
+the server reads. It is checked against the registry's own schema when it is
+written and against `package.json` on every test run, because what drifts is not
+the schema but the version in two files.
+
+```bash
+mcp-publisher login github            # the namespace is verified as the GitHub user
+mcp-publisher publish --file server.json
+```
+
+[registry]: https://github.com/modelcontextprotocol/registry
+
+## Development
+
+```bash
+bun run packages/mcp/src/stdio.ts     # serve on stdio
+bun test packages/mcp/test            # contract tests: spin the server up and call every tool
+```
+
+The contract tests connect with the SDK's own client over a real stdio pipe and validate every tool's `structuredContent` against the `outputSchema` that tool advertised, so the declared contract and the actual answer cannot drift apart.

package/bridge/protocol.d.ts

@@ -0,0 +1,99 @@
+/**
+ * What the agent and the editor say to each other.
+ *
+ * The bridge carries *documents*, not just operations. Forwarding the op
+ * stream alone would make the canvas replay every edit the agent makes, which
+ * sounds elegant until the two ends disagree about what an op means and
+ * nothing notices: the editor would drift, silently, and the drawing would
+ * stop being the design. So every change carries the whole document as the
+ * truth, with the operations beside it as the *account* of what changed —
+ * which is what a person watching wants to read.
+ *
+ * A document is not large next to what a browser already holds, and the engine
+ * that would have to be asked to reconcile a divergence is the expensive part.
+ */
+import type { Doc } from "@tensor-cad/engine";
+import type { Op } from "../ops.js";
+import type { DesignSummary } from "../store/types.js";
+/**
+ * Bumped when a message changes shape. The editor refuses a bridge whose
+ * protocol it does not know rather than half-understanding it, because a
+ * canvas that mirrors *some* of an edit is worse than one that mirrors none.
+ */
+export declare const BRIDGE_PROTOCOL = 1;
+/** Why a design arrived. `requested` answers an `attach`; `published` answers a `publish`. */
+export type ChangeReason = "registered" | "applied" | "replaced" | "saved" | "restored" | "published" | "requested";
+export interface HelloMessage {
+    type: "hello";
+    protocol: number;
+    server: string;
+    version: string;
+    /** The directory the agent's relative paths resolve against, for the editor to show. */
+    root: string;
+    designs: DesignSummary[];
+}
+/** A design as it now stands. The one message that carries a document. */
+export interface DesignMessage {
+    type: "design";
+    reason: ChangeReason;
+    design: DesignSummary;
+    doc: Doc;
+    /** Present when `reason` is `applied`: what the agent did, in its own words. */
+    ops?: Op[];
+}
+export interface ErrorMessage {
+    type: "error";
+    message: string;
+    /** The message this is a reply to, when it was a reply to one. */
+    about?: ClientMessage["type"];
+}
+export type ServerMessage = HelloMessage | DesignMessage | ErrorMessage;
+/** "This is what I have open." The bridge takes it as a new design. */
+export interface PublishMessage {
+    type: "publish";
+    doc: Doc;
+}
+/**
+ * "I had this open before." Sent instead of `publish` after a reconnect, so a
+ * dropped socket does not leave the agent looking at two copies of one design.
+ * Answered with an error when the id is unknown — a restarted server has
+ * forgotten it — and the editor then publishes.
+ */
+export interface AttachMessage {
+    type: "attach";
+    design_id: string;
+}
+/** The human edited, in a way that is one of the agent's own operations. */
+export interface OpsMessage {
+    type: "ops";
+    design_id: string;
+    /** Rejected when it is not the current revision, exactly as `tensorcad_apply_ops` is. */
+    revision?: number;
+    ops: Op[];
+}
+/**
+ * The human edited, generally.
+ *
+ * Most of what an editor does is not one of the eight operations — a block
+ * moved on the sheet, a definition written, a configuration switched — so the
+ * editor's ordinary way of saying what it has is to say the whole thing. It is
+ * an `ops` message in every other respect: revision-checked, undoable, and
+ * announced to the agent.
+ */
+export interface ReplaceMessage {
+    type: "replace";
+    design_id: string;
+    revision?: number;
+    doc: Doc;
+}
+export type ClientMessage = PublishMessage | AttachMessage | OpsMessage | ReplaceMessage;
+/** What `~/.tensorcad/session.json` holds while a bridge is listening. */
+export interface SessionFile {
+    version: number;
+    protocol: number;
+    port: number;
+    token: string;
+    pid: number;
+    root: string;
+    started_at: string;
+}

package/bridge/server.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The live editor bridge: a loopback socket the running editor attaches to, so
+ * an agent's edits appear on the canvas as it makes them and the human's edits
+ * reach the agent.
+ *
+ * It is *not* a second document store. It watches the one store the tools
+ * already write to and mirrors every change outward; an editor's own edit goes
+ * through the same `apply` a tool call does, revision check and all. There is
+ * one document, one revision counter and one undo log, which is what makes
+ * "who is right" a question that never has to be answered.
+ *
+ * Off unless asked for. An MCP server that opened a port nobody requested
+ * would be a surprise in every CI job that runs one, so `TENSORCAD_BRIDGE=1`
+ * turns it on and the server is otherwise exactly as headless as it was.
+ *
+ * ## Who is allowed to connect
+ *
+ * Three things, in order of how much they actually do:
+ *
+ * 1. **The bind.** 127.0.0.1 only, so nothing off this machine can reach it.
+ * 2. **The origin.** A page on the internet can open a WebSocket to your
+ *    loopback address — the same-origin policy does not stop it — so the
+ *    upgrade is refused unless the `Origin` header is absent (a native client)
+ *    or names a localhost origin. This is the check that matters for a browser.
+ * 3. **The token.** A random 32 bytes, in `~/.tensorcad/session.json` with
+ *    owner-only permissions, and handed to loopback callers of `/session`.
+ *    It guards against another program on this machine that guessed the port.
+ */
+import type { DocumentStore, StoreChange } from "../store/types.js";
+/**
+ * Where the editor looks first. Fixed rather than ephemeral because a browser
+ * cannot read the session file to find out — it probes this and the three
+ * ports above it, which is also the range this server falls back through when
+ * one is taken.
+ */
+export declare const DEFAULT_BRIDGE_PORT = 7357;
+export declare const PORT_ATTEMPTS = 4;
+export interface BridgeOptions {
+    store: DocumentStore;
+    /** What `hello` reports as the agent's working directory. */
+    root: string;
+    name: string;
+    version: string;
+    port?: number;
+    /** Supplied by tests; otherwise 32 random bytes. */
+    token?: string;
+    /** Where to write the session file. Omitted means the real one. */
+    sessionFile?: string;
+    /** Somewhere to say what happened. Defaults to stderr, which is where a stdio server's diagnostics go. */
+    log?: (line: string) => void;
+}
+/**
+ * A design changed; something outside the bridge may want to know.
+ *
+ * `from` is the half the store cannot say. The MCP server needs it: telling an
+ * agent that a resource changed because the agent changed it is noise, and
+ * telling it when the *human* changed it is the whole point.
+ */
+export type BridgeWatcher = (change: StoreChange, from: "agent" | "editor") => void;
+export declare class BridgeServer {
+    readonly token: string;
+    private readonly http;
+    private readonly wss;
+    private readonly options;
+    private readonly log;
+    private unsubscribe?;
+    private readonly watchers;
+    private port_;
+    /**
+     * The connection whose message is being handled right now.
+     *
+     * The store calls its listeners synchronously, inside `apply`, so this is
+     * set for exactly the duration of that call and is how a change is
+     * attributed to the socket that caused it. An editor that has already drawn
+     * its own edit does not want it sent back.
+     */
+    private acting?;
+    constructor(options: BridgeOptions);
+    get port(): number;
+    /** `ws://127.0.0.1:<port>/bridge?token=…`, which is what the editor opens. */
+    get url(): string;
+    get connections(): number;
+    /** Called for every store change, after the mirror has gone out. */
+    watch(watcher: BridgeWatcher): () => void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * One endpoint, and it exists for one reason: a browser cannot read the
+     * session file. Everything else is a 404, because this is not a web server.
+     */
+    private serveHttp;
+    /** The reason to refuse, as an HTTP status line, or undefined to allow. */
+    private refuse;
+    private attach;
+    private handle;
+    private mirror;
+    private during;
+    private send;
+}
+/**
+ * A localhost page, the desktop shell, or a file:// document.
+ *
+ * `*.localhost` is here for Wails, which serves the desktop build from
+ * `http://wails.localhost` on Windows.
+ */
+export declare function isLocalOrigin(origin: string): boolean;

package/bridge/session.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `~/.tensorcad/session.json` — how a program on this machine finds the bridge.
+ *
+ * A file rather than a fixed port alone, because the port is only half the
+ * answer: the other half is the token, and a token that lives in a file with
+ * owner-only permissions is a token that a page you happened to visit cannot
+ * read. The desktop shell reads this file. A browser cannot, and gets the
+ * token from the bridge's own `/session` endpoint instead, which answers only
+ * a loopback caller — see `server.ts`.
+ *
+ * It is written when the bridge starts listening and removed when it stops,
+ * including on a clean exit. A file left behind by a crash names a port that
+ * answers nothing, which is why every reader checks the port rather than
+ * trusting the file.
+ */
+import { type SessionFile } from "./protocol.js";
+export declare const SESSION_VERSION = 1;
+/** Overridable so a test does not write into the developer's home directory. */
+export declare function sessionPath(): string;
+export declare function writeSession(session: Omit<SessionFile, "version" | "protocol">, path?: string): Promise<void>;
+export declare function readSession(path?: string): Promise<SessionFile | undefined>;
+export declare function clearSession(path?: string): Promise<void>;
+/** The same, for `process.on("exit")`, which cannot wait for a promise. */
+export declare function clearSessionSync(path?: string): void;

package/design-schema.d.ts

@@ -0,0 +1,198 @@
+/**
+ * JSON Schema for the design document, served as `tensorcad://schema/design`.
+ *
+ * Hand-written rather than derived, because the engine describes the
+ * document with TypeScript types and a per-block parameter catalog rather than
+ * one monolithic runtime schema. Block parameters are therefore `object` here;
+ * `tensorcad_search_catalog` is where the per-type parameter schemas live.
+ */
+export declare const DESIGN_JSON_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "tensorcad://schema/design";
+    readonly title: "TensorCAD design document";
+    readonly description: "The `.tensorcad.json` format. The graph is the source of truth; the editor's node positions are a view of it.";
+    readonly type: "object";
+    readonly required: readonly ["version", "meta", "symbols", "graph"];
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly version: {
+            readonly const: 1;
+            readonly description: "Document format version.";
+        };
+        readonly meta: {
+            readonly type: "object";
+            readonly required: readonly ["name"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly name: {
+                    readonly type: "string";
+                };
+                readonly family: {
+                    readonly type: "string";
+                    readonly description: "Architecture family, e.g. llama, qwen, gpt2.";
+                };
+                readonly notes: {
+                    readonly type: "string";
+                };
+                readonly published: {
+                    readonly type: "object";
+                    readonly description: "Reference numbers from the model card or paper, asserted by the regression suite.";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly params: {
+                            readonly type: "number";
+                        };
+                        readonly activeParams: {
+                            readonly type: "number";
+                        };
+                        readonly kvBytesPerToken: {
+                            readonly type: "number";
+                        };
+                        readonly source: {
+                            readonly type: "string";
+                        };
+                        readonly tolerance: {
+                            readonly type: "number";
+                            readonly description: "Allowed relative difference. Defaults to 0.5%.";
+                        };
+                    };
+                };
+            };
+        };
+        readonly symbols: {
+            readonly type: "object";
+            readonly description: string;
+            readonly additionalProperties: {
+                readonly anyOf: readonly [{
+                    readonly type: "number";
+                }, {
+                    readonly type: "string";
+                    readonly description: "Expression over earlier symbols, e.g. \"ceil_mult(1.3*8/3*D, 1024)\".";
+                }, {
+                    readonly type: "object";
+                    readonly required: readonly ["kind", "default"];
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly kind: {
+                            readonly const: "runtime";
+                        };
+                        readonly default: {
+                            readonly type: "number";
+                        };
+                        readonly doc: {
+                            readonly type: "string";
+                        };
+                    };
+                }, {
+                    readonly type: "object";
+                    readonly required: readonly ["kind", "value"];
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly kind: {
+                            readonly const: "design";
+                        };
+                        readonly value: {
+                            readonly anyOf: readonly [{
+                                readonly type: "number";
+                            }, {
+                                readonly type: "string";
+                            }];
+                        };
+                        readonly doc: {
+                            readonly type: "string";
+                        };
+                    };
+                }];
+            };
+        };
+        readonly graph: {
+            readonly $ref: "#/$defs/graph";
+        };
+        readonly ui: {
+            readonly type: "object";
+            readonly description: "Editor state. Ignored by analysis and codegen.";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly positions: {
+                    readonly type: "object";
+                    readonly additionalProperties: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "number";
+                        };
+                        readonly minItems: 2;
+                        readonly maxItems: 2;
+                    };
+                };
+                readonly collapsed: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+    };
+    readonly $defs: {
+        readonly graph: {
+            readonly type: "object";
+            readonly required: readonly ["nodes", "edges"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly nodes: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/node";
+                    };
+                };
+                readonly edges: {
+                    readonly type: "array";
+                    readonly description: "Each edge is [\"fromBlock:port\", \"toBlock:port\"], with ids local to this graph.";
+                    readonly items: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly minItems: 2;
+                        readonly maxItems: 2;
+                    };
+                };
+            };
+        };
+        readonly node: {
+            readonly type: "object";
+            readonly required: readonly ["id", "type"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly description: "Unique within its graph.";
+                };
+                readonly type: {
+                    readonly type: "string";
+                    readonly description: "A catalog block type; see tensorcad://catalog.";
+                };
+                readonly params: {
+                    readonly type: "object";
+                    readonly description: string;
+                    readonly additionalProperties: true;
+                };
+                readonly graph: {
+                    readonly $ref: "#/$defs/graph";
+                    readonly description: "Subgraph, for container blocks such as repeat.";
+                };
+                readonly variants: {
+                    readonly type: "object";
+                    readonly description: "Named subgraph variants, for hybrid repeat patterns.";
+                    readonly additionalProperties: {
+                        readonly $ref: "#/$defs/graph";
+                    };
+                };
+                readonly label: {
+                    readonly type: "string";
+                    readonly description: "Shown on the canvas instead of the id.";
+                };
+            };
+        };
+    };
+};

package/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The library: everything this package exposes to code that imports it.
+ *
+ * Starting a server is `stdio.ts`, and the split matters. This used to be both,
+ * with an `if (import.meta.main)` at the bottom — which works under Bun and
+ * does not survive a bundler, because `import.meta.main` compiles to a
+ * CommonJS check that is not defined in an ESM output. The desktop bundle
+ * crashed before its first line ran.
+ */
+export { serve } from "./serve.js";
+export { createServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
+export { FileStore } from "./store/file-store.js";
+export type { DocumentStore, DesignRecord, DesignSummary } from "./store/types.js";
+export { TOOL_NAMES } from "./tools.js";
+export { PROMPT_NAMES } from "./prompts.js";
+export { applyOps, type Op } from "./ops.js";