perfboard-designer-mcp 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +48 -20
  2. package/dist/server.js +937 -716
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -15,35 +15,39 @@ truth: `get_project` returns it, and every tool also takes a whole file instead
15
15
 
16
16
  ## Setup
17
17
 
18
- Node.js 22 or newer. Build it from this repo:
19
-
20
- ```bash
21
- cd mcp
22
- npm install
23
- npm run build
24
- ```
25
-
26
- Then add it to your MCP client, using the absolute path to `dist/server.js`.
18
+ Node.js 22 or newer. It's on npm as
19
+ [`perfboard-designer-mcp`](https://www.npmjs.com/package/perfboard-designer-mcp), which `npx`
20
+ downloads the first time.
27
21
 
28
22
  **Claude Code:**
29
23
 
30
24
  ```bash
31
- claude mcp add perfboard -- node /path/to/perfboard-designer/mcp/dist/server.js
25
+ claude mcp add --scope user perfboard -- npx -y perfboard-designer-mcp
32
26
  ```
33
27
 
34
- **Claude Desktop** (`claude_desktop_config.json`) and other clients that take a command:
28
+ **Claude Desktop** (`claude_desktop_config.json`, Settings → Developer → Edit Config) and other
29
+ clients that take a command:
35
30
 
36
31
  ```json
37
32
  {
38
33
  "mcpServers": {
39
34
  "perfboard": {
40
- "command": "node",
41
- "args": ["/path/to/perfboard-designer/mcp/dist/server.js"]
35
+ "command": "npx",
36
+ "args": ["-y", "perfboard-designer-mcp"]
42
37
  }
43
38
  }
44
39
  }
45
40
  ```
46
41
 
42
+ To run it from this repo instead, build it and use `node /path/to/perfboard-designer/mcp/dist/server.js`
43
+ as the command:
44
+
45
+ ```bash
46
+ cd mcp
47
+ npm install
48
+ npm run build
49
+ ```
50
+
47
51
  Links open the public editor, https://perfboarddesigner.com/app/. To point them at another copy (a
48
52
  local dev server, say), set `PERFBOARD_EDITOR_URL` in the server's environment:
49
53
 
@@ -51,17 +55,14 @@ local dev server, say), set `PERFBOARD_EDITOR_URL` in the server's environment:
51
55
  {
52
56
  "mcpServers": {
53
57
  "perfboard": {
54
- "command": "node",
55
- "args": ["/path/to/perfboard-designer/mcp/dist/server.js"],
58
+ "command": "npx",
59
+ "args": ["-y", "perfboard-designer-mcp"],
56
60
  "env": {"PERFBOARD_EDITOR_URL": "http://localhost:3000/app/"}
57
61
  }
58
62
  }
59
63
  }
60
64
  ```
61
65
 
62
- Once the package is published to npm, `npx -y perfboard-designer-mcp` replaces
63
- `node /path/.../server.js` in both.
64
-
65
66
  The server works on its own, without the [hosted Worker](#hosting-it-on-cloudflare-workers). It
66
67
  only points at it for two extras, each set in the server's environment like `PERFBOARD_EDITOR_URL`,
67
68
  public unless set, and `off` to do without (agents are then not offered it):
@@ -80,10 +81,10 @@ Point them at a local Worker with `http://localhost:8787/render.svg` and `http:/
80
81
  | `list_parts` | Lists the parts a project can place (79 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. |
81
82
  | `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. |
82
83
  | `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"`). |
83
- | `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), `update_part` (move, turn, change value or ref), `remove_parts`, `add_wire` (`from`/`to`, 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), `remove_wires`, `set_board`, `add_cuts`/`remove_cuts`, `set_pad`. 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. |
84
+ | `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), `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). 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. |
84
85
  | `get_project` | The whole project file of a kept project. |
85
86
  | `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. |
86
- | `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 marked holes, 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. |
87
+ | `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. |
87
88
  | `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). |
88
89
  | `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, 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`. |
89
90
  | `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). 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. |
@@ -199,6 +200,32 @@ claude mcp add --transport http perfboard https://perfboard-designer-mcp.<your-s
199
200
  On the Workers Free plan a request gets 10 ms of CPU time, which checking a big board can run
200
201
  over; the Paid plan allows far more.
201
202
 
203
+ ## Publishing a release
204
+
205
+ The package is on npm as `perfboard-designer-mcp`, and the server is listed in the
206
+ [MCP Registry](https://registry.modelcontextprotocol.io) as `com.perfboarddesigner/mcp`, described
207
+ by `server.json`: the hosted address (`remotes`) and the npm package (`packages`). The registry
208
+ checks that `package.json`'s `mcpName` is that name, and that you own `perfboarddesigner.com`, by a
209
+ DNS TXT record on the apex domain holding a public key.
210
+
211
+ 1. Bump the version: `npm version patch` (or `minor`), and set the same `version` in `server.json`,
212
+ both at the top and in its npm package entry.
213
+ 2. `npm publish` (it builds first; npm asks for 2FA). Wait until `npm view perfboard-designer-mcp
214
+ version` shows the new version.
215
+ 3. Deploy the Worker if the server changed: `npm run worker:deploy`.
216
+ 4. Publish to the registry with [`mcp-publisher`](https://github.com/modelcontextprotocol/registry/releases):
217
+ `mcp-publisher validate`, then `mcp-publisher login dns --domain perfboarddesigner.com
218
+ --private-key "$PRIVATE_KEY"` and `mcp-publisher publish`, run in `mcp/`.
219
+
220
+ The key pair is made once with OpenSSL 3, its public half added as a TXT record on
221
+ `perfboarddesigner.com` (Cloudflare DNS); keep `key.pem` outside the repo:
222
+
223
+ ```bash
224
+ openssl genpkey -algorithm Ed25519 -out ~/.config/mcp-registry/key.pem
225
+ echo "v=MCPv1; k=ed25519; p=$(openssl pkey -in ~/.config/mcp-registry/key.pem -pubout -outform DER | tail -c 32 | base64)"
226
+ PRIVATE_KEY="$(openssl pkey -in ~/.config/mcp-registry/key.pem -noout -text | grep -A3 'priv:' | tail -n +2 | tr -d ' :\n')"
227
+ ```
228
+
202
229
  ## How things connect
203
230
 
204
231
  Wires are insulated jumpers: a wire joins only the holes at its two ends. Running over a hole
@@ -237,4 +264,5 @@ says how to remake them).
237
264
  | `npm run typecheck` | Type-check the server and the editor code it imports |
238
265
  | `npm run worker:dev` | Run the Cloudflare Worker locally, at http://localhost:8787/mcp |
239
266
  | `npm run worker:deploy` | Publish the Worker to Cloudflare |
267
+ | `npm version patch`, then `npm publish` | Release a new version to npm (`prepublishOnly` builds first; npm asks for 2FA) |
240
268
  | `npm run inspect` | Open the server in the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to try the tools by hand |