@tensor-cad/mcp 0.1.0

package/serve.js

@@ -0,0 +1,2867 @@
+// packages/mcp/src/serve.ts
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { loadEngine } from "@tensor-cad/engine/node";
+
+// packages/mcp/src/bridge/server.ts
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { WebSocketServer } from "ws";
+
+// packages/mcp/src/schemas.ts
+import * as z from "zod";
+var DESIGN_ID = z.string().describe('Handle returned by tensorcad_new_design or tensorcad_open_design, e.g. "dsn_1".');
+var Severity = z.enum(["error", "warning", "info"]);
+var Finding = z.object({
+  rule: z.string().describe('Stable rule id, e.g. "flash-head-dim".'),
+  severity: Severity,
+  path: z.string().optional().describe("Block path the finding is about."),
+  port: z.string().optional(),
+  message: z.string(),
+  hint: z.string().optional().describe("What to change to clear the finding.")
+});
+var Counts = z.object({
+  error: z.number().int(),
+  warning: z.number().int(),
+  info: z.number().int()
+});
+var ValidationSummary = z.object({
+  ok: z.boolean().describe("True when nothing blocks building this design."),
+  counts: Counts,
+  top_findings: z.array(Finding).describe("The worst few findings. Call tensorcad_validate for all of them.")
+});
+var DesignSummary = z.object({
+  design_id: z.string(),
+  name: z.string(),
+  revision: z.number().int(),
+  path: z.string().optional(),
+  source: z.enum(["preset", "file", "empty"]),
+  dirty: z.boolean(),
+  created_at: z.string(),
+  updated_at: z.string()
+});
+var OutlineSymbol = z.object({
+  name: z.string(),
+  kind: z.enum(["design", "runtime"]),
+  value: z.string().describe("Literal or expression as written in the document."),
+  resolved: z.number().optional(),
+  doc: z.string().optional()
+});
+var OutlineBlock = z.object({
+  path: z.string().describe('Slash-separated path, e.g. "layers/block".'),
+  type: z.string(),
+  kind: z.string().describe("primitive, composite, container or unknown."),
+  depth: z.number().int(),
+  label: z.string().optional(),
+  params: z.number().describe("Trainable parameters under this path, repeats included."),
+  repeat: z.number().optional().describe("Instance count, for repeat containers.")
+});
+var OutlineEdge = z.object({
+  graph: z.string().describe('Container path holding the edge; "" is the root graph.'),
+  from: z.string(),
+  to: z.string(),
+  shape: z.string().optional().describe('Inferred shape on the wire, e.g. "B T D".')
+});
+var Outline = z.object({
+  name: z.string(),
+  family: z.string().optional(),
+  notes: z.string().optional(),
+  symbols: z.array(OutlineSymbol),
+  blocks: z.array(OutlineBlock),
+  edges: z.array(OutlineEdge),
+  params_total: z.number(),
+  params_active: z.number(),
+  issues: z.number().int()
+});
+var BlockPort = z.object({
+  name: z.string(),
+  pattern: z.string().describe('Declared shape pattern, e.g. "B T D".'),
+  shape: z.string().optional().describe("Shape actually inferred for this port."),
+  dtype: z.string().optional().describe("What the tensor carries, when the port declares it rather than inheriting it."),
+  optional: z.boolean().optional().describe("True when this port may legitimately dangle."),
+  connected_to: z.array(z.string()).optional()
+});
+var analysisOptionsShape = {
+  T: z.number().int().positive().optional().describe("Sequence length. Defaults to the document's own T."),
+  B: z.number().int().positive().optional().describe("Micro-batch size."),
+  dtype: z.enum(["fp32", "bf16", "fp16", "fp8"]).optional().describe("Training dtype. Default bf16."),
+  hardware: z.string().optional().describe("Hardware id: h100-sxm, h200-sxm, b200, a100-80, rtx5080 or rtx4090. Default h100-sxm."),
+  gpus: z.number().int().positive().optional(),
+  tokens: z.number().positive().optional().describe("Training token budget. Defaults to Chinchilla-optimal."),
+  optimizer: z.enum(["adamw", "adamw8bit", "muon", "sgd_momentum", "sgd", "bf16_adam"]).optional(),
+  recompute: z.enum(["none", "selective", "full"]).optional(),
+  zero: z.number().int().min(0).max(3).optional().describe("ZeRO/FSDP sharding stage."),
+  tp: z.number().int().positive().optional().describe("Tensor parallel degree."),
+  dp: z.number().int().positive().optional().describe("Data parallel degree."),
+  pp: z.number().int().positive().optional().describe("Pipeline parallel degree."),
+  ep: z.number().int().positive().optional().describe("Expert parallel degree."),
+  concurrency: z.number().int().positive().optional().describe("Concurrent sequences when serving."),
+  mfu: z.number().positive().max(1).optional().describe("Model FLOPs utilization, 0..1.")
+};
+var ParamValue = z.any().describe("A number, an expression string over the design symbols, a boolean, null, or an object.");
+var Op = z.discriminatedUnion("op", [
+  z.object({
+    op: z.literal("add_node"),
+    parent: z.string().optional().describe("Container path to add into. Omit for the root graph."),
+    id: z.string().describe("New block id, unique within its graph."),
+    type: z.string().describe("Catalog block type; see tensorcad_search_catalog."),
+    params: z.record(z.string(), ParamValue).optional(),
+    label: z.string().optional()
+  }),
+  z.object({ op: z.literal("remove_node"), path: z.string().describe("Block path. Its edges go with it.") }),
+  z.object({
+    op: z.literal("set_param"),
+    path: z.string(),
+    key: z.string(),
+    value: ParamValue
+  }),
+  z.object({
+    op: z.literal("connect"),
+    graph: z.string().optional().describe("Container path holding the edge. Omit for the root graph."),
+    from: z.string().describe('Producer endpoint, "blockId:port", local to that graph.'),
+    to: z.string().describe('Consumer endpoint, "blockId:port", local to that graph.')
+  }),
+  z.object({
+    op: z.literal("disconnect"),
+    graph: z.string().optional(),
+    from: z.string(),
+    to: z.string()
+  }),
+  z.object({
+    op: z.literal("set_symbol"),
+    name: z.string(),
+    value: z.union([z.number(), z.string(), z.null()]).describe("Number, expression over earlier symbols, or null to delete the symbol."),
+    doc: z.string().optional(),
+    runtime: z.boolean().optional().describe("Keep the symbol indeterminate (B, T). Defaults to the current kind.")
+  }),
+  z.object({ op: z.literal("rename"), path: z.string(), id: z.string().describe("New id; edges are rewritten.") }),
+  z.object({
+    op: z.literal("set_label"),
+    path: z.string(),
+    label: z.string().nullable().optional().describe("Null or empty clears the label.")
+  })
+]);
+var num = () => z.number().nullable();
+var AnalysisOutput = z.object({
+  design_id: z.string(),
+  revision: z.number().int(),
+  name: z.string(),
+  options: z.object({
+    T: z.number(),
+    B: z.number(),
+    dtype: z.string(),
+    hardware: z.string(),
+    gpus: z.number(),
+    parallel: z.object({
+      dp: z.number(),
+      tp: z.number(),
+      pp: z.number(),
+      ep: z.number(),
+      zero: z.number(),
+      sequenceParallel: z.boolean()
+    }),
+    optimizer: z.string(),
+    recompute: z.string(),
+    tokens: z.number(),
+    tokens_were_defaulted: z.boolean(),
+    mfu: z.number(),
+    concurrency: z.number()
+  }),
+  params: z.object({
+    total: z.number(),
+    active: z.number(),
+    embedding: z.number(),
+    head: z.number(),
+    non_embedding: z.number(),
+    non_embedding_active: z.number(),
+    by_category: z.record(z.string(), z.number()),
+    by_type: z.record(z.string(), z.number())
+  }),
+  flops: z.object({
+    fwd_dense: num(),
+    fwd_attention: num(),
+    fwd_total: num(),
+    elementwise: num(),
+    train_per_token: num(),
+    attention_share: num()
+  }),
+  kv: z.object({
+    bytes_per_token: num(),
+    bytes_per_sequence: num(),
+    bytes_per_token_decompressed: num().describe("What an engine that does not absorb latent attention's up-projections caches instead; equal to bytes_per_token otherwise.")
+  }),
+  memory: z.object({
+    optimizer_label: z.string(),
+    train_weights: num(),
+    train_grads: num(),
+    train_optimizer: num(),
+    train_activations: num(),
+    train_per_gpu: num(),
+    train_total: num(),
+    infer_weights: num(),
+    infer_kv: num(),
+    infer_total: num(),
+    device_memory: num(),
+    notes: z.array(z.string())
+  }),
+  throughput: z.object({
+    decode_tokens_per_second: num(),
+    decode_weight_bytes: num().describe("What a step at this batch reads: for a mixture of experts, the union of what its tokens routed to."),
+    resident_weight_bytes: num().describe("Every weight the device holds, read or not."),
+    prefill_seconds: num(),
+    memory_bound: z.boolean(),
+    notes: z.array(z.string())
+  }),
+  cost: z.object({
+    total_flops: num(),
+    gpu_hours: num(),
+    wall_clock_hours: num(),
+    dollars: num(),
+    tokens: z.number()
+  }),
+  chinchilla: z.object({
+    optimal_tokens: num(),
+    tokens_per_param: num(),
+    over_training_ratio: num(),
+    verdict: z.string()
+  }),
+  errors: z.array(z.string())
+});
+
+// packages/mcp/src/store/types.ts
+class RevisionConflictError extends Error {
+  designId;
+  expected;
+  actual;
+  constructor(designId, expected, actual) {
+    super(`Design ${designId} is at revision ${actual}, not the expected ${expected}. ` + `Re-read it with tensorcad_get_design and rebuild the edit on the current document.`);
+    this.designId = designId;
+    this.expected = expected;
+    this.actual = actual;
+    this.name = "RevisionConflictError";
+  }
+}
+
+class UnknownDesignError extends Error {
+  constructor(id, known) {
+    super(`Unknown design_id "${id}". Open designs: ${known.length > 0 ? known.join(", ") : "(none)"}. ` + `Use tensorcad_new_design or tensorcad_open_design first.`);
+    this.name = "UnknownDesignError";
+  }
+}
+
+// packages/mcp/src/bridge/protocol.ts
+var BRIDGE_PROTOCOL = 1;
+
+// packages/mcp/src/bridge/session.ts
+import { rmSync } from "node:fs";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+var SESSION_VERSION = 1;
+function sessionPath() {
+  return process.env.TENSORCAD_SESSION_FILE ?? join(homedir(), ".tensorcad", "session.json");
+}
+async function writeSession(session, path = sessionPath()) {
+  const full = { version: SESSION_VERSION, protocol: BRIDGE_PROTOCOL, ...session };
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(full, null, 2)}
+`, "utf8");
+  try {
+    await chmod(path, 384);
+  } catch {}
+}
+async function clearSession(path = sessionPath()) {
+  await rm(path, { force: true });
+}
+function clearSessionSync(path = sessionPath()) {
+  try {
+    rmSync(path, { force: true });
+  } catch {}
+}
+
+// packages/mcp/src/bridge/server.ts
+var DEFAULT_BRIDGE_PORT = 7357;
+var PORT_ATTEMPTS = 4;
+
+class BridgeServer {
+  token;
+  http;
+  wss;
+  options;
+  log;
+  unsubscribe;
+  watchers = new Set;
+  port_ = 0;
+  acting;
+  constructor(options) {
+    this.options = options;
+    this.token = options.token ?? randomBytes(32).toString("hex");
+    this.log = options.log ?? ((line) => process.stderr.write(`${line}
+`));
+    this.http = createServer((req, res) => this.serveHttp(req, res));
+    this.wss = new WebSocketServer({ noServer: true });
+    this.http.on("upgrade", (req, socket, head) => {
+      const refusal = this.refuse(req, req.url ?? "/");
+      if (refusal) {
+        socket.end(`HTTP/1.1 ${refusal}\r
+Connection: close\r
+Content-Length: 0\r
+\r
+`);
+        setTimeout(() => socket.destroy(), 50).unref();
+        return;
+      }
+      this.wss.handleUpgrade(req, socket, head, (ws) => this.attach(ws));
+    });
+  }
+  get port() {
+    return this.port_;
+  }
+  get url() {
+    return `ws://127.0.0.1:${this.port_}/bridge?token=${this.token}`;
+  }
+  get connections() {
+    return this.wss.clients.size;
+  }
+  watch(watcher) {
+    this.watchers.add(watcher);
+    return () => this.watchers.delete(watcher);
+  }
+  async start() {
+    const first = this.options.port ?? DEFAULT_BRIDGE_PORT;
+    this.port_ = await listenSomewhere(this.http, first, PORT_ATTEMPTS);
+    this.unsubscribe = this.options.store.subscribe((change) => this.mirror(change));
+    await writeSession({
+      port: this.port_,
+      token: this.token,
+      pid: process.pid,
+      root: this.options.root,
+      started_at: new Date().toISOString()
+    }, this.options.sessionFile);
+    this.log(`tensorcad bridge on 127.0.0.1:${this.port_}`);
+  }
+  async stop() {
+    this.unsubscribe?.();
+    this.unsubscribe = undefined;
+    for (const client of this.wss.clients)
+      client.close(1001, "server stopping");
+    await new Promise((done) => this.wss.close(() => done()));
+    this.http.closeAllConnections();
+    await new Promise((done) => this.http.close(() => done()));
+    await clearSession(this.options.sessionFile);
+  }
+  serveHttp(req, res) {
+    const path = (req.url ?? "/").split("?")[0];
+    if (path !== "/session") {
+      res.writeHead(404, { "content-type": "text/plain" });
+      res.end(`tensorcad bridge
+`);
+      return;
+    }
+    const refusal = this.refuse(req, req.url ?? "/", { token: false });
+    if (refusal) {
+      res.writeHead(Number(refusal.split(" ")[0]), { "content-type": "text/plain" });
+      res.end(`${refusal}
+`);
+      return;
+    }
+    res.writeHead(200, {
+      "content-type": "application/json",
+      "access-control-allow-origin": req.headers.origin ?? "*"
+    });
+    res.end(JSON.stringify({ protocol: BRIDGE_PROTOCOL, port: this.port_, token: this.token }));
+  }
+  refuse(req, url, checks = { token: true }) {
+    const remote = req.socket.remoteAddress ?? "";
+    if (!isLoopback(remote))
+      return "403 Forbidden";
+    const origin = req.headers.origin;
+    if (origin !== undefined && !isLocalOrigin(origin))
+      return "403 Forbidden";
+    if (checks.token) {
+      const supplied = new URL(url, "http://127.0.0.1").searchParams.get("token");
+      if (supplied !== this.token)
+        return "401 Unauthorized";
+    }
+    return;
+  }
+  attach(ws) {
+    this.send(ws, {
+      type: "hello",
+      protocol: BRIDGE_PROTOCOL,
+      server: this.options.name,
+      version: this.options.version,
+      root: this.options.root,
+      designs: this.options.store.list()
+    });
+    ws.on("message", (raw) => {
+      let message;
+      try {
+        message = JSON.parse(String(raw));
+      } catch (e) {
+        this.send(ws, { type: "error", message: `not JSON: ${e.message}` });
+        return;
+      }
+      try {
+        this.handle(ws, message);
+      } catch (e) {
+        this.send(ws, { type: "error", message: e.message, about: message?.type });
+      }
+    });
+  }
+  handle(ws, message) {
+    switch (message?.type) {
+      case "publish": {
+        const doc = asDocument(message.doc);
+        const record = this.during(ws, () => this.options.store.adopt(doc));
+        this.send(ws, designMessage(record, "published"));
+        return;
+      }
+      case "attach": {
+        const record = this.options.store.get(message.design_id);
+        this.send(ws, designMessage(record, "requested"));
+        return;
+      }
+      case "ops":
+      case "replace": {
+        const write = message.type === "ops" ? () => this.options.store.apply(message.design_id, parseOps(message.ops), message.revision) : () => this.options.store.replace(message.design_id, asDocument(message.doc), message.revision);
+        try {
+          const { record } = this.during(ws, write);
+          this.send(ws, designMessage(record, message.type === "ops" ? "applied" : "replaced"));
+        } catch (e) {
+          if (e instanceof RevisionConflictError) {
+            this.send(ws, { type: "error", message: e.message, about: message.type });
+            this.send(ws, designMessage(this.options.store.get(message.design_id), "requested"));
+            return;
+          }
+          throw e;
+        }
+        return;
+      }
+      default:
+        this.send(ws, {
+          type: "error",
+          message: `unknown message type ${JSON.stringify(message?.type)}`
+        });
+    }
+  }
+  mirror(change) {
+    const from = this.acting ? "editor" : "agent";
+    const message = designMessage(change.record, change.kind, change.ops);
+    for (const client of this.wss.clients) {
+      if (client === this.acting)
+        continue;
+      this.send(client, message);
+    }
+    for (const watcher of this.watchers) {
+      try {
+        watcher(change, from);
+      } catch (e) {
+        this.log(`tensorcad bridge: watcher failed: ${e.message}`);
+      }
+    }
+  }
+  during(ws, work) {
+    this.acting = ws;
+    try {
+      return work();
+    } finally {
+      this.acting = undefined;
+    }
+  }
+  send(ws, message) {
+    if (ws.readyState !== ws.OPEN)
+      return;
+    ws.send(JSON.stringify(message));
+  }
+}
+function designMessage(record, reason, ops) {
+  const { doc, ...design } = record;
+  const message = { type: "design", reason, design, doc };
+  if (ops)
+    message.ops = ops;
+  return message;
+}
+async function listenSomewhere(server, first, attempts) {
+  let lastError;
+  for (let port = first;port < first + attempts; port++) {
+    try {
+      await new Promise((resolve, reject) => {
+        const onError = (e) => {
+          server.removeListener("listening", onListening);
+          reject(e);
+        };
+        const onListening = () => {
+          server.removeListener("error", onError);
+          resolve();
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(port, "127.0.0.1");
+      });
+      return port;
+    } catch (e) {
+      lastError = e;
+      if (e.code !== "EADDRINUSE")
+        break;
+    }
+  }
+  throw new Error(`tensorcad bridge could not listen on 127.0.0.1:${first}..${first + attempts - 1}: ${lastError?.message}`);
+}
+function isLoopback(address) {
+  const bare = address.startsWith("::ffff:") ? address.slice("::ffff:".length) : address;
+  return bare === "127.0.0.1" || bare === "::1" || bare.startsWith("127.");
+}
+function isLocalOrigin(origin) {
+  if (origin === "null" || origin === "file://")
+    return true;
+  let url;
+  try {
+    url = new URL(origin);
+  } catch {
+    return false;
+  }
+  if (url.protocol === "wails:" || url.protocol === "file:")
+    return true;
+  if (url.protocol !== "http:" && url.protocol !== "https:")
+    return false;
+  const host = url.hostname;
+  return host === "localhost" || host.endsWith(".localhost") || host === "127.0.0.1" || host === "[::1]" || host === "::1";
+}
+function asDocument(value) {
+  const doc = value;
+  if (!doc || typeof doc !== "object" || !doc.graph || !doc.meta) {
+    throw new Error(`published value is not a design document: it has no "meta" and "graph".`);
+  }
+  return doc;
+}
+function parseOps(value) {
+  if (!Array.isArray(value))
+    throw new Error("ops must be an array");
+  const parsed = Op.array().safeParse(value);
+  if (!parsed.success) {
+    throw new Error(`ops rejected: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`);
+  }
+  return parsed.data;
+}
+
+// packages/mcp/src/server.ts
+import { McpServer as McpServer2 } from "@modelcontextprotocol/server";
+// packages/mcp/package.json
+var package_default = {
+  name: "@tensor-cad/mcp",
+  version: "0.1.0",
+  description: "Model Context Protocol server for TensorCAD: design, validate, analyze and generate LLM architectures from an agent",
+  mcpName: "io.github.filip-pajalic/tensorcad",
+  type: "module",
+  bin: {
+    "tensorcad-mcp": "./src/stdio.ts"
+  },
+  main: "./src/index.ts",
+  exports: {
+    ".": "./src/index.ts",
+    "./server": "./src/server.ts"
+  },
+  files: [
+    "src",
+    "README.md",
+    "mcp.example.json"
+  ],
+  scripts: {
+    start: "bun run src/stdio.ts",
+    test: "bun test ../../packages/mcp/test",
+    typecheck: "tsc --noEmit"
+  },
+  dependencies: {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "@tensor-cad/engine": "workspace:*",
+    ws: "^8.21.3",
+    zod: "^4.2.0"
+  },
+  devDependencies: {
+    "@modelcontextprotocol/client": "^2.0.0",
+    "@types/ws": "^8.18.1"
+  },
+  license: "MIT"
+};
+
+// packages/mcp/src/store/file-store.ts
+import { readdir, readFile as readFile2, stat, writeFile as writeFile2, mkdir as mkdir2 } from "node:fs/promises";
+import { dirname as dirname2, extname, isAbsolute, join as join2, resolve } from "node:path";
+
+// packages/mcp/src/ops.ts
+import { joinPath, splitEndpoint } from "@tensor-cad/engine";
+import { getBlock } from "@tensor-cad/engine/node";
+
+class OpError extends Error {
+  index;
+  op;
+  constructor(index, op, message) {
+    super(`op ${index} (${op.op}): ${message}`);
+    this.index = index;
+    this.op = op;
+    this.name = "OpError";
+  }
+}
+function locate(doc, path) {
+  const segments = path.split("/").filter(Boolean);
+  if (segments.length === 0)
+    throw new Error(`"${path}" is not a node path`);
+  let graph = doc.graph;
+  for (let i = 0;i < segments.length - 1; i++) {
+    const id = segments[i];
+    const node = graph.nodes.find((n) => n.id === id);
+    if (!node)
+      throw new Error(`no block "${segments.slice(0, i + 1).join("/")}"`);
+    if (!node.graph)
+      throw new Error(`block "${segments.slice(0, i + 1).join("/")}" has no subgraph`);
+    graph = node.graph;
+  }
+  const id = segments[segments.length - 1];
+  const node = graph.nodes.find((n) => n.id === id);
+  if (!node)
+    throw new Error(`no block "${path}"`);
+  return { graph, node, parent: segments.slice(0, -1).join("/") };
+}
+function graphAt(doc, path) {
+  if (!path)
+    return doc.graph;
+  const { node } = locate(doc, path);
+  if (!node.graph)
+    throw new Error(`block "${path}" is not a container and has no subgraph`);
+  return node.graph;
+}
+var edgeEq = (a, from, to) => a[0] === from && a[1] === to;
+function applyOne(doc, op) {
+  switch (op.op) {
+    case "add_node": {
+      if (!op.id)
+        throw new Error("id is required");
+      const def = getBlock(op.type);
+      if (!def)
+        throw new Error(`unknown block type "${op.type}"`);
+      const graph = graphAt(doc, op.parent);
+      if (graph.nodes.some((n) => n.id === op.id)) {
+        throw new Error(`"${joinPath(op.parent ?? "", op.id)}" already exists`);
+      }
+      const node = { id: op.id, type: op.type };
+      if (op.params)
+        node.params = { ...op.params };
+      if (op.label)
+        node.label = op.label;
+      if (def.kind === "container")
+        node.graph = { nodes: [], edges: [] };
+      graph.nodes.push(node);
+      return `added ${joinPath(op.parent ?? "", op.id)} (${op.type})`;
+    }
+    case "remove_node": {
+      const { graph, node } = locate(doc, op.path);
+      const index = graph.nodes.indexOf(node);
+      graph.nodes.splice(index, 1);
+      const before = graph.edges.length;
+      graph.edges = graph.edges.filter(([from, to]) => splitEndpoint(from).node !== node.id && splitEndpoint(to).node !== node.id);
+      const dropped = before - graph.edges.length;
+      return `removed ${op.path}${dropped > 0 ? ` and ${dropped} edge${dropped === 1 ? "" : "s"}` : ""}`;
+    }
+    case "set_param": {
+      const { node } = locate(doc, op.path);
+      const def = getBlock(node.type);
+      if (def && !(op.key in (def.params ?? {}))) {
+        const known = Object.keys(def.params ?? {}).join(", ");
+        throw new Error(`"${node.type}" has no parameter "${op.key}". Known: ${known || "(none)"}`);
+      }
+      node.params ??= {};
+      const previous = node.params[op.key];
+      if (op.value === undefined)
+        delete node.params[op.key];
+      else
+        node.params[op.key] = op.value;
+      return `${op.path}.${op.key}: ${JSON.stringify(previous ?? null)} -> ${JSON.stringify(op.value ?? null)}`;
+    }
+    case "connect": {
+      const graph = graphAt(doc, op.graph);
+      assertEndpoint(graph, op.from, "from");
+      assertEndpoint(graph, op.to, "to");
+      if (graph.edges.some((e) => edgeEq(e, op.from, op.to))) {
+        throw new Error(`${op.from} -> ${op.to} already exists`);
+      }
+      const occupied = graph.edges.find((e) => e[1] === op.to);
+      if (occupied)
+        throw new Error(`${op.to} already receives ${occupied[0]}; disconnect it first`);
+      graph.edges.push([op.from, op.to]);
+      return `connected ${op.from} -> ${op.to}`;
+    }
+    case "disconnect": {
+      const graph = graphAt(doc, op.graph);
+      const index = graph.edges.findIndex((e) => edgeEq(e, op.from, op.to));
+      if (index < 0)
+        throw new Error(`no edge ${op.from} -> ${op.to}`);
+      graph.edges.splice(index, 1);
+      return `disconnected ${op.from} -> ${op.to}`;
+    }
+    case "set_symbol": {
+      if (!op.name)
+        throw new Error("name is required");
+      const existing = doc.symbols[op.name];
+      if (op.value === null) {
+        if (existing === undefined)
+          throw new Error(`no symbol "${op.name}"`);
+        delete doc.symbols[op.name];
+        return `removed symbol ${op.name}`;
+      }
+      const wasRuntime = op.runtime ?? (typeof existing === "object" && existing !== null && existing.kind === "runtime");
+      let next;
+      if (wasRuntime) {
+        if (typeof op.value !== "number")
+          throw new Error(`runtime symbol "${op.name}" needs a number default`);
+        next = { kind: "runtime", default: op.value };
+      } else {
+        next = { kind: "design", value: op.value };
+      }
+      const docString = op.doc ?? (typeof existing === "object" && existing !== null ? existing.doc : undefined);
+      if (docString)
+        next.doc = docString;
+      doc.symbols[op.name] = next;
+      return `${op.name}: ${describeSymbol(existing)} -> ${describeSymbol(next)}`;
+    }
+    case "rename": {
+      const { graph, node, parent } = locate(doc, op.path);
+      if (!op.id)
+        throw new Error("id is required");
+      if (op.id === node.id)
+        return `${op.path} unchanged`;
+      if (graph.nodes.some((n) => n.id === op.id)) {
+        throw new Error(`"${joinPath(parent, op.id)}" already exists`);
+      }
+      const old = node.id;
+      node.id = op.id;
+      graph.edges = graph.edges.map(([from, to]) => [rewrite(from, old, op.id), rewrite(to, old, op.id)]);
+      return `renamed ${op.path} -> ${joinPath(parent, op.id)}`;
+    }
+    case "set_label": {
+      const { node } = locate(doc, op.path);
+      if (op.label === null || op.label === undefined || op.label === "")
+        delete node.label;
+      else
+        node.label = op.label;
+      return `${op.path} label -> ${op.label ?? "(none)"}`;
+    }
+    default: {
+      const bad = op;
+      throw new Error(`unknown operation "${bad.op}"`);
+    }
+  }
+}
+function describeSymbol(s) {
+  if (s === undefined)
+    return "(unset)";
+  if (typeof s === "number" || typeof s === "string")
+    return String(s);
+  return s.kind === "runtime" ? `runtime(${s.default})` : String(s.value);
+}
+function rewrite(endpoint, from, to) {
+  const { node, port } = splitEndpoint(endpoint);
+  return node === from ? `${to}:${port}` : endpoint;
+}
+function assertEndpoint(graph, endpoint, which) {
+  let split;
+  try {
+    split = splitEndpoint(endpoint);
+  } catch {
+    throw new Error(`${which} endpoint "${endpoint}" is not "blockId:port"`);
+  }
+  if (!graph.nodes.some((n) => n.id === split.node)) {
+    const known = graph.nodes.map((n) => n.id).join(", ");
+    throw new Error(`${which} endpoint "${endpoint}" names no block in this graph. Blocks: ${known}`);
+  }
+}
+function applyOps(doc, ops) {
+  const next = structuredClone(doc);
+  const applied = [];
+  for (let i = 0;i < ops.length; i++) {
+    try {
+      applied.push(applyOne(next, ops[i]));
+    } catch (e) {
+      throw new OpError(i, ops[i], e.message);
+    }
+  }
+  return { doc: next, applied };
+}
+
+// packages/mcp/src/store/file-store.ts
+import { PRESET_NAMES, getPreset } from "@tensor-cad/engine/node";
+var EMPTY_DOC = (name) => ({
+  version: 1,
+  meta: { name },
+  symbols: {
+    B: { kind: "runtime", default: 1, doc: "Batch size" },
+    T: { kind: "runtime", default: 2048, doc: "Sequence length in tokens" }
+  },
+  graph: { nodes: [], edges: [] }
+});
+
+class FileStore {
+  entries = new Map;
+  listeners = new Set;
+  nextDesign = 1;
+  nextCheckpoint = 1;
+  root;
+  depth;
+  constructor(options = {}) {
+    this.root = resolve(options.root ?? process.cwd());
+    this.depth = options.depth ?? 3;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  emit(change) {
+    for (const listener of this.listeners) {
+      try {
+        listener(change);
+      } catch (e) {
+        process.stderr.write(`tensorcad: store listener failed: ${e.message}
+`);
+      }
+    }
+  }
+  list() {
+    return [...this.entries.values()].map((e) => summaryOf(e.record)).sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+  }
+  async listFiles() {
+    const out = [];
+    const skip = new Set(["node_modules", ".git", "dist", "build", ".venv", "__pycache__"]);
+    const walk = async (dir, left) => {
+      let items;
+      try {
+        items = await readdir(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const item of items) {
+        const full = join2(dir, item.name);
+        if (item.isDirectory()) {
+          if (left > 0 && !skip.has(item.name) && !item.name.startsWith("."))
+            await walk(full, left - 1);
+        } else if (item.name.endsWith(".tensorcad.json")) {
+          out.push(full);
+        }
+      }
+    };
+    await walk(this.root, this.depth);
+    return out.sort();
+  }
+  get(id) {
+    const entry = this.entries.get(id);
+    if (!entry)
+      throw new UnknownDesignError(id, [...this.entries.keys()]);
+    return entry.record;
+  }
+  create(options) {
+    let doc;
+    let source;
+    if (options.preset) {
+      if (!PRESET_NAMES.includes(options.preset)) {
+        throw new Error(`Unknown preset "${options.preset}". Available: ${PRESET_NAMES.join(", ")}`);
+      }
+      doc = getPreset(options.preset);
+      source = "preset";
+    } else {
+      doc = EMPTY_DOC(options.name ?? "untitled");
+      source = "empty";
+    }
+    if (options.name)
+      doc.meta.name = options.name;
+    return this.register(doc, source, undefined, true);
+  }
+  adopt(doc) {
+    return this.register(doc, "derived", undefined, true);
+  }
+  async open(path) {
+    const full = this.resolvePath(path);
+    for (const entry of this.entries.values()) {
+      if (entry.record.path === full)
+        return entry.record;
+    }
+    const text = await readFile2(full, "utf8");
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch (e) {
+      throw new Error(`${full} is not valid JSON: ${e.message}`);
+    }
+    const doc = parsed;
+    if (!doc || typeof doc !== "object" || !doc.graph || !doc.meta) {
+      throw new Error(`${full} does not look like a design document: it has no "meta" and "graph".`);
+    }
+    doc.symbols ??= {};
+    return this.register(doc, "file", full, false);
+  }
+  register(doc, source, path, dirty) {
+    const now = new Date().toISOString();
+    const id = `dsn_${this.nextDesign++}`;
+    const record = {
+      design_id: id,
+      name: doc.meta.name,
+      revision: 1,
+      source,
+      dirty,
+      created_at: now,
+      updated_at: now,
+      doc
+    };
+    if (path)
+      record.path = path;
+    this.entries.set(id, { record, log: [], checkpoints: new Map });
+    this.emit({ kind: "registered", record });
+    return record;
+  }
+  apply(id, ops, expectedRevision) {
+    const entry = this.entry(id);
+    const { record } = entry;
+    if (expectedRevision !== undefined && expectedRevision !== record.revision) {
+      throw new RevisionConflictError(id, expectedRevision, record.revision);
+    }
+    const before = structuredClone(record.doc);
+    const { doc, applied } = applyOps(record.doc, ops);
+    const previousRevision = record.revision;
+    entry.log.push({ revision: previousRevision, at: new Date().toISOString(), ops, before });
+    record.doc = doc;
+    record.name = doc.meta.name;
+    record.revision = previousRevision + 1;
+    record.dirty = true;
+    record.updated_at = new Date().toISOString();
+    this.emit({ kind: "applied", record, ops });
+    return { record, applied, previousRevision };
+  }
+  replace(id, doc, expectedRevision) {
+    const entry = this.entry(id);
+    const { record } = entry;
+    if (expectedRevision !== undefined && expectedRevision !== record.revision) {
+      throw new RevisionConflictError(id, expectedRevision, record.revision);
+    }
+    const previousRevision = record.revision;
+    entry.log.push({ revision: previousRevision, at: new Date().toISOString(), ops: [], before: record.doc });
+    record.doc = doc;
+    record.name = doc.meta.name;
+    record.revision = previousRevision + 1;
+    record.dirty = true;
+    record.updated_at = new Date().toISOString();
+    this.emit({ kind: "replaced", record });
+    return { record, applied: ["replaced the document"], previousRevision };
+  }
+  async save(id, path) {
+    const record = this.get(id);
+    const target = path ? this.resolvePath(path) : record.path ?? join2(this.root, `${slug(record.name)}.tensorcad.json`);
+    const text = `${JSON.stringify(record.doc, null, 2)}
+`;
+    await mkdir2(dirname2(target), { recursive: true });
+    await writeFile2(target, text, "utf8");
+    record.path = target;
+    record.dirty = false;
+    record.updated_at = new Date().toISOString();
+    this.emit({ kind: "saved", record });
+    return { record, path: target, bytes: Buffer.byteLength(text, "utf8") };
+  }
+  checkpoint(id, label) {
+    const entry = this.entry(id);
+    const info = {
+      checkpoint_id: `ckpt_${this.nextCheckpoint++}`,
+      label: label ?? `revision ${entry.record.revision}`,
+      revision: entry.record.revision,
+      created_at: new Date().toISOString()
+    };
+    entry.checkpoints.set(info.checkpoint_id, { ...info, doc: structuredClone(entry.record.doc) });
+    return info;
+  }
+  checkpoints(id) {
+    const entry = this.entry(id);
+    return [...entry.checkpoints.values()].map(({ doc: _doc, ...info }) => info);
+  }
+  restore(id, checkpointId) {
+    const entry = this.entry(id);
+    const { record } = entry;
+    let doc;
+    let restoredFrom;
+    if (checkpointId) {
+      const saved = entry.checkpoints.get(checkpointId);
+      if (!saved) {
+        const known = [...entry.checkpoints.keys()];
+        throw new Error(`Unknown checkpoint "${checkpointId}" for ${id}. ` + `Checkpoints: ${known.length > 0 ? known.join(", ") : "(none)"}.`);
+      }
+      doc = structuredClone(saved.doc);
+      restoredFrom = `checkpoint ${checkpointId} (${saved.label})`;
+    } else {
+      const last = entry.log.pop();
+      if (!last)
+        throw new Error(`Design ${id} has no edits to undo and no checkpoint was named.`);
+      doc = last.before;
+      restoredFrom = `undo of ${last.ops.length} op${last.ops.length === 1 ? "" : "s"} at revision ${last.revision}`;
+    }
+    record.doc = doc;
+    record.name = doc.meta.name;
+    record.revision += 1;
+    record.dirty = true;
+    record.updated_at = new Date().toISOString();
+    this.emit({ kind: "restored", record });
+    return { record, restoredFrom };
+  }
+  entry(id) {
+    const entry = this.entries.get(id);
+    if (!entry)
+      throw new UnknownDesignError(id, [...this.entries.keys()]);
+    return entry;
+  }
+  resolvePath(path) {
+    const full = isAbsolute(path) ? path : resolve(this.root, path);
+    if (extname(full) === "")
+      return `${full}.tensorcad.json`;
+    return full;
+  }
+  static async exists(path) {
+    try {
+      await stat(path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+function summaryOf(record) {
+  const { doc: _doc, ...summary } = record;
+  return summary;
+}
+function slug(name) {
+  return name.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "design";
+}
+
+// packages/mcp/src/prompts.ts
+import * as z2 from "zod";
+import { HARDWARE, PRESET_NAMES as PRESET_NAMES2 } from "@tensor-cad/engine/node";
+var user = (text) => ({
+  messages: [{ role: "user", content: { type: "text", text } }]
+});
+var HARDWARE_IDS = HARDWARE.map((h) => h.id).join(", ");
+function registerPrompts(server) {
+  server.registerPrompt("design_model", {
+    title: "Design a model",
+    description: "Design a decoder-only LLM to a parameter budget and context length, then check and cost it.",
+    argsSchema: z2.object({
+      target_params: z2.string().describe('Parameter budget, e.g. "3B", "8B", "70B".'),
+      context_len: z2.string().optional().describe('Context length in tokens, e.g. "8192".'),
+      family: z2.string().optional().describe(`Architecture to start from: ${PRESET_NAMES2.join(", ")}, or "empty".`)
+    })
+  }, ({ target_params, context_len, family }) => user([
+    `Design a decoder-only language model of about ${target_params} parameters` + `${context_len ? ` with a ${context_len}-token context` : ""}` + `${family ? `, starting from the ${family} architecture` : ""}.`,
+    "",
+    "Work like this:",
+    `1. ${family && family !== "empty" ? `tensorcad_new_design with preset "${family}"` : "tensorcad_new_design, choosing the closest preset with tensorcad_list_designs first"}.`,
+    "2. tensorcad_get_design (outline) to see what you have.",
+    "3. tensorcad_apply_ops with set_symbol operations to move L, D, H, Hkv, dh, F and V toward the budget.",
+    "   Keep D divisible by H, keep the head dimension in {64, 96, 128, 160, 192, 256} so fused attention",
+    "   kernels apply, keep D and F multiples of 128, and keep H divisible by Hkv.",
+    "4. tensorcad_validate and fix every error and any warning you can.",
+    `5. tensorcad_analyze${context_len ? ` with T=${context_len}` : ""} and report parameters, KV cache per token,`,
+    "   training memory per GPU and the Chinchilla-optimal token budget.",
+    "",
+    "Report the final symbol table, the parameter count against the target, and anything you traded off."
+  ].join(`
+`)));
+  server.registerPrompt("review_design", {
+    title: "Review a design",
+    description: "Read a design, run the rules, and report what is wrong and what to do about it.",
+    argsSchema: z2.object({
+      design_id: z2.string().describe("Design handle. Use tensorcad_list_designs if you do not have one."),
+      hardware: z2.string().optional().describe(`Device to judge memory against: ${HARDWARE_IDS}.`)
+    })
+  }, ({ design_id, hardware }) => user([
+    `Review design ${design_id}.`,
+    "",
+    `1. tensorcad_get_design with format "outline".`,
+    `2. tensorcad_validate${hardware ? ` with hardware "${hardware}"` : ""}.`,
+    "3. tensorcad_get_block on anything a finding points at, to see the shapes and parameters for yourself.",
+    "4. tensorcad_analyze for the numbers behind the memory and cost findings.",
+    "",
+    "Report: every error with the exact edit that fixes it, then warnings by how much they cost,",
+    "then anything the rules do not catch (unusual width ratios, a vocabulary that dominates the",
+    "parameter count, attention that dominates FLOPs at this context length).",
+    "Do not change the design unless I ask."
+  ].join(`
+`)));
+  server.registerPrompt("scale_design", {
+    title: "Scale a design",
+    description: "Scale a design up or down by a factor while keeping its proportions sane.",
+    argsSchema: z2.object({
+      design_id: z2.string().describe("Design handle."),
+      factor: z2.string().describe('Parameter multiplier, e.g. "2", "0.5", or a target such as "70B".')
+    })
+  }, ({ design_id, factor }) => user([
+    `Scale design ${design_id} by ${factor}.`,
+    "",
+    "1. tensorcad_checkpoint first, labelled with what you are about to try, so tensorcad_restore can undo it.",
+    "2. tensorcad_analyze to record the starting numbers.",
+    "3. Decide how to spend the factor. Parameters go roughly as L x D^2, so depth is linear and width is",
+    "   quadratic; published families widen and deepen together rather than stretching one axis.",
+    "4. tensorcad_apply_ops with set_symbol operations. Keep D divisible by H, keep the head dimension in",
+    "   {64, 96, 128, 160, 192, 256}, keep D and F multiples of 128, and keep H divisible by Hkv.",
+    "5. tensorcad_validate, then tensorcad_analyze again.",
+    "",
+    "Report the before and after symbol tables, the parameter count against the target, and how KV cache,",
+    "training memory and training cost moved. If you cannot hit the target without breaking a constraint,",
+    "say which constraint and what the nearest good design is."
+  ].join(`
+`)));
+  server.registerPrompt("explain_costs", {
+    title: "Explain the costs",
+    description: "Explain what a design costs to train and to serve, and where the money goes.",
+    argsSchema: z2.object({
+      design_id: z2.string().describe("Design handle."),
+      batch: z2.string().optional().describe("Micro-batch size for training, and concurrency for serving."),
+      seq: z2.string().optional().describe("Sequence length in tokens."),
+      hardware: z2.string().optional().describe(`Device: ${HARDWARE_IDS}.`)
+    })
+  }, ({ design_id, batch, seq, hardware }) => user([
+    `Explain what design ${design_id} costs.`,
+    "",
+    `1. tensorcad_analyze with${seq ? ` T=${seq}` : " the document's own T"}${batch ? `, B=${batch} and concurrency=${batch}` : ""}` + `${hardware ? `, hardware "${hardware}"` : ""}.`,
+    "2. Run it again with a different GPU count or ZeRO stage if training does not fit the device.",
+    "",
+    "Cover, in plain language:",
+    "- training memory: weights, gradients, optimizer state and activations, which one dominates, and what",
+    "  ZeRO stage or tensor parallelism would make it fit.",
+    "- training compute: FLOPs per token, the Chinchilla-optimal token budget, GPU-hours and dollars, and",
+    "  what the MFU assumption is doing to that number.",
+    "- serving: weights plus KV cache per concurrent sequence, how many sequences fit in device memory,",
+    "  decode tokens per second, and whether decode is memory-bound or compute-bound.",
+    "- the one change that would most reduce each of those."
+  ].join(`
+`)));
+}
+var PROMPT_NAMES = ["design_model", "review_design", "scale_design", "explain_costs"];
+
+// packages/mcp/src/resources.ts
+import { ResourceTemplate } from "@modelcontextprotocol/server";
+
+// packages/mcp/src/design-schema.ts
+var DESIGN_JSON_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "tensorcad://schema/design",
+  title: "TensorCAD design document",
+  description: "The `.tensorcad.json` format. The graph is the source of truth; the editor's node positions are a view of it.",
+  type: "object",
+  required: ["version", "meta", "symbols", "graph"],
+  additionalProperties: false,
+  properties: {
+    version: { const: 1, description: "Document format version." },
+    meta: {
+      type: "object",
+      required: ["name"],
+      additionalProperties: false,
+      properties: {
+        name: { type: "string" },
+        family: { type: "string", description: "Architecture family, e.g. llama, qwen, gpt2." },
+        notes: { type: "string" },
+        published: {
+          type: "object",
+          description: "Reference numbers from the model card or paper, asserted by the regression suite.",
+          additionalProperties: false,
+          properties: {
+            params: { type: "number" },
+            activeParams: { type: "number" },
+            kvBytesPerToken: { type: "number" },
+            source: { type: "string" },
+            tolerance: { type: "number", description: "Allowed relative difference. Defaults to 0.5%." }
+          }
+        }
+      }
+    },
+    symbols: {
+      type: "object",
+      description: "The design's named dimensions. A symbol is a number, an expression over earlier symbols, or a runtime " + "dimension (B, T) that stays indeterminate through analysis.",
+      additionalProperties: {
+        anyOf: [
+          { type: "number" },
+          { type: "string", description: 'Expression over earlier symbols, e.g. "ceil_mult(1.3*8/3*D, 1024)".' },
+          {
+            type: "object",
+            required: ["kind", "default"],
+            additionalProperties: false,
+            properties: {
+              kind: { const: "runtime" },
+              default: { type: "number" },
+              doc: { type: "string" }
+            }
+          },
+          {
+            type: "object",
+            required: ["kind", "value"],
+            additionalProperties: false,
+            properties: {
+              kind: { const: "design" },
+              value: { anyOf: [{ type: "number" }, { type: "string" }] },
+              doc: { type: "string" }
+            }
+          }
+        ]
+      }
+    },
+    graph: { $ref: "#/$defs/graph" },
+    ui: {
+      type: "object",
+      description: "Editor state. Ignored by analysis and codegen.",
+      additionalProperties: false,
+      properties: {
+        positions: {
+          type: "object",
+          additionalProperties: { type: "array", items: { type: "number" }, minItems: 2, maxItems: 2 }
+        },
+        collapsed: { type: "array", items: { type: "string" } }
+      }
+    }
+  },
+  $defs: {
+    graph: {
+      type: "object",
+      required: ["nodes", "edges"],
+      additionalProperties: false,
+      properties: {
+        nodes: { type: "array", items: { $ref: "#/$defs/node" } },
+        edges: {
+          type: "array",
+          description: 'Each edge is ["fromBlock:port", "toBlock:port"], with ids local to this graph.',
+          items: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 2,
+            maxItems: 2
+          }
+        }
+      }
+    },
+    node: {
+      type: "object",
+      required: ["id", "type"],
+      additionalProperties: false,
+      properties: {
+        id: { type: "string", description: "Unique within its graph." },
+        type: { type: "string", description: "A catalog block type; see tensorcad://catalog." },
+        params: {
+          type: "object",
+          description: "Block parameters. Numeric parameters accept an expression string over the design symbols. " + "The per-type schema is in tensorcad://catalog/{type}.",
+          additionalProperties: true
+        },
+        graph: { $ref: "#/$defs/graph", description: "Subgraph, for container blocks such as repeat." },
+        variants: {
+          type: "object",
+          description: "Named subgraph variants, for hybrid repeat patterns.",
+          additionalProperties: { $ref: "#/$defs/graph" }
+        },
+        label: { type: "string", description: "Shown on the canvas instead of the id." }
+      }
+    }
+  }
+};
+
+// packages/mcp/src/summarize.ts
+import { formatBytes, formatCount, formatFlops, isComposite, isContainer, isPrimitive, joinPath as joinPath2, splitEndpoint as splitEndpoint2 } from "@tensor-cad/engine";
+import { catalogByCategory, countParams, getBlock as getBlock2, inferShapes, resolveSymbols } from "@tensor-cad/engine/node";
+function outlineOf(doc) {
+  const symbols = resolveSymbols(doc);
+  const infer = inferShapes(doc);
+  const params = countParams(doc);
+  const paramsAt = (path) => {
+    let sum = 0;
+    for (const [p, v] of Object.entries(params.byPath)) {
+      if (p === path || p.startsWith(`${path}/`))
+        sum += v;
+    }
+    return sum;
+  };
+  const blocks = [];
+  const edges = [];
+  const walk = (graph, prefix, depth) => {
+    for (const [from, to] of graph.edges) {
+      const edge = { graph: prefix, from, to };
+      const source = splitEndpoint2(from);
+      const shape = infer.outputs[`${joinPath2(prefix, source.node)}:${source.port}`];
+      if (shape)
+        edge.shape = shape.symbolic;
+      edges.push(edge);
+    }
+    for (const node of graph.nodes) {
+      const path = joinPath2(prefix, node.id);
+      const def = getBlock2(node.type);
+      const block = {
+        path,
+        type: node.type,
+        kind: def?.kind ?? "unknown",
+        depth,
+        params: paramsAt(path)
+      };
+      if (node.label)
+        block.label = node.label;
+      if (node.graph) {
+        const count = infer.resolved[path]?.p?.count;
+        if (typeof count === "number")
+          block.repeat = count;
+      }
+      blocks.push(block);
+      if (node.graph)
+        walk(node.graph, path, depth + 1);
+    }
+  };
+  walk(doc.graph, "", 0);
+  const out = {
+    name: doc.meta.name,
+    symbols: outlineSymbols(doc, symbols),
+    blocks,
+    edges,
+    params_total: params.total,
+    params_active: params.active,
+    issues: infer.issues.length
+  };
+  if (doc.meta.family)
+    out.family = doc.meta.family;
+  if (doc.meta.notes)
+    out.notes = doc.meta.notes;
+  return out;
+}
+function outlineSymbols(doc, symbols) {
+  return Object.entries(doc.symbols ?? {}).map(([name, def]) => {
+    const runtime = typeof def === "object" && def !== null && def.kind === "runtime";
+    const raw = typeof def === "object" && def !== null ? runtime ? String(def.default) : String(def.value) : String(def);
+    const s = { name, kind: runtime ? "runtime" : "design", value: raw };
+    const resolved = symbols.values[name];
+    if (typeof resolved === "number")
+      s.resolved = resolved;
+    const docString = typeof def === "object" && def !== null ? def.doc : undefined;
+    if (docString)
+      s.doc = docString;
+    return s;
+  });
+}
+function outlineText(o) {
+  const lines = [
+    `${o.name}${o.family ? ` (${o.family})` : ""}  ${formatCount(o.params_total)} parameters` + (o.params_active !== o.params_total ? `, ${formatCount(o.params_active)} active` : "")
+  ];
+  if (o.notes)
+    lines.push(o.notes);
+  lines.push("", "symbols");
+  for (const s of o.symbols) {
+    lines.push(`  ${s.name} = ${s.value}${s.kind === "runtime" ? " (runtime)" : ""}${s.doc ? `  ${s.doc}` : ""}`);
+  }
+  lines.push("", "blocks");
+  for (const b of o.blocks) {
+    const indent = "  ".repeat(b.depth + 1);
+    const repeat = b.repeat !== undefined ? ` x${b.repeat}` : "";
+    const size = b.params > 0 ? `  ${formatCount(b.params)}` : "";
+    lines.push(`${indent}${b.path.split("/").pop()}  ${b.type}${repeat}${size}`);
+  }
+  lines.push("", "edges");
+  for (const e of o.edges) {
+    const where = e.graph ? `${e.graph}/` : "";
+    lines.push(`  ${where}${e.from} -> ${where}${e.to}${e.shape ? `   ${e.shape}` : ""}`);
+  }
+  if (o.issues > 0)
+    lines.push("", `${o.issues} shape issue(s); run tensorcad_validate`);
+  return lines.join(`
+`);
+}
+function blockDetail(doc, path) {
+  const infer = inferShapes(doc);
+  const params = countParams(doc);
+  const segments = path.split("/").filter(Boolean);
+  if (segments.length === 0)
+    throw new Error(`"${path}" is not a block path.`);
+  let graph = doc.graph;
+  let node = undefined;
+  for (let i = 0;i < segments.length; i++) {
+    node = findNode(graph, segments[i]);
+    if (!node) {
+      const known = graph.nodes.map((n) => n.id).join(", ");
+      throw new Error(`No block "${segments.slice(0, i + 1).join("/")}". Blocks here: ${known || "(none)"}.`);
+    }
+    if (i < segments.length - 1) {
+      if (!node.graph)
+        throw new Error(`Block "${segments.slice(0, i + 1).join("/")}" has no subgraph.`);
+      graph = node.graph;
+    }
+  }
+  if (!node)
+    throw new Error(`No block "${path}".`);
+  const def = getBlock2(node.type);
+  const ports = infer.ports[path] ?? { in: {}, out: {} };
+  const consumers = new Map;
+  for (const [consumer, producer] of Object.entries(infer.producerOf)) {
+    const list = consumers.get(producer);
+    if (list)
+      list.push(consumer);
+    else
+      consumers.set(producer, [consumer]);
+  }
+  const inputs = Object.entries(ports.in).map(([name, spec]) => {
+    const port = { name, pattern: spec.shape };
+    if (spec.dtype !== "inherit")
+      port.dtype = spec.dtype;
+    if (spec.optional)
+      port.optional = true;
+    const shape = infer.inputs[`${path}:${name}`];
+    if (shape)
+      port.shape = shape.symbolic;
+    const producer = infer.producerOf[`${path}:${name}`];
+    if (producer)
+      port.connected_to = [producer];
+    return port;
+  });
+  const outputs = Object.entries(ports.out).map(([name, spec]) => {
+    const port = { name, pattern: spec.shape };
+    if (spec.dtype !== "inherit")
+      port.dtype = spec.dtype;
+    const shape = infer.outputs[`${path}:${name}`];
+    if (shape)
+      port.shape = shape.symbolic;
+    const to = consumers.get(`${path}:${name}`);
+    if (to)
+      port.connected_to = to;
+    return port;
+  });
+  let paramsCount = 0;
+  for (const [p, v] of Object.entries(params.byPath)) {
+    if (p === path || p.startsWith(`${path}/`))
+      paramsCount += v;
+  }
+  const resolved = infer.resolved[path];
+  const detail = {
+    path,
+    id: node.id,
+    type: node.type,
+    kind: def?.kind ?? "unknown",
+    category: def?.category ?? "unknown",
+    summary: def?.docs.summary ?? "Unknown block type.",
+    params: { ...node.params ?? {} },
+    resolved_params: resolved ? { ...resolved.p } : {},
+    param_errors: resolved ? [] : [`Unknown block type "${node.type}"`],
+    inputs,
+    outputs,
+    params_count: paramsCount,
+    instances: instancesOf(infer, segments),
+    children: (node.graph?.nodes ?? []).map((n) => joinPath2(path, n.id))
+  };
+  if (node.label)
+    detail.label = node.label;
+  if (def?.docs.formula)
+    detail.formula = def.docs.formula;
+  return detail;
+}
+function findNode(graph, id) {
+  return graph.nodes.find((n) => n.id === id);
+}
+function instancesOf(infer, segments) {
+  let multiplier = 1;
+  for (let i = 0;i < segments.length - 1; i++) {
+    const prefix = segments.slice(0, i + 1).join("/");
+    const count = infer.resolved[prefix]?.p?.count;
+    if (typeof count === "number")
+      multiplier *= count;
+  }
+  return multiplier;
+}
+function blockText(b) {
+  const lines = [
+    `${b.path}  ${b.type} (${b.kind}/${b.category})${b.instances > 1 ? ` x${b.instances}` : ""}`,
+    b.summary
+  ];
+  if (b.formula)
+    lines.push(`formula: ${b.formula}`);
+  lines.push(`parameters: ${formatCount(b.params_count)}`);
+  if (Object.keys(b.params).length > 0) {
+    lines.push("", "params");
+    for (const [k, v] of Object.entries(b.params))
+      lines.push(`  ${k} = ${JSON.stringify(v)}`);
+  }
+  if (b.inputs.length > 0) {
+    lines.push("", "in");
+    for (const p of b.inputs) {
+      lines.push(`  ${p.name}: ${p.shape ?? p.pattern}${p.connected_to ? `  <- ${p.connected_to.join(", ")}` : ""}`);
+    }
+  }
+  if (b.outputs.length > 0) {
+    lines.push("", "out");
+    for (const p of b.outputs) {
+      lines.push(`  ${p.name}: ${p.shape ?? p.pattern}${p.connected_to ? `  -> ${p.connected_to.join(", ")}` : ""}`);
+    }
+  }
+  if (b.param_errors.length > 0)
+    lines.push("", ...b.param_errors.map((e) => `! ${e}`));
+  return lines.join(`
+`);
+}
+function catalogEntry(def) {
+  const entry = {
+    type: def.type,
+    kind: def.kind,
+    category: def.category,
+    summary: def.docs.summary ?? "",
+    refs: def.docs.refs ?? [],
+    params: def.paramOrder.map((name) => catalogParam(name, def.params[name])),
+    inputs: [],
+    outputs: [],
+    dynamic_ports: false
+  };
+  if (def.docs.formula)
+    entry.formula = def.docs.formula;
+  if (isPrimitive(def) || isComposite(def)) {
+    const declared = Object.keys(def.ports.in).length + Object.keys(def.ports.out).length;
+    entry.dynamic_ports = declared === 0;
+    entry.inputs = Object.entries(def.ports.in).map(([n, shape]) => `${n}: ${shape}`);
+    entry.outputs = Object.entries(def.ports.out).map(([n, shape]) => `${n}: ${shape}`);
+  } else if (isContainer(def)) {
+    entry.inputs = ["(from the container's boundary_in block)"];
+    entry.outputs = ["(from the container's boundary_out block)"];
+    entry.dynamic_ports = true;
+  }
+  return entry;
+}
+function catalogParam(name, spec) {
+  const p = { name, type: spec.type };
+  const dflt = spec.default;
+  if (dflt !== undefined)
+    p.default = JSON.stringify(dflt);
+  if (spec.doc)
+    p.doc = spec.doc;
+  if (spec.type === "enum" && spec.values)
+    p.values = [...spec.values];
+  return p;
+}
+function allCatalogEntries() {
+  const byCategory = catalogByCategory();
+  return Object.keys(byCategory).sort().flatMap((category) => byCategory[category].map(catalogEntry));
+}
+function catalogText(entries) {
+  return entries.map((e) => {
+    const lines = [`${e.type}  (${e.kind}/${e.category})`, `  ${e.summary}`];
+    if (e.formula)
+      lines.push(`  formula: ${e.formula}`);
+    if (e.params.length > 0) {
+      lines.push(`  params: ${e.params.map((p) => `${p.name}:${p.type}${p.default !== undefined ? `=${p.default}` : ""}`).join(", ")}`);
+    }
+    if (e.inputs.length > 0)
+      lines.push(`  in: ${e.inputs.join(", ")}`);
+    if (e.outputs.length > 0)
+      lines.push(`  out: ${e.outputs.join(", ")}`);
+    return lines.join(`
+`);
+  }).join(`
+
+`);
+}
+function findingsJson(report) {
+  return report.findings.map((f) => {
+    const out = { rule: f.rule, severity: f.severity, message: f.message };
+    if (f.path)
+      out.path = f.path;
+    if (f.port)
+      out.port = f.port;
+    if (f.hint)
+      out.hint = f.hint;
+    return out;
+  });
+}
+function validationSummary(report, limit = 5) {
+  return {
+    ok: report.ok,
+    counts: report.counts,
+    top_findings: findingsJson(report).slice(0, limit)
+  };
+}
+function findingsText(findings) {
+  if (findings.length === 0)
+    return "No findings.";
+  return findings.map((f) => {
+    const where = f.path ? ` [${f.path}${f.port ? `:${f.port}` : ""}]` : "";
+    return `${f.severity}: ${f.message}${where}${f.hint ? `
+  fix: ${f.hint}` : ""}  (${f.rule})`;
+  }).join(`
+`);
+}
+function n(v) {
+  return Number.isFinite(v) ? v : null;
+}
+function analysisJson(a) {
+  const o = a.options;
+  return {
+    name: a.name,
+    options: {
+      T: o.T,
+      B: o.B,
+      dtype: o.dtype,
+      hardware: o.hardware.id,
+      gpus: o.gpus,
+      parallel: { ...o.parallel },
+      optimizer: o.optimizer,
+      recompute: o.recompute,
+      tokens: o.tokens,
+      tokens_were_defaulted: o.tokensWereDefaulted,
+      mfu: o.mfu,
+      concurrency: o.concurrency
+    },
+    params: {
+      total: a.params.total,
+      active: a.params.active,
+      embedding: a.params.embedding,
+      head: a.params.head,
+      non_embedding: a.params.nonEmbedding,
+      non_embedding_active: a.params.nonEmbeddingActive,
+      by_category: a.params.byCategory,
+      by_type: a.params.byType
+    },
+    flops: {
+      fwd_dense: n(a.flops.fwdDense),
+      fwd_attention: n(a.flops.fwdAttention),
+      fwd_total: n(a.flops.fwdTotal),
+      elementwise: n(a.flops.elementwise),
+      train_per_token: n(a.flops.trainPerToken),
+      attention_share: n(a.flops.attentionShare)
+    },
+    kv: {
+      bytes_per_token: n(a.kv.bytesPerToken),
+      bytes_per_sequence: n(a.kv.bytesPerToken * o.T + a.kv.bytesPerSequenceFixed),
+      bytes_per_token_decompressed: n(a.kv.bytesPerTokenDecompressed)
+    },
+    memory: {
+      optimizer_label: a.memory.optimizerLabel,
+      train_weights: n(a.memory.train.perGpu.weights),
+      train_grads: n(a.memory.train.perGpu.grads),
+      train_optimizer: n(a.memory.train.perGpu.optimizer),
+      train_activations: n(a.memory.train.perGpu.activations),
+      train_per_gpu: n(a.memory.train.perGpu.total),
+      train_total: n(a.memory.train.total),
+      infer_weights: n(a.memory.infer.weights),
+      infer_kv: n(a.memory.infer.kv),
+      infer_total: n(a.memory.infer.total),
+      device_memory: n(o.hardware.memory),
+      notes: a.memory.notes
+    },
+    throughput: {
+      decode_tokens_per_second: n(a.throughput.decodeTokensPerSecond),
+      decode_weight_bytes: n(a.throughput.decodeWeightBytes),
+      resident_weight_bytes: n(a.throughput.residentWeightBytes),
+      prefill_seconds: n(a.throughput.prefillSeconds),
+      memory_bound: a.throughput.memoryBound,
+      notes: a.throughput.notes
+    },
+    cost: {
+      total_flops: n(a.cost.totalFlops),
+      gpu_hours: n(a.cost.gpuHours),
+      wall_clock_hours: n(a.cost.wallClockHours),
+      dollars: n(a.cost.dollars),
+      tokens: a.cost.tokens
+    },
+    chinchilla: {
+      optimal_tokens: n(a.chinchilla.optimalTokens),
+      tokens_per_param: n(a.chinchilla.tokensPerParam),
+      over_training_ratio: n(a.chinchilla.overTrainingRatio),
+      verdict: a.chinchilla.verdict
+    },
+    errors: a.errors
+  };
+}
+function analysisText(a) {
+  const o = a.options;
+  const fits = a.memory.train.perGpu.total <= o.hardware.memory;
+  return [
+    `${a.name} at T=${o.T} B=${o.B} ${o.dtype} on ${o.gpus} x ${o.hardware.id}`,
+    ``,
+    `parameters      ${formatCount(a.params.total)} total, ${formatCount(a.params.active)} active, ` + `${formatCount(a.params.nonEmbedding)} non-embedding`,
+    `flops/token     ${formatFlops(a.flops.fwdTotal)} forward, ${formatFlops(a.flops.trainPerToken)} training; ` + `attention ${(a.flops.attentionShare * 100).toFixed(1)}%`,
+    `kv cache        ${formatBytes(a.kv.bytesPerToken)}/token, ` + `${formatBytes(a.kv.bytesPerToken * o.T + a.kv.bytesPerSequenceFixed)} at T=${o.T}`,
+    `train memory    ${formatBytes(a.memory.train.perGpu.total)} per GPU ` + `(weights ${formatBytes(a.memory.train.perGpu.weights)}, optimizer ${formatBytes(a.memory.train.perGpu.optimizer)}, ` + `activations ${formatBytes(a.memory.train.perGpu.activations)}) - ` + `${fits ? "fits" : "does NOT fit"} ${formatBytes(o.hardware.memory)}`,
+    `serve memory    ${formatBytes(a.memory.infer.total)} for ${o.concurrency} concurrent sequence(s)`,
+    `throughput      ${a.throughput.decodeTokensPerSecond.toFixed(1)} tok/s decode ` + `(${a.throughput.memoryBound ? "memory" : "compute"} bound), prefill ${a.throughput.prefillSeconds.toFixed(2)} s`,
+    `training cost   ${formatCount(a.cost.tokens)} tokens, ${a.cost.gpuHours.toFixed(0)} GPU-hours, ` + `$${a.cost.dollars.toFixed(0)}`,
+    `chinchilla      ${a.chinchilla.tokensPerParam.toFixed(1)} tokens/param - ${a.chinchilla.verdict}`,
+    ...a.errors.length > 0 ? ["", ...a.errors.map((e) => `! ${e}`)] : []
+  ].join(`
+`);
+}
+
+// packages/mcp/src/resources.ts
+import { CATALOG, analyze, validate } from "@tensor-cad/engine/node";
+var JSON_MIME = "application/json";
+var json = (uri, value) => ({
+  contents: [{ uri: uri.href, mimeType: JSON_MIME, text: `${JSON.stringify(value, null, 2)}
+` }]
+});
+function registerResources(server, store) {
+  server.registerResource("design-validation", new ResourceTemplate("tensorcad://designs/{id}/validation", { list: undefined, complete: { id: completeDesignId(store) } }), {
+    title: "Design rule report",
+    description: "Every finding for a design: shape errors, memory fit, kernel constraints, Chinchilla sanity.",
+    mimeType: JSON_MIME
+  }, (uri, { id }) => {
+    const record = store.get(String(id));
+    const report = validate(record.doc);
+    return json(uri, {
+      design_id: record.design_id,
+      revision: record.revision,
+      name: record.name,
+      ok: report.ok,
+      counts: report.counts,
+      findings: findingsJson(report)
+    });
+  });
+  server.registerResource("design-analysis", new ResourceTemplate("tensorcad://designs/{id}/analysis", { list: undefined, complete: { id: completeDesignId(store) } }), {
+    title: "Design analysis",
+    description: "Parameters, FLOPs, KV cache, memory, throughput and cost at the document's own defaults.",
+    mimeType: JSON_MIME
+  }, (uri, { id }) => {
+    const record = store.get(String(id));
+    const result = analyze(record.doc);
+    return json(uri, { design_id: record.design_id, revision: record.revision, ...analysisJson(result) });
+  });
+  server.registerResource("design", new ResourceTemplate("tensorcad://designs/{id}", {
+    list: () => ({
+      resources: store.list().map((d) => ({
+        uri: `tensorcad://designs/${d.design_id}`,
+        name: d.name,
+        title: `${d.name} (revision ${d.revision})`,
+        description: `${d.source} design${d.dirty ? ", unsaved changes" : ""}`,
+        mimeType: JSON_MIME
+      }))
+    }),
+    complete: { id: completeDesignId(store) }
+  }), {
+    title: "Design document",
+    description: "The literal .tensorcad.json document, with a compact outline beside it.",
+    mimeType: JSON_MIME
+  }, (uri, { id }) => {
+    const record = store.get(String(id));
+    return json(uri, {
+      design_id: record.design_id,
+      revision: record.revision,
+      dirty: record.dirty,
+      ...record.path ? { path: record.path } : {},
+      outline: outlineOf(record.doc),
+      document: record.doc
+    });
+  });
+  server.registerResource("catalog", "tensorcad://catalog", {
+    title: "Block catalog",
+    description: "Every block type with its parameter schema, port patterns and documentation. " + "Primitives carry the formulas; composites expand into primitives; repeat is the only container.",
+    mimeType: JSON_MIME
+  }, (uri) => {
+    const blocks = allCatalogEntries();
+    return json(uri, {
+      count: blocks.length,
+      categories: [...new Set(blocks.map((b) => b.category))].sort(),
+      blocks
+    });
+  });
+  server.registerResource("catalog-block", new ResourceTemplate("tensorcad://catalog/{type}", {
+    list: () => ({
+      resources: Object.keys(CATALOG).sort().map((type) => ({
+        uri: `tensorcad://catalog/${type}`,
+        name: type,
+        title: type,
+        description: CATALOG[type].docs.summary,
+        mimeType: JSON_MIME
+      }))
+    }),
+    complete: {
+      type: (value) => Object.keys(CATALOG).filter((t) => t.startsWith(value)).sort().slice(0, 50)
+    }
+  }), { title: "Catalog block", description: "One block type in full.", mimeType: JSON_MIME }, (uri, { type }) => {
+    const def = CATALOG[String(type)];
+    if (!def) {
+      throw new Error(`Unknown block type "${String(type)}". Known: ${Object.keys(CATALOG).sort().join(", ")}`);
+    }
+    return json(uri, catalogEntry(def));
+  });
+  server.registerResource("design-schema", "tensorcad://schema/design", {
+    title: "Design document schema",
+    description: "JSON Schema for the .tensorcad.json format.",
+    mimeType: "application/schema+json"
+  }, (uri) => ({
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "application/schema+json",
+        text: `${JSON.stringify(DESIGN_JSON_SCHEMA, null, 2)}
+`
+      }
+    ]
+  }));
+}
+function completeDesignId(store) {
+  return (value) => store.list().map((d) => d.design_id).filter((id) => id.startsWith(value));
+}
+
+// packages/mcp/src/tools.ts
+import { mkdir as mkdir3, writeFile as writeFile3 } from "node:fs/promises";
+import { dirname as dirname3, isAbsolute as isAbsolute2, join as join3, resolve as resolve2 } from "node:path";
+import * as z3 from "zod";
+import { formatBytes as formatBytes2, formatCount as formatCount2 } from "@tensor-cad/engine";
+import {
+  HARDWARE as HARDWARE2,
+  PRESET_NAMES as PRESET_NAMES3,
+  analyze as analyze2,
+  diffDesigns,
+  explain,
+  generateTorch,
+  getPreset as getPreset2,
+  importHfConfig,
+  mupLadder,
+  planCluster,
+  scaleDesign,
+  validate as validate2
+} from "@tensor-cad/engine/node";
+var ok = (text, structured) => ({
+  content: [{ type: "text", text }],
+  structuredContent: structured
+});
+async function guard(run) {
+  try {
+    return await run();
+  } catch (e) {
+    return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+  }
+}
+function toAnalysisOptions(input) {
+  const out = {};
+  if (input.T !== undefined)
+    out.T = input.T;
+  if (input.B !== undefined)
+    out.B = input.B;
+  if (input.dtype)
+    out.dtype = input.dtype;
+  if (input.tokens !== undefined)
+    out.tokens = input.tokens;
+  if (input.optimizer)
+    out.optimizer = input.optimizer;
+  if (input.recompute)
+    out.recompute = input.recompute;
+  if (input.concurrency !== undefined)
+    out.concurrency = input.concurrency;
+  if (input.mfu !== undefined)
+    out.mfu = input.mfu;
+  if (input.hardware) {
+    if (!HARDWARE2.some((h) => h.id === input.hardware)) {
+      throw new Error(`Unknown hardware "${input.hardware}". Known ids: ${HARDWARE2.map((h) => h.id).join(", ")}.`);
+    }
+    out.hardware = input.hardware;
+  }
+  const parallel = {};
+  if (input.zero !== undefined)
+    parallel.zero = input.zero;
+  if (input.tp !== undefined)
+    parallel.tp = input.tp;
+  if (input.dp !== undefined)
+    parallel.dp = input.dp;
+  if (input.pp !== undefined)
+    parallel.pp = input.pp;
+  if (input.ep !== undefined)
+    parallel.ep = input.ep;
+  if (Object.keys(parallel).length > 0)
+    out.parallel = parallel;
+  if (input.gpus !== undefined)
+    out.gpus = input.gpus;
+  else {
+    const implied = (parallel.dp ?? 1) * (parallel.tp ?? 1) * (parallel.pp ?? 1);
+    if (implied > 1)
+      out.gpus = implied;
+  }
+  return out;
+}
+var READ = { readOnlyHint: true, idempotentHint: true, openWorldHint: false };
+var WRITE = { readOnlyHint: false, idempotentHint: false, openWorldHint: false };
+var DESTRUCTIVE = { readOnlyHint: false, idempotentHint: false, destructiveHint: true, openWorldHint: false };
+function registerTools(server, store) {
+  server.registerTool("tensorcad_list_designs", {
+    title: "List designs",
+    description: "List the designs this server has open, the built-in reference architectures you can start from, " + "and the .tensorcad.json files it can see on disk. Start here when you do not already hold a design_id.",
+    inputSchema: z3.object({
+      include_files: z3.boolean().optional().describe("Also scan the working directory for .tensorcad.json files.")
+    }),
+    outputSchema: z3.object({
+      designs: z3.array(DesignSummary),
+      presets: z3.array(z3.object({
+        name: z3.string(),
+        family: z3.string().optional(),
+        published_params: z3.number().optional(),
+        notes: z3.string().optional()
+      })),
+      files: z3.array(z3.string())
+    }),
+    annotations: { ...READ, title: "List designs" }
+  }, async ({ include_files }) => guard(async () => {
+    const designs = store.list();
+    const presets = PRESET_NAMES3.map((name) => {
+      const doc = getPreset2(name);
+      const p = { name };
+      if (doc.meta.family)
+        p.family = doc.meta.family;
+      if (doc.meta.published?.params)
+        p.published_params = doc.meta.published.params;
+      if (doc.meta.notes)
+        p.notes = doc.meta.notes;
+      return p;
+    });
+    const files = include_files ? await store.listFiles() : [];
+    const text = [
+      designs.length > 0 ? `open designs:
+${designs.map((d) => `  ${d.design_id}  ${d.name}  rev ${d.revision}${d.dirty ? " (unsaved)" : ""}`).join(`
+`)}` : "open designs: none. Use tensorcad_new_design or tensorcad_open_design.",
+      "",
+      `presets (${presets.length}):`,
+      ...presets.map((p) => `  ${p.name}${p.published_params ? `  ${formatCount2(p.published_params)}` : ""}`),
+      ...include_files ? ["", `files (${files.length}):`, ...files.map((f) => `  ${f}`)] : []
+    ].join(`
+`);
+    return ok(text, { designs, presets, files });
+  }));
+  server.registerTool("tensorcad_new_design", {
+    title: "New design",
+    description: "Create a design from a reference architecture, or an empty one with just the B and T runtime symbols. " + "Returns the design_id every other tool needs.",
+    inputSchema: z3.object({
+      preset: z3.string().optional().describe(`One of: ${PRESET_NAMES3.join(", ")}. Omit for an empty design.`),
+      name: z3.string().optional().describe("Name for the new design. Defaults to the preset's name.")
+    }),
+    outputSchema: z3.object({
+      design_id: z3.string(),
+      revision: z3.number().int(),
+      name: z3.string(),
+      source: z3.enum(["preset", "file", "empty"]),
+      params_total: z3.number(),
+      outline: Outline
+    }),
+    annotations: { ...WRITE, title: "New design" }
+  }, async (args) => guard(() => {
+    const record = store.create(args);
+    const outline = outlineOf(record.doc);
+    return ok(`${record.design_id} (revision ${record.revision})
+
+${outlineText(outline)}`, {
+      design_id: record.design_id,
+      revision: record.revision,
+      name: record.name,
+      source: record.source,
+      params_total: outline.params_total,
+      outline
+    });
+  }));
+  server.registerTool("tensorcad_open_design", {
+    title: "Open design",
+    description: "Load a .tensorcad.json document from disk and return a design_id for it. " + "Opening the same path twice returns the same handle.",
+    inputSchema: z3.object({
+      path: z3.string().describe("Path to a .tensorcad.json file, absolute or relative to the server's directory.")
+    }),
+    outputSchema: z3.object({
+      design_id: z3.string(),
+      revision: z3.number().int(),
+      name: z3.string(),
+      path: z3.string(),
+      params_total: z3.number(),
+      validation: ValidationSummary
+    }),
+    annotations: { ...WRITE, title: "Open design" }
+  }, async ({ path }) => guard(async () => {
+    const record = await store.open(path);
+    const report = validate2(record.doc);
+    return ok(`${record.design_id}  ${record.name}  revision ${record.revision}
+` + `${record.path}
+${formatCount2(report.analysis.params.total)} parameters, ` + `${report.counts.error} error(s), ${report.counts.warning} warning(s)`, {
+      design_id: record.design_id,
+      revision: record.revision,
+      name: record.name,
+      path: record.path ?? path,
+      params_total: report.analysis.params.total,
+      validation: validationSummary(report)
+    });
+  }));
+  server.registerTool("tensorcad_save_design", {
+    title: "Save design",
+    description: "Write a design to disk as .tensorcad.json. Overwrites the file it was opened from unless a path is given.",
+    inputSchema: z3.object({
+      design_id: DESIGN_ID,
+      path: z3.string().optional().describe("Where to write. Defaults to the path it was opened from.")
+    }),
+    outputSchema: z3.object({
+      design_id: z3.string(),
+      revision: z3.number().int(),
+      path: z3.string(),
+      bytes: z3.number().int()
+    }),
+    annotations: { ...DESTRUCTIVE, title: "Save design" }
+  }, async ({ design_id, path }) => guard(async () => {
+    const { record, path: written, bytes } = await store.save(design_id, path);
+    return ok(`wrote ${written} (${bytes} bytes, revision ${record.revision})`, {
+      design_id: record.design_id,
+      revision: record.revision,
+      path: written,
+      bytes
+    });
+  }));
+  server.registerTool("tensorcad_get_design", {
+    title: "Get design",
+    description: 'Read a design. Use format "outline" (the default) first: it is the whole structure, symbol table and ' + 'edge shapes in a fraction of the tokens. Use format "full" only when you need the literal JSON document.',
+    inputSchema: z3.object({
+      design_id: DESIGN_ID,
+      format: z3.enum(["full", "outline"]).optional().describe('"outline" is a compact block/edge summary; "full" is the whole document.')
+    }),
+    outputSchema: z3.object({
+      design_id: z3.string(),
+      revision: z3.number().int(),
+      name: z3.string(),
+      format: z3.enum(["full", "outline"]),
+      dirty: z3.boolean(),
+      path: z3.string().optional(),
+      params_total: z3.number(),
+      params_active: z3.number(),
+      outline: Outline.optional(),
+      document: z3.record(z3.string(), z3.unknown()).optional().describe("The literal design document.")
+    }),
+    annotations: { ...READ, title: "Get design" }
+  }, async ({ design_id, format }) => guard(() => {
+    const record = store.get(design_id);
+    const outline = outlineOf(record.doc);
+    const mode = format ?? "outline";
+    const base = {
+      design_id: record.design_id,
+      revision: record.revision,
+      name: record.name,
+      format: mode,
+      dirty: record.dirty,
+      params_total: outline.params_total,
+      params_active: outline.params_active,
+      ...record.path ? { path: record.path } : {}
+    };
+    if (mode === "full") {
+      return ok(JSON.stringify(record.doc, null, 2), {
+        ...base,
+        document: record.doc
+      });
+    }
+    return ok(`${record.design_id} revision ${record.revision}
+
+${outlineText(outline)}`, {
+      ...base,
+      outline
+    });
+  }));
+  server.registerTool("tensorcad_get_block", {
+    title: "Get block",
+    description: "One block of a design: its parameters as written and as resolved, the inferred shape on every port, " + "what each port is wired to, and how many trainable parameters it contributes.",
+    inputSchema: z3.object({
+      design_id: DESIGN_ID,
+      path: z3.string().describe('Block path from the outline, e.g. "layers/block" or "embed".')
+    }),
+    outputSchema: z3.object({
+      design_id: z3.string(),
+      revision: z3.number().int(),
+      path: z3.string(),
+      id: z3.string(),
+      type: z3.string(),
+      kind: z3.string(),
+      category: z3.string(),
+      label: z3.string().optional(),
+      summary: z3.string(),
+      formula: z3.string().optional(),
+      params: z3.record(z3.string(), z3.unknown()),
+      resolved_params: z3.record(z3.string(), z3.unknown()),
+      param_errors: z3.array(z3.string()),
+      inputs: z3.array(BlockPort),
+      outputs: z3.array(BlockPort),
+      params_count: z3.number(),
+      instances: z3.number(),
+      children: z3.array(z3.string())
+    }),
+    annotations: { ...READ, title: "Get block" }
+  }, async ({ design_id, path }) => guard(() => {
+    const record = store.get(design_id);
+    const detail = blockDetail(record.doc, path);
+    return ok(blockText(detail), {
+      design_id: record.design_id,
+      revision: record.revision,
+      ...detail
+    });
+  }));
+  server.registerTool("tensorcad_search_catalog", {
+    title: "Search catalog",
+    description: "Search the block catalog. Returns each block's parameter schema, port patterns and documentation, " + "which is what you need before adding a block with tensorcad_apply_ops.",
+    inputSchema: z3.object({
+      query: z3.string().optional().describe("Substring matched against type, category, summary and formula."),
+      category: z3.string().optional().describe("attention, mlp, norm, embedding, container, io, ..."),
+      kind: z3.enum(["primitive", "composite", "container"]).optional(),
+      limit: z3.number().int().positive().max(100).optional().describe("Default 20.")
+    }),
+    outputSchema: z3.object({
+      total: z3.number().int().describe("Matches before the limit was applied."),
+      categories: z3.array(z3.string()),
+      blocks: z3.array(z3.object({
+        type: z3.string(),
+        kind: z3.string(),
+        category: z3.string(),
+        summary: z3.string(),
+        formula: z3.string().optional(),
+        refs: z3.array(z3.string()),
+        params: z3.array(z3.object({
+          name: z3.string(),
+          type: z3.string(),
+          default: z3.string().optional(),
+          doc: z3.string().optional(),
+          values: z3.array(z3.string()).optional()
+        })),
+        inputs: z3.array(z3.string()),
+        outputs: z3.array(z3.string()),
+        dynamic_ports: z3.boolean()
+      }))
+    }),
+    annotations: { ...READ, title: "Search catalog" }
+  }, async ({ query, category, kind, limit }) => guard(() => {
+    const all = allCatalogEntries();
+    const q = query?.toLowerCase();
+    const matched = all.filter((e) => {
+      if (category && e.category !== category)
+        return false;
+      if (kind && e.kind !== kind)
+        return false;
+      if (!q)
+        return true;
+      const hay = `${e.type} ${e.category} ${e.summary} ${e.formula ?? ""}`.toLowerCase();
+      return hay.includes(q);
+    });
+    const blocks = matched.slice(0, limit ?? 20);
+    const categories = [...new Set(all.map((e) => e.category))].sort();
+    const header = `${matched.length} match(es)${matched.length > blocks.length ? `, showing ${blocks.length}` : ""}`;
+    return ok(`${header}
+
+${catalogText(blocks)}`, {
+      total: matched.length,
+      categories,
+      blocks
+    });
+  }));
+  server.registerTool("tensorcad_apply_ops", {
+    title: "Apply edits",
+    description: "Apply a batch of edits to a design. The batch is all-or-nothing: the first rejected operation aborts it " + "and the design is left untouched. Pass expected_revision to be told about a concurrent edit instead of " + "silently overwriting it. Returns the new revision, what changed, and a fresh validation summary.",
+    inputSchema: z3.object({
+      design_id: DESIGN_ID,
+      expected_revision: z3.number().int().optional().describe("Revision you last read. The call is rejected if the design has moved on."),
+      ops: z3.array(Op).min(1).describe("Edits applied in order.")
+    }),
+    outputSchema: z3.object({
+      design_id: z3.string(),
+      revision: z3.number().int(),
+      previous_revision: z3.number().int(),
+      name: z3.string(),
+      applied: z3.array(z3.string()).describe("One line per operation, in order."),
+      params_total: z3.number(),
+      params_active: z3.number(),
+      params_delta: z3.number().describe("Change in total parameters caused by this batch."),
+      validation: ValidationSummary
+    }),
+    annotations: { ...WRITE, title: "Apply edits" }
+  }, async ({ design_id, expected_revision, ops }) => guard(() => {
+    const before = store.get(design_id);
+    const paramsBefore = outlineOf(before.doc).params_total;
+    const outcome = store.apply(design_id, ops, expected_revision);
+    const report = validate2(outcome.record.doc);
+    const total = report.analysis.params.total;
+    const delta = total - paramsBefore;
+    const text = [
+      `${outcome.record.design_id} revision ${outcome.previousRevision} -> ${outcome.record.revision}`,
+      ...outcome.applied.map((a) => `  ${a}`),
+      "",
+      `parameters ${formatCount2(total)}` + (delta === 0 ? " (unchanged)" : ` (${delta > 0 ? "+" : ""}${formatCount2(delta)})`),
+      `${report.counts.error} error(s), ${report.counts.warning} warning(s)`,
+      ...report.findings.length > 0 ? ["", findingsText(findingsJson(report).slice(0, 5))] : []
+    ].join(`
+`);
+    return ok(text, {
+      design_id: outcome.record.design_id,
+      revision: outcome.record.revision,
+      previous_revision: outcome.previousRevision,
+      name: outcome.record.name,
+      applied: outcome.applied,
+      params_total: total,
+      params_active: report.analysis.params.active,
+      params_delta: delta,
+      validation: validationSummary(report)
+    });
+  }));
+  server.registerTool("tensorcad_validate", {
+    title: "Validate design",
+    description: "Run every design rule: shape and symbol errors, kernel-friendly head dimensions, tensor-core multiples, " + "whether training and serving fit the chosen device, Chinchilla sanity and drift from published numbers. " + "Each finding carries a fix hint.",
+    inputSchema: z3.object({
+      design_id: DESIGN_ID,
+      severity: z3.enum(["error", "warning", "info"]).optional().describe("Only return findings at least this bad."),
+      ...analysisOptionsShape
+    }),
+    outputSchema: z3.object({
+      design_id: z3.string(),
+      revision: z3.number().int(),
+      name: z3.string(),
+      ok: z3.boolean(),
+      counts: Counts,
+      findings: z3.array(Finding),
+      params_total: z3.number()
+    }),
+    annotations: { ...READ, title: "Validate design" }
+  }, async ({ design_id, severity, ...rest }) => guard(() => {
+    const record = store.get(design_id);
+    const report = validate2(record.doc, toAnalysisOptions(rest));
+    const rank = { error: 0, warning: 1, info: 2 };
+    const findings = findingsJson(report).filter((f) => severity === undefined || rank[f.severity] <= rank[severity]);
+    const text = [
+      `${record.name} (${record.design_id} revision ${record.revision})`,
+      `${report.ok ? "ok" : "FAILED"}: ${report.counts.error} error(s), ` + `${report.counts.warning} warning(s), ${report.counts.info} info`,
+      "",
+      findingsText(findings)
+    ].join(`
+`);
+    return ok(text, {
+      design_id: record.design_id,
+      revision: record.revision,
+      name: record.name,
+      ok: report.ok,
+      counts: report.counts,
+      findings,
+      params_total: report.analysis.params.total
+    });
+  }));
+  server.registerTool("tensorcad_analyze", {
+    title: "Analyze design",
+    description: "Parameters, FLOPs per token, KV cache, training and serving memory, decode throughput, training cost and " + "Chinchilla position, for a given sequence length, batch, dtype, device, GPU count and parallel plan.",
+    inputSchema: z3.object({ design_id: DESIGN_ID, ...analysisOptionsShape }),
+    outputSchema: AnalysisOutput,
+    annotations: { ...READ, title: "Analyze design" }
+  }, async ({ design_id, ...rest }) => guard(() => {
+    const record = store.get(design_id);
+    const result = analyze2(record.doc, toAnalysisOptions(rest));
+    return ok(analysisText(result), {
+      design_id: record.design_id,
+      revision: record.revision,
+      ...analysisJson(result)
+    });
+  }));
+  server.registerTool("tensorcad_generate_code", {
+    title: "Generate code",
+    description: "Emit a runnable PyTorch module plus the design document. Without out_dir the file contents come back in " + "the result; with out_dir they are written to disk and only a manifest comes back.",
+    inputSchema: z3.object({
+      design_id: DESIGN_ID,
+      class_name: z3.string().optional().describe("Class name for the top-level module."),
+      include_smoke_test: z3.boolean().optional().describe("Emit a __main__ block that checks the size."),
+      out_dir: z3.string().optional().describe("Directory to write into. Omit to get the contents inline.")
+    }),
+    outputSchema: z3.object({
+      design_id: z3.string(),
+      revision: z3.number().int(),
+      wrote: z3.boolean(),
+      out_dir: z3.string().optional(),
+      files: z3.array(z3.object({
+        path: z3.string(),
+        bytes: z3.number().int(),
+        lines: z3.number().int(),
+        contents: z3.string().optional().describe("Present only when out_dir was not given."),
+        written_to: z3.string().optional()
+      })),
+      warnings: z3.array(z3.string())
+    }),
+    annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false, title: "Generate code" }
+  }, async ({ design_id, class_name, include_smoke_test, out_dir }) => guard(async () => {
+    const record = store.get(design_id);
+    const generated = generateTorch(record.doc, {
+      ...class_name ? { className: class_name } : {},
+      includeSmokeTest: include_smoke_test ?? false
+    });
+    const root = out_dir ? isAbsolute2(out_dir) ? out_dir : resolve2(process.cwd(), out_dir) : undefined;
+    const files = [];
+    for (const file of generated.files) {
+      const bytes = Buffer.byteLength(file.contents, "utf8");
+      const lines = file.contents.split(`
+`).length;
+      if (root) {
+        const target = join3(root, file.path);
+        await mkdir3(dirname3(target), { recursive: true });
+        await writeFile3(target, file.contents, "utf8");
+        files.push({ path: file.path, bytes, lines, written_to: target });
+      } else {
+        files.push({ path: file.path, bytes, lines, contents: file.contents });
+      }
+    }
+    const text = root ? [`wrote ${files.length} file(s) to ${root}`, ...files.map((f) => `  ${f.path}  ${f.bytes} bytes`)].join(`
+`) : generated.files.map((f) => `# ${f.path}
+${f.contents}`).join(`
+
+`);
+    return ok(generated.warnings.length > 0 ? `${text}
+
+warnings:
+${generated.warnings.map((w) => `  ${w}`).join(`
+`)}` : text, {
+      design_id: record.design_id,
+      revision: record.revision,
+      wrote: Boolean(root),
+      ...root ? { out_dir: root } : {},
+      files,
+      warnings: generated.warnings
+    });
+  }));
+  server.registerTool("tensorcad_checkpoint", {
+    title: "Checkpoint design",
+    description: "Snapshot a design under a name you can come back to. Take one before an experiment so tensorcad_restore " + "can put it back exactly.",
+    inputSchema: z3.object({
+      design_id: DESIGN_ID,
+      label: z3.string().optional().describe('What this snapshot is, e.g. "before widening the FFN".')
+    }),
+    outputSchema: z3.object({
+      design_id: z3.string(),
+      checkpoint_id: z3.string(),
+      label: z3.string(),
+      revision: z3.number().int(),
+      created_at: z3.string(),
+      checkpoints: z3.array(z3.object({
+        checkpoint_id: z3.string(),
+        label: z3.string(),
+        revision: z3.number().int(),
+        created_at: z3.string()
+      }))
+    }),
+    annotations: { ...WRITE, title: "Checkpoint design" }
+  }, async ({ design_id, label }) => guard(() => {
+    const info = store.checkpoint(design_id, label);
+    return ok(`${info.checkpoint_id} at revision ${info.revision}: ${info.label}`, {
+      design_id,
+      ...info,
+      checkpoints: store.checkpoints(design_id)
+    });
+  }));
+  server.registerTool("tensorcad_restore", {
+    title: "Restore design",
+    description: "Put a design back. With a checkpoint_id it restores that snapshot; without one it undoes the most recent " + "tensorcad_apply_ops batch. Either way the revision moves forward, so a stale expected_revision still fails.",
+    inputSchema: z3.object({
+      design_id: DESIGN_ID,
+      checkpoint_id: z3.string().optional().describe("Omit to undo the last batch of edits.")
+    }),
+    outputSchema: z3.object({
+      design_id: z3.string(),
+      revision: z3.number().int(),
+      name: z3.string(),
+      restored_from: z3.string(),
+      params_total: z3.number(),
+      validation: ValidationSummary
+    }),
+    annotations: { ...DESTRUCTIVE, title: "Restore design" }
+  }, async ({ design_id, checkpoint_id }) => guard(() => {
+    const { record, restoredFrom } = store.restore(design_id, checkpoint_id);
+    const report = validate2(record.doc);
+    return ok(`${record.design_id} restored from ${restoredFrom}; now revision ${record.revision}, ` + `${formatCount2(report.analysis.params.total)} parameters`, {
+      design_id: record.design_id,
+      revision: record.revision,
+      name: record.name,
+      restored_from: restoredFrom,
+      params_total: report.analysis.params.total,
+      validation: validationSummary(report)
+    });
+  }));
+  server.registerTool("tensorcad_explain", {
+    title: "Explain a block",
+    description: "What one block is and what it contributes: its parameters as written and as evaluated, the shape on " + "every port, its share of the model's weights and compute, and its documentation. Use it to answer " + '"why is this block this size" without reading the whole design.',
+    inputSchema: z3.object({
+      design_id: DESIGN_ID,
+      path: z3.string().describe('Full path of the block, e.g. "layers/block/attn".'),
+      ...analysisOptionsShape
+    }),
+    outputSchema: z3.object({
+      design_id: z3.string(),
+      revision: z3.number().int(),
+      path: z3.string(),
+      type: z3.string(),
+      kind: z3.string(),
+      summary: z3.string().optional(),
+      params: z3.number(),
+      share_of_params: z3.number(),
+      flops_per_token: z3.number(),
+      share_of_flops: z3.number(),
+      copies: z3.object({ total: z3.number(), active: z3.number() }),
+      parameters: z3.array(z3.object({
+        name: z3.string(),
+        expression: z3.string().optional(),
+        value: z3.number().optional(),
+        doc: z3.string().optional()
+      })),
+      ports: z3.object({
+        in: z3.record(z3.string(), z3.string()),
+        out: z3.record(z3.string(), z3.string())
+      })
+    }),
+    annotations: { ...READ, title: "Explain a block" }
+  }, async ({ design_id, path, ...rest }) => guard(() => {
+    const record = store.get(design_id);
+    const e = explain(record.doc, path, toAnalysisOptions(rest));
+    const lines = [
+      `${path}  ${e.type} (${e.kind})`,
+      e.docs.summary ?? "",
+      `parameters ${formatCount2(e.contributes.params)}  ${(e.contributes.shareOfParams * 100).toFixed(1)}% of the model`,
+      `FLOPs/token ${formatCount2(e.contributes.flopsPerToken)}  ${(e.contributes.shareOfFlops * 100).toFixed(1)}%`,
+      `copies ${e.copies.total} total, ${e.copies.active} active per token`,
+      "",
+      ...e.paramOrder.map((name) => {
+        const p = e.params[name];
+        const written = p.expression !== undefined && String(p.expression) !== String(p.value);
+        return `  ${name} = ${p.value ?? "—"}${written ? `  (${p.expression})` : ""}`;
+      })
+    ];
+    return ok(lines.filter((l) => l !== "").join(`
+`), {
+      design_id: record.design_id,
+      revision: record.revision,
+      path,
+      type: e.type,
+      kind: e.kind,
+      ...e.docs.summary ? { summary: e.docs.summary } : {},
+      params: e.contributes.params,
+      share_of_params: e.contributes.shareOfParams,
+      flops_per_token: e.contributes.flopsPerToken,
+      share_of_flops: e.contributes.shareOfFlops,
+      copies: e.copies,
+      parameters: e.paramOrder.map((name) => ({
+        name,
+        ...e.params[name].expression !== undefined ? { expression: String(e.params[name].expression) } : {},
+        ...typeof e.params[name].value === "number" ? { value: e.params[name].value } : {},
+        ...e.params[name].doc ? { doc: e.params[name].doc } : {}
+      })),
+      ports: {
+        in: Object.fromEntries(Object.entries(e.shapes.in).map(([k, v]) => [k, String(v)])),
+        out: Object.fromEntries(Object.entries(e.shapes.out).map(([k, v]) => [k, String(v)]))
+      }
+    });
+  }));
+  server.registerTool("tensorcad_scale", {
+    title: "Scale a design",
+    description: "Shrink a design towards a parameter budget while keeping its proportions, and save the result as a new " + "design. Use it to get a bench-sized proxy of a large architecture: the widths and depth move together, " + "the head dimension stays sane, and the result is reported with how close it landed.",
+    inputSchema: z3.object({
+      design_id: DESIGN_ID,
+      target_params: z3.number().positive().describe("The parameter count to aim for."),
+      target_basis: z3.enum(["total", "non-embedding"]).optional().describe('Whether target_params counts the embedding tables. At bench sizes "non-embedding" is usually meant.'),
+      vocab: z3.number().int().positive().optional().describe("Replace the vocabulary, for a smaller tokenizer."),
+      tie_head: z3.boolean().optional().describe("Share the output projection with the embedding."),
+      keep_depth: z3.boolean().optional().describe("Hold the layer count fixed and move only the width.")
+    }),
+    outputSchema: z3.object({
+      design_id: z3.string().describe("The new design, saved in this session."),
+      from: z3.string(),
+      name: z3.string(),
+      achieved: z3.number(),
+      target: z3.number(),
+      changes: z3.array(z3.object({ symbol: z3.string(), from: z3.number(), to: z3.number() })),
+      notes: z3.array(z3.string())
+    }),
+    annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false, title: "Scale a design" }
+  }, async ({ design_id, target_params, target_basis, vocab, tie_head, keep_depth }) => guard(() => {
+    const record = store.get(design_id);
+    const result = scaleDesign(record.doc, {
+      targetParams: target_params,
+      ...target_basis ? { targetBasis: target_basis } : {},
+      ...vocab !== undefined ? { vocab } : {},
+      ...tie_head !== undefined ? { tieHead: tie_head } : {},
+      ...keep_depth !== undefined ? { keepDepth: keep_depth } : {}
+    });
+    const saved = store.adopt(result.doc);
+    const changes = Object.entries(result.changes).map(([symbol, c]) => ({
+      symbol,
+      from: c.from,
+      to: c.to
+    }));
+    const text = [
+      `${result.doc.meta.name}: ${formatCount2(result.achieved)} against a target of ${formatCount2(result.target)}`,
+      ...changes.map((c) => `  ${c.symbol}  ${c.from} -> ${c.to}`),
+      ...result.notes.map((n) => `  note: ${n}`)
+    ].join(`
+`);
+    return ok(text, {
+      design_id: saved.design_id,
+      from: record.design_id,
+      name: result.doc.meta.name,
+      achieved: result.achieved,
+      target: result.target,
+      changes,
+      notes: result.notes
+    });
+  }));
+  server.registerTool("tensorcad_mup", {
+    title: "Build a width ladder",
+    description: "The same design at several widths, with what to multiply the initialization and the learning rate by at " + "each, following Tensor Programs V. Sweep hyperparameters at the narrow end and carry the answer up: a " + "learning rate tuned at the base rung is the right one at every rung, scaled per class. Every rung is " + "saved as a design of its own, ready to analyze or generate. It does not choose a learning rate; that is " + "what the sweep is for.",
+    inputSchema: z3.object({
+      design_id: DESIGN_ID,
+      widths: z3.array(z3.number().positive()).optional().describe("The widths to build. Omit to halve the design's own width down to a width worth sweeping at."),
+      base_width: z3.number().positive().optional().describe("The width the sweep happens at. Omit for the narrowest.")
+    }),
+    outputSchema: z3.object({
+      width_symbol: z3.string(),
+      base_width: z3.number(),
+      head_dim: z3.number().describe("Held fixed while the width moves: the heads get more numerous, not wider."),
+      rungs: z3.array(z3.object({
+        design_id: z3.string().describe("The rung, saved in this session."),
+        width: z3.number(),
+        multiplier: z3.number().describe("Width over the base width: the m every rule is written in."),
+        heads: z3.number(),
+        params: z3.number(),
+        base: z3.boolean(),
+        scaling: z3.array(z3.object({
+          class: z3.enum(["input", "hidden", "output"]),
+          init_std: z3.number().describe("Multiplies the base model's initialization standard deviation."),
+          adam_lr: z3.number().describe("Multiplies the base model's learning rate."),
+          paths: z3.array(z3.string()),
+          why: z3.string()
+        })),
+        notes: z3.array(z3.string())
+      })),
+      notes: z3.array(z3.string())
+    }),
+    annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false, title: "Build a width ladder" }
+  }, async ({ design_id, widths, base_width }) => guard(() => {
+    const record = store.get(design_id);
+    const ladder = mupLadder(record.doc, {
+      ...widths ? { widths } : {},
+      ...base_width !== undefined ? { baseWidth: base_width } : {}
+    });
+    const rungs = ladder.rungs.map((rung) => ({
+      design_id: store.adopt(rung.doc).design_id,
+      width: rung.width,
+      multiplier: rung.multiplier,
+      heads: rung.heads,
+      params: rung.params,
+      base: rung.base,
+      scaling: rung.scaling.map((s) => ({
+        class: s.class,
+        init_std: s.initStd,
+        adam_lr: s.adamLr,
+        paths: s.paths,
+        why: s.why
+      })),
+      notes: rung.notes
+    }));
+    const text = [
+      `${record.doc.meta.name} laddered by ${ladder.widthSymbol}, tuned at ${ladder.baseWidth}, ` + `heads of ${ladder.headDim} throughout`,
+      ...rungs.map((r) => `  ${r.base ? "base " : "     "}${r.width} wide, ${r.heads} heads, ${formatCount2(r.params)}` + `  ${r.scaling.filter((s) => s.class !== "input").map((s) => `${s.class} init x${s.init_std.toPrecision(4)} rate x${s.adam_lr.toPrecision(4)}`).join(", ")}`),
+      ...ladder.notes.map((n) => `  note: ${n}`)
+    ].join(`
+`);
+    return ok(text, {
+      width_symbol: ladder.widthSymbol,
+      base_width: ladder.baseWidth,
+      head_dim: ladder.headDim,
+      rungs,
+      notes: ladder.notes
+    });
+  }));
+  server.registerTool("tensorcad_plan", {
+    title: "Plan a cluster",
+    description: "Every way of splitting the training across a cluster that fits, least demanding first. Prices data, " + "tensor, pipeline and expert parallelism, the four ZeRO stages, sequence parallelism and the three " + "recompute settings. Memory is the claim and it is arithmetic; which plan is fastest is not claimed, so " + "each one carries a note about what it costs to run.",
+    inputSchema: z3.object({
+      design_id: DESIGN_ID,
+      ...analysisOptionsShape,
+      gpus: z3.number().int().positive().describe("How many devices there are."),
+      gpus_per_node: z3.number().int().positive().optional().describe("Bounds the tensor-parallel degree. Default 8."),
+      headroom: z3.number().positive().max(0.9).optional().describe("Fraction of device memory left free. Default 0.1."),
+      limit: z3.number().int().positive().optional().describe("How many plans to return. Default 8.")
+    }),
+    outputSchema: z3.object({
+      design_id: z3.string(),
+      revision: z3.number().int(),
+      hardware: z3.string(),
+      budget_bytes: z3.number(),
+      considered: z3.number().int(),
+      fits: z3.array(z3.object({
+        summary: z3.string(),
+        dp: z3.number(),
+        tp: z3.number(),
+        pp: z3.number(),
+        ep: z3.number(),
+        zero: z3.number().int(),
+        sequence_parallel: z3.boolean(),
+        recompute: z3.string(),
+        per_gpu_bytes: z3.number(),
+        used: z3.number(),
+        notes: z3.array(z3.string())
+      })),
+      closest: z3.object({ summary: z3.string(), per_gpu_bytes: z3.number() }).optional(),
+      notes: z3.array(z3.string())
+    }),
+    annotations: { ...READ, title: "Plan a cluster" }
+  }, async ({ design_id, gpus, gpus_per_node, headroom, limit, ...rest }) => guard(() => {
+    const record = store.get(design_id);
+    const result = planCluster(record.doc, toAnalysisOptions(rest), {
+      gpus,
+      ...gpus_per_node !== undefined ? { gpusPerNode: gpus_per_node } : {},
+      ...headroom !== undefined ? { headroom } : {},
+      ...limit !== undefined ? { limit } : {}
+    });
+    const text = result.fits.length === 0 ? [
+      `nothing fits on ${gpus} x ${result.hardware}`,
+      ...result.closest ? [`  closest: ${result.closest.summary} at ${formatBytes2(result.closest.perGpu.total)}`] : [],
+      ...result.notes.map((n) => `  ${n}`)
+    ].join(`
+`) : [
+      `${gpus} x ${result.hardware}, ${formatBytes2(result.budget)} usable each, ${result.considered} plans priced`,
+      ...result.fits.map((p) => `  ${p.summary}  ${formatBytes2(p.perGpu.total)}  ${Math.round(p.used * 100)}% of budget`)
+    ].join(`
+`);
+    return ok(text, {
+      design_id: record.design_id,
+      revision: record.revision,
+      hardware: result.hardware,
+      budget_bytes: result.budget,
+      considered: result.considered,
+      fits: result.fits.map((p) => ({
+        summary: p.summary,
+        dp: p.parallel.dp,
+        tp: p.parallel.tp,
+        pp: p.parallel.pp,
+        ep: p.parallel.ep,
+        zero: p.parallel.zero,
+        sequence_parallel: p.parallel.sequenceParallel,
+        recompute: p.recompute,
+        per_gpu_bytes: p.perGpu.total,
+        used: p.used,
+        notes: p.notes
+      })),
+      ...result.closest ? { closest: { summary: result.closest.summary, per_gpu_bytes: result.closest.perGpu.total } } : {},
+      notes: result.notes
+    });
+  }));
+  server.registerTool("tensorcad_diff", {
+    title: "Compare two designs",
+    description: "What changed between two designs and what it cost: the symbols, blocks and wires that moved, then the " + "parameters, FLOPs, cache and memory. Both sides are measured at one operating point, so the attention " + "terms are comparable. Use it after an edit, or against a preset, to check the change did what was meant.",
+    inputSchema: z3.object({
+      a: DESIGN_ID.describe("The design to compare from."),
+      b: DESIGN_ID.describe("The design to compare to."),
+      ...analysisOptionsShape
+    }),
+    outputSchema: z3.object({
+      a: z3.string(),
+      b: z3.string(),
+      identical: z3.boolean().describe("True when nothing structural moved; the numbers may still differ."),
+      at: z3.object({ T: z3.number(), B: z3.number(), hardware: z3.string() }),
+      symbols: z3.object({
+        added: z3.array(z3.string()),
+        removed: z3.array(z3.string()),
+        changed: z3.array(z3.object({ name: z3.string(), from: z3.string(), to: z3.string() }))
+      }),
+      blocks: z3.object({
+        added: z3.array(z3.string()),
+        removed: z3.array(z3.string()),
+        changed: z3.array(z3.object({
+          path: z3.string(),
+          params: z3.array(z3.object({ key: z3.string(), from: z3.string(), to: z3.string() }))
+        }))
+      }),
+      edges: z3.object({ added: z3.number().int(), removed: z3.number().int() }),
+      metrics: z3.array(z3.object({
+        metric: z3.string(),
+        a: z3.number(),
+        b: z3.number(),
+        delta: z3.number(),
+        ratio: z3.number().nullable()
+      }))
+    }),
+    annotations: { ...READ, title: "Compare two designs" }
+  }, async ({ a, b, ...rest }) => guard(() => {
+    const left = store.get(a);
+    const right = store.get(b);
+    const d = diffDesigns(left.doc, right.doc, toAnalysisOptions(rest));
+    const brief = (v) => {
+      if (v === undefined || v === null)
+        return "—";
+      if (typeof v === "object") {
+        const o = v;
+        const n = o.value ?? o.expr ?? o.default;
+        if (n !== undefined)
+          return String(n);
+      }
+      return String(v);
+    };
+    const text = [
+      `${d.a} -> ${d.b} at T=${d.at.T}, B=${d.at.B}`,
+      ...d.identical ? ["structurally identical"] : [],
+      ...d.symbols.changed.map((s) => `  ~ ${s.name}  ${brief(s.from)} -> ${brief(s.to)}`),
+      ...d.symbols.added.map((s) => `  + ${s.name} = ${brief(s.to)}`),
+      ...d.symbols.removed.map((s) => `  - ${s.name}`),
+      ...d.blocks.added.map((x) => `  + ${x.path}  ${x.type}`),
+      ...d.blocks.removed.map((x) => `  - ${x.path}  ${x.type}`),
+      ...d.blocks.changed.map((c) => `  ~ ${c.path}  ${c.params.map((p) => p.key).join(", ")}`),
+      "",
+      ...d.metrics.filter((m) => m.delta !== 0).map((m) => `  ${m.metric}  ${formatCount2(m.a)} -> ${formatCount2(m.b)}`)
+    ].filter((l) => l !== "").join(`
+`);
+    return ok(text, {
+      a: d.a,
+      b: d.b,
+      identical: d.identical,
+      at: d.at,
+      symbols: {
+        added: d.symbols.added.map((x) => x.name),
+        removed: d.symbols.removed.map((x) => x.name),
+        changed: d.symbols.changed.map((x) => ({
+          name: x.name,
+          from: brief(x.from),
+          to: brief(x.to)
+        }))
+      },
+      blocks: {
+        added: d.blocks.added.map((x) => x.path),
+        removed: d.blocks.removed.map((x) => x.path),
+        changed: d.blocks.changed.map((c) => ({
+          path: c.path,
+          params: c.params.map((p) => ({ key: p.key, from: brief(p.from), to: brief(p.to) }))
+        }))
+      },
+      edges: { added: d.edges.added.length, removed: d.edges.removed.length },
+      metrics: d.metrics
+    });
+  }));
+  server.registerTool("tensorcad_import_hf", {
+    title: "Import a Hugging Face config",
+    description: "Read a Hugging Face `config.json` into a design and save it in this session. Covers the Llama, Mistral, " + "Qwen, Gemma, Mixtral, DeepSeek and GPT-2 families. Anything the importer cannot model faithfully comes " + "back as a warning rather than being approximated silently.",
+    inputSchema: z3.object({
+      config: z3.string().describe("The contents of config.json."),
+      name: z3.string().optional().describe("A name for the design; the config's own is used otherwise.")
+    }),
+    outputSchema: z3.object({
+      design_id: z3.string(),
+      name: z3.string(),
+      params_total: z3.number(),
+      warnings: z3.array(z3.string())
+    }),
+    annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false, title: "Import a config" }
+  }, async ({ config, name }) => guard(() => {
+    const result = importHfConfig(config, name);
+    const record = store.adopt(result.doc);
+    const total = analyze2(result.doc).params.total;
+    const text = [
+      `${result.doc.meta.name}: ${formatCount2(total)} parameters`,
+      ...result.warnings.map((w) => `  warning: ${w}`)
+    ].join(`
+`);
+    return ok(text, {
+      design_id: record.design_id,
+      name: result.doc.meta.name,
+      params_total: total,
+      warnings: result.warnings
+    });
+  }));
+}
+var TOOL_NAMES = [
+  "tensorcad_list_designs",
+  "tensorcad_new_design",
+  "tensorcad_open_design",
+  "tensorcad_save_design",
+  "tensorcad_get_design",
+  "tensorcad_get_block",
+  "tensorcad_search_catalog",
+  "tensorcad_apply_ops",
+  "tensorcad_validate",
+  "tensorcad_analyze",
+  "tensorcad_generate_code",
+  "tensorcad_checkpoint",
+  "tensorcad_restore",
+  "tensorcad_explain",
+  "tensorcad_scale",
+  "tensorcad_mup",
+  "tensorcad_plan",
+  "tensorcad_diff",
+  "tensorcad_import_hf"
+];
+
+// packages/mcp/src/server.ts
+var SERVER_NAME = "tensorcad";
+var SERVER_VERSION = package_default.version;
+var INSTRUCTIONS = [
+  "TensorCAD designs transformer language models as a graph of typed blocks and reports what they would cost.",
+  "",
+  "Hold a design_id from tensorcad_new_design or tensorcad_open_design and pass it to everything else.",
+  'Read with tensorcad_get_design format "outline" before reaching for the full document: it carries the whole',
+  "structure, the symbol table and the shape on every edge for a fraction of the tokens.",
+  "",
+  "Edit through tensorcad_apply_ops. A batch is all-or-nothing, and passing expected_revision turns a concurrent",
+  "edit into a clear error instead of a silent overwrite. Take an tensorcad_checkpoint before an experiment;",
+  "tensorcad_restore puts it back, or undoes the last batch when you name no checkpoint.",
+  "",
+  "Most designs are parameterised by symbols (L layers, D width, H heads, Hkv key/value heads, dh head dim,",
+  "F feed-forward width, V vocabulary), so a set_symbol operation is usually the right edit rather than",
+  "touching individual blocks.",
+  "",
+  "After an edit, tensorcad_diff against the design you started from says what moved and what it cost;",
+  "tensorcad_explain answers why one block is the size it is without reading the whole document.",
+  "tensorcad_plan answers whether the thing would train on a given number of GPUs and how it would have to",
+  "be split. tensorcad_scale shrinks a design to a bench budget, and tensorcad_import_hf reads a Hugging Face",
+  "config.json into one. Both save their result as a new design, analysable and diffable like any other."
+].join(`
+`);
+function createServer2(options = {}) {
+  const { store: given, bridge, ...storeOptions } = options;
+  const store = given ?? new FileStore(storeOptions);
+  const server = new McpServer2({ name: SERVER_NAME, version: SERVER_VERSION }, {
+    capabilities: { tools: {}, resources: {}, prompts: {}, completions: {} },
+    instructions: INSTRUCTIONS
+  });
+  registerTools(server, store);
+  registerResources(server, store);
+  registerPrompts(server);
+  if (bridge)
+    followEditor(server, bridge);
+  return server;
+}
+function followEditor(server, bridge) {
+  const stop = bridge.watch((change, from) => {
+    if (from !== "editor")
+      return;
+    const base = `tensorcad://designs/${change.record.design_id}`;
+    for (const uri of [base, `${base}/analysis`, `${base}/validation`]) {
+      server.server.sendResourceUpdated({ uri }).catch(() => {});
+    }
+  });
+  const closed = server.server.onclose;
+  server.server.onclose = () => {
+    stop();
+    closed?.();
+  };
+}
+
+// packages/mcp/src/serve.ts
+async function serve(root = process.env.TENSORCAD_ROOT ?? process.cwd()) {
+  await loadEngine();
+  const store = new FileStore({ root });
+  const bridge = await startBridge(store, root);
+  serveStdio(() => createServer2({ root, store, bridge }));
+  process.stderr.write(`tensorcad mcp server on stdio, root ${root}
+`);
+}
+async function startBridge(store, root) {
+  if (process.env.TENSORCAD_BRIDGE !== "1")
+    return;
+  const bridge = new BridgeServer({
+    store,
+    root,
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+    port: Number(process.env.TENSORCAD_BRIDGE_PORT) || DEFAULT_BRIDGE_PORT
+  });
+  try {
+    await bridge.start();
+  } catch (e) {
+    process.stderr.write(`tensorcad: the editor bridge did not start: ${e.message}
+`);
+    return;
+  }
+  process.once("exit", () => clearSessionSync());
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.once(signal, () => {
+      clearSessionSync();
+      process.exit(0);
+    });
+  }
+  return bridge;
+}
+export {
+  serve
+};