# 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](docs/project-status.md) and
> [Editor freeze issue](docs/issues/schematic-workflow-editor-freeze.md) 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](skills/jlc-mcp/references/tool-catalog.md).

## 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:

```bash
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

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

### 2. Start the server

For development:

```bash
npm run dev
```

For a production build:

```bash
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:

```text
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:

```text
http://127.0.0.1:8787/mcp
```

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

```json
{
  "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:

```bash
npm run dev -- --port 9000
```

```bash
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

```text
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](docs/project-status.md)                                    | Maintenance state, release posture and final verification   |
| [Open editor-freeze issue](docs/issues/schematic-workflow-editor-freeze.md) | Critical known defect and recovery guidance                 |
| [Architecture](docs/architecture.md)                                        | Transport, Bridge and domain-service design                 |
| [Tool catalog](skills/jlc-mcp/references/tool-catalog.md)                   | All 172 tools grouped by domain                             |
| [Usage notes](skills/jlc-mcp/references/usage-notes.md)                     | Identifiers, transactions, rollback and workflow guidance   |
| [Version 0.19.1 record](docs/version-0191-completion.md)                    | Final high-level workflow milestone and later incident note |
| [Security policy](SECURITY.md)                                              | Supported security boundary and reporting guidance          |
| [TODO](TODO.md)                                                             | 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:

```bash
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](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](LICENSE)