tensorcad

@tensor-cad/mcp

一个 MCP 服务，让助手能够设计 Transformer 语言模型，并在有人编写训练脚本之前了解其成本。

它封装了 @tensor-cad/engine，这是一个从 Go 编译为 WebAssembly 的分析引擎：包含类型化区块图、符号形状推断、设计规则检查、参数量/FLOPs/内存/成本模型，以及 PyTorch 代码生成器。该服务不依赖界面，可处理 .tensorcad.json 文件和内置参考架构，无需运行编辑器。

基于官方 TypeScript SDK v2（@modelcontextprotocol/server 2.0.0）构建，通过 stdio 提供服务。

安装

Claude Code

# from a checkout, during development
claude mcp add --transport stdio tensorcad -- bun packages/mcp/src/stdio.ts

# published
claude mcp add --transport stdio tensorcad -- npx -y @tensor-cad/mcp

添加 --scope project，即可为仓库中的所有人写入已提交的 .mcp.json。资源随后会以 @tensorcad:tensorcad://... 的形式显示为提及，提示词则显示为 /mcp__tensorcad__design_model。

Cursor

项目中的 .cursor/mcp.json，或供所有项目使用的 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "tensorcad": {
      "command": "npx",
      "args": ["-y", "@tensor-cad/mcp"]
    }
  }
}

Cursor 会限制所有服务中同时启用的工具数量，因此本服务提供 18 个工具，而不是 40 个。

Claude Desktop，一键安装

从发布版本下载 tensorcad.mcpb 并打开。Claude Desktop 会将其安装为扩展，并提示你选择一个用于存放设计的文件夹。

该捆绑包包含为 Node 构建的服务——Claude Desktop 附带 Node，而本仓库不使用 Node——以及与之并列的 WebAssembly 引擎。bun run build:mcpb 会构建捆绑包，并在构建完成前通过 Node 启动它，因为导致问题的两处差异都来自 Bun 与 Node 的不同，而不是服务本身。

Claude Desktop，手动安装

claude_desktop_config.json（Settings、Developer、Edit Config）：

{
  "mcpServers": {
    "tensorcad": {
      "command": "npx",
      "args": ["-y", "@tensor-cad/mcp"],
      "env": { "TENSORCAD_ROOT": "/absolute/path/to/your/designs" }
    }
  }
}

任何客户端

mcp.example.json 是基于仓库相对路径的开发配置：在仓库根目录运行 bun packages/mcp/src/stdio.ts。

TENSORCAD_ROOT 用于设置 tensorcad_list_designs 扫描 .tensorcad.json 文件的目录，也是相对路径的解析基准。默认值为进程的工作目录。

工具

共有 18 个工具，名称均以 tensorcad_ 为前缀。每个工具都声明了 inputSchema 和 outputSchema，并在返回易读文本的同时提供 structuredContent；读取操作标注为 readOnlyHint 和 idempotentHint，两个会覆盖内容的工具则标注为 destructiveHint。

工具	功能
tensorcad_list_designs	列出已打开的设计、内置参考架构和磁盘上的 .tensorcad.json 文件
tensorcad_new_design	从预设或空白设计开始；返回 design_id
tensorcad_open_design	加载 .tensorcad.json；重复打开同一路径会返回同一个句柄
tensorcad_save_design	将设计写回磁盘
tensorcad_get_design	format: "outline"（默认）或 "full"
tensorcad_get_block	获取单个区块：书面参数及解析后参数、端口形状、连线、参数量
tensorcad_search_catalog	查询区块目录，包括参数模式、端口模式和文档
tensorcad_apply_ops	使用乐观并发控制批量编辑
tensorcad_validate	检查所有设计规则，并为每项发现提供修复提示
tensorcad_analyze	分析参数量、FLOPs、KV 缓存、内存、吞吐量、成本、Chinchilla
tensorcad_generate_code	生成 PyTorch 模块和配置，可内联返回或写入目录
tensorcad_checkpoint	创建命名快照
tensorcad_restore	恢复到检查点，或撤销上一个批次
tensorcad_explain	解释单个区块的作用，以及其尺寸的由来
tensorcad_scale	按比例缩小设计以满足参数预算，同时保持设计比例
tensorcad_plan	列出在集群上拆分训练的所有方式，并指出哪些方式可行
tensorcad_diff	对比两个设计在结构和数值上的变化
tensorcad_import_hf	将 Hugging Face config.json 读入设计

