Easy Eda MCP

EasyEDA MCP支架

快速开始

本文详细介绍了MCP服务器和EasyEDA网桥。如果你想快速设置和使用它，从这里开始。

你需要的

• Node.js >= 20.17.0
• npm
• EasyEDA Pro/JLCEDA Pro
• 此存储库在本地克隆

1.安装依赖项

从存储库根目录：

npm install

2.构建EasyEDA桥接扩展

npm run build

这将在下面创建可安装的EasyEDA扩展包 ./build/dist/.

3.在EasyEDA Pro中安装扩展

从安装生成的包 ./build/dist/ 进入EasyEDA Pro。

安装后，EasyEDA顶部菜单显示 EasyEDA MCP Bridge 与：

• Reconnect
• Status

如果EasyEDA提示外部交互权限，请允许它，以便网桥可以连接回本地MCP服务器。

4.启动本地MCP服务器

从存储库根目录运行此命令：

npm run mcp:server

默认情况下，这将开始：

• 用于AI客户端的MCP stdio服务器
• EasyEDA桥接WebSocket ws://127.0.0.1:19732/easyeda-mcp
• 本地HTTP连接端点位于 http://127.0.0.1:19733/mcp

npm run mcp:server 已经公开了上面的HTTP连接端点。如果要在没有stdio传输的情况下运行网桥服务，请使用：

npm run mcp:server:daemon

5.配置您的MCP客户端

VS Code或其他基于stdio的MCP客户端：

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

克劳德桌面示例：

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

准备复制的示例已经包含在此仓库中：

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

6.首次连接

1. 打开EasyEDA Pro。
2. 确保已安装EasyEDA MCP桥扩展。
3. 启动本地MCP服务器。
4. 将您的MCP客户端连接到 easyeda-mcp.
5. 在EasyEDA中，单击 EasyEDA MCP Bridge -> Reconnect.
6. 呼叫 bridge_status 来自您的MCP客户。

如果桥梁健康，继续 get_current_context 查看EasyEDA当前是否正在公开项目、原理图或PCB文档。

7.最小有效烟雾测试

使用此工具顺序验证整个链条的端到端：

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

如果 bridge_status 报告网桥已断开连接，通常的修复方法是返回EasyEDA并单击 Reconnect 一次。

8.典型的第一工作流程

一旦连接了网桥，实用的第一个工作流程是：

1. list_project_objects 检查电路板、原理图、PCB和面板
2. open_document 切换到要编辑的文档
3. search_library_devices 按关键字或LCSC零件号查找组件
4. add_schematic_component 或 add_pcb_component 放置组件
5. get_capabilities 或 get_usage_guide 如果需要适应主机/运行时限制

9.故障排除

• 网桥未连接：在EasyEDA中，使用 EasyEDA MCP Bridge -> Reconnect，确认已启用外部交互权限，然后调用 bridge_status 再一次。
• MCP客户端无法启动服务器：确认 npm install 已运行并使用Node.js >= 20.17.0.
• EasyEDA中缺少扩展菜单：使用重建 npm run build 并从重新安装该软件包 ./build/dist/.
• 您需要附加样式测试而不是stdio：在以下位置使用本地端点 http://127.0.0.1:19733/mcp.

该存储库现在包括一个本地MCP服务器支架和一个匹配的EasyEDA扩展桥。

脚手架现在包括原始桥梁之外的三个额外部分：

• 文档源覆盖的乐观修订检查
• 准备复制客户端配置示例
• 第一遍高级编辑工具，不需要替换整个文档源

现在还包括：

• 用于往返健康检查的桥接自检工具
• 元件放置流的库设备搜索
• 原理图和PCB文档上的元件放置和编辑
• 支持的图元族的图元ID和边界框查询工具
• PCB网络检测和显示颜色编辑工具
• 原理图引脚和PCB焊盘检查以及意图级连接助手
• 批量原理图引脚到网络工作流程和基于路点的PCB布线
• 用于真实EasyEDA桥接会话的可选择的实时MCP集成测试工具

