vhdl-rag-mcp

コーディングエージェントに対して、組織内のVHDLコード、VHDL関連ドキュメント、および一般的なソースコード（C/C++、Python、...）に対する高品質なセマンティック検索を提供するMCP（Model Context Protocol）サーバーです。すべて相互参照され、すべてに正確なソース帰属が付きます。

uvx vhdl-rag-mcp としてstdio上で動作します。外部サービスは不要です。Qdrantは組み込みで動作し、埋め込みモデルはローカルで動作します（FastEmbedによるONNX）。

機能

• 3つのインデックス対象ドメイン、1つのサーバー。 VHDLソース、ドキュメント（Markdown/reST/text），および一般的なコード（C/C++、Python、...）は、3つのQdrantコレクションに格納されます。各チャンクには、denseベクトル（jina v2）と sparseベクトル（BM25）の両方を持ちます。

• ハイブリッド検索。 すべてのクエリは、Qdrantのネイティブなハイブリッド（dense + sparse、RRF融合）クエリを実行します。意味的な類似性と正確な識別子の一致を、1回の呼び出しで実現します。rst_n で検索すれば、確実に結果が得られます。

• VHDL対応のチャンク分割。 VHDLファイルは、vhdl_ls 言語サーバーのdocumentSymbol（正確な行範囲）を使用して、コンストラクト（entity、architecture、process、package、function、component）ごとにチャンク化されます。構文エラーがあるファイルには構造的な行スキャナーによるフォールバックがあり、さらにファイル全体をチャンクとする最終手段も備えているため、VHDLが失われることは決してありません。

• 構造を意識したチャンク分割。 ドキュメントは見出しセクションごとに分割され、一般的なコードはtree-sitter（文法を持つ任意の言語）によってトップレベルの関数・クラスごとに分割されます。カバーされていないトップレベルのコードには、ファイルスコープのギャップチャンクも生成されます。

• 相互参照。 各チャンクのペイロードには、定義または参照する識別子（symbols）が格納されます。検索ツールは、指定された識別子を参照するチャンクに一致するsymbolsフィルターを受け付け、ドキュメント ↔ VHDL ↔ ソースコードを相互に結び付けます（例：fifo_write に触れるすべてのVHDLプロセスとC関数を見つける）。

• 優先度を考慮したランキング。 リポジトリには、カテゴリ（golden > approved > project > legacy）または明示的なpriority（0〜100）が付与されます。このため、融合スコアに制限付きボーナスが適用され、参照リポジトリは関連性タイブレークで優先されますが、真の類似度が埋もれることはありません。

• 正確なソース帰属。 すべての結果は、リポジトリ、ファイル、行範囲、およびコミットを特定します。get_source は、同期済みの作業ツリーから現在の正確なファイル（または行範囲）を返します。

• インクリメンタルで自己保守型のインデックス。 リポジトリはGit（clone/fetch/diff）から同期されます。変更されたファイルだけが再チャンク化・再埋め込みされます。バックグラウンドタスクが sync_interval 秒ごとに同期を実行します。ツールからは、いつでも強制同期または完全な再インデックスを実行できます。

• 优雅な縮退動作。 障害はリポジトリごとに分離され、状態に記録されます。壊れたリポジトリが他のリポジトリやサーバー自体をブロックすることはありません。

• 標準出力はプロトコル的にクリーン。 すべてのログはstderrとローテーション式ログファイルに出力されるため、サーバーはどのMCPホストからでも安全に実行できます。

Related MCP server: PAMPA

インストール

必要なもの:

• uv（uvx を使用）、Python ≥ 3.12

• Git（プライベートリポジトリには通常の認証情報・SSH設定を使用）

• vhdl_ls バイナリ（VHDLを含むリポジトリにのみ必要）: <https://vhdl-lang.org/> からリリースをインストールし、vhdl_ls を PATH に通すか、vhdl_ls_path にバイナリを指定します。このバイナリに付属する vhdl_libraries ディレクトリは自動検出されます。

$ uvx vhdl-rag-mcp --help
# (the server speaks MCP over stdio; --help is not a flag — see "Usage")

初回起動時、サーバーはデータディレクトリを作成し、埋め込みモデル（jina v2 base-code と base-en、各数十MB、初回のみ）をダウンロードし、設定されているすべてのリポジトリの初期同期を実行します。

設定

設定ファイル: ~/.config/vhdl-rag/config.toml（最初の実行時に存在しない場合は、コメント付きテンプレートが作成されます）。

data_dir = "~/.local/share/vhdl-rag"   # all state lives here
sync_interval = 300                    # seconds between periodic syncs
vhdl_ls_path = "vhdl_ls"               # binary on PATH or full path
log_level = "INFO"

[embeddings]
vhdl_model = "jinaai/jina-embeddings-v2-base-code"  # per-collection dense models
docs_model = "jinaai/jina-embeddings-v2-base-en"
code_model = "jinaai/jina-embeddings-v2-base-code"
sparse_model = "Qdrant/bm25"           # one shared sparse model

[qdrant]
mode = "local"                         # embedded (default) — or "server" with url
# url = "http://qdrant:6333"

