Perfboard Designer

Perfboard Designer MCP 服务

一个 MCP 服务，让 AI Agent（Claude 或任何 MCP 客户端）能够为 Perfboard Designer 设计洞洞板和条形板布局。Agent 会查找元件、将电路板写入项目文件、检查文件，并提供一个分享链接。点击链接即可在编辑器中打开电路板，查看并修改它。

“在一块小洞洞板上布置一个 555 LED 闪烁电路，并把链接发给我。”

它在你的电脑上运行（stdio），无需账号，也不会将任何内容保存到磁盘；也可以托管在 Cloudflare Workers 上（下文）。运行期间，它会将 Agent 正在处理的项目保存在内存中，每个项目对应一个 projectId，这样 Agent 只需发送一次项目，之后再通过小幅修改来更新。项目文件始终是事实来源：get_project 会返回该文件，每个工具也都接收完整文件，而不是 ID。

设置

需要 Node.js 22 或更高版本。它发布在 npm 上，名为 perfboard-designer-mcp，npx 会在首次运行时下载它。

Claude Code：

claude mcp add --scope user perfboard -- npx -y perfboard-designer-mcp

Claude Desktop（claude_desktop_config.json，Settings → Developer → Edit Config）以及其他接收命令的客户端：

{
  "mcpServers": {
    "perfboard": {
      "command": "npx",
      "args": ["-y", "perfboard-designer-mcp"]
    }
  }
}

如需从此仓库运行，请先构建，然后将 node /path/to/perfboard-designer/mcp/dist/server.js 设为命令：

cd mcp
npm install
npm run build

链接会打开公共编辑器 https://perfboarddesigner.com/app/。如需将链接指向其他副本（例如本地开发服务器），请在服务的环境中设置 PERFBOARD_EDITOR_URL：

{
  "mcpServers": {
    "perfboard": {
      "command": "npx",
      "args": ["-y", "perfboard-designer-mcp"],
      "env": {"PERFBOARD_EDITOR_URL": "http://localhost:3000/app/"}
    }
  }
}

该服务无需托管的 Worker即可独立运行。只有两项附加功能会指向它们；在服务环境中设置这些功能的方式与 PERFBOARD_EDITOR_URL 类似。默认公开；若设为 off，则不使用该功能（Agent 不会看到此选项）：

设置	附加功能	默认值
PERFBOARD_IMAGE_URL	make_share_link 的 image，即电路板图片（render_board 的 PNG 会在此处绘制，无需此项）	https://mcp.perfboarddesigner.com/render.svg
PERFBOARD_PROJECTS_URL	make_share_link 的 store：指向已存储项目的短链接。只有 Agent 请求时才会发送内容	https://projects.perfboarddesigner.com

将它们指向本地 Worker，分别使用 http://localhost:8787/render.svg 和 http://localhost:8787。

工具

