@tensor-cad/mcp 0.1.0

package/store/file-store.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The headless document store: `.tensorcad.json` files plus the built-in presets,
+ * held in memory with a revision counter and an operation log.
+ *
+ * The live editor bridge watches this store through `subscribe` rather than
+ * replacing it. An earlier note here proposed a second `DocumentStore` that
+ * proxied to the editor; that would have given a design two homes and no rule
+ * for which one is right when they differ. See `src/bridge/`.
+ */
+import { type Op } from "../ops.js";
+import type { Doc } from "@tensor-cad/engine";
+import { type ApplyOutcome, type CheckpointInfo, type DesignRecord, type DesignSummary, type DocumentStore, type NewDesignOptions, type StoreListener } from "./types.js";
+export interface FileStoreOptions {
+    /** Directory `listFiles` scans and relative save paths resolve against. */
+    root?: string;
+    /** How deep `listFiles` walks. */
+    depth?: number;
+}
+export declare class FileStore implements DocumentStore {
+    private readonly entries;
+    private readonly listeners;
+    private nextDesign;
+    private nextCheckpoint;
+    readonly root: string;
+    private readonly depth;
+    constructor(options?: FileStoreOptions);
+    subscribe(listener: StoreListener): () => void;
+    /**
+     * A listener that throws must not take the edit down with it. The store's
+     * job is the document; a mirror that has fallen over is the mirror's problem,
+     * and it is reported where a server's diagnostics go.
+     */
+    private emit;
+    list(): DesignSummary[];
+    listFiles(): Promise<string[]>;
+    get(id: string): DesignRecord;
+    create(options: NewDesignOptions): DesignRecord;
+    adopt(doc: Doc): DesignRecord;
+    open(path: string): Promise<DesignRecord>;
+    private register;
+    apply(id: string, ops: Op[], expectedRevision?: number): ApplyOutcome;
+    replace(id: string, doc: Doc, expectedRevision?: number): ApplyOutcome;
+    save(id: string, path?: string): Promise<{
+        record: DesignRecord;
+        path: string;
+        bytes: number;
+    }>;
+    checkpoint(id: string, label?: string): CheckpointInfo;
+    checkpoints(id: string): CheckpointInfo[];
+    restore(id: string, checkpointId?: string): {
+        record: DesignRecord;
+        restoredFrom: string;
+    };
+    private entry;
+    private resolvePath;
+    /** Whether a path exists, used by tools that want a friendlier message. */
+    static exists(path: string): Promise<boolean>;
+}

