# vivado-mcp-agent

`vivado-mcp-agent` is a Windows-first Model Context Protocol server for Vivado 2025.2 automation. It gives Codex Desktop deterministic FPGA engineering tools: project scaffolding, Tcl generation, simulation/synthesis/implementation runs, XDC safety checks, report parsing, AXI/CDC/IP planning, gated bitstream generation, and hardware programming only after explicit confirmation.

The MCP server does not call an external LLM. Codex makes architecture/debug decisions; this server provides safe tools, parsers, templates, and Vivado batch execution.

## Why MCP

MCP lets Codex call audited tools instead of guessing shell commands. This project exposes FPGA workflows as typed tools with structured JSON results, timeouts, logs, safety gates, resources, and prompts.

## Features

- Windows 11 and Vivado 2025.2 first.
- Uses `vivado.bat`, never `vvgl.exe`.
- Detects Vivado with `VIVADO_BIN` first, then common Windows install paths.
- Starts every automated design with requirements intake, missing-info questions, assumption tracking, design-spec review, and explicit freeze.
- Generates `design_spec.yaml`, RTL/TB skeletons, XDC templates, and Tcl scripts.
- Runs whitelisted Vivado flows only: project, sim, synth, impl, DRC, CDC, bitstream.
- Parses logs, timing, utilization, power, DRC, CDC, and XDC.
- Plans AXI-Lite register banks and AXI-Stream ready/valid pipelines.
- Plans CDC and clock/reset architecture.
- Recommends Vivado IP placeholders for clock wizard, FIFO, BRAM, AXI, debug, and DDR/MIG.
- Produces `reports/summary.json`, `summary.md`, `failure_analysis.md`, `bringup_checklist.md`, and `release_report.md`.

Raw MCP clients pass tool inputs inside a `params` object because each tool is backed by a Pydantic model. Codex Desktop uses the tool schema automatically.

## Windows 11 Install

```powershell
cd C:\Users\LENOVO\Projects\vivado-mcp-agent
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e .[dev]
pytest
```

## Vivado 2025.2 Configuration

Preferred launcher:

```powershell
$env:VIVADO_BIN = "D:\Xilinx\Vivado\2025.2\2025.2\Vivado\bin\vivado.bat"
```

Do not use:

```text
D:\Xilinx\Vivado\2025.2\2025.2\Vivado\bin\unwrapped\win64.o\vvgl.exe
```

## Codex Desktop MCP Configuration

Add this to `C:\Users\LENOVO\.codex\config.toml`:

```toml
[mcp_servers.vivado]
command = "python"
args = ["-m", "vivado_mcp_agent.server"]
cwd = "C:\\Users\\LENOVO\\Projects\\vivado-mcp-agent"
tool_timeout_sec = 3600
enabled = true

[mcp_servers.vivado.env]
VIVADO_BIN = "D:\\Xilinx\\Vivado\\2025.2\\2025.2\\Vivado\\bin\\vivado.bat"
```

Python launcher alternative:

```toml
[mcp_servers.vivado]
command = "py"
args = ["-3", "-m", "vivado_mcp_agent.server"]
cwd = "C:\\Users\\LENOVO\\Projects\\vivado-mcp-agent"
tool_timeout_sec = 3600
enabled = true

[mcp_servers.vivado.env]
VIVADO_BIN = "D:\\Xilinx\\Vivado\\2025.2\\2025.2\\Vivado\\bin\\vivado.bat"
```

Project-local Python 3.12 environment alternative:

```toml
[mcp_servers.vivado]
command = "C:\\Users\\LENOVO\\Documents\\codex+vivado+MCP\\vivado-mcp-agent\\.venv\\python.exe"
args = ["-m", "vivado_mcp_agent.server"]
cwd = "C:\\Users\\LENOVO\\Documents\\codex+vivado+MCP\\vivado-mcp-agent"
tool_timeout_sec = 3600
enabled = true

[mcp_servers.vivado.env]
VIVADO_BIN = "D:\\Xilinx\\Vivado\\2025.2\\2025.2\\Vivado\\bin\\vivado.bat"
```

## Examples

### led_blink