工具	功能
list_parts	列出项目可放置的元件（目前有 79 种）。不带查询词时，按类别逐行列出所有元件（包括其 ID、名称和引脚数）。输入 "capacitor" 或 "555" 等词时，列出匹配所有词的元件；如果没有完全匹配，则列出最接近的元件。
get_part	按 ids 中指定的名称，完整列出多个元件的信息：每个元件所属的列表、引脚及引脚标签、极性、数值单位、元件本体覆盖的孔位，以及可供复制的示例条目。
new_project	在内存中创建一个项目并返回其 projectId：可创建指定尺寸的空白实验板或条形板，也可复制示例（example: "555-led-blinker"）。
edit_project	通过一组操作修改内存中保存的项目，操作要么全部生效，要么全部不生效：add_part（按元件 ID 添加，并指定 at；对于双引脚元件，可指定 from/to；如果未指定，参考编号会自动编号；也可以添加 Agent 自定义的元件：custom，引脚可位于任意位置；或使用目录元件封装，通过 shape 指定其自定义引脚名称；还可以添加 chip，即双排引脚芯片或开发板，之后可按名称再次放置）、update_part（移动、旋转、更改数值或参考编号）、remove_parts、add_wire（指定 from/to；可用 via 指定弯折经过的孔位，或用 path 指定一串孔位，每段路径都会成为一根导线；任一端也可以按名称指定引脚，例如 "U1.7" 或 "D1.K"，表示该引脚所在的孔位）、update_wire（端点也可按孔位或引脚指定；用 via 替换弯折路径）、remove_wires、set_board、add_cuts/remove_cuts、set_pad（为孔位添加备注）。返回变更内容、新添加或移动的元件引脚所在位置，以及像 validate_project 一样检查过的电路板；如果没有错误，还会返回网络信息。
get_project	返回内存中保存项目的完整文件。
get_pin_positions	返回放置的每个元件旋转后的引脚在电路板上的位置，例如 U1 pin 8 (VCC) at [9, 3]，方便将导线布线到正确的孔位。
render_board	以文本绘制电路板，每个孔位占一格，并标注列号和行号：引脚按元件标识和编号显示（a1）；本体下方的孔位、导线端点、导线经过但未连接的孔位、条形板切口和带备注的孔位；然后列出每个标识对应的元件，以及带有网络信息的所有导线。area 仅绘制电路板的一部分（孔位超过 6000 个时需要使用）。format: "png" 则绘制图片，效果与编辑器中的绘图相同（孔间距为 50 px，并缩小至 1000 px 以内；area 会裁剪图片），供 Agent 查看。
get_nets	返回电路板上彼此连接的引脚：列出每个网络及其名称（例如 GND）、引脚（芯片引脚为 U1.8 VCC，有极性的双引脚元件为 D1.K 或 C1.+，其他元件为 R1.1）和导线；此外还会列出未连接的引脚、接点（三个或更多对象相连的孔位）和交叉处（导线跨过另一根导线或孔位但未与其相连）。
validate_project	列出所有问题及其位置：无法读取的条目、未知元件、位于电路板外的引脚、两个元件的引脚或导线端点占用同一孔位、元件重叠、未连接任何对象的导线（端点悬空，或其网络上没有引脚）、导线经过引脚但未终止于该处、未连接任何对象的 IC 引脚和双引脚元件端点、电源轨短路（VCC 和 5V 属于同一条电源轨，VCC 和 GND 短路）、LED、电解电容和 +、− 引脚反接，或二极管直接跨接电源导致电流直通（根据电源轨判断：名称类似 VCC、GND 或 5V 的引脚、电池座端子，以及标注为 +9V 的孔位）；对于条形板，还会检查引脚是否因导电条或切口处的孔位而短路。导线交叉会作为备注列出，不算问题。传入 expectNets（预期的网表，例如 [["U1.8", "U1.4", "R1.1", "J1.1"], ["U1.2", "U1.6", "C1.+"]]）后，任何缺失或多余的连接都会报错；对于内存中保存的项目，此设置会被记住，因此 edit_project 和 make_share_link 也会据此检查（传入 [] 可清除设置）。发送至此的完整项目会被保存，回复中会提供其 projectId。
make_share_link	检查项目（依据传入或已记住的 expectNets），并返回可打开该项目的链接，以及 image：电路板 SVG 图片的地址，图片由下文提到的托管 Worker 按编辑器的绘图方式生成。除非设置 allowErrors，否则有错误的项目无法生成链接。editorUrl 可指定编辑器的另一份副本，例如 http://localhost:3000/app/；默认值为 PERFBOARD_EDITOR_URL。设置 store: true（或 storeAs: "led-blinker"，即期望使用的 ID）后，还会保存项目（见下文），并返回 stored：其中包含项目 ID、短链接以及项目文件和图片。无论是否保存，都会生成独立链接；如果保存失败，storeError 会说明原因。
show_board	在聊天中直接向用户展示电路板图片，绘图方式与编辑器相同，并附带一个可在编辑器中打开图片的按钮。这是一个 MCP App，适用于支持此类应用的客户端（例如 Claude、ChatGPT）；这些客户端不会加载链接中的 Markdown 图片。图片会随结果中的 _meta 一起发送给页面，而不会发送给 Agent；该页面是 ui://perfboard/board-view.html 资源。不支持 MCP Apps 的客户端不会显示任何内容。
read_share_link	从 Agent 收到的分享链接中读取项目（支持 z=、json= 或 src=，也支持已保存项目的短链接），并以 projectId 保存项目，以便 Agent 修改现有电路板。
每个读取项目的工具都接受 projectId 或作为 project 传入的整个文件。保留的项目会在服务器进程运行期间持续有效（最多保留最近使用的 200 个）；在 Cloudflare 上，项目在最后一次使用 30 天后过期。

给 Agent 的指令保持简短（客户端会在约 2 KB 处截断）；完整指南是资源 perfboard://docs/guide（src/guide.ts）。

