Perfboard Designer

Perfboard Designer MCP server

An MCP server that lets an AI agent (Claude, or any MCP client) design perfboard and stripboard layouts for Perfboard Designer. The agent looks up parts, writes the board as a project file, checks it, and gives you a share link. Clicking the link opens the board in the editor, where you can look at it and change it.

"Lay out a 555 LED blinker on a small perfboard and send me the link."

It runs on your computer (stdio), needs no account and saves nothing to disk; or it can be hosted on Cloudflare Workers (below). While it runs it keeps the projects an agent is working on in memory, each under a projectId, so the agent sends a project at most once and then changes it with small edits. The project file stays the source of truth: get_project returns it, and every tool also takes a whole file instead of an id.

Setup

Node.js 22 or newer. It's on npm as perfboard-designer-mcp, which npx downloads the first time.

Claude Code:

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

Claude Desktop (claude_desktop_config.json, Settings → Developer → Edit Config) and other clients that take a command:

{

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

To run it from this repo instead, build it and use node /path/to/perfboard-designer/mcp/dist/server.js as the command:

cd mcp

npm install npm run build

Links open the public editor, https://perfboarddesigner.com/app/. To point them at another copy (a local dev server, say), set PERFBOARD_EDITOR_URL in the server's environment:

{

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

The server works on its own, without the hosted Worker. It only points at it for two extras, each set in the server's environment like PERFBOARD_EDITOR_URL, public unless set, and off to do without (agents are then not offered it):

Point them at a local Worker with http://localhost:8787/render.svg and http://localhost:8787.

Tools

Every tool that reads a project takes either projectId or the whole file as project. Kept projects last as long as the server process (the 200 most recently used); on Cloudflare, 30 days after they were last used.

Its instructions to agents are kept short (clients cut them off at about 2 KB); the full guide is the resource perfboard://docs/guide (src/guide.ts).

It also serves the format as resources: perfboard://docs/project-file (the project file format, field by field), perfboard://docs/share-links (the link format), perfboard://parts (the whole parts catalog as JSON), and example projects: perfboard://examples/555-led-blinker (a 555 LED blinker on a perfboard, all wired with jumpers) and perfboard://examples/555-led-blinker-stripboard (the same circuit on a stripboard), read from ../examples/.

Hosting it on Cloudflare Workers

The public copy runs at https://mcp.perfboarddesigner.com/mcp; how to add it to Claude Code, claude.ai, ChatGPT, Cursor and other clients is on https://perfboarddesigner.com/mcp-server/ (../mcp-server/index.html).

The same server also runs as a Cloudflare Worker, so an MCP client can reach it over the web with nothing installed: Streamable HTTP at /mcp (src/worker.ts). It's stateless, every request getting a fresh server, so kept projects can't live in memory: each is kept in its own Durable Object (ProjectHolder), named by its projectId, and forgotten after 30 days unused. Project ids are random, so they can't be guessed. There's no sign-in: anyone with the address can use it.

It also draws boards: /render.svg? followed by a share link's part after the # (name=…&z=… or json=…; src= links aren't fetched) answers with an SVG picture of that board, drawn by the editor's own board renderer (../src/board-render/) with the part icons baked in. /render.png? with the same parameters answers with a PNG of it instead, for places that don't show SVG, such as chat apps and link previews. An address says everything in its picture, so it's cached for good (src/image-requests.ts).

The PNGs, from /render.png and render_board, are drawn from the same SVG by resvg, compiled to WebAssembly (@resvg/resvg-wasm, MPL-2.0), so they come out the same from the Worker and from stdio (src/board-png.ts). Drawing one takes around a tenth of a second of CPU for a small board, far more than the Workers Free plan's 10 ms a request, so the hosted server needs a paid plan to draw them.

So pictures aren't drawn again for every request, each Cloudflare data center keeps a copy of every picture and stored project file it serves (the Workers Cache API), for as long as its Cache-Control says: a year for /render.*, a day for stored projects. Repeat requests there are answered from it (CF-Cache-Status: HIT) without drawing again or waking the stored project's Durable Object (edgeCached() in src/worker.ts). Only answers that worked are kept, so an unknown id is looked up again next time. After a change to how boards are drawn, old pictures stay until they expire or the zone's cache is purged in the Cloudflare dashboard. The cache does nothing on the workers.dev address, only on the custom domains.

Stored projects

A share link carries the whole project, so it works without any server, but it gets long. The Worker can also store a project under a short id and serve it, at https://projects.perfboarddesigner.com (the same Worker, at its own address so the storage could move to a Worker of its own without breaking links). It's the project storage behind short links, for agents (make_share_link with store) and for people (the editor's Share dialog), documented for both in docs/share-links.md:

| Request |