五个能回答其他工具无法回答的问题

analyze 会说明设计的成本，但不会说明原因。explain 只需针对一条路径，就能回答这个问题——参数的书写值和计算值、每个端口的形状，以及模型权重和计算量的占比——无需 Agent 阅读整份文档来推断。

diff 是编辑的另一半。刚应用了四项操作的 Agent 可以询问这些操作相对于初始设计在结构和数值上造成了哪些变化。plan 回答决定这一切是否有意义的问题：该设计能否在现有机器上训练，以及需要如何切分。

scale 和 import_hf 都会生成设计，而不是报告；二者也都会将设计保存到会话中，因此结果可以像其他设计一样进行分析、比较和生成。这就是存储区新增 adopt 的原因：create 会根据预设或从零构建设计，而这两个工具会导入完整设计。

句柄，而非会话

tensorcad_new_design 和 tensorcad_open_design 会生成 design_id；其他所有工具都将其作为参数。这正是 2026-07-28 版修订所要求的——跨调用状态通过显式句柄传递，而非作为连接状态——这意味着客户端可以在对话过程中重启服务端，而不会丢失当前所指设计的信息。

每个设计都有一个 revision，每次更改都会递增。向 tensorcad_apply_ops 传入 expected_revision，并发编辑就会触发明确错误，指出当前版本，而不是悄无声息地覆盖更改。

一个补丁工具，而非三十个设置器

tensorcad_apply_ops 接收操作列表，并按顺序将其应用于副本。第一项被拒绝的操作会中止整个批次，设计保持原样，因此绝不会出现只应用了一半的编辑。

操作	字段
add_node	parent?、id、type、params?、label?
remove_node	path（其边也会一并删除）
set_param	path、key、value
connect	graph?、from、to
disconnect	graph?、from、to
set_symbol	name、value（数字、表达式，或用 null 删除）、doc?、runtime?
rename	path、id（边也会随之改写）
set_label	path、label

path 用斜杠分隔（layers/block），端点格式为 blockId:port，且仅在各自的图中有效。大多数设计都由符号参数化——L 层、D 宽度、H 头数、Hkv 键值头数、dh 头维度、F 前馈宽度、V 词表大小——因此通常应使用 set_symbol 编辑，而不是逐个修改模块。

资源

URI	内容
tensorcad://designs/{id}	文档及其大纲
tensorcad://designs/{id}/validation	所有检查结果
tensorcad://designs/{id}/analysis	按文档自身默认值计算的所有数值
tensorcad://catalog	所有模块类型及其参数模式和端口模式
tensorcad://catalog/{type}	单个模块类型
tensorcad://schema/design	.tensorcad.json 格式的 JSON Schema

模板化资源支持参数补全；设计和目录模板会列出各自的实例，因此客户端无需猜测 ID 即可提供这些资源。

提示词

design_model（目标参数量、上下文长度、模型系列）、review_design、scale_design、explain_costs。

典型会话

tensorcad_new_design { preset: "llama-3-8b" }        -> dsn_1, revision 1
tensorcad_get_design { design_id: "dsn_1" }          -> the outline: symbols, blocks, edge shapes
tensorcad_checkpoint { design_id: "dsn_1" }          -> ckpt_1
tensorcad_apply_ops  { design_id: "dsn_1", expected_revision: 1,
                    ops: [{ op: "set_symbol", name: "D", value: 5120 },
                          { op: "set_symbol", name: "L", value: 40 }] }
                                                  -> revision 2, parameters and a validation summary
tensorcad_validate   { design_id: "dsn_1" }          -> findings with fix hints
tensorcad_analyze    { design_id: "dsn_1", T: 8192, hardware: "h100-sxm", gpus: 8, zero: 3 }
tensorcad_generate_code { design_id: "dsn_1", out_dir: "out/my-model" }
tensorcad_restore    { design_id: "dsn_1", checkpoint_id: "ckpt_1" }   # if it did not work out