组件

1. src/mcp-server.ts

通过stdio运行本地MCP服务器，并公开此处记录的EasyEDA MCP工具界面。

1. src/easyeda-mcp-bridge.ts

在EasyEDA Pro扩展运行时内运行，并通过WebSocket连接回MCP服务器。

1. src/mcp-bridge-protocol.ts

本地主机网桥的共享协议定义。

MCP服务器还公开了一个本地Streamable HTTP端点，用于在以下位置进行连接样式测试 http://127.0.0.1:19733/mcp 默认情况下。

包含MCP工具

• 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

来源修订

get_document_source 现在返回：

• source
• sourceHash
• characters

set_document_source 现在预计：

• expectedSourceHash
• 或 force: true

它还接受：

• skipConfirmation: true 取消显示网桥侧覆盖确认对话框

推荐流量：

1. 呼叫 get_document_source.
2. 制作您编辑过的源代码。
3. 呼叫 set_document_source 与返回 sourceHash 作为 expectedSourceHash.
4. 如果哈希值不匹配，请在重试之前重新读取文档。

MCP工具层现在验证 set_document_source 通过在正常响应和超时恢复路径之后重新读取活动文档。如果EasyEDA报告成功，但重新读取的源哈希与请求的源不匹配，则该工具将返回错误而不是错误的成功。

请求负载示例：

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

如果你需要绕过乐观检查：

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

桥梁自检工具

这些工具用于桥梁验证，而不是CAD编辑：

• bridge_status：从MCP服务器端检查当前网桥连接状态
• get_usage_guide：返回一份简洁的操作指南，描述推荐的工具顺序、通用标识符和工作流程顺序
• ping_bridge：验证MCP服务器->websocket网桥->EasyEDA扩展->websocket网桥->MCP服务器往返运行状况
• echo_bridge：通过同一路径发送消息并验证返回的有效载荷

get_capabilities 返回全桥表面和当前由实时EasyEDA主机运行时支持的子集。主机构建缺少原理图网络标签API， supportedMethods 排除受影响的网络标签方法 hostRuntimeUnsupportedMethods 加 hostRuntimeCapabilities 描述限制和建议的回退。

bridge_status 和 get_current_context 还包括 recommendedNextSteps 在他们的结构化响应中，MCP客户可以减少猜测，选择下一个工具。

高级编辑工具

这些工具避免了常见编辑案例的整个文档源替换：

• add_schematic_text：将文本图元添加到活动原理图页面
• add_schematic_net_label：向活动原理图页面添加网络标签
• add_schematic_wire：将导线图元添加到活动原理图页面
• add_pcb_line：向活动PCB文档添加行图元。信号线需要非空 net；板上的轮廓线 BoardOutLine 可以省略 net 或者使用空字符串。
• add_pcb_text：将文本图元添加到活动PCB文档中
• save_active_document：保存活动原理图页面、PCB或面板

每个编辑工具都接受 saveAfter: true 如果您希望在创建图元后立即保存文档。

add_pcb_text 需要 fontFamily 它已经存在于EasyEDA Pro环境中。

相同的原始族现在也支持有针对性的修改，并在宿主SDK允许的情况下支持删除。

删除工具也接受 skipConfirmation: true 在向EasyEDA发送删除请求之前，抑制网桥侧确认提示。

文档生命周期工具

该桥现在覆盖了主要的项目对象生命周期：

• create_board：创建电路板，可选择链接现有的原理图UUID和PCB UUID；如果读回显示链接的原理图仍然在其标题栏中通告不同的电路板名称，则失败
• create_pcb：创建PCB，可选地在命名板下
• import_schematic_to_pcb：将链接的原理图更改导入PCB；当目标PCB没有与板支持的原理图一致链接时，会快速失败；当项目清单的标题栏过时时，会回退到链接的原理图页面源；在主机上 pcb_Document.importChanges(...) 对未更改的空PCB错误成功，请通过EasyEDA用于的相同主机UI差异/应用流重试 Design -> Import Changes from Schematic 失败之前
• create_panel：创建面板文档
• create_schematic：创建原理图，可选地在命名板下
• create_schematic_page：向现有原理图添加新页面
• copy_board：按板名复制板
• copy_pcb：复制PCB，可选择将副本放置在指定的板下
• copy_panel：按UUID复制面板
• copy_schematic：复制原理图，可选择将副本放在指定的板下
• copy_schematic_page：复制原理图页面，可选地复制到另一个原理图中

