EasyEDA MCP Scaffold

Quick Start

This document describes the MCP server and EasyEDA bridge in detail. If you want to set it up and use it quickly, start here.

What You Need

• Node.js >= 20.17.0
• npm
• EasyEDA Pro / JLCEDA Pro
• This repository cloned locally

1. Install Dependencies

From the repository root:

npm install

2. Build the EasyEDA Bridge Extension

npm run build

This creates the installable EasyEDA extension package under ./build/dist/.

3. Install the Extension in EasyEDA Pro

Install the generated package from ./build/dist/ into EasyEDA Pro.

After installation, the EasyEDA top menu exposes EasyEDA MCP Bridge with:

• Reconnect
• Status

If EasyEDA prompts for external interaction permission, allow it so the bridge can connect back to the local MCP server.

4. Start the Local MCP Server

Run this from the repository root:

npm run mcp:server

By default this starts:

• the MCP stdio server for your AI client
• the EasyEDA bridge WebSocket at ws://127.0.0.1:19732/easyeda-mcp
• the local HTTP attach endpoint at http://127.0.0.1:19733/mcp

npm run mcp:server already exposes the HTTP attach endpoint above. If you want to run the bridge services without the stdio transport, use:

npm run mcp:server:daemon

5. Configure Your MCP Client

VS Code or another stdio-based MCP client:

{
   "servers": {
      "easyeda-mcp": {
         "type": "stdio",
         "command": "npm",
         "args": ["run", "mcp:server"],
         "cwd": "/path/to/EasyEDA-MCP"
      }
   }
}

Claude Desktop example:

{
   "mcpServers": {
      "easyeda-mcp": {
         "command": "npm",
         "args": ["run", "mcp:server"],
         "cwd": "/path/to/EasyEDA-MCP"
      }
   }
}

Ready-to-copy examples are already included in this repo:

• examples/mcp/vscode.mcp.json
• examples/mcp/claude_desktop_config.json

6. First Connection

1. Open EasyEDA Pro.
2. Make sure the EasyEDA MCP Bridge extension is installed.
3. Start the local MCP server.
4. Connect your MCP client to easyeda-mcp.
5. In EasyEDA, click EasyEDA MCP Bridge -> Reconnect.
6. Call bridge_status from your MCP client.

If the bridge is healthy, continue with get_current_context to see whether EasyEDA is currently exposing a project, schematic, or PCB document.

7. Smallest Useful Smoke Test

Use this tool order to verify the full chain end to end:

1. bridge_status
2. ping_bridge
3. get_current_context
4. list_project_objects

If bridge_status reports that the bridge is disconnected, the usual fix is to go back to EasyEDA and click Reconnect once.

8. Typical First Workflow

Once the bridge is connected, a practical first workflow is:

1. list_project_objects to inspect boards, schematics, PCBs, and panels
2. open_document to switch to the document you want to edit
3. search_library_devices to find components by keyword or LCSC part number
4. add_schematic_component or add_pcb_component to place components
5. get_capabilities or get_usage_guide if you need to adapt to host/runtime limitations

9. Troubleshooting

• Bridge not connected: In EasyEDA, use EasyEDA MCP Bridge -> Reconnect, confirm external interaction permission is enabled, then call bridge_status again.
• MCP client cannot start the server: confirm npm install has been run and use Node.js >= 20.17.0.
• Extension menu missing in EasyEDA: rebuild with npm run build and reinstall the package from ./build/dist/.
• You need attach-style testing instead of stdio: use the local endpoint at http://127.0.0.1:19733/mcp.

This repository now includes a local MCP server scaffold and a matching EasyEDA extension bridge.

The scaffold now includes three additional pieces beyond the original bridge:

• optimistic revision checks for document-source overwrite
• ready-to-copy client configuration examples
• first-pass higher-level edit tools that do not require replacing the entire document source

It now also includes:

• bridge self-test tools for round-trip health checks
• library device search for component placement flows
• component placement and editing on schematic and PCB documents
• primitive ID and bounding-box query tools for supported primitive families
• PCB net inspection and display-color editing tools
• schematic pin and PCB pad inspection plus intent-level connection helpers
• bulk schematic pin-to-net workflows and waypoint-based PCB routing
• an opt-in live MCP integration test harness for real EasyEDA bridge sessions

Components

1. src/mcp-server.ts

   Runs a local MCP server over stdio and exposes the EasyEDA MCP tool surface documented here.

