Vivado Agent MCP

面向 AMD Vivado 的 MCP server。它让支持 MCP 的 Agent 通过结构化、受策略约束的工具执行无板卡 Vivado Project Mode PL 开发流程，并保留可诊断、可复现的工程证据。

项目状态

公开源码不代表当前版本已达到无人监督生产部署标准。当前支持范围、安全边界和已知限制以本 README 与 SECURITY.md 为准。

Related MCP server: vivado-mcp-agent

实现与验证状态

GitHub Actions 的绿色状态证明 Python、MCP 契约和发行物安装链路。仓库公开保存源提交 4bfd3dbba05dc5fab9cdb048776a70de6d75f731 的 commit-bound Vivado 2021.2 qualification record；该记录来自维护者 self-hosted Windows 环境，不表示普通 GitHub-hosted Runner 安装了 Vivado。任何后续 commit 都必须生成自己的 record，不能继承 4bfd3db 的资格；软件 qualification 也不表示真实 FPGA 硬件通过。

Commit-bound Live Vivado Qualification

仓库提供第一版正式 qualification 合约，用于把一个 Git commit、immutable source archive、exact wheel/sdist、真实 Vivado executable/build、确定性 fixture 和最终 evidence digest 绑定到同一机器可验证记录：

• Qualification record JSON Schema

• Vivado qualification matrix

• 4bfd3db public qualification record、脱敏 evidence snapshots 与 validator result

• 确定性 fixture：minimal-counter-v1，随 wheel 分发的 SystemVerilog RTL、自检查 testbench 和 XDC

• 本地 runner：tests/live_qualification_runner.py

• 手动 self-hosted workflow：.github/workflows/live-qualification.yml

资格状态含义：

qualified 只证明无板卡 Project Mode 软件流。它不会把 hardware_validation.status 从 NOT_VALIDATED 改为真实板卡通过。tracked matrix 只在审阅 qualification record 后更新；普通 Python CI、mock、fake-session、doctor 或维护者口头 smoke 都不能产生 qualified。

安全边界

• MCP list_tools 定义、core/advanced/all profile、risk、MCP annotations、Agent catalog 和 workflow tags 由同一 CapabilitySpec 投影生成；selftest 会检查公开 annotations 是否与该契约一致。

• 默认 core profile 只暴露标准 workflow、诊断和恢复工具。

• 公共 run_tcl / safe_tcl 不能执行任意 Tcl，只保留 dry-run 分类。

• 已有工程通过 Vivado 原生 open_project -read_only 与 MCP policy 双重进入 inspection-only 模式；需要执行时，Agent 必须先采集三个 fileset 的受支持逐文件语义，再在独立路径创建并核对 MCP 管理的工作工程。

• trusted XSIM 只适用于管理员已审阅并显式放入可信根的纯 RTL 工程；它不是操作系统沙箱。

• 删除、重置和清理操作默认 dry-run，并要求 identity、intent 和固定确认。

• Hardware Manager、烧录、JTAG、ILA/VIO 和真实板卡行为不属于当前验证范围。

• READY 只表示相应的软件证据就绪，绝不表示真实 FPGA 硬件通过。

详细威胁边界见 SECURITY.md。

环境要求

• Windows 10/11。

• Python 3.11 或 3.12。

• AMD Vivado 2021.2。版本证明保留完整补丁号；包括 2021.2.1 在内的其它版本当前不会继承 2021.2 的受信任资格，而是 fail-closed。

• 一个独立、可写的 runtime 目录。

• 使用 XSIM 时，显式配置经过审阅的可信工程根目录。

从源码安装

git clone https://github.com/zzszzs-lll/vivado-agent-mcp.git
cd vivado-agent-mcp
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e .

确认入口：

.\.venv\Scripts\vivado-agent-mcp.exe --help
.\.venv\Scripts\vivado-agent-mcp.exe --version

不带参数的 vivado-agent-mcp 会启动 stdio MCP server，不是人工交互式 CLI。

首次自检

先检查 Python、runtime、Vivado 路径、XSIM companion tools 和有界启动探针：

