copperflow
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
copperflow lets you design circuit boards (*.circuit.tsx files) together with a human, who edits the same files in the Studio.
Call project_status first in every task, then follow the copperflow skill: its design workflow says which tool to call at each step and what its answer looks like.
Change circuit files through these tools wherever one does the change: each call is one history entry the human can undo, and the tools enforce locks. Write code by hand only for what no tool writes.
Never change, move or remove anything marked [LOCKED]; if a summary lists lock violations, restore those parts. "Marks from the human" are instructions; follow them. Do not redo a change the human undid.
There is no tool to unlock a part or verify a library part: only the human does that.
Without the copperflow skill installed, call guide (no topic) for it, then guide { topic } for a reference it names.
When the person asks to open copperflow or to see the board, call open_studio and give them the address it returns.
A new board starts with a plan, before any circuit file: guide { topic: "planning" } (the questions to ask the person, what to look up first, the blocks and their ports, one sub-agent per block).
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_circuitsA | List the circuit files (*.circuit.tsx) in the project. |
| circuit_summaryA | Summarize a circuit: one line per part and per net, then locked parts, marks from the human and lock violations. filter "PS1" shows one sub-sheet instance; detail "full" lists every prop and trace. |
| set_propsA | Set literal props of a part (pcbX, pcbY, pcbRotation, schX, resistance, footprint, …); missing props are added. schNameAt, schValueAt and pcbNameAt are label offsets { x, y }; noConnect: "pin3,pin10" flags pins meant to stay open; supplierPartNumbers: "jlcpcb:C25804". null removes these. |
| remove_partB | Remove a part and every trace connected to it. |
| add_traceA | Schematic trace (a connection, no copper): connect two ports or nets, e.g. from ".R1 > .pin1" to "net.GND". |
| remove_traceA | Schematic trace (a connection, not copper): remove the one between two selectors (in either direction). |
| check_circuitA | Check the circuit: electrical, placement, copper and pour rules. Answers with the error and warning counts, then up to 20 findings. Run it after autoplace, after autoroute and after removing copper; fix the errors before reporting success. |
| route_trackA | Copper track (not a schematic trace): draw one of a net by hand as ONE change: corners on one layer, or from and to pads (via: corners between; none: the router finds the path or says what is in the way). It starts on the net's copper, not a locked part's pad, and touches no other net. The answer lists copper violations. For what autoroute could not route. |
| add_viaB | Place a via by hand as ONE change; its net is that of the copper under it unless given. |
| remove_copperA | Remove tracks and vias by id (from copper_summary or check_circuit) as ONE change; { id, segment } removes one segment. Locked copper is refused. |
| fillet_tracksA | Round the square corners of tracks as ONE change. A corner stays square where the arc would break clearance; the answer counts those with reasons. Locked tracks are left alone; straighten_tracks undoes it. |
| straighten_tracksA | Put back the square corners fillet_tracks rounded, as ONE change, where clearance allows. Locked tracks are left alone. |
| autoplaceA | Place parts by their connections as ONE change: every part without a position, or only some parts or one instance. Placed and locked parts stay. Run it before autoroute. With fit: true a part with no room grows the board. The answer gives wire length, board size, overlaps, parts with no room and copper a move left behind. |
| fit_boardB | Set the board as ONE change: by default a rectangle round the parts plus margin; or width and height (centred on x, y), or an outline; layers: 2 or 4 copper layers. The answer names parts left outside. |
| set_rulesA | Change rules.yaml as ONE change, merged into it: netClasses (trackWidth, clearance, via), fabrication (profile "jlcpcb-4layer", minimums, placementRotations). A bad value is refused with the reason. The answer says what it means for the board. |
| import_boardA | Set the board from a DXF or SVG drawing as ONE change: the largest closed shape is the outline, circles in it mounting holes, other shapes keepouts. Parts are not moved; the answer lists those now outside. A .kicad_pcb instead makes file a new circuit (outline, parts, nets, copper); the answer lists what did not come over. |
| import_graphicA | Place a drawing (logo, mark) from source, a project .svg/.dxf, on the board as ONE change; kept in graphics/. Centre x,y and width in mm (else board centre); width keeps aspect; fill fills closed outlines; net (copper) makes it that net's copper. Answers id, size, omissions. |
| autorouteA | Route the unrouted connections as ONE change: the whole board, or only some nets, parts or one instance (one of these). Run it after placing; parts with no position get no copper; existing copper is kept. It names each connection it could not route, with the reason: route those with route_track, or move parts and run it again. |
| unrouteA | Remove the router's copper, for some nets or all, as ONE change. Hand-drawn and locked copper stay. |
| add_pourB | Add a copper pour of a net on one layer as ONE change; it fills round other nets' copper on every build, and what it joins counts as routed. The answer gives its id and the pads it joins: check them. |
| remove_pourA | Remove a copper pour by id as ONE change. Locked pours are refused; a pour inside an instance ("PS1/copperpour:1") lives in its sheet file. |
| add_holeC | Add a non-plated mounting hole as ONE change. |
| remove_holeA | Remove a non-plated hole by id as ONE change. Locked holes are refused; a hole inside an instance ("PS1/hole:1") lives in its sheet file. |
| copper_summaryA | Summarize the copper in at most 60 lines: totals, per net (tracks, vias, unrouted), pours and holes by id, violations by rule. Call it before and after drawing copper. |
| board_summaryA | The board in about 60 lines: size, layers, courtyard use, one line per part (position, side, [LOCKED] or "not placed"), the ten longest connections, overlaps, parts off the board, pours, silkscreen texts, drawings, unrouted count. |
| renderB | A PNG of the board or one schematic page, as the person sees it; view board: the bare board as made; 3d: with parts as simple shapes, at an angle. Look after autoplace and autoroute, before asking the person. |
| project_statusA | Call this first in every task: PROJECT.md (intent, blocks, last decisions, open items), then per circuit file its counts, unplaced, unrouted, errors, warnings and last changes. |
| note_decisionB | Note a design decision in PROJECT.md as one dated line, as ONE change: each choice a later context should not undo (a part and why, a board size, what the person approved). |
| set_projectA | Rewrite sections of PROJECT.md as ONE change: intent (at most 2000 characters), blocks (an array of at most 50 { name, does, status }) and open (an array of at most 50 non-empty strings). Sections not given and Decisions stay. |
| new_circuitA | Write a whole new circuit file from a netlist in one call: parts (no positions) and nets (pin lists). Unless place is false the board is then placed (fitted when no board is given) as a second entry. A block used more than once goes in sheets, used by instances. Nothing is written if anything is wrong; the answer says what. An existing file is refused unless replace. Details: guide { topic: "writing-circuits" }. |
| describe_sheetB | Write a sheet's card: does (one line), sources, each port's type and what it carries, cases for simulate. "" or [] removes. One history entry. Limits and a good card: guide { topic: "modules" }. |
| simulateA | DC operating point of a circuit, or of a sheet beside it: set nets to volts ("open" floats), close switches, energise relay coils; answers nets, sources, parts beyond a limit, then each part. With sheet and no set it runs the sheet's cases; no time, frequency or tolerance, and chips are not modelled. |
| make_sheetA | Move parts into a new sub-sheet .sheet.tsx and put an instance of it in their place, as ONE change. Each net crossing the boundary becomes a port of that name, so the netlist stays the same. |
| edit_circuitA | Apply several edits in order as ONE change, each with one key shaped like the tool of that name (connect also takes corners). add_drawing, set_drawing, remove_drawing, add_page, rename_page, remove_page, wire_corners, rename_parts, rename_port, sheet_size, set_pour, set_hole: guide { topic: "writing-circuits" }. One refused edit writes nothing; the answer names it. |
| connect_netsA | Connect pins to named nets as ONE change, e.g. { "GND": ["R1.pin2", "C1.pin2"] }; pins already on the net are skipped. |
| list_partsA | List the parts library (parts/) with verification status. Built-in kinds (resistor, capacitor, led, pinheader, …) are not here: guide { topic: "writing-circuits" } lists them. |
| part_infoB | Show a library part's part.yaml, its footprint's pads and the verification checklist. |
| create_partA | Create a library part from a datasheet you have read: pins by number with names and types, a footprint string (sot23_5, 0402), MPN, suppliers. When no string fits, package { "file": "footprint.yaml" } with footprint_file pads copied from the datasheet land pattern (never estimated). datasheet (url, file, title) e.g. { "url": "https://example.com/ds.pdf", "title": "TJA1051 datasheet" }; pin table pages go to attach_datasheet. An existing id is refused unless replace. The part starts NOT verified: tell the human to check verification.md. |
| set_part_fieldsA | Set a library part's suppliers, mpn, manufacturer or description; pins and footprint stay. null removes one. A verified part is refused. |
| attach_datasheetA | Record the datasheet a part's pins came from (link, title, pages) in part.yaml and verification.md. The link is not fetched. |
| guideC | The copperflow skill: SKILL.md, or a reference with a topic. A text already read answers a short line unless again. Call it when the skill is not installed. |
| import_partA | Import one part by its LCSC number when the human asks: symbol, footprint and attributes from the JLCEDA/EasyEDA library into parts//. It is NOT verified: tell the human to check verification.md, and that the import is for personal, non-commercial use only (EasyEDA's terms). Never import in bulk. Needs the internet. Letter-numbered pins (BGA, many USB-C) and bottom pads are refused: use create_part. |
| place_partB | Add a part to a circuit: a library part id from list_parts or a built-in kind (guide { topic: "writing-circuits" }). |
| bomB | Bill of materials for a circuit, grouped by part, and whether the board is ready to order. |
| export_fabricationA | Write the JLCPCB fabrication files to -fab/ and a zip: Gerbers, drills, pick-and-place and BOM CSVs, pictures of the board as made and a STEP model. Call it after a clean check_circuit: a design with errors is refused. |
| export_modelA | Write the board and its parts as one 3D model file beside the circuit: a STEP file for mechanical CAD (parts as boxes) or a GLB file a 3D viewer turns (the board as made). An unfinished design is written too. |
| export_htmlA | Write the design as one HTML file beside the circuit (schematic, board, 3D, BOM, fabrication and model files inside; opens offline). Use it to hand the design to a person as one file. |
| export_packageC | Write a folder with the BOM, local datasheets and the library parts' verification status. |
| recent_changesB | List recent changes by you and the human, newest first, with undos and redos. id: what one change did; since: all after it. |
| undo_changeA | Undo one of your own changes: the newest, or the given id. A human's "Redo:" of it is theirs; you cannot undo it. |
| redo_changeA | Redo one of your own undos: the newest, or the given id (the undo's or the undone change's). A human's undo is theirs; you cannot redo it. |
| add_textA | Write text as ONE change. Without layer: a note on a schematic page (default Main) at (x, y) sheet units. With layer: board silkscreen at (x, y) mm, height default 1.5. The answer names it (G3 or silkscreentext:1) for edit_circuit set_drawing/remove_drawing. Other shapes: add_drawing. |
| open_studioA | Open the Studio, the visual editor, for the person: reuses this project's running Studio or starts one, and opens it in their browser. Call it when the person asks to open copperflow, the editor or the board, or wants to watch. Give them the address it returns, to them only. |
| save_moduleC | Copy a described sheet and its library parts to the person's shelf of modules, after they approved the board. Refused without does or with a port that has no type and no carries (describe_sheet). |
| list_modulesB | The shelf, then each library (modules named library/Name), one line a module. Look here before designing a block. |
| module_infoC | A module's card, ports, parts, sources and origin. |
| use_moduleC | Copy a module's sheet (and parts the project lacks) beside the circuit file; then add_instance. A library's sheet must be plain; its parts come as data. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| SKILL | |
| planning | |
| design-workflow | |
| copper | |
| writing-circuits | |
| parts-library | |
| design-rules | |
| editable-subset | |
| modules |
TDQS
Scored across 57 tools
There are clear but overlapping tool families: connect_nets, add_trace, route_track and edit_circuit wire_corners all relate to connections; copper_summary, board_summary, circuit_summary and project_status all summarize state; and export_fabrication, export_model, export_html and export_package all export. The descriptions do distinguish schematic trace from copper track and give hints, but with 57 tools an agent can easily pick a near-miss sibling.
Almost all tools use snake_case verb_noun or noun pairs (set_project, add_trace, remove_copper, export_fabrication), with only minor deviations such as noun-only bom, render and guide, plus new_circuit versus the usual create/import pattern. The naming is predictable enough that an agent can guess tool names reliably.
57 tools is far above a comfortable range, even for a complex PCB design domain. Several clusters could be consolidated (four export_* tools, three summary tools, multiple connection and module tools), so the count feels heavy and increases selection cost.
The surface covers a broad lifecycle: project intent, circuits, parts, placement, routing, copper, pours, holes, rules, simulation, checking, fabrication exports, modules and undo/redo. Minor gaps remain, such as no explicit circuit file deletion or rename, no library part removal, and no tool for locking a part despite lock-aware tools elsewhere.