vhdl-rag-mcp

Ein MCP-Server (Model Context Protocol), der Coding-Agenten hochwertige semantische Suche über den VHDL-Code einer Organisation, die dazugehörige VHDL-Dokumentation und allgemeinen Quellcode (C/C++, Python, ...) bietet – alles untereinander referenziert, alles mit exakter Quellenangabe.

Der Server läuft als uvx vhdl-rag-mcp über stdio. Keine externen Dienste erforderlich: Qdrant läuft eingebettet und die Embedding-Modelle laufen lokal (ONNX via FastEmbed).

Funktionen

• Drei indexierte Domänen, ein Server. VHDL-Quellcode, Dokumentation (Markdown/reST/text) und allgemeiner Code (C/C++, Python, ...) liegen in drei Qdrant-Collections, jeweils mit einem dense- (jina v2) und einem sparse- (BM25) Vektor pro Chunk.

• Hybride Suche. Jede Abfrage nutzt Qdrants native Hybrid-Suche (dense + sparse, RRF-fused): semantische Ähnlichkeit und exaktes Identifier-Matching in einem Aufruf. Frag nach rst_n, und du bekommst es.

• VHDL-bewusstes Chunking. VHDL-Dateien werden pro Konstrukt (entity, architecture, process, package, function, component) zerlegt, mithilfe des Sprache-Servers vhdl_ls (documentSymbol mit exakten Zeilenbereichen), mit einem strukturellen Zeilenscanner als Fallback für Dateien mit Syntaxfehlern – und als letzte Option das Ganze Datei, damit nichts verloren geht.

• Strukturbewusstes Chunking für die übrigen Inhalte. Dokumentation wird pro Überschriftenabschnitt in Chunks aufgeteilt; allgemeiner Code wird mit tree-sitter (jede Sprache mit Grammatik) pro Top-Level-Funktion/Klasse in Chunks aufgeteilt, mit Gap-Chunks auf Dateiebene für nicht abgedeckten Top-Level-Code.

• Querverweise. Jeder Chunk-Payload speichert die Identifier, die er definiert oder referenziert (symbols). Die Suche akzeptiert einen symbols-Filter, der Chunks auswählt, die die angegebenen Identifier referenzieren – verbindet Dokumentation ↔ VHDL ↔ Testcode (z. B. jeden VHDL-Prozess und jede C-Funktion finden, die fifo_write berühren).

• Prioritätsbewusstes Ranking. Repositories tragen eine Kategorie (golden > approved > project > legacy oder einen expliziten priority 0–100), die einen begrenzten Bonus auf den fusionierten Score anwendet: Referenz-Repositories gewinnen bei Relevanz-Gleichstand, ohne die eigentliche Ähnlichkeit zu überdecken.

• ** exakte Quellenangabe.** Jedes Ergebnis nennt Repository, Datei, Zeilenbereich und Commit; get_source liefert den exakten aktuellen Dateiinhalt (oder einen Zeilenbereich) aus dem synchronisierten Arbeitsverzeichnis.

• Incremental, self-maintaining index. Repositories werden aus Git synchronisiert (clone/fetch/diff): implica . Nur geänderte Dateien werden neu in Chunks aufgeteilt uns neu eingebettett. Ein Hintergrund-Task synchronisiert alle sync_interval Sekunden; die unbfänger können jederzeit einen Sync oder einen vollständigen Reindex erzwingen.

• Graceful Degradation. Fehler werden pro Repository gekapselt und im Zustand festgehalten; ein defektes Repository blockiert weder die anderen noch den Server.

• Stdout ist protokollsauber. Alle Logging-Ausgaben gehen an stderr und in eine rotierende Logdatei, so dass with jedem MCP-Host bedenkenlos ausgeführt werden kann.

Related MCP server: PAMPA

Installation

Voraussetzungen:

• uv (für uvx), Python ≥ 3.12

• Git (mit deinen üblichen Zugangsdaten/SSH-Setup für private Repositories)

• Die vhdl_ls-Binärdatei (nur für Repositories mit VHDL nötig): Installiere ein Release von https://vhdl-lang.org/, sodass vhdl_ls in deinem PATH liegt, oder weise vhdl_ls_path auf die Binärdatei. Das Verzeichnis vhdl_libraries, das neben der Binärdatei ausgeliefert wird, wird automatisch erkannt.

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

