apply_candidate
Destructive
Apply a previewed route candidate to a KiCad PCB board, replacing the file on disk. Creates an undoable pre-apply copy before making changes.
Instructions
Apply a previewed route candidate to a board, replacing the file on disk.
**This is the only tool that changes a board.** It is disabled unless the operator set
`COPPER_MCP_ALLOW_APPLY=1`, and it additionally requires an `apply_token` issued by
`preview_route` for this exact candidate, board revision and path. A model cannot enable
the flag or mint a token.
`request` takes `board`, `candidate` (the manifest from the preview), `apply_token`,
`expect_board_revision` (the board digest the caller previewed), and `constraints`.
The board must not be open in KiCad: a lockfile beside it is a hard refusal, because
pcbnew has no external-change watcher and would silently overwrite the applied board on
its next save. Before anything is written, a timestamped pre-apply copy is created beside
the board and its path is returned - **that copy is the undo**, restored by copying it
back. This is not a KiCad undo step.
Only additive route patches are applied. Nothing here applies a placement, and the applied
board carries no DRC evidence: the reported verification covers byte preservation, a
fail-closed reparse, and Board IR equality, and says `not_run` for anything involving
KiCad.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| request | Yes | ||
| board_path | Yes | ||
| diagnostic | Yes | ||
| backup_path | Yes | ||
| bytes_added | Yes | ||
| candidate_id | Yes | ||
| verification | Yes | ||
| apply_version | Yes | ||
| base_revision | Yes | ||
| segments_added | Yes | ||
| board_revision_after | Yes | ||
| board_revision_before | Yes | ||
| snapshot_digest_before | Yes | ||
| conversion_diagnostic_counts | Yes |