[Gherkin]

The agent MCP epic (#73), merged child by child into agent-mcp. Each child PR had its own /prr review.

What it adds:

• An MCP server for agents (mcp/). It runs in Docker as a second service behind /mcp, or locally over stdio against a static site.
• Tools: list_boards, locate, net_places, nearest, nearest_vias, link, snapshot.
• build_boards.py writes pcbs/index.json; the board list page reads it.
• Pad names in the KiCad export, pin in the tools, and pin names in the viewer.
• A mark= link key that draws a marker.
• The viewer and MCP images are built before either is pushed.
• README sections for the MCP server, static hosting and the agent skill.
• An agent skill in skills/pcb-viewer/.

Changes for running servers:

• docker-compose.yml has a second service, pcb-mcp. Set VIEWER_URL to the address users open.
• A new image, ghcr.io/gherkin/htmlpcbviewer-mcp, about 592 MB (Chromium for snapshot).
• The first arm64 build of the MCP image runs in the publish job after this merge. It was only built for amd64 before.

Closes #73
Closes #74
Closes #75
Closes #76
Closes #77
Closes #78
Closes #79
Closes #80
Closes #81
Closes #82
Closes #83
Closes #84
Closes #87
Closes #90
Closes #96
Closes #14

🤖 Generated with Claude Code

https://claude.ai/code/session_01FzHC7LspikUyimHw5ptN8x

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-11 19:17 UTC

[Gherkin]

/prr round 1 (code-review run on the whole epic). 10 findings, each checked against the code.

To fix on agent-mcp:

1. mcp/src/pads.js:56 - boardPads merges any two pads of one footprint at the same pos when either is "th", so an SMD pad on another net at a TH pad's center is lost from net_places/nearest. Fix: merge only pads on the same net (the Allegro pair always is).
2. mcp/src/boards.js:38 - diskStore turns only ENOENT into a tool error; a folder path (EISDIR) or an unreadable file (EACCES) becomes an internal error with no hint. Fix: map those to BoardError too.
3. mcp/src/tools/locate.js:53 - own exact/lower-case refdes maps instead of footprintsByRef from footprints.js. Fix: use footprintsByRef (same results).
4. web/render.js:1065 - padLabel's comment sits on padName; padLabel has none. Fix: move it.

Need a decision (not fixed):
5. docker/index.html:121 - once pcbs/index.json exists, the board list (and list_boards) ignores the directory listing. A board copied into pcbs/ by hand, as worked before, does not show until build_boards.py runs again. Matches #74 ("instead of the nginx listing") and README:59 says so, but it changes things for existing Docker users.
6. build_boards.py:76 - write_index json.loads every board payload on every run, also when all were skipped, only for metadata.title. An incremental run over many large boards is no longer near-instant.

FYI (not fixing):
7. web/app.js:995 - "Pin" header over list places on unnamed boards. User decision on #96; no change.
8. mcp/src/browser.js:143 - any uncaught page error ends a snapshot. Deliberate (fast fail on a board that does not load); no known harmless error in the viewer.
9. mcp/src/boards.js:28 - diskStore re-reads and parses the board on every call; no cache. Perf only, the cost is a cache design choice.
10. mcp/src/tools/snapshot.js:73 - url mode parses the board only to check it exists. Same cause as 9.

[Gherkin]

Decisions on the round 1 findings (user):

• Finding 5, boards copied in by hand: keep as is. The README says to run build_boards.py.
• Finding 6, build time: build_boards.py reuses the title from the existing index.json for boards whose output file did not change, and loads only boards that were built or are missing from the old index.
• Merge into main: squash.

[Gherkin]

/prr round 2 (code-review run on e1bf597 and 1448b4b, the commits after the round 1 comment).

Fixed: finding 6 in 1448b4b, as decided. build_boards.py reuses the title from the old index.json for boards skipped as up to date. Built boards, boards missing from the old index, and files not from the source are still read. A missing or unreadable old index falls back to reading every payload. Tests in tests/browser/board-index.spec.js: skipped board keeps its title with a payload that is no JSON (fails on the old code), rebuilt board gets its new title, corrupt old index falls back.

Review findings, all checked against the code. None fixed:

1. build_boards.py:127 - a payload rewritten outside build_boards.py (newer than its source) is skipped, so the index keeps the old title, and a broken payload stays listed. This follows from the approved rule (reuse for skipped boards). A guard "reuse only if the payload is older than the old index.json" would close it; that is a new choice, so not made here.
2. mcp/src/pads.js:56 - a same-net SMD pad and TH pad at one center in one KiCad footprint (e.g. EP plus a thermal pin named differently) still merge, and the SMD pad name is lost. Edge case; tightening to the exact Allegro shape is a new choice.
3. mcp/src/pads.js:56 - a pair with net "" on one pad and no net on the other is not merged. generate.py writes both the same way; speculative.
4. mcp/src/boards.js:38 - ENAMETOOLONG and ELOOP still come out as internal errors, not tool errors. Minor.
5. mcp/src/tools/locate.js:58 - footprintsByRef scans all footprints per ref. Cost is small for real boards; this was the round 1 fix as asked.
6. build_boards.py:121 - path normalization for the skipped set is done in main and in write_index. Minor duplication.
7. tests/browser/board-index.spec.js:120 - future mtimes in the rebuilt-title test. The finally block restores and backdates the source, so later tests are not affected.

CI green on 1448b4b. Merging by squash, as decided.