Content
# DipTrace MCP
MCP server for reading, analyzing, and controlled modification of DipTrace projects through the official XML format. The repository contains two related components:
- `diptrace-mcp` — local Model Context Protocol server for Codex, Claude Desktop, and other MCP clients;
- `diptrace_mcp_bridge.exe` — plugin-bridge for working with the project that is currently open in PCB Layout or Schematic Capture.
## What already works
- Summary of the schematic or board: components, parts, pins, nets, layers, and differential pairs;
- Search for components by `RefDes`, name, value, and additional fields;
- Viewing nets with endpoints `RefDes + pin/pad`;
- Reading ERC, DRC, net classes, via styles, and routing defaults settings;
- Limited reading of the source XML by XPath;
- Safe XML edits with a mandatory number of matches;
- `dry_run` preview mode with diff;
- Protection against simultaneous modification via `SHA-256`;
- Automatic backup before each write;
- Live session with explicit completion `apply` or `cancel`;
- Offline work with exported or native XML without running DipTrace;
- `stdio` and Streamable HTTP MCP transports.
## How it works
```text
MCP Client diptrace-mcp
(Codex/Claude) <--------> analysis and safe XML edits
|
| shared state directory
v
DipTrace <--------> diptrace_mcp_bridge.exe
temporary plugin_exchange.xml
```
DipTrace officially launches the plugin as a separate `.exe`, passes it the path to a temporary XML file, and after the process is completed, imports the XML back. The bridge saves a working copy in `%LOCALAPPDATA%\DipTraceMCP`, waits for commands from the MCP server, and only after an explicit `apply` returns the modified XML to DipTrace.
## Requirements
- Windows 10/11 for live integration with desktop DipTrace;
- DipTrace with XML plugin support;
- Python 3.10 or newer;
- MCP client: Codex, Claude Desktop, or compatible application;
- PowerShell and administrator access only for installing the plugin in `C:\Program Files\DipTrace`.
Offline XML analysis also works on Linux, macOS, and WSL.
## Quick start on Windows
### 1. Install MCP server
```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 .
```
Check the launch:
```powershell
.\.venv\Scripts\diptrace-mcp.exe --help
```
### 2. Build and install DipTrace plugin
The build is performed locally, so you get an unsigned `.exe` from the source code of this repository:
```powershell
powershell -ExecutionPolicy Bypass -File .\plugin\build_bridge.ps1
```
Close all DipTrace modules. Then open PowerShell **as administrator**:
```powershell
powershell -ExecutionPolicy Bypass -File .\plugin\install_plugin.ps1
```
For a non-standard directory:
```powershell
.\plugin\install_plugin.ps1 -DipTraceDir "D:\Apps\DipTrace" -Mode Both
```
### 3. Connect to 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
```
Or add the contents of `examples/codex-config.toml` to `~/.codex/config.toml`, replacing paths with your own.
### 4. Open live session
1. Open and save the project in DipTrace.
2. Select `Tools → Plugins → DipTrace MCP Bridge`.
3. Leave the bridge window open. At this time, DipTrace is waiting for the plugin to complete - this is normal.
4. In the MCP client, write, for example:
> Check the active board: give a summary, find unconnected nets, and show DRC. Don't change anything.
5. To change, ask to show the diff first:
> Change the value of R1 to 22k. First, do a dry-run and explain the diff, then apply the edit.
6. After analysis, complete the live session via `finish_live_session(action="apply")` or `cancel`. The buttons in the bridge window do the same manually.
## Offline mode
Pass the path to the XML file within the allowed workspace to the tools:
> Call `summarize_design` for `boards/controller.xml`, then show all power nets.
For old binary `.dip`/`.dch`, first use `File → Export → DipTrace XML` in DipTrace. In versions with native XML `.dip` or `.dch`, you can analyze directly if the file itself starts with `<Source Type="DipTrace-...">`.
## Change safety
`apply_xml_edits` by default does not write anything:
1. the first call uses `dry_run=true`;
2. the server returns diff, `before_sha256`, and `after_sha256`;
3. the second call repeats the same operations with `dry_run=false` and `expected_sha256=<before_sha256>`;
4. before writing, a `.bak` is created;
5. the live project is imported into DipTrace only after a separate `finish_live_session(action="apply")`.
XML with `DOCTYPE` or `ENTITY` is declined. The server reads an explicit workspace and additional directories from `DIPTRACE_MCP_ALLOWED_ROOTS`, not an arbitrary file system.
## Limitations
- the server does not control the DipTrace GUI and does not press menu items;
- DipTrace blocks the current document while the live plugin waits for `apply`/`cancel`;
- MCP does not replace visual inspection, ERC/DRC, and engineering review;
- universal XML operations allow changing the structure, but the model must comply with the official DipTrace scheme;
- old binary projects require export to XML;
- only one live session is supported at a time;
- an unsigned bridge `.exe` may require permission from Windows Defender/SmartScreen.
## Documentation
- [Full guide in English](docs/USAGE.md)
- [Architecture and security model](docs/ARCHITECTURE.md)
- [Development and testing](docs/DEVELOPMENT.md)
- [Official DipTrace XML and plugin specifications](https://diptrace.com/support/tutorials/)
- [Official Python SDK MCP](https://github.com/modelcontextprotocol/python-sdk)
- [Connecting MCP to Codex](https://learn.chatgpt.com/docs/extend/mcp)
## Development
```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
pytest
ruff check .
```
