# JLC EDA MCP Server

这是从原 `jlc_import` 目录整理出来的独立仓库，用来让支持 Model Context Protocol 的客户端控制嘉立创 EDA。

## Credits

当前仓库基于 [hyl64/jlcmcp](https://github.com/hyl64/jlcmcp) 整理和改造。

```bash
git clone <this-repo-url> jlc-mcp
cd jlc-mcp
```

仓库包含三个部分：

- `src/`: MCP server，向 Codex、Claude Code、Cursor、Windsurf 等客户端暴露 PCB/原理图工具。
- `local_jlc_gateway.cjs`: 本机 gateway，接收 MCP server 的 HTTP 命令，并通过 WebSocket 转发给 EDA 插件。
- `jlc-bridge/`: 嘉立创 EDA 扩展插件，运行在 EDA 里执行实际操作。

## 架构

```text
MCP client
  -> stdio
MCP server: <absolute-path-to-jlc-mcp>/dist/index.js
  -> HTTP POST http://127.0.0.1:18800/command
local gateway: local_jlc_gateway.cjs
  -> WebSocket ws://127.0.0.1:18800/ws/bridge
jlc-bridge extension
  -> 嘉立创 EDA
```

MCP server 本身不直接控制 EDA，它只把工具调用发送给本机 gateway。`jlc-bridge` 插件启动后会连接 gateway 的 `/ws/bridge`，再由插件调用嘉立创 EDA 的扩展 API。

## 前置条件

- Node.js 18 或更新版本
- 嘉立创 EDA 专业版，能安装本地扩展
- 一个支持 MCP 的客户端
- 如需使用 `pcb_agent`，需要设置 `ANTHROPIC_API_KEY`

## 安装

```bash
cd /path/to/jlc-mcp
npm install
npm run build
```

构建成功后，MCP 入口文件是：

```bash
/path/to/jlc-mcp/dist/index.js
```

## 构建并安装 EDA 插件

```bash
cd /path/to/jlc-mcp/jlc-bridge
npm install
npm run build
```

构建后会生成：

```text
/path/to/jlc-mcp/jlc-bridge/build/jlc-bridge.eext
/path/to/jlc-mcp/jlc-bridge/build/jlc-bridge.lcex
/path/to/jlc-mcp/jlc-bridge/build/jlc-bridge_v0.1.29.eext
```

在嘉立创 EDA 里安装其中一个扩展包。插件会在 EDA 启动后自动尝试连接：

```text
ws://127.0.0.1:18800/ws/bridge
```

也可以在 EDA 的 `JLC Bridge` 菜单里查看状态或手动切换。

WebSocket 是默认通信方式。插件还保留文件轮询 fallback，默认目录名是 `jlc-bridge`；如果确实要使用文件轮询，可以在 EDA 开发者控制台里设置 `localStorage.jlcBridgeDir` 为本机可写目录后重启插件。

## 启动 gateway

在一个单独终端中运行：

```bash
cd /path/to/jlc-mcp
npm run gateway
```

默认监听：

```text
http://127.0.0.1:18800
```

检查状态：

```bash
curl http://127.0.0.1:18800/state
```

如果 `bridgeConnected` 是 `true`，说明嘉立创 EDA 插件已经连上 gateway。

可选环境变量：

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `JLC_GATEWAY_HOST` | `127.0.0.1` | gateway 监听地址 |
| `JLC_GATEWAY_PORT` | `18800` | gateway 监听端口 |

## 配置 MCP 客户端

把下面配置加入你的 MCP 客户端配置文件。仓库里也有同样内容的 `mcp_config.example.json`。

```json
{
  "mcpServers": {
    "jlceda": {
      "command": "node",
      "args": [
        "/absolute/path/to/jlc-mcp/dist/index.js"
      ],
      "env": {
        "GATEWAY_HTTP_URL": "http://127.0.0.1:18800/command"
      }
    }
  }
}
```

配置后重启 MCP 客户端。

如果要启用 `pcb_agent`，加上：

```json
{
  "env": {
    "GATEWAY_HTTP_URL": "http://127.0.0.1:18800/command",
    "ANTHROPIC_API_KEY": "sk-ant-...",
    "AGENT_MODEL": "claude-sonnet-4-20250514"
  }
}
```

## 运行顺序

1. 启动 gateway。
2. 打开嘉立创 EDA，并确认 `jlc-bridge` 插件已连接。
3. 启动或重启 MCP 客户端。
4. 在客户端里调用 `pcb_ping` 或 `pcb_get_state` 验证链路。

如果顺序反了也可以，插件和客户端可以稍后重连。但首次验证时按上面顺序更容易定位问题。

## 可用工具

当前 MCP server 默认注册 51 个工具；配置 `ANTHROPIC_API_KEY` 后增加 `pcb_agent`，共 52 个。分组如下：

- 状态查询：`pcb_get_state`、`pcb_screenshot`、`pcb_run_drc`、`pcb_get_tracks`、`pcb_get_pads`、`pcb_get_net_primitives`、`pcb_get_board_info`、`pcb_get_feature_support`、`pcb_ping`
- 元件操作：`pcb_move_component`、`pcb_relocate_component`、`pcb_batch_move`、`pcb_select_component`、`pcb_delete_selected`、`pcb_create_component`
- 走线和过孔：`pcb_route_track`、`pcb_create_via`、`pcb_delete_tracks`、`pcb_delete_via`
- 铺铜和禁布区：`pcb_create_copper_pour`、`pcb_delete_pour`、`pcb_create_keepout`、`pcb_delete_keepout`
- 丝印：`pcb_get_silkscreens`、`pcb_move_silkscreen`、`pcb_auto_silkscreen`
- 高级规则：`pcb_create_diff_pair`、`pcb_list_diff_pairs`、`pcb_delete_diff_pair`、`pcb_create_equal_length`、`pcb_list_equal_lengths`、`pcb_delete_equal_length`
- 原理图：`sch_get_state`、`sch_get_netlist`、`sch_run_drc`、`pcb_open_document`
- 工程及原生数据：`eda_open_project`、`eda_get_project_context`、`eda_get_available_commands`、`pcb_get_netlist`、`eda_get_document_source`、`eda_set_document_source`、`eda_export_project`
- 规则和同步：`pcb_get_design_rules`、`pcb_set_design_rules`、`pcb_save_rule_configuration`、`pcb_import_changes`、`pcb_save_document`、`sch_save_document`
- 计算工具：`calc_impedance`、`calc_trace_width`
- Agent：`pcb_agent`，仅在设置 `ANTHROPIC_API_KEY` 后注册

所有 PCB 坐标和尺寸参数默认使用 mil。

0.1.27 增加迁移核对工具，并修正 DRC 分类计数、原生线宽读取和多板工程的保存目标。新工具需要同时更新 MCP server 和 EDA 扩展；完整参数、兼容性及更新步骤见 [0.1.27 说明](docs/0.1.27-migration-tools.md)。

0.1.28 修复原生导出临时元数据造成的版本误报，正确区分原理图 DRC 摘要与详细问题，并明确网表导入仍可能需要界面确认。见 [0.1.28 说明](docs/0.1.28-native-export-fixes.md)。

0.1.29 增加 `eda_open_project`，按 UUID 或精确名称打开已有项目，默认保护其它已打开的编辑文档。见 [打开项目说明](docs/0.1.29-open-project.md)。

## 本地验证

安装根目录和 `jlc-bridge` 的依赖后，运行：

```bash
npm run verify
```

它会检查新扩展模块的类型、构建 MCP 和扩展，并运行 12 项回归测试，包括构建后的 stdio → HTTP → 扩展 WebSocket 命令分发测试。测试使用模拟的 EDA API，不连接真实编辑器；测试环境需要 Node.js 22 或更新版本。真实 EDA 的兼容性和项目 DRC 仍需在安装新扩展后验证。

只验证 MCP server 能启动并列出工具，不需要 gateway：

```bash
cd /path/to/jlc-mcp
npm run build
printf '%s\n' \
  '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"manual","version":"1.0.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
  '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | node dist/index.js
```

端到端验证需要 gateway 和 EDA 插件都运行：

```bash
curl http://127.0.0.1:18800/state
```

然后在 MCP 客户端调用：

```text
pcb_ping
pcb_get_state
```

## 项目结构

```text
.
├── src/
│   ├── index.ts
│   ├── bridge-client.ts
│   ├── agent.ts
│   ├── calculators.ts
│   └── tools/
├── jlc-bridge/
│   ├── src/index.ts
│   ├── extension.json
│   ├── build/pack.js
│   ├── package.json
│   └── tsconfig.json
├── local_jlc_gateway.cjs
├── mcp_config.example.json
├── package.json
└── tsconfig.json
```

## 常见问题

### `jlc bridge is not connected`

gateway 已启动，但 EDA 插件没有连上。检查嘉立创 EDA 是否已打开、插件是否安装并启用，然后访问：

```bash
curl http://127.0.0.1:18800/state
```

### MCP 客户端找不到工具

先确认已经构建：

```bash
cd /path/to/jlc-mcp
npm run build
```

再确认 MCP 配置里的路径是当前仓库的 `dist/index.js` 绝对路径，不是旧的 `jlc_import` 或 `/tmp/jlcmcp` 路径。

### 端口被占用

改 gateway 端口：

```bash
JLC_GATEWAY_PORT=18801 npm run gateway
```

同时把 MCP 配置改成：

```json
{
  "GATEWAY_HTTP_URL": "http://127.0.0.1:18801/command"
}
```

注意：当前 `jlc-bridge` 插件源码里默认连接 `ws://127.0.0.1:18800/ws/bridge`。如果改 gateway 端口，也需要同步修改 `jlc-bridge/src/index.ts` 里的 `WS_URL` 后重新构建并安装插件。