perfboard-designer-mcp 0.1.1 → 0.3.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 -2
  2. package/dist/server.js +1749 -1063
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -81,10 +81,10 @@ Point them at a local Worker with `http://localhost:8787/render.svg` and `http:/
81
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. |
82
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. |
83
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"`). |
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`, 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. |
85
85
  | `get_project` | The whole project file of a kept project. |
86
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. |
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 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. |
88
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). |
89
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`. |
90
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. |
@@ -153,6 +153,7 @@ for both in [`docs/share-links.md`](../docs/share-links.md):
153
153
  | Request | Answer |
154
154
  | --- | --- |
155
155
  | `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 |
156
+ | `GET /projects?q=blinker&limit=20` | Stored projects matching the id or name, newest first, with links and a pagination cursor |
156
157
  | `GET /<id>.json` | the project file |
157
158
  | `GET /<id>.png`, `GET /<id>.svg` | pictures of it |
158
159
 
@@ -175,6 +176,34 @@ for both in [`docs/share-links.md`](../docs/share-links.md):
175
176
 
176
177
  There's no sign-in or rate limit yet: anyone can store projects.
177
178
 
179
+ #### Querying stored projects
180
+
181
+ The listing is public and requires no token. Deploy from `mcp/`:
182
+
183
+ ```bash
184
+ npm run worker:deploy
185
+ ```
186
+
187
+ Then query it:
188
+
189
+ ```bash
190
+ curl 'https://projects.perfboarddesigner.com/projects?q=blinker&limit=20'
191
+ ```
192
+
193
+ Omit `q` to list all indexed projects. Search matches a literal substring of the id or name
194
+ (ASCII case-insensitive). `limit` defaults to 20 and accepts 1–100. The response is
195
+ `{projects: [{id, name?, storedAt, link, file, image, png}], nextCursor}`; `storedAt` is the
196
+ original save time in Unix milliseconds. Pass `nextCursor` as the URL-encoded `cursor` query
197
+ parameter with the same `q` to get the next page; `null` means there are no more results.
198
+ Listings are not cached and do not extend projects' lifetimes.
199
+
200
+ The `StoredProjectIndex` Durable Object tracks new saves and removes expired projects. Existing
201
+ projects from before this index was deployed appear when saved again or read from their storage
202
+ object (an edge-cache hit does not reach storage). This is not a complete historical inventory:
203
+ there was no central index before. Temporary MCP working projects are not included.
204
+
205
+ For local use, run `npm run worker:dev` and query `http://localhost:8787/projects`.
206
+
178
207
  Try it locally (at http://localhost:8787/mcp):
179
208
 
180
209
  ```bash
@@ -266,3 +295,20 @@ says how to remake them).
266
295
  | `npm run worker:deploy` | Publish the Worker to Cloudflare |
267
296
  | `npm version patch`, then `npm publish` | Release a new version to npm (`prepublishOnly` builds first; npm asks for 2FA) |
268
297
  | `npm run inspect` | Open the server in the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to try the tools by hand |
298
+
299
+ ### Requirements and component identities
300
+
301
+ The shared reader supports format 8, including optional independent `requirements`; format 7
302
+ adds project-scoped component `instanceId` fields. `edit_project` preserves all intended nets,
303
+ gives new parts fresh identities, and includes them in the requirement inventory without
304
+ assigning connections. Removed required parts remain reportable by identity, even if another
305
+ part reuses their reference name. A `schematic` field from older editors is ignored.
306
+
307
+ When `requirements.validate` is true, checks also compare the board with the saved requirements:
308
+ missing components/pins, missing connections and unexpected joins are errors; incomplete coverage
309
+ is a warning and never described as a full requirement match. Unspecified pins remain unchecked.
310
+ This is independent of the existing complete-list `expectNets` contract, which is unchanged.
311
+ The project-format resource includes the requirement types.
312
+
313
+ Deploy this shared reader with the frontend before sharing version-8 files through hosted
314
+ storage. Embedded links remain usable without hosted storage.