2. src/easyeda-mcp-bridge.ts

   Runs inside the EasyEDA Pro extension runtime and connects back to the MCP server over WebSocket.

3. src/mcp-bridge-protocol.ts

   Shared protocol definitions for the localhost bridge.

The MCP server also exposes a local Streamable HTTP endpoint for attach-style testing at http://127.0.0.1:19733/mcp by default.

Included MCP Tools

• bridge_status
• get_usage_guide
• ping_bridge
• echo_bridge
• search_library_devices
• get_capabilities
• get_current_context
• list_project_objects
• open_document
• save_active_document
• create_board
• create_pcb
• import_schematic_to_pcb
• create_panel
• create_schematic
• create_schematic_page
• copy_board
• copy_pcb
• copy_panel
• copy_schematic
• copy_schematic_page
• add_schematic_component
• modify_schematic_component
• delete_schematic_component
• add_schematic_net_flag
• add_schematic_net_port
• add_schematic_short_circuit_flag
• list_schematic_component_pins
• set_schematic_pin_no_connect
• connect_schematic_pin_to_net
• connect_schematic_pins_to_nets
• connect_schematic_pins_with_prefix
• add_schematic_text
• add_schematic_net_label
• add_schematic_wire
• list_schematic_primitive_ids
• get_schematic_primitive
• get_schematic_primitives_bbox
• add_pcb_component
• modify_pcb_component
• delete_pcb_component
• list_pcb_component_pads
• route_pcb_line_between_component_pads
• route_pcb_lines_between_component_pads
• add_pcb_line
• add_pcb_text
• list_pcb_primitive_ids
• get_pcb_primitive
• get_pcb_primitives_bbox
• list_pcb_nets
• get_pcb_net
• set_pcb_net_color
• get_pcb_net_primitives
• modify_schematic_text
• delete_schematic_text
• modify_schematic_net_label
• modify_schematic_wire
• delete_schematic_wire
• modify_pcb_line
• delete_pcb_line
• modify_pcb_text
• delete_pcb_text
• rename_board
• rename_pcb
• rename_schematic
• rename_schematic_page
• rename_panel
• delete_board
• delete_pcb
• delete_schematic
• delete_schematic_page
• delete_panel
• get_document_source
• set_document_source
• compute_source_revision

Source Revisions

get_document_source now returns:

• source
• sourceHash
• characters

set_document_source now expects either:

• expectedSourceHash
• or force: true

It also accepts:

• skipConfirmation: true to suppress the bridge-side overwrite confirmation dialog

Recommended flow:

1. Call get_document_source.
2. Produce your edited source.
3. Call set_document_source with the returned sourceHash as expectedSourceHash.
4. If the hash mismatches, re-read the document before retrying.

The MCP tool layer now verifies set_document_source by rereading the active document after both normal responses and timeout-recovery paths. If EasyEDA reports success but the reread source hash does not match the requested source, the tool returns an error instead of a false success.

Example request payload:

{
   "source": "...updated source...",
   "expectedSourceHash": "1234:deadbeef",
   "skipConfirmation": true
}

If you need to bypass the optimistic check:

{
   "source": "...updated source...",
   "force": true,
   "skipConfirmation": true
}

Bridge Self-Test Tools

These tools are intended for bridge verification rather than CAD editing:

• bridge_status: inspect current bridge connection state from the MCP server side
• get_usage_guide: return a compact operational guide describing recommended tool order, common identifiers, and workflow sequencing
• ping_bridge: verify MCP server -> websocket bridge -> EasyEDA extension -> websocket bridge -> MCP server round-trip health
• echo_bridge: send a message through the same path and verify the returned payload

get_capabilities returns both the full bridge surface and the subset currently supported by the live EasyEDA host runtime. On host builds missing schematic net-label APIs, supportedMethods excludes the affected net-label methods and hostRuntimeUnsupportedMethods plus hostRuntimeCapabilities describe the limitation and suggested fallbacks.

bridge_status and get_current_context also include recommendedNextSteps in their structured responses so MCP clients can choose the next tool with less guesswork.

Higher-Level Edit Tools

These tools avoid whole-document source replacement for common edit cases:

• add_schematic_text: add a text primitive to the active schematic page
• add_schematic_net_label: add a net label to the active schematic page
• add_schematic_wire: add a wire primitive to the active schematic page
• add_pcb_line: add a line primitive to the active PCB document. Signal lines require a non-empty net; board outline lines on BoardOutLine may omit net or use an empty string.
• add_pcb_text: add a text primitive to the active PCB document
• save_active_document: save the active schematic page, PCB, or panel