[[repositories]]
name = "company-standards"             # unique, [A-Za-z0-9._-]
url = "git@github.com:company/vhdl-standards.git"
ref = "main"                           # branch (tracked on every sync),
                                       # tag, or commit SHA (pinned)
category = "golden"                    # golden | approved | project | legacy
priority = 100                         # optional 0-100 (defaults by category:
                                       # golden=100, approved=90, project=70, legacy=20)
# domains = ["vhdl", "docs", "code"]   # which domains to index (default: all)
# exclude = ["sim", "build/*", "*.log"]# glob path excludes ('*' crosses '/');
                                       # wildcard-free patterns exclude the subtree

注記:

• ref: ブランチ名は、同期のたびにフェッチされ追跡されます。タグまたはコミットSHAを指定するとリポジトリを固定できます（完全な40桁の16進SHAを指定した場合、ネットワークフェッチは完全にスキップされます）。

• リポジトリごとのドメイン・除外設定: リポジトリが貢献すべき部分のみをインデックスする設定です。例：付与される純粋なIPリポジトリでは domains = ["vhdl"]、シミュレーション専用ファイルを除く場合は exclude = ["sim"] のように指定します。

• 埋め込みモデルの変更: denseベクトルの次元が変わるため、インデックスを横壊して壊すのではなく、サーバーは実行可能なメッセージと一緒に明確に失敗します（その場合はコレクションまたは data_dir を削除して再インデックスしてください）。

使用方法

サーバーの起動

$ uvx vhdl-rag-mcp

サーバーは、ホストが接続を閉じるまでstdio経由でMCPを提供します。バックグラウンドタスクは sync_interval 秒ごとに全リポジトリを同期します。単一インスタンスのロック（data_dir/server.lock）により、まれに2つのサーバーが同じデータディレクトリを共有することを防ぎます。

MCPクライアントへの登録

Claude Code:

$ claude mcp add vhdl-rag-mcp -- uvx vhdl-rag-mcp

Maki（TOML設定 — 正確なテーブル名は、お使いのMakiバージョンのドキュメントを確認してください）:

[mcp_servers.vhdl_rag_mcp]
command = "uvx"
args = ["vhdl-rag-mcp"]

ツール

すべての検索ツールでは、オプションの repository（名前）と category（golden/approved/project/legacy）に加え、symbols: list[str] を受け取ります。指定された識別子のいずれかを参照するチャンクのみに結果を絞り込めます。結果は、ソースの帰属、スコア、参照された識別子とともにMarkdownでレンダリングされ、コンテンツはドメインごとにマークされます。

エージェントの活用例:

1. search_knowledge("asynchronous reset conventions") → リセットを実装するVHDLプロセスと、対応するドキュメントセクションが取得されます。

2. search_vhdl("reset", symbols=["rst_n"]) → rst_n に触れるすべてのVHDLチャンクが取得されます。

3. get_source("company-standards", "rtl/reset_ctrl.vhd", 12, 40) → そのまま使用できる正確な行を取得します。

運用

• データディレクトリ（data_dir）: Qdrantコレクション、リポジトリごとのGit作業ツリー（<name>/）、同期状態（state/repositories.json）、ログファイル（logs/vhdl-rag-mcp.log）、ロックファイルを格納します。削除するとインデックスがリセットされます。

• 状態と再試行: リポジトリの indexed_commit は、インデックスの更新が完全に成功した場合にのみ進みます。失敗した同期では前回のコミットが保持され、次の同期で同じ差分を再試行します。last_sync_error は repository_status で確認できます。

• リポジトリを設定から外す場合: 次回起動時に、サーバーは状態ファイルで外されたリポジトリを検出し、そのチャンクと状態を自動的に破棄します。

• ログ: stderr と logs/vhdl-rag-mcp.log（（ローテーション、3×5MB）。log_level = "DEBUG" でLSP/Git/埋め込みの詳細を出力します。

開発

$ uv sync
$ uv run ruff format -q . && uv run ruff check .   # format + lint
$ uv run mypy src                                   # strict types
$ uv run pytest -q                                  # offline test suite

テストスイート、完全なオフライン動作をします: ローカルの file:// Gitリモート、偽のLSPサーバースクリプト、および偽の埋め込みプロバイダー（実際のバイナリを使ったテストは VHDL_LS_TEST_BIN 環境変数が設定された場合のみ実行されます）。

レイアウト:

src/vhdl_rag_mcp/
  config.py        typed config (pydantic) + default template
  state.py         atomic repository sync state
  git_manager.py   async clone/fetch/checkout + incremental SyncPlan
  routing.py       extension -> domain classification (+domains/excludes)
  lsp/client.py    vhdl_ls LSP client (handshake, quiet-wait, symbols)
  embeddings/      FastEmbed dense/sparse providers (per-collection + shared)
  vector_store.py  Qdrant wrapper: hybrid RRF query, payload filters
  indexing/        vhdl (LSP-primary), docs (sections), code (tree-sitter),
                   pipeline (incremental sync driver)
  retrieval.py     search service: fusion, priority bonus, source access
  server.py        FastMCP tools + startup + periodic sync + lock