Skip to main content
Glama
Vivado Agent MCP

Vivado Agent MCP

Vivado Agent MCP

一个面向 AI Agent 的 Vivado 自动化 MCP Server。它不追求把所有 Vivado Tcl 命令逐个包装成工具,而是提供少量、状态明确、可恢复的能力,让 Agent 完成“观察 → 决策 → 执行 → 验证”的闭环。

这个项目解决什么问题

普通脚本只会按固定顺序执行;直接把任意 Tcl 暴露给大模型又缺少边界。本项目在两者之间增加一层 Agent 运行时:

AI Agent
   │  MCP: Tools / Resources / Prompts
   ▼
Vivado Agent Service
   │  状态检查、前置条件、job id、统一结果
   ▼
单个 Vivado Tcl Session
   │  唯一请求标记、串行执行、超时隔离
   ▼
Vivado Project / Runs / Logs

核心目标:

  • 让 Agent 在行动前先读取工程状态,而不是猜测;

  • 综合、实现和 bitstream 都异步启动,并返回可查询的 job id;

  • 每个 Tool 返回同一种 JSON 结构;

  • 在综合未完成、时序失败或日志存在阻断问题时拒绝危险的下一步;

  • 保留 run_tcl 作为逃生舱,但优先使用有语义的专用 Tool。

Related MCP server: vivado-mcp

MCP 能力

10 个 Tools

Tool

用途

start_vivado

启动唯一的无头 Tcl 会话,可选打开 .xpr

stop_vivado

关闭本 Server 拥有的 Vivado 进程

run_tcl

执行无法由专用 Tool 表达的 Tcl

inspect_project

读取器件、顶层、文件数和 run 状态

inspect_run

用 job id 或 Vivado run 名查询进度

run_synthesis

幂等启动综合并返回 job id

run_implementation

检查综合前置条件后启动实现

generate_bitstream

通过 readiness gate 后启动 bitstream

diagnose_run

从 runme.log 提取有界错误证据

check_build_readiness

检查 routed 状态、setup/hold slack 和阻断日志

2 个 Resources

  • vivado://project/current:当前工程快照;

  • vivado://jobs/{job_id}:某个异步任务的最近状态。

2 个 Prompts

  • vivado_build_workflow:完整构建工作流;

  • vivado_debug_workflow:失败诊断与最小修复工作流。

Agent 友好的统一返回值

每个 Tool 都返回:

{
  "ok": true,
  "state_changed": false,
  "summary": "Project demo is open.",
  "evidence": {"project": {}},
  "recommended_actions": [
    {
      "tool": "run_synthesis",
      "reason": "Synthesis has not completed.",
      "arguments": {}
    }
  ],
  "error_code": null
}

ok 表示 Tool 自身是否成功执行;业务结论放在 evidence 中。例如 readiness 检查成功,但 evidence.verdict 仍可能是 BLOCKED。

安装

要求:Python 3.10+、支持 Tcl 模式的 Vivado。项目测试不要求安装 Vivado。

cd C:\path\to\vivado-agent-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

指定 Vivado 可执行文件:

$env:VIVADO_PATH = "C:\Xilinx\Vivado\2024.2\bin\vivado.bat"

如果没有指定,程序依次检查参数、VIVADO_PATH、系统 PATH 和常见 Xilinx 安装目录。

运行与接入 Agent

本地启动 stdio MCP Server:

python -m vivado_agent_mcp

Codex/兼容客户端的配置思路见 examples/codex-config.toml。把路径改成自己的绝对路径:

[mcp_servers.vivado_agent]
command = "C:\\path\\to\\vivado-agent-mcp\\.venv\\Scripts\\python.exe"
args = ["-m", "vivado_agent_mcp"]
env = { VIVADO_PATH = "C:\\Xilinx\\Vivado\\2024.2\\bin\\vivado.bat" }

连接后可对 Agent 说:

使用 vivado_build_workflow 构建 D:\fpga\demo\demo.xpr。每个阶段都展示 evidence;遇到失败先诊断,不要绕过 readiness gate。

测试

python -m pytest -q
python -m ruff check .

默认测试使用假 Vivado 会话,覆盖协议封装、状态解析、job 幂等性、工作流前置条件和 bitstream 安全门。当前测试结果为 18/18 passed。

真实 Vivado 实验

项目已在 Vivado 2018.3 和 Artix-7 xc7a35tcpg236-1 上完成真实端到端验证:

  • MCP discovery:10 Tools、2 Resources、2 Prompts;

  • connectivity:start_vivado → inspect_project → run_tcl → stop_vivado;

  • 完整构建:synthesis、implementation、readiness gate、bitstream 全部完成;

  • timing:setup slack 7.201 ns,hold slack 0.324 ns;

  • bitstream:真实文件大小 2,192,119 bytes;

  • debug recovery:根据 [Synth 8-2715] 证据补回一个分号,错误数从 2 降为 0;

  • safety gate:缺少 create_clock 时 readiness 为 UNKNOWN,bitstream 被 BUILD_NOT_READY 阻止。

完整过程、job id、异常保护、两个真实 bug 修复和 Demo 脚本见 VIVADO_MCP_EXPERIMENT_REPORT.md。

实验目录说明

experiments/projects/ 中只应提交可复现输入:RTL、XDC 和 create_project.tcl。Vivado 生成的 .xpr、.runs、缓存、报告、DCP 和 bitstream 由 .gitignore 排除,避免把机器相关文件和大体积构建产物提交到 GitHub。