推荐的复制流程：

1. 呼叫 list_project_objects 查找源板、PCB、原理图、页面或面板。
2. 调用匹配 copy_* 带有源标识符的工具。
3. 如果需要，请使用现有的重命名工具来指定最终名称。

组件放置和查询工具

该桥现在支持更完整的组件和检查工作流程：

• search_library_devices：按关键字或LCSC零件号搜索EasyEDA库
• add_schematic_component：将搜索到的库设备放置在活动原理图页面上
• add_pcb_component：将搜索到的库设备放置在活动PCB文档上，当创建后某些主机构建抛出时，从活动PCB状态恢复创建的图元
• modify_schematic_component 和 modify_pcb_component：调整放置的组件属性，如坐标、旋转、指示符和元数据
• delete_schematic_component 和 delete_pcb_component：使用本机EasyEDA确认对话框删除放置的组件；MCP工具层在删除后重新读取PCB组件清单，并将主机端的无操作确认视为失败，而不是报告错误的成功
• delete_* 工具：接受 skipConfirmation: true 抑制桥侧删除提示
• add_schematic_net_flag 和 add_schematic_net_port：放置常见的网络感知原理图标记组件，而无需编辑整个源文本
• add_schematic_short_circuit_flag：放置EasyEDA短路标记组件，而不编辑整个源文本
• list_schematic_component_pins：检查已解析的符号引脚，包括坐标和引脚号
• set_schematic_pin_no_connect：切换引脚的显式无连接标记
• connect_schematic_pin_to_net：在选定的组件引脚位置连接一个命名的网络，首选网络标签，并在需要时回落到短接线柱上
• connect_schematic_pins_to_nets：在一个请求中附加多个显式的引脚到网络映射，首选网络标签，并在需要时回退到短接线头
• connect_schematic_pins_with_prefix：派生网络名称，如 BUS_1, BUS_2，等等，从前缀和引脚号开始，更喜欢网络标签，并在需要时回落到短接线头
• list_schematic_primitive_ids 和 list_pcb_primitive_ids：按族枚举支持的基本体ID
• get_schematic_primitive 和 get_pcb_primitive：读取特定ID的完整基元有效载荷
• get_schematic_primitives_bbox 和 get_pcb_primitives_bbox：计算所选图元ID的组合BBox
• list_pcb_component_pads：检查已解析的封装焊盘，包括坐标、焊盘编号和当前网络
• route_pcb_line_between_component_pads：在两个元件焊盘之间创建直接的PCB线段，同时尽可能地导出网络
• route_pcb_lines_between_component_pads：使用呼叫者提供的路点在两个元件焊盘之间创建多个PCB线段

推荐的组件放置流程：

1. 呼叫 search_library_devices 和 query 或 lcscIds.
2. 拿一个返回 libraryUuid 和 uuid.
3. 呼叫 add_schematic_component 或 add_pcb_component 具有这些标识符和目标坐标。

建议针到网流量：

1. 呼叫 list_schematic_component_pins 对于放置的组件。
2. 选择所需 pinNumber.
3. 呼叫 connect_schematic_pin_to_net 包含组件基元ID、引脚号和目标网络名称。

推荐的总线或分组净流量：

1. 呼叫 list_schematic_component_pins 对于放置的组件。
2. 选择应连接到基于共享前缀的命名方案的引脚。
3. 呼叫 connect_schematic_pins_with_prefix 和 netPrefix 可选 separator 或 pinOffset.

建议显式散装净流量：