Each edit tool accepts saveAfter: true if you want the document saved immediately after the primitive is created.

add_pcb_text requires a fontFamily that already exists in the EasyEDA Pro environment.

The same primitive families now also support targeted modification and, where the host SDK allows it, deletion.

Delete tools also accept skipConfirmation: true to suppress the bridge-side confirmation prompt before the delete request is sent to EasyEDA.

Document Lifecycle Tools

The bridge now covers the main project object lifecycle:

• create_board: create a board, optionally linking an existing schematic UUID and PCB UUID; fail if readback shows the linked schematic still advertises a different board name in its title block
• create_pcb: create a PCB, optionally under a named board
• import_schematic_to_pcb: import linked schematic changes into a PCB; fail fast when the target PCB is not coherently linked to a board-backed schematic, fall back to linked schematic page source when project inventory has a stale title block, and on hosts where pcb_Document.importChanges(...) falsely succeeds against an unchanged empty PCB, retry through the same host UI diff/apply flow that EasyEDA uses for Design -> Import Changes from Schematic before failing
• create_panel: create a panel document
• create_schematic: create a schematic, optionally under a named board
• create_schematic_page: add a new page to an existing schematic
• copy_board: duplicate a board by board name
• copy_pcb: duplicate a PCB, optionally placing the copy under a named board
• copy_panel: duplicate a panel by UUID
• copy_schematic: duplicate a schematic, optionally placing the copy under a named board
• copy_schematic_page: duplicate a schematic page, optionally into another schematic

Recommended duplication flow:

1. Call list_project_objects to find the source board, PCB, schematic, page, or panel.
2. Call the matching copy_* tool with the source identifier.
3. If needed, follow with the existing rename tools to assign final names.

Component Placement And Query Tools

The bridge now supports a fuller component and inspection workflow:

• search_library_devices: search the EasyEDA library by keyword or LCSC part number(s)
• add_schematic_component: place a searched library device onto the active schematic page
• add_pcb_component: place a searched library device onto the active PCB document, recovering the created primitive from live PCB state when some host builds throw after creation
• modify_schematic_component and modify_pcb_component: adjust placed component properties such as coordinates, rotation, designator, and metadata
• delete_schematic_component and delete_pcb_component: remove placed components with native EasyEDA confirmation dialogs; the MCP tool layer rereads PCB component inventory after delete and treats host-side no-op acknowledgements as failures instead of reporting false success
• delete_* tools: accept skipConfirmation: true to suppress the bridge-side delete prompt
• add_schematic_net_flag and add_schematic_net_port: place common net-aware schematic marker components without editing whole source text
• add_schematic_short_circuit_flag: place the EasyEDA short-circuit marker component without editing whole source text
• list_schematic_component_pins: inspect resolved symbol pins, including coordinates and pin numbers
• set_schematic_pin_no_connect: toggle a pin's explicit no-connect marker
• connect_schematic_pin_to_net: attach a named net at a chosen component pin location, preferring a net label and falling back to a short wire stub when needed
• connect_schematic_pins_to_nets: attach multiple explicit pin-to-net mappings in one request, preferring net labels and falling back to short wire stubs when needed
• connect_schematic_pins_with_prefix: derive net names like BUS_1, BUS_2, and so on from a prefix and pin numbers, preferring net labels and falling back to short wire stubs when needed
• list_schematic_primitive_ids and list_pcb_primitive_ids: enumerate supported primitive IDs by family
• get_schematic_primitive and get_pcb_primitive: read the full primitive payload for a specific ID
• get_schematic_primitives_bbox and get_pcb_primitives_bbox: compute combined BBoxes for selected primitive IDs
• list_pcb_component_pads: inspect resolved footprint pads, including coordinates, pad numbers, and current nets
• route_pcb_line_between_component_pads: create a direct PCB line segment between two component pads while deriving the net when possible
• route_pcb_lines_between_component_pads: create multiple PCB line segments between two component pads using caller-supplied waypoints

Recommended component-placement flow:

1. Call search_library_devices with query or lcscIds.
2. Take a returned libraryUuid and uuid.
3. Call add_schematic_component or add_pcb_component with those identifiers and target coordinates.

Recommended pin-to-net flow:

1. Call list_schematic_component_pins for a placed component.
2. Select the desired pinNumber.
3. Call connect_schematic_pin_to_net with the component primitive ID, pin number, and target net name.

Recommended bus or grouped-net flow:

1. Call list_schematic_component_pins for a placed component.
2. Choose the pins that should be attached to a shared prefix-based naming scheme.
3. Call connect_schematic_pins_with_prefix with netPrefix and optional separator or pinOffset.

Recommended explicit bulk-net flow:

1. Call list_schematic_component_pins for a placed component.
2. Build a connections array of { "pinNumber": ..., "net": ... } objects.
3. Call connect_schematic_pins_to_nets to attach all requested named nets in one request.

Recommended pad-to-pad route flow:

1. Call list_pcb_component_pads for each placed PCB component.
2. Choose the source and destination padNumber values.
3. Call route_pcb_line_between_component_pads with both component primitive IDs, pad numbers, and a PCB line layer.

Recommended waypoint route flow:

1. Call list_pcb_component_pads for each placed PCB component.
2. Choose one or more intermediate { "x": ..., "y": ... } waypoints.
3. Call route_pcb_lines_between_component_pads to emit a multi-segment line path between the resolved pad centers.

PCB Net Tools

The PCB tool surface now includes:

• list_pcb_nets: full net inventory for the active PCB
• get_pcb_net: detail, routed length, and current display color for a net
• set_pcb_net_color: update a net's display color using { "r": ..., "g": ..., "b": ..., "alpha": ... } or null
• get_pcb_net_primitives: fetch primitives associated with a net, optionally filtered by numeric PCB primitive type IDs

SDK limitation: schematic net labels are implemented as attribute primitives, and the EasyEDA Pro API does not expose attribute deletion. The bridge therefore supports modify_schematic_net_label but not delete for that primitive type.

Host compatibility limitation: some EasyEDA builds do not expose the sch_PrimitiveAttribute runtime API even though it exists in the published type definitions. On those builds, add_schematic_net_label and modify_schematic_net_label are reported as runtime-unsupported in get_capabilities, and direct calls return a compatibility error that points back to the live capability report. connect_schematic_pin_to_net, connect_schematic_pins_to_nets, and connect_schematic_pins_with_prefix still fall back to short net-assigned wire stubs so pin-level net attachment can succeed.

Host placement limitation: some EasyEDA builds can throw Cannot convert undefined or null to object from add_pcb_component even after successfully creating the component. The bridge now snapshots component primitive IDs before placement and recovers the newly created primitive from live PCB state when that false-negative pattern occurs.

Host PCB text limitation: some EasyEDA builds can leave pcb_PrimitiveString calls hanging instead of resolving or rejecting. add_pcb_text, modify_pcb_text, delete_pcb_text, and list_pcb_primitive_ids with family="text" now fail fast with a compatibility error when the host text API stops responding, instead of waiting for the full MCP bridge timeout.

Routing limitation: the current SDK surface exposed here supports creating PCB line segments and inspecting connected pads, but it does not expose a true interactive autorouter API for arbitrary multi-segment pathfinding from the extension bridge. route_pcb_line_between_component_pads therefore creates a direct segment between the resolved pad centers, while route_pcb_lines_between_component_pads follows caller-supplied waypoints rather than performing automatic obstacle-aware routing.

Usage

1. Build and install the EasyEDA extension package.

   npm run build
   

2. Start the MCP server locally.

   npm run mcp:server
   

   If the local MCP server is already running, starting it again will stop the older instance and replace it with the new one.

   This starts both:

   • the stdio MCP transport used by normal MCP hosts
   • a local Streamable HTTP MCP endpoint at http://127.0.0.1:19733/mcp for attach-style testing

   For local regression coverage while developing the bridge:

   npm test
   

   For an opt-in live MCP smoke test against a real EasyEDA bridge session:

   EASYEDA_MCP_LIVE_TEST=1 npm run test:live
   

   To fail if EasyEDA is not actually connected to the bridge:

   EASYEDA_MCP_LIVE_TEST=1 EASYEDA_MCP_LIVE_REQUIRE_CONNECTED=1 npm run test:live
   

   To attach the live test to an already-running MCP server instead of spawning a second server:

   EASYEDA_MCP_LIVE_TEST=1 EASYEDA_MCP_LIVE_ATTACH_EXISTING=1 EASYEDA_MCP_LIVE_REQUIRE_CONNECTED=1 npm run test:live
   

   To override the attach URL for that mode:

   EASYEDA_MCP_LIVE_TEST=1 EASYEDA_MCP_LIVE_ATTACH_EXISTING=1 EASYEDA_MCP_LIVE_SERVER_URL=http://127.0.0.1:19733/mcp npm run test:live
   

