jlc-mcp

jlc-mcp is a local Model Context Protocol server that exposes EasyEDA Pro Run API Gateway capabilities as structured MCP tools.

It connects an MCP client to a live EasyEDA Pro window through loopback-only HTTP and Bridge endpoints. The repository includes tools for project inspection, schematic editing, PCB placement and routing, design validation, manufacturing exports, and experimental high-level schematic workflows.

At a glance

• Transport: Streamable HTTP MCP

• Default endpoint: http://127.0.0.1:8787/mcp

• Health endpoint: http://127.0.0.1:8787/health

• EasyEDA Bridge ports: 127.0.0.1:49620-49629

• Public tools: 172

• Write policy: disabled by default

• Runtime: Node.js 20 or later

• License: MIT

Related MCP server: KiCad MCP Server

What this project provides

The tool surface is organized around a few practical areas:

The complete list is maintained in the tool catalog.

Important safety model

jlc-mcp intentionally separates planning from mutation.

Most write tools use this sequence:

1. Call the tool with dryRun: true.

2. Review the target, baseline fingerprint, warnings, DRC evidence and rollback details.

3. Apply with dryRun: false, the returned one-time applyToken, and the expected document UUID.

4. Replan after any EasyEDA edit, focus change, document switch, token expiry or fingerprint conflict.

Actual writes require:

JLC_MCP_ENABLE_WRITES=1

Keep writes disabled when you only need inspection, planning, validation or export.

Quick start

1. Install dependencies

git clone https://github.com/InkRoad/jlc-mcp.git
cd jlc-mcp
npm install

2. Start the server

For development:

npm run dev

For a production build:

npm run build
npm start

The host is intentionally fixed to 127.0.0.1.

3. Connect EasyEDA Pro

Open EasyEDA Pro and enable the official Run API Gateway extension with its external-interaction permission. The embedded Bridge listens on the first available port in 49620-49629 and waits for the EasyEDA window to register.

Check the connection:

http://127.0.0.1:8787/health

The response should report an EasyEDA connection and at least one registered window before design tools are used.

4. Connect an MCP client

Point the client at:

http://127.0.0.1:8787/mcp

A typical client entry looks like this, although the exact configuration format depends on the MCP client:

{
  "mcpServers": {
    "jlc-mcp": {
      "url": "http://127.0.0.1:8787/mcp"
    }
  }
}

Start with these read-only tools:

• jlc_server_status

• jlc_session_status

• jlc_session_list_windows

• jlc_editor_get_context

• jlc_write_get_policy

Recommended workflow

Read-only inspection

1. Confirm the connected EasyEDA window.

2. Read the focused document context.

3. Probe the relevant capability tool.

4. Read complete paginated inventories.

5. Run DRC and validation tools before making completion claims.

Controlled writes

1. Back up the project.

2. Enable JLC_MCP_ENABLE_WRITES=1 only for the current session.

3. Run a dry-run plan.

4. Inspect every warning and blocker.

5. Apply the one-time token without editing the design between plan and apply.

6. Re-read the resulting state and run DRC.

7. Save explicitly only after visual confirmation in EasyEDA.

High-level schematic workflow

Version 0.19.1 includes this experimental chain:

1. jlc_schematic_create_design_plan

2. jlc_schematic_generate_from_plan

3. jlc_schematic_plan_functional_layout

4. jlc_schematic_apply_layout_plan

5. jlc_schematic_plan_orthogonal_wiring

6. jlc_schematic_apply_wiring_plan

7. jlc_schematic_review_design

8. jlc_schematic_repair_design

9. jlc_schematic_finalize

These interfaces are retained as a development snapshot. They are not considered safe for autonomous live-editor use while the editor-freeze issue remains open.

For ordinary local schematic connectivity, the workflow prefers the wire primitive's own network name. IN/OUT/BI arrow ports are reserved for explicit cross-page connections. Power and ground flags remain supported.

Common commands

Configuration

Use a custom HTTP port with either form:

npm run dev -- --port 9000

JLC_MCP_HTTP_PORT=9000 npm run dev

Do not expose the internal Bridge ports outside loopback. A reverse tunnel may publish the MCP HTTP endpoint, but the EasyEDA Bridge must remain local.

Key limitations

• The project is paused and has no scheduled maintenance release.

• The high-level schematic workflow has an unresolved critical editor-stability issue.

• Request timeout is not an EasyEDA-side cancellation guarantee.

• EasyEDA runtime capability probes are evidence, not promises that later calls will succeed.

• Footprint reassignment for an existing schematic component is not reliably exposed by the accepted public API; use EasyEDA's Footprint Manager and verify afterward.

• Import Changes still requires the user to review and apply or cancel the official EasyEDA dialog.

• Full-board autorouting and unrestricted arbitrary JavaScript execution are not provided.

• A successful DRC does not replace visual inspection, page-boundary checks or manufacturing review.

Project structure

src/
  bridge/                 EasyEDA Gateway Bridge and request lifecycle
  mcp/                    MCP server and tool registration
  schematic-workflow/     High-level schematic planning and review
  schematic-visual/       Geometry, overlap and visual-quality analysis
  schematic-render/       Official canvas capture and image validation
  connectivity/           Wires, tracks, vias and network transactions
  routing/                PCB routing planners and validators
  manufacturing/          BOM, PnP, Gerber and project exports
tests/                    Unit and protocol tests
scripts/                  Real-Gateway and release-specific E2E scripts
skills/jlc-mcp/           ChatGPT Skill instructions and reference material
docs/                     Architecture, status, issue and version records

Documentation

Earlier milestone records are available under docs/version-*.md. The previous long-form README is preserved in Git history at commit 096726a.

Development notes

Run the complete repository check before submitting changes:

npm run check

The final archived snapshot was verified with:

• Prettier

• Oxlint with zero warnings

• TypeScript --noEmit

• 73 test files and 224 tests

• production build

These checks prove internal consistency of the checked-in host code. They do not resolve the open live-editor freeze issue.

Security boundary

• MCP and Bridge listeners bind only to loopback addresses.

• Writes are disabled unless explicitly enabled.

• Mutations use bounded tool-specific APIs rather than arbitrary script execution.

• Write plans are short-lived, one-time and bound to document and state fingerprints.

• Audit events are written locally.

• Exports are restricted to the configured artifact directory.

Read SECURITY.md before exposing the MCP endpoint through any tunnel or shared host.

Disclaimer

This project is not affiliated with or endorsed by JLCPCB or EasyEDA. It is an experimental local integration that depends on EasyEDA Pro runtime APIs, including APIs marked Beta by EasyEDA.

License

MIT