1. 呼叫 list_schematic_component_pins 对于放置的组件。
2. 建立一个 connections 数组 { "pinNumber": ..., "net": ... } 物体。
3. 呼叫 connect_schematic_pins_to_nets 将所有请求的命名网络附加到一个请求中。

推荐的焊盘间路线流程：

1. 呼叫 list_pcb_component_pads 对于每个放置的PCB组件。
2. 选择源和目标 padNumber 价值观。
3. 呼叫 route_pcb_line_between_component_pads 具有元件图元ID、焊盘编号和PCB线路层。

推荐航路点路线流：

1. 呼叫 list_pcb_component_pads 对于每个放置的PCB组件。
2. 选择一个或多个中间体 { "x": ..., "y": ... } 航路点。
3. 呼叫 route_pcb_lines_between_component_pads 以在所解析的焊盘中心之间发射多段线路径。

PCB网络工具

PCB工具表面现在包括：

• list_pcb_nets：活动PCB的全部净库存
• get_pcb_net：网络的详细信息、布线长度和当前显示颜色
• set_pcb_net_color：使用以下命令更新网络的显示颜色 { "r": ..., "g": ..., "b": ..., "alpha": ... } 或 null
• get_pcb_net_primitives：获取与网络关联的图元，可选地通过数字PCB图元类型ID进行过滤

SDK限制：原理图网络标签作为属性原语实现，EasyEDA Pro API不暴露属性删除。因此，这座桥支撑着 modify_schematic_net_label 但不删除该原始类型。

主机兼容性限制：一些EasyEDA构建没有公开 sch_PrimitiveAttribute 运行时API，即使它存在于已发布的类型定义中。在这些建筑上， add_schematic_net_label 和 modify_schematic_net_label 在中报告为不支持运行时 get_capabilities，并且直接调用返回指向实时能力报告的兼容性错误。 connect_schematic_pin_to_net, connect_schematic_pins_to_nets，以及 connect_schematic_pins_with_prefix 仍然可以退回到短网分配的接线头，这样针级网连接就可以成功。

主机放置限制：一些EasyEDA构建可能会抛出 Cannot convert undefined or null to object 从 add_pcb_component 即使在成功创建组件之后。桥现在会在放置之前快照组件图元ID，并在出现假阴性模式时从活动PCB状态恢复新创建的图元。

主机PCB文本限制：一些EasyEDA构建可以离开 pcb_PrimitiveString 呼叫挂起，而不是解决或拒绝。 add_pcb_text, modify_pcb_text, delete_pcb_text，以及 list_pcb_primitive_ids 和 family="text" 现在，当主机文本API停止响应，而不是等待完整的MCP桥接超时时，会出现兼容性错误，从而快速失败。

路由限制：这里暴露的当前SDK表面支持创建PCB线段和检查连接的焊盘，但它没有暴露出真正的交互式自动外部API，用于从扩展桥进行任意多段路径查找。 route_pcb_line_between_component_pads 因此，在已解析的焊盘中心之间创建了一个直接段，而 route_pcb_lines_between_component_pads 遵循呼叫者提供的航路点，而不是执行自动障碍感知路线。

用法

1. 构建并安装EasyEDA扩展包。

   npm run build

1. 在本地启动MCP服务器。

   npm run mcp:server

如果本地MCP服务器已在运行，重新启动它将停止旧实例并用新实例替换它。

这从两个方面开始：

- 普通MCP主机使用的stdio MCP传输 - 位于的本地可流式HTTP MCP端点 http://127.0.0.1:19733/mcp 用于附件样式测试

对于开发桥梁时的局部回归覆盖：

   npm test

对于针对真实EasyEDA桥接会话的选择加入实时MCP烟雾测试：

   EASYEDA_MCP_LIVE_TEST=1 npm run test:live

如果EasyEDA实际上没有连接到网桥，则失败：

   EASYEDA_MCP_LIVE_TEST=1 EASYEDA_MCP_LIVE_REQUIRE_CONNECTED=1 npm run test:live