它还将以下格式作为资源提供：perfboard://docs/project-file（逐字段介绍项目文件格式）、perfboard://docs/share-links（链接格式）、perfboard://parts（完整的零件目录，以 JSON 格式提供），以及示例项目：perfboard://examples/555-led-blinker（在万能板上用跳线完成所有布线的 555 LED 闪烁器）和 perfboard://examples/555-led-blinker-stripboard（同一电路在条形板上的版本）；这些项目从 ../examples/ 读取。

在 Cloudflare Workers 上托管

公开版本运行于 https://mcp.perfboarddesigner.com/mcp；关于如何将其添加到 Claude Code、 claude.ai、ChatGPT、Cursor 和其他客户端，请参阅 https://perfboarddesigner.com/mcp-server/ （../mcp-server/index.html）。

同一服务也以 Cloudflare Worker 的形式运行，因此 MCP 客户端无需安装任何内容，即可通过 Web 访问它：/mcp 上的 Streamable HTTP（src/worker.ts）。它是无状态的，每个请求都会创建一个新的服务，因此项目无法保存在内存中：每个项目都保存在各自的 Durable Object（ProjectHolder）中，以其 projectId 命名，并在闲置 30 天后删除。项目 ID 是随机生成的，无法猜测。它没有登录功能：任何拥有地址的人都可以使用。

它还会绘制电路板：/render.svg? 后接分享链接中 # 后面的部分（name=…&z=… 或 json=…；不会获取 src= 链接），并返回该电路板的 SVG 图片。图片由编辑器自己的电路板渲染器（../src/board-render/）绘制，并内嵌零件图标。对于不支持显示 SVG 的场景（例如聊天应用和链接预览），使用相同参数访问 /render.png? 可返回 PNG 图片。

图片中的所有内容都由其地址决定，因此图片会永久缓存（src/image-requests.ts）。

/render.png 和 render_board 生成的 PNG 都由同一 SVG 使用 resvg 绘制；它被编译为 WebAssembly（@resvg/resvg-wasm，MPL-2.0），因此无论通过 Worker 还是 stdio，生成的图片都相同（src/board-png.ts）。绘制一个小型电路板约需十分之一秒的 CPU 时间，远超 Workers 免费计划每个请求 10 ms 的限制，因此托管服务需要付费计划才能绘制这些图片。

为避免每次请求都重新绘制图片，每个 Cloudflare 数据中心都会缓存其提供的所有图片和存储的项目文件（使用 Workers 的 Cache API），并按照 Cache-Control 指定的时长保留：/render.* 的图片保留一年，存储的项目保留一天。后续请求会直接从缓存中返回（CF-Cache-Status: HIT），无需重新绘制，也不会唤醒存储项目的 Durable Object（src/worker.ts 中的 edgeCached()）。只有成功的响应才会缓存，因此下次仍会重新查询未知 ID。电路板绘制方式更改后，旧图片会一直保留，直到过期或在 Cloudflare 控制面板中清除该区域的缓存。缓存不适用于 workers.dev 地址，仅适用于自定义域名。

已存储的项目

分享链接包含整个项目，因此无需任何服务端即可使用，但链接会很长。Worker 也可以为项目分配一个短 ID 并提供访问服务，地址为 https://projects.perfboarddesigner.com（同一个 Worker，使用它自己的地址，这样存储服务就能迁移到独立的 Worker，而不会导致链接失效）。它是短链接背后的项目存储，供 Agent 使用（make_share_link 搭配 store）以及供用户使用（编辑器的分享对话框）。相关说明见 docs/share-links.md：

请求	响应
POST /projects，正文为 {"project": {…}, "id": "led-blinker", "name": "LED blinker"}（id 和 name 可选）	{id, link, file, image, png}：分配的 ID、编辑器短链接、文件及其图片
GET /projects?q=blinker&limit=20	匹配 ID 或名称的已存储项目，按最新优先排序，包含链接和分页游标
GET /<id>.json	项目文件
GET /<id>.png、GET /<id>.svg	项目的图片