Open `examples/led_blink`. Replace placeholder LED and clock pins in `constraints/top.xdc` with board-verified pins, then run:

```powershell
vivado_check_env
vivado_analyze_xdc
vivado_run_sim
vivado_run_synth
vivado_run_impl
```

### uart_loopback

Use `examples/uart_loopback` for a UART RX/TX skeleton. Set real UART pins and baud parameters before synthesis.

### AXI-Lite

Use `vivado_generate_axi_lite_plan` and `examples/axi_lite_register_bank` to create a register-bank contract with address map, register map, strobe behavior, reset behavior, and protocol checks.

### AXI-Stream

Use `vivado_generate_axi_stream_plan` and `examples/axi_stream_pipeline` for ready/valid pipeline contracts and backpressure tests.

## From One Requirement to Bitstream

1. `vivado_start_requirements_intake`
2. `vivado_validate_requirements`
3. `vivado_generate_missing_info_questions` when required fields or hardware-critical assumptions remain.
4. `vivado_update_requirements` after the user answers.
5. `vivado_generate_design_spec_from_requirements`
6. `vivado_review_design_spec`
7. `vivado_freeze_design_spec` with `confirm=true`
8. `vivado_create_project_scaffold`
9. Review generated RTL/TB/XDC.
10. `vivado_check_design_against_requirements`
11. `vivado_analyze_xdc`
12. `vivado_run_sim`
13. `vivado_run_synth`
14. `vivado_run_impl`
15. `vivado_parse_timing_report`, `vivado_parse_utilization_report`, `vivado_run_drc`, `vivado_run_cdc`
16. `vivado_build_bitstream` only when the frozen design spec, timing, and DRC gates pass.

Programming is never part of default workflow. Use `vivado_program_device` separately with `confirm=true`.

## Requirements And Design Planning Gate

All uncertain facts go into `assumptions` with risk `low`, `medium`, `high`, or `hardware_critical`. Hardware-critical assumptions must be confirmed before `design_spec.yaml` can be frozen. `vivado_workflow_run` always calls `vivado_requirement_gate` first. If requirements or the frozen design spec are missing, the workflow is blocked and returns the exact questions Codex should ask next.

## Safety Policy

- No arbitrary shell execution.
- `subprocess.run(..., shell=False)` with list arguments only.
- All paths are restricted to project/workspace roots.
- `vivado_program_device` requires `confirm=true`.
- DRC ERROR blocks bitstream by default.
- Timing failure blocks bitstream by default.
- Missing `create_clock` is a critical warning.
- Duplicate `PACKAGE_PIN` is an error.
- PACKAGE_PIN without IOSTANDARD is a warning.
- XDC timing exceptions and real board pin edits are high risk.

## Board Registry

Board YAML supports `board_name`, `vendor`, `part`, `clocks`, `resets`, `buttons`, `switches`, `leds`, `uart`, `spi`, `i2c`, `pmod`, `gpio`, optional `ddr`, and optional `xdc_template`. Validate with `vivado_validate_board_file`, then generate a template with `vivado_generate_xdc_from_board`.

## Timing Closure

Use `vivado_timing_closure_advice`. It classifies deep combinational paths, high fanout, unconstrained paths, missing generated clocks, CDC-like paths, IO timing issues, routing congestion, and clock uncertainty. It never auto-applies `set_false_path` or `set_multicycle_path`.

## CDC Analysis

Use `vivado_generate_cdc_plan`, `vivado_run_cdc`, `vivado_parse_cdc_report`, and `vivado_cdc_advice`. Multi-bit CDC should use async FIFO or protocol handshakes. Async reset deassertion should be synchronized per domain.

## XDC Safety

Use `vivado_analyze_xdc` before implementation and after any constraint change. `vivado_xdc_fix_advice` provides advice only by default.

## Open Source Release

```powershell
git init
git add .
git commit -m "feat: release vivado-mcp-agent v0.1.0"
gh repo create vivado-mcp-agent --public --source . --remote origin
git push -u origin main
git tag v0.1.0
git push origin v0.1.0
gh release create v0.1.0 --title v0.1.0 --notes-file CHANGELOG.md
```