3. In EasyEDA Pro, ensure the extension is installed and has permission for external interaction.

4. Open the extension menu and use Reconnect if EasyEDA needs to reattach to the local bridge.

5. Inspect Status to confirm that the bridge is connected.

Client Config Examples

Ready-to-adapt example files are included in examples/mcp/claude_desktop_config.json and examples/mcp/vscode.mcp.json.

Data structure notes:

• easyeda-mcp is just the server name key. You can rename it, but the same name should be used consistently within that config object.
• Claude Desktop expects a top-level mcpServers object.
• VS Code expects a top-level servers object.
• The value under easyeda-mcp is the actual server definition.
• command is the executable to run.
• args is the argument array passed to that executable.
• cwd is the working directory where the command should run.
• VS Code also requires "type": "stdio" for this server.

Claude Desktop

Structure:

{
   "mcpServers": {
      "<server-name>": {
         "command": "<executable>",
         "args": ["<arg1>", "<arg2>"],
         "cwd": "/absolute/path/to/project"
      }
   }
}

Example structure:

{
   "mcpServers": {
      "easyeda-mcp": {
         "command": "npm",
         "args": ["run", "mcp:server"],
         "cwd": "/home/i/repos/EasyEDA-MCP"
      }
   }
}

VS Code

Structure:

{
   "servers": {
      "<server-name>": {
         "type": "stdio",
         "command": "<executable>",
         "args": ["<arg1>", "<arg2>"],
         "cwd": "/absolute/path/to/project"
      }
   }
}

Workspace or user mcp.json example:

{
   "servers": {
      "easyeda-mcp": {
         "type": "stdio",
         "command": "npm",
         "args": ["run", "mcp:server"],
         "cwd": "/home/i/repos/EasyEDA-MCP"
      }
   }
}

Default Bridge Endpoint

ws://127.0.0.1:19732/easyeda-mcp

Environment Variables

• EASYEDA_MCP_BRIDGE_HOST
• EASYEDA_MCP_BRIDGE_PORT
• EASYEDA_MCP_BRIDGE_PATH
• EASYEDA_MCP_BRIDGE_TIMEOUT_MS base bridge timeout in milliseconds, default 30000
• EASYEDA_MCP_GET_DOCUMENT_SOURCE_TIMEOUT_MS optional per-method override for get_document_source
• EASYEDA_MCP_SET_DOCUMENT_SOURCE_TIMEOUT_MS optional per-method override for set_document_source
• EASYEDA_MCP_HTTP_ENABLED
• EASYEDA_MCP_HTTP_HOST
• EASYEDA_MCP_HTTP_PORT
• EASYEDA_MCP_HTTP_PATH
• EASYEDA_MCP_LIVE_ATTACH_EXISTING
• EASYEDA_MCP_LIVE_SERVER_URL

Slow bridge operations such as get_document_source, set_document_source, and primitive BBox queries use higher internal per-method timeout floors so large EasyEDA documents are less likely to fail spuriously. The current server defaults are 60000 for get_document_source and 120000 for set_document_source.

If your EasyEDA build is still slow on large source writes, set EASYEDA_MCP_SET_DOCUMENT_SOURCE_TIMEOUT_MS explicitly when starting the server.

Bridge requests are also serialized server-side so the EasyEDA runtime only handles one in-flight MCP operation at a time. This reduces instability from overlapping long-running bridge calls.

Notes

• The extension side depends on EasyEDA Pro's external interaction permission for WebSocket access.
• This scaffold intentionally starts with a small, explicit tool set rather than exposing arbitrary eda.* execution.
• ping_bridge and echo_bridge are minimal round-trip bridge diagnostics and are useful for proving the MCP call path independently of document edits.
• Destructive tools are explicit MCP calls, and the EasyEDA extension shows a bridge-side confirmation dialog before delete or overwrite operations unless skipConfirmation: true is provided on the supported delete and source-overwrite tools.
• The VS Code client configuration format follows the documented mcp.json servers structure for local stdio servers, and the Claude example follows the documented claude_desktop_config.json mcpServers structure.
• The included tests cover tool registration, local schema validation for optimistic source writes, and revision-hash stability without requiring a live EasyEDA instance.
• The included tests also cover bridge-session timeout handling, disconnect rejection, and out-of-order response correlation without requiring a live EasyEDA instance.
• The live integration test is intentionally opt-in so normal local development and CI do not depend on an interactive EasyEDA Pro session being open and bridge-connected.