@tensor-cad/mcp 0.1.0

package/mcp.example.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "tensorcad": {
+      "type": "stdio",
+      "command": "bun",
+      "args": ["packages/mcp/src/stdio.ts"],
+      "env": {
+        "TENSORCAD_ROOT": "."
+      }
+    }
+  }
+}

package/ops.d.ts

@@ -0,0 +1,69 @@
+import type { Doc, Graph, ParamValue } from "@tensor-cad/engine";
+/**
+ * The edit operations an agent can apply to a design.
+ *
+ * One patch tool beats thirty setters: it keeps the tool count under the caps
+ * some clients impose, and a batch either lands whole or not at all, so a
+ * half-applied edit can never be observed.
+ */
+export type Op = {
+    op: "add_node";
+    /** Container node whose subgraph receives the block. Empty or absent means the root graph. */
+    parent?: string;
+    id: string;
+    type: string;
+    params?: Record<string, ParamValue>;
+    label?: string;
+} | {
+    op: "remove_node";
+    path: string;
+} | {
+    op: "set_param";
+    path: string;
+    key: string;
+    value: ParamValue;
+} | {
+    op: "connect";
+    graph?: string;
+    from: string;
+    to: string;
+} | {
+    op: "disconnect";
+    graph?: string;
+    from: string;
+    to: string;
+} | {
+    op: "set_symbol";
+    name: string;
+    value: number | string | null;
+    doc?: string;
+    runtime?: boolean;
+} | {
+    op: "rename";
+    path: string;
+    id: string;
+} | {
+    op: "set_label";
+    path: string;
+    label?: string | null;
+};
+/** A rejected operation. The message is meant to be read by a model. */
+export declare class OpError extends Error {
+    readonly index: number;
+    readonly op: Op;
+    constructor(index: number, op: Op, message: string);
+}
+/** The graph identified by a container path; the empty string is the root. */
+export declare function graphAt(doc: Doc, path: string | undefined): Graph;
+/** Every node path in the document, parents before children. */
+export declare function allPaths(graph: Graph, prefix?: string, out?: string[]): string[];
+export interface ApplyResult {
+    doc: Doc;
+    /** One human-readable line per operation, in order. */
+    applied: string[];
+}
+/**
+ * Apply a batch to a copy of the document. The original is never touched, and
+ * the first failing operation aborts the whole batch.
+ */
+export declare function applyOps(doc: Doc, ops: Op[]): ApplyResult;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "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",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./server": {
+      "types": "./server.d.ts",
+      "import": "./server.js"
+    },
+    "./stdio": {
+      "types": "./stdio.d.ts",
+      "import": "./stdio.js"
+    }
+  },
+  "bin": {
+    "tensorcad-mcp": "./stdio.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "@tensor-cad/engine": "0.1.0",
+    "ws": "^8.21.3",
+    "zod": "^4.2.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Filip-Pajalic/TensorCAD.git"
+  }
+}

package/prompts.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Prompts.
+ *
+ * Four workflows worth having a slash command for. In Claude Code these show
+ * up as `/mcp__tensorcad__design_model` and friends.
+ *
+ * MCP prompt arguments are strings on the wire, so the schemas take strings and
+ * the text says what a good value looks like.
+ */
+import type { McpServer } from "@modelcontextprotocol/server";
+export declare function registerPrompts(server: McpServer): void;
+export declare const PROMPT_NAMES: readonly ["design_model", "review_design", "scale_design", "explain_costs"];

package/resources.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resources.
+ *
+ * Almost no design tool exposes its document as an MCP resource, which is a
+ * gap worth closing: resources are `@`-mentionable in Claude Code, they are
+ * cache friendly, and they let a client read a design without spending a tool
+ * call on it.
+ */
+import { McpServer } from "@modelcontextprotocol/server";
+import type { DocumentStore } from "./store/types.js";
+export declare function registerResources(server: McpServer, store: DocumentStore): void;

package/schemas.d.ts