package/store/types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The document store the tools talk to.
+ *
+ * Designs are addressed by a server-minted `design_id` rather than by a
+ * session, which is what the 2026-07-28 spec asks for: state crosses calls as
+ * an explicit handle in the arguments, never as an implicit connection.
+ *
+ * `FileStore` is the only implementation. The live editor bridge is *not* a
+ * second store: it observes this one through `subscribe` and mirrors it to a
+ * running editor. Two stores could disagree about what a design is; one store
+ * with a listener cannot.
+ */
+import type { Op } from "../ops.js";
+import type { Doc } from "@tensor-cad/engine";
+/**
+ * Where a design in this session came from. `derived` is one the engine
+ * produced from another — scaled, or read out of a Hugging Face config — which
+ * has no file behind it and is not a preset.
+ */
+export type DesignSource = "preset" | "file" | "empty" | "derived";
+export interface DesignSummary {
+    design_id: string;
+    name: string;
+    revision: number;
+    /** Absolute path this design was opened from or last saved to. */
+    path?: string;
+    source: DesignSource;
+    /** True when there are edits that `tensorcad_save_design` has not written yet. */
+    dirty: boolean;
+    created_at: string;
+    updated_at: string;
+}
+export interface DesignRecord extends DesignSummary {
+    doc: Doc;
+}
+export interface CheckpointInfo {
+    checkpoint_id: string;
+    label: string;
+    revision: number;
+    created_at: string;
+}
+export interface ApplyOutcome {
+    record: DesignRecord;
+    applied: string[];
+    previousRevision: number;
+}
+export interface NewDesignOptions {
+    preset?: string;
+    name?: string;
+}
+/** What happened to a design, for anybody mirroring the store. */
+export interface StoreChange {
+    kind: "registered" | "applied" | "replaced" | "saved" | "restored";
+    record: DesignRecord;
+    /** The operations, when there were any — `applied` alone carries them. */
+    ops?: Op[];
+}
+export type StoreListener = (change: StoreChange) => void;
+export interface DocumentStore {
+    /**
+     * Watch every change to every design. Returns the function that stops
+     * watching.
+     *
+     * Listeners are called *synchronously*, inside the call that changed
+     * something, which is what lets the bridge attribute a change to the
+     * connection that caused it without threading an origin through every
+     * signature.
+     */
+    subscribe(listener: StoreListener): () => void;
+    /** Designs this server has open, newest first. */
+    list(): DesignSummary[];
+    /** `.tensorcad.json` files near the server's root that could be opened. */
+    listFiles(): Promise<string[]>;
+    create(options: NewDesignOptions): DesignRecord;
+    /**
+     * Take a document the engine produced — scaled, imported, derived — as a new
+     * design in this session.
+     *
+     * Separate from `create`, which builds one from a preset or from nothing:
+     * these arrive whole and there is nothing to build.
+     */
+    adopt(doc: Doc): DesignRecord;
+    open(path: string): Promise<DesignRecord>;
+    get(id: string): DesignRecord;
+    apply(id: string, ops: Op[], expectedRevision?: number): ApplyOutcome;
+    /**
+     * The whole document, in place of a list of operations.
+     *
+     * The editor's edits are not all expressible as the eight operations a tool
+     * call can send — a block moved on the sheet, a definition, a configuration —
+     * so what the running editor sends back is the document it now has. It is
+     * otherwise an `apply`: the revision is checked, the previous document goes
+     * on the undo log, and the change is announced.
+     */
+    replace(id: string, doc: Doc, expectedRevision?: number): ApplyOutcome;
+    save(id: string, path?: string): Promise<{
+        record: DesignRecord;
+        path: string;
+        bytes: number;
+    }>;
+    checkpoint(id: string, label?: string): CheckpointInfo;
+    checkpoints(id: string): CheckpointInfo[];
+    /** Without a checkpoint id this undoes the most recent `apply`. */
+    restore(id: string, checkpointId?: string): {
+        record: DesignRecord;
+        restoredFrom: string;
+    };
+}
+/** Thrown when a mutating call names a revision that is no longer current. */
+export declare class RevisionConflictError extends Error {
+    readonly designId: string;
+    readonly expected: number;
+    readonly actual: number;
+    constructor(designId: string, expected: number, actual: number);
+}
+/** Thrown when a `design_id` is unknown. */
+export declare class UnknownDesignError extends Error {
+    constructor(id: string, known: string[]);
+}

package/summarize.d.ts

