vunit-mcp

一个 MCP（stdio）服务器，让 LLM/智能体能够端到端驱动 VUnit（HDL 单元测试）项目：列出测试、编译、运行，并查看报告和每个测试的日志。

VUnit 没有独立的 CLI，且 VUnit.main() 会调用 sys.exit()，因此服务器从不在进程内运行 vunit——它通过 shell 调用项目自己的 run.py，就像人类运行它一样。一个刻意的例外：vunit_test_dependencies 会在进程内构建项目模型，以回答“实现这个测试需要哪些文件？”。vunit-hdl 是本包的硬依赖，因此导入始终可用；但它仍然采用惰性导入，仅在使用该工具时才加载。

Logo

候选 Logo，均基于官方 VUnit 徽章（蓝色 #0c479d、白色圆环、粗体 V）。SVG 源文件位于 logos/；PNG 为 400×400 预览图。

Related MCP server: Lupa MCP Server

设置

uv venv .venv
uv pip install -e .            # installs vunit-mcp + mcp + pydantic + vunit-hdl
# compile/run also need a simulator, in the env that runs run.py
# (default: this same venv):
uv pip install ghdl

环境变量（配置）

MCP 客户端配置（Claude Code）

{
  "mcpServers": {
    "vunit": {
      "command": "/home/sebbe/git/vunit-mcp/.venv/bin/vunit-mcp",
      "env": {
        "VUNIT_MCP_PROJECT_DIR": "/path/to/your/vunit/project"
      }
    }
  }
}

或使用 MCP Inspector 进行手动测试：

VUNIT_MCP_PROJECT_DIR=/path/to/project npx @modelcontextprotocol/inspector \
  /home/sebbe/git/vunit-mcp/.venv/bin/python -m vunit_mcp

技能（Skill）

本仓库附带一个智能体技能 skills/vunit-mcp/SKILL.md，它告诉 LLM 何时以及如何使用这些工具：哪个工具回答哪种请求、工作流配方（“测试 X 为什么失败？”→ vunit_get_test_log）、lib.entity[.proc] 测试名称格式，以及 VUNIT_MCP_* 配置。将其安装到服务器旁边，智能体即可自动加载。

Claude Code

符号链接可保持仓库检出为唯一事实来源（若你更喜欢静态安装，可用 cp -r 复制）：

# personal — available in every project
ln -s /path/to/vunit-mcp/skills/vunit-mcp ~/.claude/skills/vunit-mcp

# or project-local — available only in that project
mkdir -p <your-project>/.claude/skills
ln -s /path/to/vunit-mcp/skills/vunit-mcp <your-project>/.claude/skills/vunit-mcp

Maki

Maki 从相同的 ~/.claude/skills/ 目录加载技能：

ln -s /path/to/vunit-mcp/skills/vunit-mcp ~/.claude/skills/vunit-mcp

工具

导出缓存

vunit_export_json 和 vunit_test_dependencies 不会在每次调用时都重新运行 run.py --export-json：导出的模型会连同其输入的指纹一起写入 <project>/.vunit-mcp-cache/export.json，只要指纹匹配就从该文件提供数据。缓存在以下情况失效：

• 任何已注册源文件的 mtime 或大小发生变化，或文件消失；

• run.py 本身发生变化（涵盖添加/移除/移动文件）；

• VUNIT_MCP_PYTHON、VUNIT_MCP_SIMULATOR 或 VUNIT_MCP_EXTRA_ARGS 发生变化。

匹配 VUNIT_MCP_FINGERPRINT_EXCLUDE（逗号分隔的 fnmatch 通配符，针对文件名或项目相对路径，或目录名）的文件不受第一条规则约束——不跟踪其 mtime/大小，适用于生成文件或易变文件（其重写会导致缓存频繁失效）。但它们的名称和存在性仍被跟踪，因此添加或移除此类文件仍会使缓存失效。

如需强制刷新导出，请删除 .vunit-mcp-cache/export.json。vunit_test_dependencies 使用的进程内项目模型还会按导出内容为键在内存中额外缓存。

内部脚手架

有些 VUnit 问题无法通过项目自己的 run.py CLI 回答——例如“实现这个测试需要哪些文件？”。为此，vunit-mcp 会从缓存的 --export-json 模型构建一个进程内 VUnit 项目（“脚手架”）：一个真实的 VUnit 实例，注册了项目的库和源文件，仅用于调用 VUnit 的内部 API（目前是 vunit_test_dependencies 中的 get_implementation_subset；未来更多内部查询将在此基础上构建）。

脚手架绝不通过 CLI 运行：导出模型并不包含用户 run.py 的全部细节（自定义选项、测试属性、需求等），因此任何需要编译或运行的操作都必须通过项目自己的 run.py 进行。进程内实例位于 project_model.InternalProject，按导出内容在内存中缓存，并使用 <project>/.vunit-mcp-cache 作为其临时目录（绝不使用项目的 vunit_out，因为 VUnit 会清空该目录）。

日志大小策略

工具输出被有意限制，以保持对 LLM 友好——原始日志从不完整转储：

• vunit_get_test_log 默认返回最后 100 行并明确说明（例如“显示 3421 行中的最后 100 行”）；需要更多可增加 lines。即使显式请求“完整”读取，也限制在约 24 KB（文件的尾部）。

• vunit_compile 成功时返回 10 行尾部，失败时返回错误行摘录（error/fatal/failure 行 + 2 行上下文）。

• 所有其他原始输出回退（失败的 run.py、无法解析的输出）均截断为尾部 4 000 字符，保留错误和结果行所在的结尾部分。

• vunit_run_tests / vunit_get_report 返回解析后的 JUnit 汇总（计数 + 失败的测试名），而非原始输出。

• vunit_export_json 仅在 JSON 小于 8 000 字符时内联；超过该长度则返回计数 + 文件/测试名称列表。

• vunit_list_files / vunit_export_json 仅列出项目文件；VUnit 内置库源文件（已安装包中的文件）汇总为计数，因为它们稳定且不属于项目。

开发

uv pip install -e ".[dev]"
uv run pytest tests/          # pure parsers — no simulator required
uv run ruff check src/ tests/
uv run mypy src/vunit_mcp/