要将实时测试附加到已运行的MCP服务器，而不是生成第二个服务器，请执行以下操作：

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

要覆盖该模式的附加URL，请执行以下操作：

   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

1. 在EasyEDA Pro中，确保已安装扩展并具有外部交互权限。

1. 打开扩展菜单并使用 Reconnect 如果EasyEDA需要重新连接到本地网桥。

1. 检查 Status 以确认桥接器已连接。

客户端配置示例

已准备好适应的示例文件包含在 examples/mcp/claude_desktop_config json 和 examples/mcp/vscode.mcp.json.

数据结构说明：

• easyeda-mcp 只是服务器名称密钥。您可以重命名它，但在该配置对象中应始终使用相同的名称。
• Claude Desktop希望有一个顶级 mcpServers 对象。
• VS Code需要一个顶级 servers 对象。
• 价值低于 easyeda-mcp 是实际的服务器定义。
• command 是要运行的可执行文件。
• args 是传递给该可执行文件的参数数组。
• cwd 是运行命令的工作目录。
• VS Code还要求 "type": "stdio" 对于这台服务器。

克劳德桌面

结构：

{
   "mcpServers": {
      "": {
         "command": "",
         "args": ["", ""],
         "cwd": "/absolute/path/to/project"
      }
   }
}

示例结构：

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

VS Code

结构：

{
   "servers": {
      "": {
         "type": "stdio",
         "command": "",
         "args": ["", ""],
         "cwd": "/absolute/path/to/project"
      }
   }
}

工作区或用户 mcp.json 例子：

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

默认网桥端点

ws://127.0.0.1:19732/easyeda-mcp

环境变量

• EASYEDA_MCP_BRIDGE_HOST
• EASYEDA_MCP_BRIDGE_PORT
• EASYEDA_MCP_BRIDGE_PATH
• EASYEDA_MCP_BRIDGE_TIMEOUT_MS 基桥超时（毫秒），默认值 30000
• EASYEDA_MCP_GET_DOCUMENT_SOURCE_TIMEOUT_MS 可选的每种方法重写 get_document_source
• EASYEDA_MCP_SET_DOCUMENT_SOURCE_TIMEOUT_MS 可选的每种方法重写 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

缓慢的桥梁操作，如 get_document_source, set_document_source，原始BBox查询使用更高的内部每方法超时下限，因此大型EasyEDA文档不太可能出现错误。当前服务器默认值为 60000 为了 get_document_source 和 120000 为了 set_document_source.

如果您的EasyEDA构建在大型源代码写入时仍然很慢，请设置 EASYEDA_MCP_SET_DOCUMENT_SOURCE_TIMEOUT_MS 在启动服务器时明确表示。

网桥请求也在服务器端序列化，因此EasyEDA运行时一次只处理一个正在进行的MCP操作。这减少了重叠的长时间桥接调用的不稳定性。

备注

• 扩展端取决于EasyEDA Pro对WebSocket访问的外部交互权限。
• 这个脚手架故意从一个小的、明确的工具集开始，而不是随意暴露 eda.* 执行。
• ping_bridge 和 echo_bridge 是最小的往返网桥诊断，可用于独立于文档编辑证明MCP调用路径。
• 破坏性工具是显式的MCP调用，EasyEDA扩展在删除或覆盖操作之前显示网桥侧确认对话框，除非 skipConfirmation: true 在支持的删除和源代码覆盖工具上提供。
• VS Code客户端配置格式遵循文档 mcp.json servers 本地stdio服务器的结构，Claude示例遵循文档 claude_desktop_config.json mcpServers 结构。
• 所包含的测试包括工具注册、乐观源代码写入的本地模式验证以及修订哈希稳定性，而不需要实时EasyEDA实例。
• 所包含的测试还包括桥接会话超时处理、断开连接拒绝和无序响应相关性，而不需要实时EasyEDA实例。
• 实时集成测试是有意选择的，因此正常的本地开发和CI不依赖于开放和桥接的交互式EasyEDA Pro会话。