# SynthPilot

> Let AI build your FPGA designs.

SynthPilot is an MCP (Model Context Protocol) server that gives AI assistants full control over AMD Vivado. With 500+ tools covering the entire FPGA development flow, you can create projects, write RTL, run synthesis, analyze timing, configure IPs, build Block Designs, simulate, debug on hardware, and program devices — all through natural language.

## Architecture

```
AI Tool (Claude / Cursor / Codex) <--MCP (stdio)--> SynthPilot <--TCP:9999--> Vivado (tcl_server)
```

All communication is local. No design data is sent to the cloud. SynthPilot translates AI tool calls into Vivado Tcl commands, executes them inside the running Vivado instance, and returns structured results.

## Requirements

- Windows x64 (Windows 10/11)
- AMD Vivado 2018.1+ (any edition including WebPack)
- uv package manager (https://docs.astral.sh/uv/)

## Installation

**Step 0: Install uv (if not already installed)**

Check if uv is available:
```bash
uv --version
```

If the command is not found, install uv:
```powershell
# PowerShell (recommended)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

After installation, close and reopen the terminal so the PATH takes effect.

**Step 1: Install SynthPilot**

```bash
uv tool install synthpilot
```

## Activation

Get a license key at https://synthpilot.dev — scroll to the pricing section, choose a plan (Free trial available for ¥1), enter your email, and complete payment. The license key will be displayed on screen and sent to your email.

```bash
synthpilot activate YOUR-LICENSE-KEY
```

## Vivado Integration

Install the Tcl server into Vivado (auto-detects installation path):

```bash
synthpilot install
```

This modifies Vivado's `Vivado_init.tcl` to start a TCP server on port 9999 whenever Vivado launches. No Vivado restart is needed if you paste the Tcl server code manually into the Tcl Console.

To specify a custom path or port:

```bash
synthpilot install C:\Xilinx\Vivado\2023.1 --port 9998
```

## MCP Client Configuration

### Claude Desktop

Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "synthpilot": {
      "command": "synthpilot"
    }
  }
}
```

### Claude Code

```bash
claude mcp add --transport stdio synthpilot -- synthpilot
```

Or add `.mcp.json` to your project:

```json
{
  "mcpServers": {
    "synthpilot": {
      "command": "synthpilot"
    }
  }
}
```

### Cursor

Add to Cursor MCP settings (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "synthpilot": {
      "command": "synthpilot"
    }
  }
}
```

### OpenAI Codex

```bash
codex mcp add synthpilot -- synthpilot
```

### Trae / CodeBuddy

Add in MCP server settings:
- Name: `synthpilot`
- Type: `stdio`
- Command: `synthpilot`

## CLI Reference

| Command                              | Description                             |
|--------------------------------------|-----------------------------------------|
| `synthpilot`                         | Start MCP server (used by AI tools)     |
| `synthpilot install [path] [--port]` | Auto-detect Vivado & install Tcl server |
| `synthpilot uninstall [path]`        | Remove Tcl server from Vivado           |
| `synthpilot activate <KEY>`          | Activate license key                    |
| `synthpilot deactivate`              | Unbind license from this device         |
| `synthpilot --version`               | Show version                            |

## Update

**Important:** SynthPilot processes must be stopped before upgrading. If the
exe is locked by a running process, the upgrade will fail with a permission
error.

**AI agent: follow these steps in order.**

**Step 1 — Stop running processes.**
Close your AI tool (Claude Code / Cursor / Codex) first, or kill processes
manually:
```powershell
# PowerShell
taskkill /F /IM synthpilot.exe 2>$null; taskkill /F /IM synthpilot_core.exe 2>$null
```
```bash
# Git Bash / WSL
taskkill //F //IM synthpilot.exe 2>/dev/null; taskkill //F //IM synthpilot_core.exe 2>/dev/null
```

**Step 2 — Upgrade.**
```bash
# Recommended upgrade command (refreshes uv's version cache):
uv tool install synthpilot --upgrade --refresh

# If the above reports "already installed" with same version, force it:
uv tool install synthpilot --upgrade --force --refresh