$env:VIVADO_PATH = "C:\Xilinx\Vivado\2021.2\bin\vivado.bat"
.\.venv\Scripts\vivado-agent-mcp.exe doctor

再检查 MCP stdio、工具发现、结构化响应、安全门禁和硬件边界：

.\.venv\Scripts\vivado-agent-mcp.exe selftest `
  --output-dir .\.vivado_agent_mcp\selftest

doctor 和 selftest 通过不等于已完成真实工程或真实板卡验证。

MCP 客户端配置

将下列路径替换为本机实际路径：

{
  "mcpServers": {
    "vivado-agent": {
      "command": "C:/path/to/vivado-agent-mcp/.venv/Scripts/vivado-agent-mcp.exe",
      "args": [],
      "env": {
        "VIVADO_PATH": "C:/Xilinx/Vivado/2021.2/bin/vivado.bat",
        "VIVADO_AGENT_MCP_RUNTIME_DIR": "C:/vivado-agent-mcp-runtime/runtime",
        "VIVADO_AGENT_MCP_TRUSTED_PROJECT_ROOTS": "C:/fpga-work",
        "VIVADO_AGENT_MCP_TOOL_PROFILE": "core",
        "SystemRoot": "C:/WINDOWS",
        "WINDIR": "C:/WINDOWS"
      }
    }
  }
}

可直接参考：

• 完整配置模板

• 最小配置模板

关键环境变量：

Agent 使用协议

Agent 开始 Vivado 工作时应遵循以下顺序：

1. 调用 get_tool_catalog，确认当前 profile、工具和硬件边界。

2. 调用 get_agent_workflows，选择新工程、已有工程审计、仿真修复或 handoff 流程。

3. 按 recipe 的 steps 执行，并直接消费结构化 next_actions。

4. 遇到 BLOCK、stop_required=true 或安全门禁时停止，不使用 Shell 绕过。

5. bitstream 生成只代表构建完成；完整 Agent handoff 还需要 artifact、report、signoff、audit 和 diagnostic evidence。

6. 任何无板卡结果都必须保持 hardware_validation.status=NOT_VALIDATED。

get_tool_catalog 默认返回适合 Agent 路由的紧凑 CapabilitySpec 投影；需要审计 profile、workflow tags、状态前置条件和 dispatch lane 时，传入 {"detail":"full"}。

推荐从 get_agent_workflows 选择标准路径：新工程先完成语法与有限时长仿真，再异步启动 synthesis/implementation/bitstream 并轮询；已有工程默认只读检查；bitstream 后继续收集 artifact、report、signoff、audit 和 diagnostic bundle 才算完整 handoff。

本 MCP 是 Vivado 控制与诊断平面，不负责创建或修改 RTL、SystemVerilog testbench 等源码字节。新工程和源码修复流程要求 Agent 同时具备经过用户授权的文件读取与代码编辑能力；Vivado、XSIM、run、报告和安全门禁仍应通过本 MCP 执行，不应使用 Shell 绕过。

验证范围

• python -m pytest：Python 单元测试、解析器、安全门禁、fake session 与 MCP 契约。

• tests/agent_stdio_regression.py：只通过 MCP stdio 消费 catalog、workflow、next_actions 和诊断结果。

• tests/agent_scenario_runner.py：S00-S07 Agent 场景；默认不启动 Vivado，显式 --include-live-vivado 才运行本地软件流程。

• tests/live_qualification_runner.py：使用 exact wheel、source provenance 和 S01 MCP stdio live flow 生成 commit-bound qualification record；未显式授权 live 或环境不可用时只能生成 unvalidated / unavailable 结果。

• doctor：检查本机 Python、runtime 和由实际 vivado -version 输出证明的 Vivado 版本。

• selftest：检查已安装入口、stdio、工具目录、结构化响应和安全边界。

• GitHub CI 使用 requirements/ 中按 Python 版本区分的精确版本与 SHA256 lock；发行物从 immutable git archive HEAD snapshot 构建，并逐字节核对 wheel 中的 Python package members。

• CI 使用 source-provenance.json 将当前 clean Git identity、逐字节 package manifest 与 exact wheel SHA 交叉绑定，在 Python 3.11/3.12 安装同一个 wheel，并验证 sdist；wheel、sdist、SHA256SUMS、provenance 和 smoke reports 作为短期 Actions artifact 保留。它们不是 tag、Release 或 PyPI 发布。

• 真实 FPGA、JTAG、烧录、ILA/VIO 不在当前验证范围内。

Runtime 与工程产物

• runtime 临时内容统一写入 VIVADO_AGENT_MCP_RUNTIME_DIR，可用 get_runtime_cache_status 查看，并通过 clean_runtime_cache 的 dry-run 计划安全清理。

• 工程交付物只写入工程目录内的 vmcp_artifacts、vmcp_reports、vmcp_signoff、vmcp_diagnostics 和 vmcp_constraints。

• MCP 不会把工程交付物混入统一 runtime；runtime 清理也不会删除工程内 vmcp_* 结果。

• 当前 diagnostic bundle 是绑定原工程路径和文件哈希的 project-local reference index，不是可复制到另一台机器后独立验证的 portable archive。

常见问题

• doctor 找不到 Vivado：在启动 MCP server 或 doctor 前设置 VIVADO_PATH 为可信 vivado.bat 的绝对路径。可选 --vivado-path 只能重复声明同一个 canonical 文件身份，不能选择其它 executable。

• 路径看似是 2021.2 但仍被阻断：目录名只是提示；只有实际 vivado -version 输出可以证明版本。

• 实际版本是 2021.2.1：当前验证矩阵只覆盖精确的 2021.2，补丁版本需要单独资格验证，默认会被阻断。

• Vivado GUI 无法显示：MCP 宿主必须运行在可交互的 Windows 桌面会话中。

• 仿真被 VCD 门禁阻断：使用有限 run_time，优先保留 WDB，避免 testbench 无限 dump。

• 已有工程无法直接执行：open_project 使用 Vivado -read_only 并施加 MCP inspection-only policy；按 next_actions 采集 sources_1、constrs_1、sim_1 的 file_specs，在独立路径完成语义等价重建后再执行。

• core profile 看不到硬件工具：这是默认安全策略，且真实硬件当前未验证。

开发与验证

python -m pytest
python -m compileall src
git diff --check

安装态 smoke、Agent scenario runner 和 Vivado live 验证入口见 贡献指南。

已知限制

• 当前受信任执行基线固定为 Windows 与 Vivado 2021.2；其它 Vivado 版本默认 fail-closed。

• 受信任版本不等于已完成公开 qualification；以 tracked qualification matrix 和对应 workflow artifact 为准。

• 当前主流程是 Project Mode，不覆盖 Non-Project Mode。

• 已有工程默认按 inspection-only 边界接手，避免 Agent 无意修改外部工程。

• working-copy 重建只复现当前 allowlist 中的逐文件语义，包括 file type、library、global include、used-in、XDC processing order 和 scope；发现未知、缺失或重建后不一致时会 fail-closed。

• RTL/Testbench 的创建与修改依赖 Agent 宿主提供的受控文件编辑能力；本 MCP 当前不提供 HDL 源码 patch 工具。

• diagnostic handoff 当前限于原工程可访问的 project-local reference 模式，不支持跨机器 portable bundle。

• trusted XSIM 只适用于管理员已审阅的纯 RTL/XDC 工程，不构成恶意 HDL 的操作系统级隔离。

• 真实板卡、JTAG、烧录、ILA/VIO 和 flash cfgmem 尚未验证，相关状态必须保持 NOT_VALIDATED。

• 当前版本定位为 Alpha，建议在受监督、可回滚的工程副本上使用。

参与贡献

提交 Issue 或 Pull Request 前请阅读 CONTRIBUTING.md。安全问题请按 SECURITY.md 私下报告，不要在公开 Issue 中披露利用细节。

许可证

本项目采用 Apache License 2.0。

本项目不包含或分发 AMD Vivado。用户需要自行取得、安装 Vivado，并遵守适用的 AMD 软件许可条款。

AMD、Vivado、Xilinx 及相关名称可能是其各自权利人的商标。本项目是独立开源项目，不隶属于 AMD，也不代表其官方认可或支持。