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.

[!WARNING] Development is paused at version 0.19.1.

A live high-level schematic-generation exercise exposed a critical failure mode: EasyEDA could contain newly created components while the canvas appeared blank, followed by an unresponsive editor during heavyweight layout and visual scans.

Do not use the high-level schematic write workflow on an unsaved or valuable project. Read Project status and Editor freeze issue before enabling writes.

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

What this project provides

The tool surface is organized around a few practical areas:

Area	Examples
Runtime and sessions	Server status, EasyEDA windows, document context, write policy
Project management	Project tree, document creation, document switching
Libraries and parts	Device search, exact LCSC lookup, symbol and footprint inspection
Schematics	Component inspection, wires, labels, DRC, editing, layout and visual review
Schematic-to-PCB	Association checks, Import Changes preparation and verification
PCB design	Placement, board outline, rules, routing, pours, repair and cleanup
Manufacturing	BOM, pick-and-place, Gerber and project archive exports

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.

[!CAUTION] A host-side timeout does not guarantee that an already-running EasyEDA-side script has stopped. If EasyEDA becomes unresponsive, stop the MCP server and reload or restart EasyEDA before doing more work.

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

Command	Purpose
npm run dev	Start the TypeScript development server
npm run build	Build production JavaScript and declarations
npm start	Run the built CLI
npm test	Run the Vitest suite
npm run typecheck	Run TypeScript without emitting files
npm run lint	Run Oxlint with warnings denied
npm run format:check	Check Prettier formatting
npm run check	Run formatting, lint, typecheck, tests and build
npm run clean	Remove generated build, test and runtime artifacts

Configuration

Variable	Default	Purpose
JLC_MCP_HTTP_PORT	8787	Loopback HTTP MCP port
JLC_MCP_ENABLE_WRITES	disabled	Enable tools that mutate EasyEDA state
JLC_MCP_WRITE_PLAN_TTL_MS	2 minutes	Lifetime of signed write plans
JLC_MCP_CREATION_REVERT_TTL_MS	10 minutes	Ownership window for created objects
JLC_MCP_WRITE_AUDIT_FILE	user audit directory	JSONL write-audit path
JLC_MCP_EXPORT_DIR	~/jlc-mcp-exports	Export and rendered-artifact directory
JLC_MCP_MAX_ARTIFACT_BYTES	256 MiB	Maximum artifact size; may only be lowered

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

Document	Contents
Project status	Maintenance state, release posture and final verification
Open editor-freeze issue	Critical known defect and recovery guidance
Architecture	Transport, Bridge and domain-service design
Tool catalog	All 172 tools grouped by domain
Usage notes	Identifiers, transactions, rollback and workflow guidance
Version 0.19.1 record	Final high-level workflow milestone and later incident note
Security policy	Supported security boundary and reporting guidance
TODO	Known gaps and paused follow-up work

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