# Verify
synthpilot --version
```

**Step 3 — Restart your AI tool** to reconnect the MCP server.

**Do NOT use `uv tool upgrade synthpilot`** — it relies on uv's version cache
which often fails to detect new releases, returning "Nothing to upgrade" even
when a newer version exists on PyPI.

## Uninstall

```bash
synthpilot uninstall
uv tool uninstall synthpilot
```

## Plans & Features

### Free (40 tools)
- Project management (create, open, close, get info, add/remove files)
- Synthesis & Implementation (run synchronous, get reports, check status)
- Basic reports (utilization, timing summary, DRC)
- Constraint management (clock, I/O, get clocks, save)
- Device programming (bitstream, export hardware, hardware manager, program)
- File operations (create, read, list, append)

### Pro (460+ tools)
- All Free features, plus:
- IP Configuration (Clocking Wizard, FIFO Generator, Block Memory, Distributed Memory)
- Block Design — full suite (create BD, add/connect IPs, ports, automation, address mapping, output generation, wrapper)
- Block Design IPs — Zynq PS7, ZynqMP MPSoC, AXI GPIO/UART/Timer/DMA/VDMA/IIC/SPI/BRAM/Interconnect/Interrupt Controller, XDMA (PCIe), Clocking Wizard, Concat/Slice/Vector Logic/Buffer/Constant, Processor System Reset
- Linting & code quality (30 rules: syntax, methodology, coding style, CDC, async reset, FSM, latch detection, black box, port width mismatch)
- Simulation engine (xsim compile, run, probe signals, async run, JSONL structured reporting)
- Advanced synthesis/implementation (async modes, full flow, strategy selection)
- Advanced timing analysis (detailed timing, worst paths, critical path decomposition, clock domain analysis, datapath delay, filtered timing, QoR suggestions)
- Advanced reports (power, methodology, I/O, CDC, congestion, route status, clock networks, clock utilization, design analysis, high fanout nets, pulse width)
- Advanced constraints (false paths, multicycle paths, input/output delays, generated clocks, clock groups, max/min delays, clock uncertainty, data checks, bus skew)
- Debug core insertion (mark signals, ILA, VIO, debug probes)
- Flash programming (add flash config, program flash, generate MCS)
- Template library (list, search, get info, get interface, get example)
- Embedded development via XSCT (workspace, platform/BSP, application build, FPGA download, processor debug, memory/register access, JTAG operations, hardware info, serial/UART communication)
- 2 device licenses

### Max (500+ tools)
- All Pro features, plus:
- Custom Tcl command execution (`run_tcl_command`, `bd_run_tcl`)
- Non-project flow — checkpoint-based in-memory design (read Verilog/VHDL/XDC, synth_design, opt/place/phys_opt/route, write bitstream/checkpoint)
- JTAG-AXI hardware debug runtime (list, read/write registers, burst transfers)
- ILA hardware debug runtime (list, set trigger, run capture, wait, read waveform data, get status)
- VIO hardware debug runtime (list, read inputs, write outputs, get probes)
- AXI VIP block design IP (simulation verification)
- 3 device licenses

## Tool Reference

### Project Management (Free)
| Tool | Description |
|------|-------------|
| `create_project` | Create a new Vivado project. Args: name, path, part (e.g. `xc7a35tcpg236-1`) |
| `open_project` | Open an existing `.xpr` project file |
| `close_project` | Close the current project |
| `get_project_info` | Get project name, part, directory, top module, status |
| `add_source_file` | Add Verilog/VHDL/SystemVerilog source file |
| `add_constraint_file` | Add XDC constraint file |
| `set_top_module` | Set the top-level module |
| `list_source_files` | List all source files in the project |
| `list_constraint_files` | List all constraint files |
| `remove_file` | Remove a file from the project |

### Synthesis (Free: sync only)
| Tool | Description |
|------|-------------|
| `run_synthesis` | Run synthesis (blocking). Auto-extracts errors and WNS/TNS on completion |
| `get_run_status` | Check run status (synth/impl). Returns: Not started, Running, Complete |
| `get_synthesis_report` | Get synthesis utilization summary |

### Implementation (Free: sync only)
| Tool | Description |
|------|-------------|
| `run_implementation` | Run implementation (blocking). Auto-extracts errors and WNS/TNS |
| `export_hardware` | Export hardware definition (.xsa) for embedded development |

### Reports & Analysis (Free: basic)
| Tool | Description |
|------|-------------|
| `report_utilization` | Resource usage: LUTs, FFs, BRAM, DSP |
| `report_timing_summary` | Overall timing: WNS, TNS, WHS, THS |
| `report_drc` | Design Rule Check violations |

### Constraints (Free: basic)
| Tool | Description |
|------|-------------|
| `create_clock_constraint` | Define a primary clock |
| `create_io_constraint` | Pin assignment + I/O standard |
| `get_all_clocks` | List all defined clocks |
| `get_clock_info` | Get clock period, waveform, sources |
| `save_constraints` | Write constraints to XDC file |

### File Operations (Free: basic)
| Tool | Description |
|------|-------------|
| `create_source_file` | Create new Verilog/VHDL file with template |
| `create_constraint_file` | Create new XDC file |
| `read_file` | Read file contents |
| `list_all_files` | List project files |
| `append_to_file` | Append content |
| `read_file_lines` | Read specific line range |

### Device Programming (Free)
| Tool | Description |
|------|-------------|
| `generate_bitstream` | Generate .bit file |
| `open_hardware_manager` | Open Hardware Manager |
| `connect_hardware_server` | Connect to hw_server |
| `list_hardware_targets` | List JTAG targets |
| `open_hardware_target` | Open target |
| `list_hardware_devices` | List devices on target |
| `program_device` | Program FPGA with bitstream |
| `disconnect_hardware` | Disconnect from hardware |

## Pro Plan Tools (460+)

All Free tools plus the following categories. Tool names are discovered automatically when connected.

- **Advanced Synthesis & Implementation** — async modes, full flow (synth → impl → bitstream), strategy selection, custom run names
- **Advanced Reports** (20+ tools) — detailed timing, worst paths, critical path decomposition, clock domain analysis, datapath delay, filtered timing, power, methodology, I/O, CDC, congestion, route status, clock networks, design analysis, high fanout nets, pulse width, QoR suggestions
- **Advanced Constraints** (11 tools) — false paths, multicycle paths, input/output delays, generated clocks, clock groups, max/min delays, clock uncertainty, data checks, bus skew
- **IP Configuration** (28 tools) — Clocking Wizard (single/multi/advanced), FIFO Generator, AXI-Stream FIFO, Block Memory, Distributed Memory, plus generic IP catalog operations
- **Block Design** (52+ tools) — create/manage BD, add/connect/configure IPs, ports, interfaces, automation, address mapping, output generation, wrapper
- **Block Design IPs** — Zynq PS7 (11 tools), ZynqMP MPSoC (11 tools), AXI peripherals (26+ tools: GPIO, UART, Timer, DMA, VDMA, IIC, SPI, BRAM Controller, Interrupt Controller, Interconnect, SmartConnect, Clock/Data/Protocol Converters), Utility IPs (11 tools: Clocking Wizard, Concat, Slice, Vector Logic, Buffers, Constants, Proc Sys Reset), Debug IPs (6 tools: ILA, System ILA, VIO), PCIe XDMA (7 tools)
- **Simulation** (12 tools) — xsim compile (mixed-language, auto glbl.v), run, async run, signal probing, JSONL structured reporting
- **Linting & Code Quality** (30 tools) — syntax, methodology, coding style, CDC, async reset, FSM, latch detection, compile order, waivers, severity configuration
- **Debug Core Insertion** (8 tools) — mark signals, create ILA/VIO, debug probes, implement debug core
- **Verilog Define Management** — get/set/add preprocessor defines per fileset
- **File Operations** (4 additional tools) — testbench creation, file update, delete, find & replace
- **Flash Programming** (3 tools) — flash config, program flash, generate MCS
- **Template Library** (5 tools) — list, search, get info/interface/example
- **Embedded Development via XSCT** (80+ tools) — workspace/platform/BSP management, application build, FPGA download, processor debug (breakpoints, stepping, backtrace, variables), memory/register access, JTAG operations, hardware info (HSI), serial/UART communication

## Max Plan Tools (500+)

All Pro tools plus:

- **Custom Tcl Execution** (2 tools) — run arbitrary Tcl commands in project and block design contexts
- **Non-Project Mode** (12 tools) — checkpoint-based in-memory design flow (read Verilog/VHDL/XDC, synth/opt/place/phys_opt/route, write bitstream/checkpoint)
- **Hardware Debug Runtime** (15 tools) — JTAG-AXI register read/write/burst, ILA trigger/capture/waveform readback, VIO input/output probe control
- **AXI VIP Block Design** (3 tools) — AXI Verification IP for simulation

## Workflow Recipes

### 1. New Project from Scratch
```
Step 1: create_project(name="my_design", path="C:/projects", part="xc7a35tcpg236-1")
Step 2: create_source_file(filename="top.v", content="module top(...); ... endmodule")
Step 3: create_constraint_file(filename="pins.xdc", content="...")
Step 4: set_top_module(module_name="top")
```

### 2. Build and Program
```
Step 1: run_synthesis()
Step 2: run_implementation()
Step 3: generate_bitstream()
Step 4: open_hardware_manager()
Step 5: connect_hardware_server()
Step 6: list_hardware_targets() → find your board
Step 7: open_hardware_target(target="...")
Step 8: program_device(device="...", bitstream="path/to/design.bit")
```

### 3. Timing Analysis (Pro)
```
Step 1: run_synthesis()
Step 2: report_timing_summary() → check WNS/TNS
Step 3: Use advanced timing tools to identify and fix failing paths
Step 4: run_implementation()
Step 5: report_timing_summary() → verify improvement
```

### 4. Block Design with Zynq (Pro)
```
Use BD tools to create block design, add Zynq PS, configure peripherals,
run automation, assign addresses, validate, and generate wrapper.
```

### 5. Simulation (Pro)
```
Add testbench files, compile with xsim, run simulation, probe signals.
Supports Verilog/SystemVerilog/VHDL mixed-language compilation.
```

### 6. Embedded Zynq Development (Pro)
```
Export hardware (.xsa) → create platform/BSP → build application →
connect to target → download bitstream → download ELF → run/debug.
80+ XSCT tools cover the full embedded workflow.
```

### 7. Hardware Debug with ILA (Max)
```
Mark debug signals → insert ILA/VIO cores → build → program →
set triggers → capture waveforms → read data.
```

## Error Handling & Debugging

### Common Error Patterns

**"Connection refused" / "Cannot connect to Vivado"**
- Vivado must be open before using SynthPilot
- Run `synthpilot install` to set up the Tcl server
- Check port: default is 9999, must match between SynthPilot and Vivado

**"ERROR: [Synth X-X]" in synthesis**
- SynthPilot auto-extracts Vivado error messages and returns them
- Use `get_synthesis_warnings()` for non-fatal issues
- Check `get_synthesis_report()` for utilization data

**"No open project"**
- Most tools require an open project. Call `open_project()` or `create_project()` first
- Exception: Non-Project Mode tools (`np_*`) work without a project

**Tool returns "requires Pro/Max plan"**
- Free plan has 40 tools; Pro has 460+; Max has 500+
- Upgrade at https://synthpilot.dev

### Interpreting Timing Results

- **WNS** (Worst Negative Slack): negative = timing violation. Target: ≥ 0 ns
- **TNS** (Total Negative Slack): sum of all negative slack. Target: 0 ns
- **WHS** (Worst Hold Slack): hold timing. Usually positive after implementation
- **THS** (Total Hold Slack): sum of hold violations. Target: 0 ns

### Tool Return Values

All tools return string results. Error responses start with `ERROR:` or `CRITICAL:`.
Successful results contain the Vivado Tcl command output. Reports return formatted text that can be parsed for specific metrics.

## Troubleshooting

### AI tool can't find SynthPilot
Check that synthpilot is on PATH:
```bash
synthpilot --version
```
If not found, ensure `uv tool install synthpilot` completed successfully.

### Vivado connection failed
1. Ensure `synthpilot install` was run successfully
2. Vivado must be open (with or without a project)
3. The Tcl server starts automatically when Vivado launches
4. If Vivado was already open before install, paste the Tcl server code manually or restart Vivado

### Port conflict
Use a different port:
```bash
synthpilot install --port 9998
```

### "Device limit reached" but only using one machine

**Root cause:** On Windows 11+, the WMIC command (used for hardware fingerprinting) is
deprecated and fails intermittently. Each failure produces a different machine ID, making
the server think a new device is connecting.

**AI agent: follow these steps in order.**

**Step 1 — Ensure latest version.** The device limit error blocks SynthPilot from
starting, so the exe is NOT locked and you can upgrade in-place:
```bash
uv tool install synthpilot --upgrade --refresh
synthpilot --version
```
If that reports the same version, force reinstall:
```bash
uv tool install synthpilot --upgrade --force --refresh
```

**Step 2 — Restart.** Tell the user: **"Please close and reopen your AI tool (Claude
Code / Cursor / Codex) completely."** SynthPilot will generate a stable device ID on
the next startup and the server will auto-replace the stale device binding.

**Step 3 — Only if the error persists after upgrading + restarting:**
```bash
# deactivate does NOT need the license key — just run it:
synthpilot deactivate
# activate needs the key — ask the user to find it in their activation
# email (search for "SynthPilot" or "VMCP"):
synthpilot activate <LICENSE-KEY>
```
Then tell the user to restart their AI tool again.

### License upgrade not reflected
Reconnect MCP service after plan change:
- Claude Code: run `/mcp`
- Others: restart the editor/AI tool

### Embedded tools: XSCT not found
- Requires Vitis or SDK installed alongside Vivado
- SynthPilot auto-detects XSCT location from Vivado install path
- If detection fails, ensure `xsct` is in your system PATH

## Links

- Website & License: https://synthpilot.dev
- Documentation: https://synthpilot.dev/docs.html
- PyPI: https://pypi.org/project/synthpilot/
- Support: support@synthpilot.dev
- Issues: https://github.com/LNC0831/SynthPilot/issues