内容
# DipTrace MCP
MCP服务器，用于通过官方XML格式读取、分析和受控修改DipTrace项目。仓库包含两个相关组件：
- `diptrace-mcp` — 用于Codex、Claude Desktop和其他MCP客户端的本地Model Context Protocol服务器；
- `diptrace_mcp_bridge.exe` — 用于处理当前在PCB Layout或Schematic Capture中打开的项目的插件桥。
## 已实现功能
- 原理图或PCB汇总：元件、零件、引脚、网络、层和差分对；
- 按`RefDes`、名称、值和附加字段搜索元件；
- 以`RefDes + pin/pad`为终点查看网络；
- 读取ERC、DRC、网络类、过孔样式和路由默认值设置；
- 基于XPath的有限原始XML读取；
- 具有必需匹配次数的安全XML编辑；
- 带有差异的`dry_run`预览模式；
- 通过`SHA-256`防止并发修改；
- 每次写入前自动备份；
- 具有显式提交或取消的实时会话；
- 使用导出的或原生XML的离线工作，无需启动DipTrace；
- `stdio`和Streamable HTTP MCP传输。
## 系统架构
```text
MCP客户端 diptrace-mcp
(Codex/Claude) <--------> 分析和安全XML编辑
|
| 共享状态目录
v
DipTrace <--------> diptrace_mcp_bridge.exe
临时plugin_exchange.xml
```
DipTrace正式将插件作为单独的`.exe`启动，将临时XML文件路径传递给它，并在进程完成时将XML导入回DipTrace。桥保存工作副本在 `%LOCALAPPDATA%\DipTraceMCP`，等待MCP服务器的命令，只有在显式`apply`后才将修改后的XML返回给DipTrace。
## 要求
- 用于与桌面DipTrace实时集成的Windows 10/11；
- 支持XML插件的DipTrace；
- Python 3.10或更新版本；
- MCP客户端：Codex、Claude Desktop或兼容的应用程序；
- PowerShell和管理员权限仅用于将插件安装到 `C:\Program Files\DipTrace`。
离线XML分析也可在Linux、macOS和WSL上运行。
## Windows快速入门
### 1. 安装MCP服务器
```powershell
git clone https://github.com/fireostendere/mcp_diptrace.git
cd mcp_diptrace
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
```
启动检查：
```powershell
.\.venv\Scripts\diptrace-mcp.exe --help
```
### 2. 构建和安装DipTrace插件
构建在本地执行，因此您从此存储库的源代码获得未签名的`.exe`：
```powershell
powershell -ExecutionPolicy Bypass -File .\plugin\build_bridge.ps1
```
关闭所有DipTrace模块。然后以**管理员身份**打开PowerShell：
```powershell
powershell -ExecutionPolicy Bypass -File .\plugin\install_plugin.ps1
```
对于非标准目录：
```powershell
.\plugin\install_plugin.ps1 -DipTraceDir "D:\Apps\DipTrace" -Mode Both
```
### 3. 连接到Codex
```powershell
codex mcp add diptrace `
--env "DIPTRACE_MCP_WORKSPACE=C:\Users\you\Documents\DipTrace" `
-- "C:\path\to\mcp_diptrace\.venv\Scripts\diptrace-mcp.exe"
codex mcp list
```
或者，将 `examples/codex-config.toml` 的内容添加到 `~/.codex/config.toml` 中，并替换为您的路径。
### 4. 打开实时会话
1. 在DipTrace中打开并保存项目。
2. 选择 `Tools → Plugins → DipTrace MCP Bridge`。
3. 保持桥梁窗口打开。此时，DipTrace等待插件完成 - 这是正常的。
4. 在MCP客户端中，写例如：
> 检查活动板：提供摘要，查找未连接的网络并显示DRC。不要更改任何内容。
5. 要进行更改，请先显示差异：
> 将R1的值更改为22k。首先执行dry-run并解释差异，然后应用编辑。
6. 分析完成后，通过 `finish_live_session(action="apply")` 或 `cancel` 结束实时会话。桥梁窗口中的按钮也可以手动完成相同操作。
## 离线模式
将XML文件路径传递给工具：
> 对 `boards/controller.xml` 调用 `summarize_design`，然后显示所有电源网络。
对于旧二进制 `.dip`/`.dch` 文件，首先在DipTrace中使用 `File → Export → DipTrace XML`。在具有原生XML `.dip` 或 `.dch` 的版本中，可以直接分析文件，只要文件确实以 `<Source Type="DipTrace-...">` 开头。
## 变更安全
`apply_xml_edits` 默认情况下不写入任何内容：
1. 首次调用使用 `dry_run=true`；
2. 服务器返回差异、`before_sha256` 和 `after_sha256`；
3. 第二次调用使用相同的操作，`dry_run=false` 和 `expected_sha256=<before_sha256>`；
4. 在写入之前创建 `.bak` 备份；
5. 只有在单独的 `finish_live_session(action="apply")` 之后，实时项目才导入到DipTrace中。
包含 `DOCTYPE` 或 `ENTITY` 的XML被拒绝。服务器读取明确的工作空间和 `DIPTRACE_MCP_ALLOWED_ROOTS` 中的附加目录，而不是任意文件系统。
## 限制
- 服务器不控制DipTrace的GUI，也不点击菜单项；
- 在实时插件等待 `apply`/`cancel` 时，DipTrace阻止当前文档；
- MCP不取代视觉检查、ERC/DRC和工程审查；
- 通用XML操作允许更改结构，但模型必须遵守官方DipTrace模式；
- 旧二进制项目需要导出到XML；
- 同时支持一个实时会话；
- 未签名的桥接`.exe`可能需要Windows Defender/SmartScreen许可。
## 文档
- [中文完整指南](docs/USAGE_RU.md)
- [架构和安全模型](docs/ARCHITECTURE.md)
- [开发和测试](docs/DEVELOPMENT.md)
- [官方DipTrace XML和插件规范](https://diptrace.com/support/tutorials/)
- [官方Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk)
- [将MCP连接到Codex](https://learn.chatgpt.com/docs/extend/mcp)
## 开发
```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
pytest
ruff check .
```