• ID 由小写字母、数字和连字符组成，根据指定的 ID 生成；若未指定，则根据名称生成 （"Mágneses kapcsoló!" → magneses-kapcsolo），最长 40 个字符，且不区分大小写。如果另一块板已有该 ID，则会附加几位板子的 SHA-256 字符（led-blinker-08196a）； 再次以相同 ID 存储同一块板，会返回相同的 ID。如果两者都未提供，ID 就是哈希值。短于 3 个字符或与服务自身地址同名（mcp、render、projects……）的 ID，始终会附加哈希值。
• 已存储的项目永远不会更改：再次存储会生成新的 ID。项目在一年未被访问后会删除（每次请求其文件或图片都会重新计算期限）。
• 只存储有效的项目文件（即编辑器可读取的文件），大小上限为 1 MB。
• 短链接是 p= 分享链接（…/app/#name=LED%20blinker&p=led-blinker），编辑器会直接从此存储打开项目，无需询问。如果存储在其他位置（PERFBOARD_PROJECTS_URL），链接则为指向文件的 src= 链接，任何编辑器都可以打开。任何拥有链接的人都能读取该板。
• 每个已存储的项目都是一个以其 ID 命名的 Durable Object（StoredProjectHolder），因此同时存储的两块板不会获得相同的 ID（src/stored-projects.ts、src/project-requests.ts）。stdio 服务通过 POST /projects 进行存储。

目前没有登录或速率限制：任何人都可以存储项目。

查询已存储的项目

项目列表为公开内容，无需令牌。从 mcp/ 部署：

npm run worker:deploy

然后查询：

curl 'https://projects.perfboarddesigner.com/projects?q=blinker&limit=20'

省略 q 即可列出所有已索引的项目。搜索会匹配 ID 或名称中的字面子字符串（不区分 ASCII 大小写）。limit 默认为 20，接受 1–100。响应为 {projects: [{id, name?, storedAt, link, file, image, png}], nextCursor}；storedAt 是原始保存时间，以 Unix 毫秒为单位。将 nextCursor 作为经过 URL 编码的 cursor 查询参数，并使用相同的 q，即可获取下一页；null 表示没有更多结果。项目列表不会缓存，也不会延长项目的存续时间。

StoredProjectIndex Durable Object 会追踪新保存的项目并移除过期项目。在此索引部署前已存在的项目，会在再次保存或从其存储对象读取时显示（边缘缓存命中不会访问存储）。这不是完整的历史清单：此前没有中央索引。临时 MCP 工作项目不会包含在内。

如需本地使用，请运行 npm run worker:dev，然后查询 http://localhost:8787/projects。

在本地试用（地址为 http://localhost:8787/mcp）：

npm run worker:dev

将其发布到你的 Cloudflare 账户（先运行一次 npx wrangler login）：

npm run worker:deploy

两种方式都会先进行构建；worker:dev 也会在 http://localhost:8787 提供已存储的项目。wrangler.toml 是 Worker 的配置文件：包括其名称、域名、Durable Object 绑定，以及 [vars] 中用于指定链接打开位置的 PERFBOARD_EDITOR_URL 和用于指定已存储项目提供位置的 PERFBOARD_PROJECTS_URL。然后通过其地址将其添加到客户端：

claude mcp add --transport http perfboard https://perfboard-designer-mcp.<your-subdomain>.workers.dev/mcp

在 Workers Free 计划中，每个请求有 10 ms 的 CPU 时间，检查大型电路板可能会超出限制；Paid 计划允许的时间要长得多。

发布版本

该软件包以 perfboard-designer-mcp 的名称发布在 npm 上，服务在 MCP Registry 中登记为 com.perfboarddesigner/mcp，其描述文件为 server.json：其中包含托管地址（remotes）和 npm 软件包（packages）。注册表会检查 package.json 中的 mcpName 是否为该名称，并通过 apex 域名上的 DNS TXT 记录（其中保存公钥）验证你是否拥有 perfboarddesigner.com。

1. 更新版本：运行 npm version patch（或 minor），并在 server.json 中设置相同的 version，包括文件顶部和 npm 软件包条目中的版本。
2. 运行 npm publish（会先进行构建；npm 会要求进行双重身份验证）。等待 npm view perfboard-designer-mcp version 显示新版本。
3. 如果服务有变更，则部署 Worker：运行 npm run worker:deploy。
4. 使用 mcp-publisher 发布到注册表：先运行 mcp-publisher validate，然后运行 mcp-publisher login dns --domain perfboarddesigner.com --private-key "$PRIVATE_KEY" 和 mcp-publisher publish；这些命令需在 mcp/ 中运行。

密钥对使用 OpenSSL 3 生成一次，将公钥添加为 perfboarddesigner.com（Cloudflare DNS）上的 TXT 记录；请将 key.pem 保存在仓库之外：

openssl genpkey -algorithm Ed25519 -out ~/.config/mcp-registry/key.pem
echo "v=MCPv1; k=ed25519; p=$(openssl pkey -in ~/.config/mcp-registry/key.pem -pubout -outform DER | tail -c 32 | base64)"
PRIVATE_KEY="$(openssl pkey -in ~/.config/mcp-registry/key.pem -noout -text | grep -A3 'priv:' | tail -n +2 | tr -d ' :\n')"

