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.
- package/README.md +48 -20
- package/dist/server.js +937 -716
- 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.
|
|
19
|
-
|
|
20
|
-
|
|
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 --
|
|
25
|
+
claude mcp add --scope user perfboard -- npx -y perfboard-designer-mcp
|
|
32
26
|
```
|
|
33
27
|
|
|
34
|
-
**Claude Desktop** (`claude_desktop_config.json
|
|
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": "
|
|
41
|
-
"args": ["
|
|
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": "
|
|
55
|
-
"args": ["
|
|
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
|
|
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
|
|
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 |
|