@@ -0,0 +1,291 @@
+/**
+ * The wire contract.
+ *
+ * Every tool declares both an `inputSchema` and an `outputSchema`, so a client
+ * can validate what it gets back and a model can see the shape of an answer
+ * before it asks for one.
+ */
+import * as z from "zod";
+export declare const DESIGN_ID: z.ZodString;
+export declare const Severity: z.ZodEnum<{
+    error: "error";
+    warning: "warning";
+    info: "info";
+}>;
+export declare const Finding: z.ZodObject<{
+    rule: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+        info: "info";
+    }>;
+    path: z.ZodOptional<z.ZodString>;
+    port: z.ZodOptional<z.ZodString>;
+    message: z.ZodString;
+    hint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const Counts: z.ZodObject<{
+    error: z.ZodNumber;
+    warning: z.ZodNumber;
+    info: z.ZodNumber;
+}, z.core.$strip>;
+export declare const ValidationSummary: z.ZodObject<{
+    ok: z.ZodBoolean;
+    counts: z.ZodObject<{
+        error: z.ZodNumber;
+        warning: z.ZodNumber;
+        info: z.ZodNumber;
+    }, z.core.$strip>;
+    top_findings: z.ZodArray<z.ZodObject<{
+        rule: z.ZodString;
+        severity: z.ZodEnum<{
+            error: "error";
+            warning: "warning";
+            info: "info";
+        }>;
+        path: z.ZodOptional<z.ZodString>;
+        port: z.ZodOptional<z.ZodString>;
+        message: z.ZodString;
+        hint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const DesignSummary: z.ZodObject<{
+    design_id: z.ZodString;
+    name: z.ZodString;
+    revision: z.ZodNumber;
+    path: z.ZodOptional<z.ZodString>;
+    source: z.ZodEnum<{
+        file: "file";
+        preset: "preset";
+        empty: "empty";
+    }>;
+    dirty: z.ZodBoolean;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+export declare const OutlineSymbol: z.ZodObject<{
+    name: z.ZodString;
+    kind: z.ZodEnum<{
+        runtime: "runtime";
+        design: "design";
+    }>;
+    value: z.ZodString;
+    resolved: z.ZodOptional<z.ZodNumber>;
+    doc: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const OutlineBlock: z.ZodObject<{
+    path: z.ZodString;
+    type: z.ZodString;
+    kind: z.ZodString;
+    depth: z.ZodNumber;
+    label: z.ZodOptional<z.ZodString>;
+    params: z.ZodNumber;
+    repeat: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const OutlineEdge: z.ZodObject<{
+    graph: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodString;
+    shape: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const Outline: z.ZodObject<{
+    name: z.ZodString;
+    family: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    symbols: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            runtime: "runtime";
+            design: "design";
+        }>;
+        value: z.ZodString;
+        resolved: z.ZodOptional<z.ZodNumber>;
+        doc: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    blocks: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        type: z.ZodString;
+        kind: z.ZodString;
+        depth: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+        params: z.ZodNumber;
+        repeat: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    edges: z.ZodArray<z.ZodObject<{
+        graph: z.ZodString;
+        from: z.ZodString;
+        to: z.ZodString;
+        shape: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    params_total: z.ZodNumber;
+    params_active: z.ZodNumber;
+    issues: z.ZodNumber;
+}, z.core.$strip>;
+export declare const BlockPort: z.ZodObject<{
+    name: z.ZodString;
+    pattern: z.ZodString;
+    shape: z.ZodOptional<z.ZodString>;
+    dtype: z.ZodOptional<z.ZodString>;
+    optional: z.ZodOptional<z.ZodBoolean>;
+    connected_to: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** The knobs `tensorcad_analyze` and `tensorcad_validate` share. */
+export declare const analysisOptionsShape: {
+    T: z.ZodOptional<z.ZodNumber>;
+    B: z.ZodOptional<z.ZodNumber>;
+    dtype: z.ZodOptional<z.ZodEnum<{
+        fp32: "fp32";
+        bf16: "bf16";
+        fp16: "fp16";
+        fp8: "fp8";
+    }>>;
+    hardware: z.ZodOptional<z.ZodString>;
+    gpus: z.ZodOptional<z.ZodNumber>;
+    tokens: z.ZodOptional<z.ZodNumber>;
+    optimizer: z.ZodOptional<z.ZodEnum<{
+        adamw: "adamw";
+        adamw8bit: "adamw8bit";
+        muon: "muon";
+        sgd_momentum: "sgd_momentum";
+        sgd: "sgd";
+        bf16_adam: "bf16_adam";
+    }>>;
+    recompute: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        selective: "selective";
+        full: "full";
+    }>>;
+    zero: z.ZodOptional<z.ZodNumber>;
+    tp: z.ZodOptional<z.ZodNumber>;
+    dp: z.ZodOptional<z.ZodNumber>;
+    pp: z.ZodOptional<z.ZodNumber>;
+    ep: z.ZodOptional<z.ZodNumber>;
+    concurrency: z.ZodOptional<z.ZodNumber>;
+    mfu: z.ZodOptional<z.ZodNumber>;
+};
+export declare const Op: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"add_node">;
+    parent: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    type: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"remove_node">;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"set_param">;
+    path: z.ZodString;
+    key: z.ZodString;
+    value: z.ZodAny;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"connect">;
+    graph: z.ZodOptional<z.ZodString>;
+    from: z.ZodString;
+    to: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"disconnect">;
+    graph: z.ZodOptional<z.ZodString>;
+    from: z.ZodString;
+    to: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"set_symbol">;
+    name: z.ZodString;
+    value: z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodNull]>;
+    doc: z.ZodOptional<z.ZodString>;
+    runtime: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"rename">;
+    path: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"set_label">;
+    path: z.ZodString;
+    label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>], "op">;
+export declare const AnalysisOutput: z.ZodObject<{
+    design_id: z.ZodString;
+    revision: z.ZodNumber;
+    name: z.ZodString;
+    options: z.ZodObject<{
+        T: z.ZodNumber;
+        B: z.ZodNumber;
+        dtype: z.ZodString;
+        hardware: z.ZodString;
+        gpus: z.ZodNumber;
+        parallel: z.ZodObject<{
+            dp: z.ZodNumber;
+            tp: z.ZodNumber;
+            pp: z.ZodNumber;
+            ep: z.ZodNumber;
+            zero: z.ZodNumber;
+            sequenceParallel: z.ZodBoolean;
+        }, z.core.$strip>;
+        optimizer: z.ZodString;
+        recompute: z.ZodString;
+        tokens: z.ZodNumber;
+        tokens_were_defaulted: z.ZodBoolean;
+        mfu: z.ZodNumber;
+        concurrency: z.ZodNumber;
+    }, z.core.$strip>;
+    params: z.ZodObject<{
+        total: z.ZodNumber;
+        active: z.ZodNumber;
+        embedding: z.ZodNumber;
+        head: z.ZodNumber;
+        non_embedding: z.ZodNumber;
+        non_embedding_active: z.ZodNumber;
+        by_category: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        by_type: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    }, z.core.$strip>;
+    flops: z.ZodObject<{
+        fwd_dense: z.ZodNullable<z.ZodNumber>;
+        fwd_attention: z.ZodNullable<z.ZodNumber>;
+        fwd_total: z.ZodNullable<z.ZodNumber>;
+        elementwise: z.ZodNullable<z.ZodNumber>;
+        train_per_token: z.ZodNullable<z.ZodNumber>;
+        attention_share: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    kv: z.ZodObject<{
+        bytes_per_token: z.ZodNullable<z.ZodNumber>;
+        bytes_per_sequence: z.ZodNullable<z.ZodNumber>;
+        bytes_per_token_decompressed: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    memory: z.ZodObject<{
+        optimizer_label: z.ZodString;
+        train_weights: z.ZodNullable<z.ZodNumber>;
+        train_grads: z.ZodNullable<z.ZodNumber>;
+        train_optimizer: z.ZodNullable<z.ZodNumber>;
+        train_activations: z.ZodNullable<z.ZodNumber>;
+        train_per_gpu: z.ZodNullable<z.ZodNumber>;
+        train_total: z.ZodNullable<z.ZodNumber>;
+        infer_weights: z.ZodNullable<z.ZodNumber>;
+        infer_kv: z.ZodNullable<z.ZodNumber>;
+        infer_total: z.ZodNullable<z.ZodNumber>;
+        device_memory: z.ZodNullable<z.ZodNumber>;
+        notes: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    throughput: z.ZodObject<{
+        decode_tokens_per_second: z.ZodNullable<z.ZodNumber>;
+        decode_weight_bytes: z.ZodNullable<z.ZodNumber>;
+        resident_weight_bytes: z.ZodNullable<z.ZodNumber>;
+        prefill_seconds: z.ZodNullable<z.ZodNumber>;
+        memory_bound: z.ZodBoolean;
+        notes: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    cost: z.ZodObject<{
+        total_flops: z.ZodNullable<z.ZodNumber>;
+        gpu_hours: z.ZodNullable<z.ZodNumber>;
+        wall_clock_hours: z.ZodNullable<z.ZodNumber>;
+        dollars: z.ZodNullable<z.ZodNumber>;
+        tokens: z.ZodNumber;
+    }, z.core.$strip>;
+    chinchilla: z.ZodObject<{
+        optimal_tokens: z.ZodNullable<z.ZodNumber>;
+        tokens_per_param: z.ZodNullable<z.ZodNumber>;
+        over_training_ratio: z.ZodNullable<z.ZodNumber>;
+        verdict: z.ZodString;
+    }, z.core.$strip>;
+    errors: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type OpInput = z.infer<typeof Op>;

package/serve.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Starting the server, as a function rather than as a side effect.
+ *
+ * It used to be a bare `if (import.meta.main)` at the bottom of `index.ts`,
+ * which made that module two things: a library other code imports and a program
+ * that starts a server. That works under Bun and does not survive a bundler —
+ * `import.meta.main` compiles to a CommonJS check that is not defined in an ESM
+ * output, so the bundled server crashed before its first line ran.
+ */
+/** Serve on stdio until the transport closes. */
+export declare function serve(root?: string): Promise<void>;