各部分如何连接

导线是带绝缘层的跳线：一根导线只连接两端的孔。导线经过某个孔上方并不会连接到该孔，两根导线交叉也不会短接，因此交叉没有问题（编辑器会标记交叉，以免误认为连接点；3D 视图则会让上方的导线拱起）。一个孔最多可容纳一个元件的引脚或引线（第二个元件放入同一孔会报错，这与真实电路板相同），此外还可容纳任意数量的导线端；同一个孔中的所有部件都会连通：若要连接两个元件，请在它们的引脚之间接一根导线。跳线也可以位于焊接面（side: "bottom"，格式版本 9）：它以相同方式连接两端的孔，但绝不会与顶面的导线交叉。 在条形板上，每条导电条上的孔都会彼此连通，直至遇到断口；断口处的孔不与任何部分连接。get_nets 和 validate_project 使用与编辑器 Nets 面板相同的代码进行计算，因此结果与面板中的显示一致。

构建方式

src/ 是服务端：create-server.ts 将各部分组装起来，server.ts 通过 stdio 运行服务，worker.ts 则在 Cloudflare 上运行；tools/ 按组存放工具，resources.ts 存放它提供的文档，project-handles.ts 管理保留的项目（及其存储位置），edit-ops.ts 和 edit-project.ts 存放 edit_project 的操作，validate.ts 存放检查逻辑，guide.ts 存放其指令和指南；board-view/ 存放 show_board 展示电路板的页面（一个 MCP App；view.ts 在客户端的框架中运行，并自行处理所需的少量 MCP Apps 消息，因此页面只有几 KB）。它基于编辑器自身的纯代码构建，这些代码都通过 editor.ts 引入；这是唯一从 ../src/ 导入内容的文件：包括 ../src/project-file/ 中的项目文件读取器、分享链接代码、引脚位置、网络（nets.ts）和导线交叉（wire-crossings.ts），../src/parts/ 中的元件定义和元件几何信息，以及用于生成电路板图片的电路板渲染器（../src/board-render/）。这样，它始终与编辑器对格式、元件和连接关系的理解一致。编辑器不会从这里导入任何内容。npm run build 会将这些代码和 MCP SDK 打包到单个 dist/server.js 中（Cloudflare 还会生成 dist/worker.js），且不需要运行时依赖；同时会内嵌其提供的文档和示例、图片中嵌入的元件图标，以及 show_board 的页面（board-view/view.html，其中包含打包后供浏览器使用的 view.ts）。PNG 图片还需要 resvg 的 WebAssembly；构建会将其复制到图片旁边，保存为 dist/resvg.wasm（与 Worker 一起上传）；此外还需要字体，因为 resvg 无法使用系统字体：Noto Sans 和 Noto Sans Mono，这些字体已精简至电路板所用字符，存放在 fonts/ 中（采用 SIL Open Font License；fonts/README.md 说明了如何重新制作）。

命令	作用
npm run build	打包 dist/server.js 和 dist/worker.js
npm run typecheck	对服务端及其导入的编辑器代码进行类型检查
npm run worker:dev	在本地运行 Cloudflare Worker，地址为 http://localhost:8787/mcp
npm run worker:deploy	将 Worker 发布到 Cloudflare
npm version patch，然后运行 npm publish	发布新版本到 npm（prepublishOnly 会先执行构建；npm 会要求进行双重身份验证）
npm run inspect	在 MCP Inspector 中打开服务端，手动试用工具

要求与元件身份标识

共享读取器支持格式 8，其中包含可选的独立 requirements；格式 7 为项目级元件添加了 instanceId 字段。edit_project 会保留所有预期网络，为新元件分配新的身份标识，并将其纳入要求清单，但不分配连接。即使其他元件重复使用了已移除的必需元件的位号，仍可通过身份标识报告该元件。旧版编辑器中的 schematic 字段会被忽略。

当 requirements.validate 为 true 时，检查还会将电路板与已保存的要求进行比对：缺少元件/引脚、缺少连接和意外连接都会报错；覆盖不完整则会产生警告，且绝不会被描述为完全符合要求。未指定的引脚不会检查。这与现有的完整列表 expectNets 约定相互独立，后者保持不变。项目格式资源包含要求类型。

通过托管存储分享格式 8 文件之前，请先将此共享读取器与前端一同部署。嵌入式链接无需托管存储即可使用。