实时编辑器桥接

使用 TENSORCAD_BRIDGE=1 启动服务，运行中的 TensorCAD 编辑器便会连接到它。Agent 的编辑会实时显示在画布上，人的编辑也会反向传回。

TENSORCAD_BRIDGE=1 bun run packages/mcp/src/stdio.ts

然后打开编辑器（bun run --cwd packages/ui dev，或桌面版）。状态栏最右侧的单元格会显示 agent，按下即可断开连接。

具体流程如下：编辑器找到桥接，将屏幕上的设计发布出来——这样 Agent 操作的就是这个设计，而不是一个与之相似的文件——随后 Agent 会在 tensorcad_list_designs 中看到它。从此以后，tensorcad_apply_ops 的操作会落到画布上，而人的操作会进入 Agent 的存储区；此时，客户端会通过 notifications/resources/updated 收到设计资源已更改的通知。来自 Agent 的编辑会进入编辑器的撤销栈，方便旁观的人撤销。

这里没有第二份文档。早期设计是在 FileStore 旁边放一个 LiveStore，两者都置于 DocumentStore 后面；这样一来，同一个设计就有两个存放位置，而且两者不一致时也没有规则来判断哪个才是正确的。桥接会观察工具已有的那个存储区，而编辑器的编辑也会通过与工具调用相同的 apply 进行——使用相同的修订版本检查和撤销日志。

默认关闭，需主动启用。 不设置环境变量时，服务不会打开任何端口，完全保持无头运行，这样才能在 CI 中使用。

连接权限。 服务绑定到 127.0.0.1，因此机器外部无法访问。若 Origin 不是本地主机来源，服务就会拒绝升级连接，因为同源策略并不能阻止互联网网页通过 WebSocket 连接到你的回环地址。服务还要求提供令牌。令牌以仅所有者可读的权限写入 ~/.tensorcad/session.json，并通过 GET /session 提供给回环地址的调用者——浏览器无法读取该文件，这也是此端点存在的唯一原因。当前机器上任何以你的身份运行的程序都能读取该文件；令牌并不能防范这种情况，也无意于此。

TENSORCAD_BRIDGE_PORT 可将端口从 7357 改为其他值。编辑器会探测该端口及其上方的三个端口；桥接在端口被占用时也会依次尝试这个范围内的端口。

有意不包含的还有：tensorcad_render_preview（画布图像需要编辑器）和 tensorcad_run_script（这是一个脚本逃生通道；只有在提供沙箱和选择性启用的环境变量后，才值得发布）。研究笔记中将两者列为未来的工具；暂不加入，可让工具数量保持在客户端易于处理的范围内。

发布

与本 README 同目录的 server.json 是 MCP 注册表清单： 其中包含命名空间（io.github.Filip-Pajalic/tensorcad，与 package.json 中的 mcpName 一致）、其指向的 npm 包，以及服务读取的唯一环境变量。写入时会根据注册表自身的架构进行校验，每次测试运行时也会与 package.json 对照，因为会发生偏差的不是架构，而是两个文件中的版本号。

命名空间的拼写与 GitHub 账户名一致，包括大小写。注册表会按所有者账户名的大小写，为 GitHub 登录授予 io.github.<owner>/*，并区分大小写进行比对；因此，即使 GitHub 本身不区分大小写，小写命名空间也会被拒绝并返回 403（参见 registry#689）。有一项测试会确保命名空间与仓库 URL 一致。

发布工作流会发布它：npm 作业上传该清单指向的包后，registry 作业会使用工作流自身的 GitHub OIDC 令牌登录——无需密钥——并运行 mcp-publisher publish。也可以在此目录中手动发布：

mcp-publisher login github
mcp-publisher publish

开发

bun run packages/mcp/src/stdio.ts     # serve on stdio
bun test packages/mcp/test            # contract tests: spin the server up and call every tool

契约测试通过真实的 stdio 管道连接 SDK 自带的客户端，并根据每个工具公布的 outputSchema 验证其 structuredContent，确保声明的契约与实际响应始终一致。