Beim ersten Start erzeugt der Server sein Datenverzeichnis, lädt die Embedding-Modelle herunter (jina v2 base-code + base-en, jeweils ~Toten von MB, einmalig) und führt eine initiale Synchronisierung aller konfigfierten Repositories durch.

Configuration

Konfigdatei: ~/.config/vhdl-rag/config.toml (wird beim ersten Start, falls nicht vorhanden, mit kommentierter Vorlage erstellt).

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

Hinweise:

• ref: Ein Branchname wird bei jeder Synchronisierung geholt und verfolgt. Ein Tag oder Commit-SHA fixiert das Repository fest (eine complete vollständige 40-char Hex-SHA überspringt den Netz-Fetch vollständige).

• Domänen/Ausschlüsse pro Repository: Es wird nur das indexiert, was das Repository zum Index beitragen soll – z. B. domains = ["vhdl"] für ein reines IP-Repository, exclude = ["sim"], um simulationsspezifische Dateien zu übergehen.

• Änderung der Embedding-Modelle ändert die Dimension des dense-Vektors; der Server scheitert sonst mit einer klaren und hilfreichen Meldung, statt den Index zu korruptieren (Collection oder data_dir löschen und neu indexieren).

Verwendung

Server starten

$ uvx vhdl-rag-mcp

Er stellt MCP über stdio bereit, bis der Host die Verbindung schließt; ein Hintergrund-Task synchronisiert alle Repositories alle sync_interval Sekunden. Eine Einzelinstanz-Sperre (data_dir/server.lock) verhindert, dass zwei Server ein gemeinsames Datenverzeichnis nutzen.

Bei einem MCP-Client registrieren

Claude Code:

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

Maki (TOML-Konfiguration – prüfe die genauen Tabellennamen in der Dokumentation deiner Maki-Version):

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

Tools

Alle Suchwerkzeuge akzeptieren optionale Filter für repository (Name) und category (golden/approved/project/legacy) sowie symbols: list[str] – schränken die Ergebnisse auf Chunks ein, die einen der angegebenen Identifier referenzieren. Ergebnisse werden als Markdown mit Quellenangabe, Score und referenzierten Identifiers ausgegeben; Inhalte sind nach Domäne in Code-Fences abgegrenzt.

Beispiel für einen Agenten-Ablauf:

1. search_knowledge("asynchronous reset conventions") → einen Dokumentationsabschnitt und die VHDL-Prozesse, die Resets implementieren.

2. search_vhdl("reset", symbols=["rst_n"]) → jeden VHDL-Chunk, der rst_n berührt.

3. get_source("company-standards", "rtl/reset_ctrl.vhd", 12, 40) → die exakten Zeilen zum Kopieren.

Betrieb

• Datenverzeichnis (data_dir): Qdrant-Collections, die Git-Arbeitsverzeichnisse je Repository (<name>/), Synchronisationszustand (state/repositories.json), die Logdatei (logs/vhdl-rag-mcp.log) sowie data_dir und die Sperrdatei. Das Löschen setzt den Index zurück.

• Zustand & Retry: Der indexed_commit eines Repos wird nur dann weitergeführt, wenn seine Indexaktualisierung vollständig erfolgreich war; ein fehlgeschlagener Sync behält den vorherigen Commit, und der nächste Sync bearbeitet denselben Diff erneut. last_sync_error ist über repository_status sichtbar.

• Entfernen eines Repos aus der Konfiguration: Beim nächsten Start erkennt der Server es in der Zustandsdatei und entfernt restlos alle seine Chunks und den Zustand.

• Logs: stderr + logs/vhdl-rag-mcp.log (rotierend, 3×5 MB). log_level = "DEBUG" für Details zu LSP/Git/Embedding.

Entwicklung

$ 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

Die Testsuite läuft vollständig offline: lokale file://-Git-Remotes, ein simuliertes LSP-Server-Skript sowie simulierte Embedding-Anbieter (ein Test mit echter Binärdatei ist durch die Umgebungsvariable VHDL_LS_TEST_BIN geschützt).

Layout:

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