vhdl-rag-mcp

Un servidor MCP (Model Context Protocol) que ofrece a los agentes de programación una búsqueda semántica de alta calidad sobre el código VHDL de una organización, la documentación relacionada con VHDL y el código fuente general (C/C++, Python, ...) — todo con referencias cruzadas y con atribución exacta de la fuente.

Se ejecuta como uvx vhdl-rag-mcp por stdio. No se requieren servicios externos: Qdrant se ejecuta embebido y los modelos de embeddings se ejecutan localmente (ONNX mediante FastEmbed).

Capacidades

• Tres dominios indexados, un único servidor. El código fuente de VHDL, la documentación (Markdown/reST/texto) y el código general (C/C++, Python, ...) residen en tres colecciones de Qdrant, cada una con un vector denso (jina v2) y un vector disperso (BM25) por fragmento.

• Búsqueda híbrida. Cada consulta ejecuta la búsqueda híbrida nativa de Qdrant (denso + disperso, fusionada con RRF): la similitud semántica y la coincidencia exacta de identificadores en una sola llamada. Pregunta por rst_n y lo obtienes.

• Segmentación específica de VHDL. Los archivos VHDL se dividen en fragmentos por constructo (entidad, arquitectura, proceso, paquete, función, componente) mediante el servidor de lenguaje vhdl_ls (documentSymbol con rangos de línea exactos), con un escáner estructural de líneas como alternativa para archivos con errores de sintaxis, y un último recurso que indexa el archivo completo para que nunca se pierda código VHDL.

• Segmentación estructural en el resto de contenidos. La documentación se divide en fragmentos por sección de encabezado; el código general se divide por función/clase de nivel superior mediante tree-sitter (cualquier lenguaje con una gramática), con fragmentos de relleno de ámbito de archivo para el código de nivel superior no cubierto.

• Referencias cruzadas. La carga de cada fragmento almacena los identificadores que define o a los que referencia (symbols). Las herramientas de búsqueda aceptan un filtro symbols que restringe los resultados a los fragmentos que referencia los identificadores dados — pertencenting un puente entre documentación ↔ VHDL ↔ código de prueba (por ejemplo, encontrar cada proceso VHDL y función en C que toquen fifo_write).

• Ranking con prioridad. Los repositorios tienen una categoría (golden > approved > project > legacy) o una priority explícita de 0 a 100 que aplica una bonificación acotada a la puntuación fusionada: los repositorios de referencia ganan los empates de relevancia sin ahogar la similitud real.

• Atribución exacta de la fuente. Cada resultado nombra repositorio, archivo, rango de líneas y commit; get_source devuelve el contenido exacto del archivo actual (o un rango de líneas) desde el árbol de trabajo sincronizado.

• Índice incremental y que se mantiene solo. Los repositorios se sincronizan desde Git (clone/fetch/diff): solo los archivos modificados se vuelven a fragmentar y se vuelven a generar sus embeddings. Una tarea en segundo plano sincroniza cada sync_interval segundos; las herramientas pueden forzar una sincronización o un reindexado completo en cualquier momento.

• Degradación controlada. Los fallos se aíslan por repositorio y se registran en el estado; un repositorio roto no bloquea a los demás ni al servidor.

• Salida estándar limpia de protocolo. Todo el logging va a stderr y a un archivo de registro rotativo, por lo que el servidor se puede ejecutar desde cualquier host MCP.

Related MCP server: PAMPA

Instalación

Requisitos:

• uv (para uvx), Python ≥ 3.12

• Git (con tus credenciales normales o configuración SSH para repositorios privados)

• El binario vhdl_ls (solo necesario en los repositorios que contengan VHDL): instal una release desde https://vhdl-lang.org/ para tener vhdl_ls en tu PATH, o indica en vhdl_ls_path la ruta al binario. El directorio vhdl_libraries que se distribuye junto al binario se detecta automáticamente.

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

En el primer arranque el servidor crea su directorio de datos, descarga los modelos de embeddings (jina v2 base-code + base-en, ~decenas de MB cada uno, una sola vez) y realiza la sincronización inicial de todos los repositorios configurados.

Configuración

Archivo de configuración: ~/.config/vhdl-rag/config.toml (se crea con una plantilla comentada en el primer arranque si no existe).

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

Notas:

• ref: se obtiene y se mantiene el seguimiento de una rama en cada sincronización. Una etiqueta o un SHA de commit fija el repositorio (un SHA hexadecimal completo de 40 caracteres evita por completo la operación de red).

• Dominios/exclusiones por repositorio: indexa solo lo que un repositorio debería aportar; por ejemplo, domains = ["vhdl"] for a pure IP repository and exclude = ["sim"] para omitir archivos solo de simulación.

• Cambiar los modelos de embeddings cambia the dimension of the vector denso; el servidor falla de forma evidente y con un mensaje accionable en lugar de corromper el índice (elimina la colección o data_dir y vuelve a indexar).

Uso

Ejecutar el servidor

$ uvx vhdl-rag-mcp

El servidor sirve MCP por stdio hasta que el host cierra la conexión; una tarea en segundo plano sincroniza todos los repositorios cada sync_interval segundos. Un candado de instancia única (data_dir/server.lock) evita que dos servidores compartan el mismo directorio de datos.

Registrar en un cliente MCP

Claude Code:

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

Maki (configuración TOML: verifica los nombres exactos de las tablas en la documentación de tu versión de Maki):

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

Herramientas

Todas las herramientas de búsqueda aceptan los filtros opción repository (nombre), category (golden/approved/project/legacy) y symbols: list[str], que restringe los resultados a los fragmentos que referencien cualquiera de los identificadores indicados. Los resultados se muestran en Markdown with attribution of the source, score e identificadores referenciados; the content goes separated by domain.

Example of agent flow:

1. search_knowledge("asynchronous reset conventions") → una sección de documentación y los procesos VHDL que implementan resets.

2. search_vhdl("reset", symbols=["rst_n"]) → todos los fragmentos VHDL que hagan referencia rst_n.

3. get_source("company-standards", "rtl/reset_ctrl.vhd", 12, 40) → the exact borders of the copy.

Operations

• Directorio de datos (data_dir): colecciones de Qdrant, árboles de trabajo Git de cada repositorio (<name>/), estado de sincronización (state/repositories.json), archivo de registro (logs/vhdl-rag-mcp.log) y candado. Eliminarlo restablece el índice.

• Estado y reintentos: el indexed_commit de un repositorio solo avanza cuando la actualización de su índice finaliza correctamente; una sincronización fallida conserva el commit anterior y la siguiente sincronización vuelve a intentar el mismo diff. last_sync_error es visible mediante repository_status.

• Eliminar un repositorio de la configuración: en el siguiente arranque el servidor lo detecta en el archivo de estado y elimina automáticamente todos sus fragmentos y su estado.

• Registro: stderr + logs/vhdl-rag-mcp.log (rotatorio, 3×5 MB). Ajusta log_level = "DEBUG" para ver el detalle de LSP/git/embeddings.

Desarrollo

$ 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

La suite de pruebas se ejecuta completamente sin conexión: remotos Git locales con file://, un servidor LSP simulado y proveedores de embeddings simulados (una prueba con binario real se sutorna mediante la variable de entorno VHDL_LS_TEST_BIN). The "Layout:" section:

Structure:

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