需要复现实验工程时,在安装了 Vivado 的 Windows 环境中执行对应的 create_project.tcl,再通过 MCP 工作流启动构建。默认测试不会启动 Vivado。

项目边界

第一版刻意不做 GUI 自动化、波形查看、IP Catalog、设备下载、远程 attach、自动安装和几十个同质化 Tcl wrapper。这些功能会放大代码量,却削弱“Agent 如何通过 MCP 可靠控制有状态工具”这一主线。

与参考项目相比,本项目的主要差异不是少几个 Tool,而是重新定义了抽象层:

  • 从“Vivado 命令集合”改为“Agent 决策接口”;

  • 从同步长调用改为 job id + 轮询;

  • 从自由调用改为前置条件与 readiness gate;

  • 从自然语言输出改为稳定的结构化证据和下一步建议;

  • 核心逻辑可在无 Vivado 环境中测试。

代码导航

src/vivado_agent_mcp/
├── server.py           # MCP Tools / Resources / Prompts
├── service.py          # Agent 工作流、前置条件和错误恢复
├── models.py           # 统一 JSON 返回契约
├── tcl_commands.py     # 有标签、可解析的 Tcl 查询
├── config.py           # Vivado 路径发现
├── agent_context/
│   ├── state.py        # 工程状态解析与下一步推荐
│   └── jobs.py         # 异步 job id 注册表
└── vivado/
    ├── protocol.py     # 请求编码、唯一标记和响应解析
    └── session.py      # 单 Vivado 进程与串行命令通道

想真正掌握项目,请继续阅读 docs/FROM_ZERO.md。

Available Tools

10 tools
check_build_readinessB

Gate bitstream generation on routed state, timing slack, and blocking diagnostics.

Inputs: no named parameters. Returns: ok, summary, evidence, error_code, +2 more

diagnose_runC

Extract bounded errors and critical warnings from a Vivado run log.

Inputs: run_name (required), max_issues. Returns: ok, summary, evidence, error_code, +2 more

generate_bitstreamA

Launch bitstream generation only when timing and diagnostic gates pass.

Inputs: jobs. Returns: ok, summary, evidence, error_code, +2 more

inspect_projectA

Read current project, sources, part, top module, and build-run states.

Inputs: no named parameters. Returns: ok, summary, evidence, error_code, +2 more

inspect_runB

Inspect an asynchronous job by MCP job ID or a native Vivado run name.

Inputs: job_id, run_name. Returns: ok, summary, evidence, error_code, +2 more

run_implementationB

Launch implementation only after project and synthesis prerequisites pass.

Inputs: jobs. Returns: ok, summary, evidence, error_code, +2 more

run_synthesisB

Launch synthesis idempotently and return a job ID instead of blocking.

Inputs: jobs. Returns: ok, summary, evidence, error_code, +2 more

run_tclC

Use raw Tcl as an escape hatch, then refresh project context before further actions.

Inputs: command (required), timeout_seconds. Returns: ok, summary, evidence, error_code, +2 more

start_vivadoA

Start one headless Vivado Tcl session and optionally open an existing .xpr project.

Inputs: vivado_path, project_path. Returns: ok, summary, evidence, error_code, +2 more

stop_vivadoA

Stop the Vivado process owned by this MCP server.

Inputs: no named parameters. Returns: ok, summary, evidence, error_code, +2 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct stage or concern: session lifecycle, raw Tcl escape hatch, project/run inspection, build steps, log diagnostics, and readiness gating. No two tools have overlapping purposes, and run_tcl is clearly an escape hatch rather than a duplicate.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (start_vivado, inspect_project, run_synthesis, generate_bitstream, check_build_readiness). The naming convention is uniform and predictable, making tool selection straightforward.

    Tool Count5/5

    With 10 tools, the server is well-scoped for a Vivado build automation agent, covering lifecycle, inspection, build steps, diagnostics, and gating without redundancy. Each tool has a clear responsibility and earns its place.

    Completeness5/5

    The tool surface covers the full FPGA build flow: session management, project/run inspection, synthesis, implementation, bitstream generation, and diagnostics/gating. The raw Tcl escape hatch also covers edge cases, so there are no obvious dead ends for the stated purpose.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      C
      quality
      D
      maintenance
      An AI-centric MCP server that enables automated Xilinx Vivado workflows, including project management, synthesis, implementation, and timing analysis. It allows AI agents to drive hardware design processes while integrating directly with the official Vivado GUI for visual context.
      15
      4
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A lean MCP server that lets AI agents drive Xilinx Vivado for synthesis, implementation, simulation, and diagnostics through 30 curated tools and raw Tcl execution.
      Apache 2.0
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents such as Claude Code, Cursor, and Codex to safely drive a locally installed Xilinx Vivado through MCP tools covering sessions, synthesis, implementation, timing and CDC analysis, XDC constraints, IP, waveform queries, and device programming. Includes evidence-driven workflow prompts, environment self-checks, and Chinese-language diagnostics for timing and CRITICAL WARNING issues.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents such as Claude Code, Cursor, and Codex to safely drive a locally installed Xilinx Vivado through 32 MCP tools spanning GUI/Tcl/attach sessions, synthesis, implementation, timing and CDC analysis, XDC/IO validation, IP inspection, VCD waveform queries, and device programming. It adds structured JSON timing evidence with baseline comparison, Chinese-language diagnostics for CRITICAL WARNINGs, environment self-checks, and evidence-driven workflow prompts that gate each FPGA design stage.
      -