npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

perfboard-designer-mcp

v0.6.0

Published

MCP server for Perfboard Designer: lets AI agents look up parts, check perfboard and stripboard layouts, and hand back a link that opens the board in the editor.

Readme

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):

| Setting | Extra | Default | | --- | --- | --- | | PERFBOARD_IMAGE_URL | make_share_link's image, a picture of the board (render_board's PNGs are drawn here and need nothing) | https://mcp.perfboarddesigner.com/render.svg | | PERFBOARD_PROJECTS_URL | make_share_link's store: a short link to a stored project. Nothing is sent unless an agent asks | https://projects.perfboarddesigner.com |

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

Tools

| Tool | What it does | | --- | --- | | list_parts | Lists the parts a project can place (175 today). Without a query, every part by category, one line each (its id, name and pin count). With words such as "capacitor" or "555", the parts matching all of them, or the closest ones when none do. | | get_part | Parts in full, as many as you name in ids: which list each goes in, its pins and pin labels, polarity, value unit, holes its body covers, and an example entry to copy. | | new_project | Starts a project kept in memory and returns its projectId: a blank perfboard or stripboard of the size you give, or a copy of an example (example: "555-led-blinker"). | | edit_project | Changes a kept project with a list of ops, all or none: add_part (by part id, with at, or from/to for two-lead parts; refs are numbered if left out; or a part of the agent's own: custom, pins anywhere or a catalog part's package via shape with its own pin names, or chip, a dual-row chip or dev board, placed again later by name), update_part (move, turn, change value or ref), remove_parts, add_wire (from/to, with via for the holes it bends at, or a path of holes made into one wire per leg; any end can be a pin by name, e.g. "U1.7" or "D1.K", for the hole it's in), update_wire (ends by hole or pin too, via to replace its bends), remove_wires, set_board, add_cuts/remove_cuts, set_pad (a note on a hole), set_description (what the board is and how it works, for whoever opens it). Returns what changed, where the new or moved parts' pins landed, and the board checked as validate_project does; when it has no errors, also its nets. | | get_project | The whole project file of a kept project. | | get_pin_positions | Where every placed part's pins land on the board after rotation, e.g. U1 pin 8 (VCC) at [9, 3], so wires can be routed to the right holes. | | render_board | Draws the board as text, one cell per hole with column and row numbers: pins by part key and number (a1), holes under a body, wire ends, holes a wire runs over without joining them, strip cuts and holes with notes, then which part each key is and every wire with its net. area draws only part of the board (needed above 6000 holes). format: "png" draws a picture instead, as the editor draws it (holes 50 px apart, scaled down to fit 1000 px; area crops it), for an agent to look at. | | get_nets | Which pins the board connects: each net with its name (e.g. GND), its pins (U1.8 VCC for a chip pin, D1.K or C1.+ for a polarized lead, R1.1 otherwise) and its wires, plus pins connected to nothing, junctions (holes where three or more things join) and crossings (where a wire goes over another wire or a hole without joining it). | | validate_project | Lists every problem, with where it is: unreadable entries, unknown parts, pins off the board, two parts' pins or leads in one hole, overlapping parts, wires that connect nothing (a loose end, or no pins on their net), a wire passing over a pin without ending there, IC pins and two-lead parts' leads connected to nothing, supply rails shorted together (VCC with 5V is one rail, VCC with GND a short), LEDs, electrolytic capacitors and + and − pins in backwards or a diode conducting straight across the supply (judged by the rails: pins named like VCC, GND or 5V, battery holders' terminals and holes noted +9V), and on a stripboard, pins shorted by a strip or in a cut hole. Wires crossing are listed as notes, not problems. Pass expectNets (the netlist you meant, e.g. [["U1.8", "U1.4", "R1.1", "J1.1"], ["U1.2", "U1.6", "C1.+"]]) and every missing or extra connection is an error; for a kept project it's remembered, so edit_project and make_share_link check against it too ([] forgets it). A whole project sent here is kept, and the reply gives its projectId. | | make_share_link | Validates the project (with expectNets, given or remembered) and returns the link that opens it, and image: the address of an SVG picture of the board, drawn as the editor draws it (served by the hosted Worker, below). A project with a description also gets page: the same link opening a page to read, with the board, its description, parts and nets. It refuses a project with errors unless allowErrors is set. editorUrl points it at another copy of the editor, e.g. http://localhost:3000/app/; it defaults to PERFBOARD_EDITOR_URL. With store: true (or storeAs: "led-blinker", the id it'd like), it also stores the project (below) and returns stored: its id, a short link and its file and pictures. The self-contained link is made either way, and if storing fails, storeError says why. | | show_board | Shows the user a picture of the board right in the chat, as the editor draws it, with a button that opens it in the editor: an MCP App, for clients that show them (e.g. Claude, ChatGPT), which don't load Markdown images from links. The picture travels in the result's _meta, to the page and not to the agent; the page is the ui://perfboard/board-view.html resource. Clients without MCP Apps show nothing. | | read_share_link | Reads the project out of a link you share with the agent (z=, json= or src=, a stored project's short link too) and keeps it under a projectId, so the agent can change an existing board. |

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 | Answer | | --- | --- | | POST /projects with {"project": {…}, "id": "led-blinker", "name": "LED blinker"} (id and name optional) | {id, link, file, image, png}: the id it got, a short editor link, the file and its pictures | | GET /projects?q=blinker&limit=20 | Stored projects matching the id or name, newest first, with links and a pagination cursor | | GET /<id>.json | the project file | | GET /<id>.png, GET /<id>.svg | pictures of it |

  • Ids are lowercase letters, digits and dashes, made from the wanted id or else the name ("Mágneses kapcsoló!" → magneses-kapcsolo), at most 40 characters, ignoring case. If another board has that id, a few characters of the board's SHA-256 are added (led-blinker-08196a); storing the same board again under the same id gives the same id back. With neither, the id is the hash. Ids shorter than 3 characters or naming the server's own addresses (mcp, render, projects…) always get the hash added.
  • A stored project never changes: storing again makes a new id. It's deleted after a year unopened (every request for its file or pictures pushes that back).
  • Only valid project files are stored, as the editor reads them, up to 1 MB.
  • The short link is a p= share link (…/app/#name=LED%20blinker&p=led-blinker), which the editor opens from this storage without asking. Stored anywhere else (PERFBOARD_PROJECTS_URL), it's a src= link to the file instead, which any editor opens. Anyone with a link can read the board.
  • Each stored project is a Durable Object (StoredProjectHolder) named by its id, so two boards stored at once can't both get an id (src/stored-projects.ts, src/project-requests.ts). The stdio server stores through POST /projects.

There's no sign-in or rate limit yet: anyone can store projects.

Querying stored projects

The listing is public and requires no token. Deploy from mcp/:

npm run worker:deploy

Then query it:

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

Omit q to list all indexed projects. Search matches a literal substring of the id or name (ASCII case-insensitive). limit defaults to 20 and accepts 1–100. The response is {projects: [{id, name?, storedAt, link, file, image, png}], nextCursor}; storedAt is the original save time in Unix milliseconds. Pass nextCursor as the URL-encoded cursor query parameter with the same q to get the next page; null means there are no more results. Listings are not cached and do not extend projects' lifetimes.

The StoredProjectIndex Durable Object tracks new saves and removes expired projects. Existing projects from before this index was deployed appear when saved again or read from their storage object (an edge-cache hit does not reach storage). This is not a complete historical inventory: there was no central index before. Temporary MCP working projects are not included.

For local use, run npm run worker:dev and query http://localhost:8787/projects.

Try it locally (at http://localhost:8787/mcp):

npm run worker:dev

Publish it to your Cloudflare account (npx wrangler login once first):

npm run worker:deploy

Both build first; worker:dev serves stored projects at http://localhost:8787 too. wrangler.toml is the Worker's config: its name, its domains, the Durable Object bindings and, in [vars], PERFBOARD_EDITOR_URL for where links open and PERFBOARD_PROJECTS_URL for where stored projects are served. Then add it to a client by its address:

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

On the Workers Free plan a request gets 10 ms of CPU time, which checking a big board can run over; the Paid plan allows far more.

Publishing a release

The package is on npm as perfboard-designer-mcp, and the server is listed in the MCP Registry as com.perfboarddesigner/mcp, described by server.json: the hosted address (remotes) and the npm package (packages). The registry checks that package.json's mcpName is that name, and that you own perfboarddesigner.com, by a DNS TXT record on the apex domain holding a public key.

  1. Bump the version: npm version patch (or minor), and set the same version in server.json, both at the top and in its npm package entry.
  2. npm publish (it builds first; npm asks for 2FA). Wait until npm view perfboard-designer-mcp version shows the new version.
  3. Deploy the Worker if the server changed: npm run worker:deploy.
  4. Publish to the registry with mcp-publisher: mcp-publisher validate, then mcp-publisher login dns --domain perfboarddesigner.com --private-key "$PRIVATE_KEY" and mcp-publisher publish, run in mcp/.

The key pair is made once with OpenSSL 3, its public half added as a TXT record on perfboarddesigner.com (Cloudflare DNS); keep key.pem outside the repo:

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')"

How things connect

Wires are insulated jumpers: a wire joins only the holes at its two ends. Running over a hole doesn't connect it, and two wires crossing aren't shorted, so a crossing is fine (the editor marks it so it doesn't pass for a joint, and the 3D view arches the upper wire). A hole takes one part's pin or lead at most (a second part there is an error, as on a real board) plus any number of wire ends, and everything in a hole is joined: to connect two parts, run a wire between their pins. A jumper can lie on the solder side (side: "bottom", format version 9): it joins its end holes the same way but never crosses a top wire. On a stripboard, every hole along a strip is joined up to the next cut, and a cut hole connects to nothing. get_nets and validate_project work this out with the same code as the editor's Nets panel, so they agree with what you see there.

How it's built

src/ is the server: create-server.ts puts it together, server.ts runs it over stdio and worker.ts on Cloudflare, tools/ holds the tools by group, resources.ts the documents it serves, project-handles.ts the kept projects (and where they're stored), edit-ops.ts and edit-project.ts edit_project's ops, validate.ts the checks, guide.ts its instructions and guide, board-view/ the page show_board shows the board in (an MCP App; view.ts runs in the client's frame and speaks the few MCP Apps messages it needs itself, so the page stays a few KB). It builds on the editor's own pure code, all of it taken through editor.ts, the one file that imports from ../src/: the project file reader, share-link code, pin positions, nets (nets.ts) and wire crossings (wire-crossings.ts) in ../src/project-file/, the part definitions and part geometry in ../src/parts/, and the board renderer (../src/board-render/) for pictures of a board. That way it always agrees with the editor about the format, the parts and what's connected. The editor never imports anything from here. npm run build bundles that code and the MCP SDK into a single dist/server.js (and dist/worker.js for Cloudflare) with no runtime dependencies, and bakes in the docs and examples it serves, the part icons its pictures embed and show_board's page (board-view/view.html with view.ts bundled for the browser into it). PNG pictures also need resvg's WebAssembly, which the build copies beside them as dist/resvg.wasm (uploaded with the Worker), and fonts, since resvg can't use the system's: Noto Sans and Noto Sans Mono, cut down to the characters boards use, in fonts/ (SIL Open Font License; fonts/README.md says how to remake them).

| Command | What it does | | --- | --- | | npm run build | Bundle dist/server.js and dist/worker.js | | npm run typecheck | Type-check the server and the editor code it imports | | npm run worker:dev | Run the Cloudflare Worker locally, at http://localhost:8787/mcp | | npm run worker:deploy | Publish the Worker to Cloudflare | | npm version patch, then npm publish | Release a new version to npm (prepublishOnly builds first; npm asks for 2FA) | | npm run inspect | Open the server in the MCP Inspector to try the tools by hand |

Requirements and component identities

The shared reader supports format 8, including optional independent requirements; format 7 adds project-scoped component instanceId fields. edit_project preserves all intended nets, gives new parts fresh identities, and includes them in the requirement inventory without assigning connections. Removed required parts remain reportable by identity, even if another part reuses their reference name. A schematic field from older editors is ignored.

When requirements.validate is true, checks also compare the board with the saved requirements: missing components/pins, missing connections and unexpected joins are errors; incomplete coverage is a warning and never described as a full requirement match. Unspecified pins remain unchecked. This is independent of the existing complete-list expectNets contract, which is unchanged. The project-format resource includes the requirement types.

Deploy this shared reader with the frontend before sharing version-8 files through hosted storage. Embedded links remain usable without hosted storage.