vunit-mcp

MCP (stdio) サーバーで、LLM/エージェントが VUnit (HDL ユニットテスト) プロジェクトを最初から最後まで操作できるようにします: テストの一覧表示、コンパイル、実行、レポートやテストごとのログの検査。

VUnit にはスタンドアロンの CLI がなく、VUnit.main() は sys.exit() を呼び出すため、サーバーは vunit をプロセス内で 実行 することはありません。代わりに、人間が実行するのとまったく同じように、プロジェクト自身の run.py をシェルアウトします。意図的な例外が 1 つあります: vunit_test_dependencies は、プロセス内のプロジェクトモデルを構築して、「このテストを実装するにはどのファイルが必要か」という質問に答えます。vunit-hdl はこのパッケージのハードな依存関係であるため、インポートは常に利用可能ですが、それでも遅延インポートされ、そのツールが呼び出されたときだけインポートされます。

ロゴ

候補ロゴはすべて、公式の VUnit バッジ (青 #0c479d、白いリング、太い V) に基づいています。SVG ソースは logos/ にあり、PNG は 400×400 のプレビューです。

Related MCP server: Lupa MCP Server

Setup

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

Configuration (env vars)

MCP client config (Claude Code)

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

Or with MCP Inspector for manual testing:

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

スキル

このリポジトリにはエージェントスキル 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 が消去するプロジェクトの vunit_out は決して使用しません)。

ログサイズポリシー

ツールの出力は意図的に制限されており、LLM に優しい状態を保ちます — 生のログが完全にダンプされることはありません:

• vunit_get_test_log はデフォルトで 最後の 100 行 を返し、その旨を明示します (例: "showing last 100 of 3421 lines"); より多く取得するには lines を増やします。明示的な「完全」読み取りでも ~24 KB (ファイルの末尾) に制限されます。

• vunit_compile は成功時には 10 行の末尾を返し、失敗時には エラー行の抜粋 (エラー/致命的/失敗行 + コンテキスト 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 組み込みライブラリのソース (インストールされたパッケージファイル) は、安定しておりプロジェクトの一部ではないため、カウントとして要約されます。

Development

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/