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

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:

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

Do not use:

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:

[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:

[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:

[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:

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

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