vunit-mcp

MCP-(stdio)-Server, mit dem ein LLM/Agent ein VUnit-Projekt (HDL-Unit-Tests) durchgängig steuern kann: Tests auflisten, kompilieren, ausführen und Berichte sowie Logs pro Test einsehen.

VUnit hat keine eigenständige CLI und VUnit.main() ruft sys.exit() auf. Der Server führt VUnit also nicht im eigenen Prozess aus – er stößt das projekteigene run.py als externen Prozess an, genau so, wie es auch ein Mensch täte. Eine bewusste Ausnahme: vunit_test_dependencies erstellt ein In-Process-Projektmodell, um die Frage „Welche Dateien brauche ich, um diesen Test zu implementieren?“ zu beantworten. vunit-hdl ist eine feste Abhängigkeit dieses Pakets, daher ist der Import immer verfügbar; importiert wird es trotzdem lazy, nur wenn dieses Werkzeug aufgerufen wird.

Logo

Kandidatenlogos, alle auf dem offiziellen VUnit-Badge basierend (blau #0c479d, weißer Ring, kräftiges V). Die SVG-Quellen liegen in logos/; PNGs sind 400×400-Vorschauen.

Related MCP server: Lupa MCP Server

Einrichtung

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

Konfiguration (Umgebungsvariablen)

MCP-Client-Konfiguration (Claude Code)

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

Oder mit MCP Inspector für manuelle Tests:

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

Skill

Dieses Repo enthält einen Agenten-Skill, skills/vunit-mcp/SKILL.md, der dem LLM erklärt, wann und wie die Werkzeuge eingesetzt werden: welches Werkzeug welche Anfrage beantwortet, Workflow-Rezepte („Warum ist Test X fehlgeschlagen?“ → vunit_get_test_log), das Testname-Format lib.entity[.fix] und die VUNIT_MCP_*-Konfiguration. Installiere ihn direkt daneben, damit ihn der Agent automatisch findet.

Claude Code

Symlinks halten den Repo-Checkout als alleinige maßgebliche Quelle (mit cp -r kopieren, falls eine statische Installation bevorzugt wird):

# 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 lädt Skills aus demselben Verzeichnis ~/.claude/skills/:

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

Werkzeuge

Export-Cache

vunit_export_json und vunit_test_dependencies führen bei jedem Aufruf nicht erneut run.py --export-json aus: Das exportierte Modell wird samt Fingerprint seiner Eingaben nach <project>/.vunit-mcp-cache/export.json geschrieben und wird solange aus dieser Datei geliefert, wie der Fingerprint passt. Der Cache wird ungültig, wenn:

• sich Änderung der mtage oder Größe einer registrierten Quelldatei ändert oder die Datei verschwindet;

• sich run.py selbst ändert (umfasst Hinzufügen/Entfernen/Verschieben von Dateien);

• sich VUNIT_MCP_PYTHON, VUNIT_MCP_SIMULATOR oder VUNIT_MCP_EXTRA_ARGS ändern.

Dateien, die zu VUNIT_MCP_FINGERPRINT_EXCLUDE passen (dk kommssparierte fnmatch-Globs auf Dateinamen, projektrelative Pfade oder Verzeichnisnamen), sind von der ersten Regel ausgenommen – ihr mtime bzw. ihre Größe wird nicht mitverfolgt, gedacht für generierte oder flüchtige Dateien, deren Neuschreiben den Cache sonst ständig ungültig machen würde. Name und Existenz werden weiterhin mitverfolgt, daher macht das Hinzufügen oder Entfernen den Cache wie gewohnt ungültig.

Um einen frischen Export zu erzwingen, lösche .vunit-mcp-cache/export.json. Das In-Process-Projektmodell von vunit_test_dependencies wird zusätzlich im Speicher gecacht, mit dem Exportinhalt als Schlüssel.

Internes Grundgerüst

Einige VUnit-Fragen lassen sich nicht über den eigenen run.py-CLI des Projekts beantworten – etwa „Welche Dateien brauche ich, um diesen Test zu implementieren?“. Dafür baut vunit-mcp aus dem gecachten --export-json-Modell ein In-Process-VUnit-Projekt („das Grundgerüst“) Psychology auf: eine echte VUnit-Instanz with registrierten Bibliotheken und Quelldateien des Projekts ist, die ausschließlich dazu dient, die interne API von VUnit aufzurufen (heute get_implementation_subset über vunit_test_dependencies; weitere interne Abfragen werden darauf aufbauen).

Das Grundgerüst wird nie über die CLI ausgeführt: Das Exportmodell enthielt nicht alle run.py-Besonderheiten des Benutzers (benutzerdefinierte Optionen, Testattribute, Anforderungen, …), also muss alles, was kompiliert oder läuft, durch das projekteigene run.py laufen. Die In-Process-Instanz lebt in project_model.InternalProject, wird pro Exportinhalt im Speicher gecacht und verwendet <project>/.vunit-mcp-cache als Scratch-Verzeichnis (niemals das vunit_out des Projekts, das VUnit löschen würde).

Begrenzung der Loggröße

Die Ausgabe der Werkzeuge ist bewusst begrenzt, damit sie LLM-freundlich bleibt – Roh-Logs werden niemals vollständig ausgegeben:

• vunit_get_test_log liefert standardmäßig die letzten 100 Zeilen und weist darauf hin (z. B. „showing last 100 of 3421 lines“); lines erhöhen, um mehr zu erhalten. Auch ein explizites „vollständiges“ Lesen bleibt auf etwa 2 KB (am Ende) gedeckelt.

• vunit_compile liefert bei Erfolg die letzten 10 Zeilen und bei Misserfolg einen Auszug der Fehlerzeilen (Fehler-/Fatal-/Failure-Zeilen plus 2 Kontextzeilen).

• Alle anderen Fallbacks auf Rohausgaben (fehlgeschlagenes run.py, unparsebare Ausgabe) werden am Ende auf 4 000 Zeichen gekürzt, damit das Ende erhalten bleibt, wo Fehler- und Ergebniszeilen liegen.

• vunit_run_tests / vunit_get_report liefern die geparste JUnit-Zusammenfassung (Anzahlen und Namen der fehlgeschlagenen Tests) statt der Rohausgabe.

• vunit_export_json gibt das JSON nur unterhalb von 8 000 Zeichen aus; darüber enthält die Ausgabe Zählungen und Listen der Datei-/Testnamen.

• vunit_list_files / vunit_export_json listen nur Projektdateien auf; eingebettete VUnit-Quellbibliotheken (installierte Paketdateien) werden als Anzahl zusammengefasst, da sie stabil und nicht Teil des Projekts sind.

Entwicklung

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/