vunit-mcp

MCP-сервер (stdio), который позволяет LLM/агенту управлять VUnit-проектом (HDL-модульное тестирование) от начала до конца: перечислять тесты, компилировать, запускать и просматривать отчёты и журналы по каждому тесту.

У VUnit нет отдельного CLI, а VUnit.main() вызывает sys.exit(), поэтому сервер никогда не запускает vunit в собственном процессе — он обращается к run.py проекта, как это делал бы человек. Одно осознанное исключение: vunit_test_dependencies строит внутрипроцессную модель проекта, чтобы ответить на вопрос «какие файлы мне нужны для реализации этого теста?». vunit-hdl является жёсткой зависимостью этого пакета, поэтому импорт всегда доступен; он всё равно выполняется лениво, только при вызове этого инструмента.

Логотип

Кандидаты логотипов, все на основе официального значка 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 вместе с отпечатком (fingerprint) её входных данных и используется из файла, пока отпечаток совпадает. Кэш инвалидируется, когда:

• изменяется 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, дополнительно кэшируется в памяти по содержимому экспорта.

Внутренний каркас (scaffold)

На некоторые вопросы о VUnit нельзя ответить через собственный run.py проекта — например, «какие файлы мне нужны, чтобы реализовать этот тест?». Для таких случаев vunit-mcp строит внутрипроцессный VUnit-проект («каркас») на основе модели из --export-json: настоящий экземпляр VUnit с зарегистрированными библиотеками и исходными файлами проекта, используемый только для вызова внутреннего API VUnit (сегодня — get_implementation_subset через vunit_test_dependencies; в будущем — другие внутренние запросы).

Каркас никогда не запускается через CLI: экспортированная модель не содержит всех особенностей пользовательского run.py (пользовательские опции, атрибуты тестов, требования, …), поэтому всё, что компилируется или запускается, должно идти через собственный run.py проекта. Внутрипроцессный экземпляр живёт в project_model.InternalProject, кэшируется в памяти по содержимому экспорта и использует <project>/.vunit-mcp-cache как свою рабочую директорию (никогда — vunit_out проекта, который VUnit мог бы стереть).

Политика размера журналов

Вывод инструментов намеренно ограничен, чтобы оставаться дружелюбным к LLM — сырые журналы никогда не выгружаются целиком:

• vunit_get_test_log возвращает последние 100 строк по умолчанию и сообщает об этом (например, «показаны последние 100 из 3421 строк»); увеличьте lines для большего объёма. Даже явное чтение «полностью» ограничено ~24 КБ (хвост файла).

• 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/