@@ -0,0 +1,128 @@
+import type { CatalogEntry as EngineCatalogEntry } from "@tensor-cad/engine";
+import type { AnalysisResult, Doc, ValidationReport } from "@tensor-cad/engine";
+/**
+ * Projections of a design that are cheap for a model to read.
+ *
+ * `outline` is the one an assistant should reach for first: it is the whole
+ * shape of the design in a few hundred tokens, where the full document is a few
+ * thousand. The others mirror the core's results as plain JSON, because
+ * `AnalysisResult` carries `Map`s that do not survive serialization.
+ */
+export interface OutlineSymbol {
+    name: string;
+    kind: "design" | "runtime";
+    value: string;
+    resolved?: number;
+    doc?: string;
+}
+export interface OutlineBlock {
+    path: string;
+    type: string;
+    kind: string;
+    depth: number;
+    label?: string;
+    /** Trainable parameters under this path, including every repeat instance. */
+    params: number;
+    /** Instance count for `repeat` containers. */
+    repeat?: number;
+}
+export interface OutlineEdge {
+    /** Container path the edge lives in; `""` is the root graph. */
+    graph: string;
+    from: string;
+    to: string;
+    /** Inferred shape on the wire, e.g. `"B T D"`. */
+    shape?: string;
+}
+export interface Outline {
+    name: string;
+    family?: string;
+    notes?: string;
+    symbols: OutlineSymbol[];
+    blocks: OutlineBlock[];
+    edges: OutlineEdge[];
+    params_total: number;
+    params_active: number;
+    issues: number;
+}
+export declare function outlineOf(doc: Doc): Outline;
+/** The outline rendered for a human (and as the text mirror of the tool result). */
+export declare function outlineText(o: Outline): string;
+export interface BlockPort {
+    name: string;
+    pattern: string;
+    shape?: string;
+    /** Declared element type, when it is not inherited from the producer. */
+    dtype?: string;
+    /** True when this port may legitimately be left unwired. */
+    optional?: boolean;
+    /** The port on the other end of the wire, as a full path. */
+    connected_to?: string[];
+}
+export interface BlockDetail {
+    path: string;
+    id: string;
+    type: string;
+    kind: string;
+    category: string;
+    label?: string;
+    summary: string;
+    formula?: string;
+    params: Record<string, unknown>;
+    resolved_params: Record<string, unknown>;
+    param_errors: string[];
+    inputs: BlockPort[];
+    outputs: BlockPort[];
+    params_count: number;
+    /** Multiplied instances of this block, from the enclosing `repeat`s. */
+    instances: number;
+    children: string[];
+}
+export declare function blockDetail(doc: Doc, path: string): BlockDetail;
+export declare function blockText(b: BlockDetail): string;
+export interface CatalogParam {
+    name: string;
+    type: string;
+    default?: string;
+    doc?: string;
+    values?: string[];
+}
+export interface CatalogEntry {
+    type: string;
+    kind: string;
+    category: string;
+    summary: string;
+    formula?: string;
+    refs: string[];
+    params: CatalogParam[];
+    inputs: string[];
+    outputs: string[];
+    /** True when the port list depends on the block's parameters. */
+    dynamic_ports: boolean;
+}
+export declare function catalogEntry(def: EngineCatalogEntry): CatalogEntry;
+export declare function allCatalogEntries(): CatalogEntry[];
+export declare function catalogText(entries: CatalogEntry[]): string;
+export interface FindingJson {
+    rule: string;
+    severity: "error" | "warning" | "info";
+    path?: string;
+    port?: string;
+    message: string;
+    hint?: string;
+}
+export declare function findingsJson(report: ValidationReport): FindingJson[];
+export interface ValidationSummary {
+    ok: boolean;
+    counts: {
+        error: number;
+        warning: number;
+        info: number;
+    };
+    /** The first few findings, worst first. Call `tensorcad_validate` for all of them. */
+    top_findings: FindingJson[];
+}
+export declare function validationSummary(report: ValidationReport, limit?: number): ValidationSummary;
+export declare function findingsText(findings: FindingJson[]): string;
+export declare function analysisJson(a: AnalysisResult): Record<string, unknown>;
+export declare function analysisText(a: AnalysisResult): string;

package/tools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The tool surface: thirteen tools, namespaced `tensorcad_`.
+ *
+ * Deliberately few and coarse. Some clients cap how many tools they keep
+ * active, so graph editing is one batched `tensorcad_apply_ops` rather than a
+ * setter per property, and reads default to the compact outline.
+ */
+import type { McpServer } from "@modelcontextprotocol/server";
+import type { DocumentStore } from "./store/types.js";
+export declare function registerTools(server: McpServer, store: DocumentStore): void;
+/** The tools this server registers, in the order it registers them. */
+export declare const TOOL_NAMES: readonly ["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"];