vhdl-rag-mcp

MCP-сервер (Model Context Protocol), который даёт агентам, пишущим код, высококачественный семантический поиск по VHDL-коду организации, связанной с ним документации и общим исходникам (C/C++, Python, ...) — всё перекрёстно слинковано и с точной атрибуцией источника.

Запускается как uvx vhdl-rag-mcp через stdio. Внешние сервисы не требуются: Qdrant работает во встроенном режиме, а модели эмбеддингов выполняются локально (ONNX через FastEmbed).

Возможности

• Три индексируемых домена — один сервер. VHDL-исходники, документация (Markdown/reST/text) и обычный код (C/C++, Python, ...) хранятся в трёх коллекциях Qdrant, и для каждого чанка есть плотный (jina v2) и разрежённый (BM25) вектор.

• Гибридный поиск. Каждый запрос использует нативный гибридный поиск Qdrant (dense + sparse, с RRF-объединением): семантическая близость и точное совпадение идентификатора в одном вызове. Спросите про rst_n — и вы получите результат.

• Нарезка с учётом структуры VHDL. VHDL-файлы нарезаются по конструкциям (entity, architecture, process, package, function) с помощью языкового сервера vhdl_ls (documentSymbol с точными диапазонами строк), со структурным построчным сканером как запасным вариантом для файлов с синтаксическими ошибками — и с целым файлом как последним средством, чтобы ни один VHDL не терялся.

• Нарезка с учётом структуры в остальных случаях. Документация разбивается по секциям заголовков; обычный код — по функциям/классам верхнего уровня с помощью tree-sitter (для любого языка, у которого есть грамматика), с gap-чанками в области видимости файла для непокрытого кода верхнего уровня.

• Перекрёстные ссылки. В полезной нагрузке каждого чанка хранятся идентификаторы, которые он определяет или на которые ссылается (symbols). Поисковые инструменты принимают фильтр symbols, который отбирает чанки, ссылающиеся на заданные идентификаторы, — соединяя документацию ↔ VHDL ↔ тестовый код (например, можно найти все VHDL-процессы и C-функции, работающие с fifo_write).

• Ранжирование с учётом приоритета. Репозитории имеют категорию (golden > approved > project > legacy) или явный priority 0–100, к которому применяется ограниченный бонус к суммарному скору: эталонные репозитории побеждают при равенстве релевантности, не перебивая истинное сходство.

• Точная атрибуция источника. Каждый результат указывает репозиторий, файл, диапазон строк и коммит; get_source возвращает точное текущее содержимое файла (или диапазон строк) из синхронизированного рабочего дерева.

• Инкрементальный самообновляющийся индекс. Репозитории синхронизируются из Git (clone/fetch/diff); заново нарезаются и эмбеддятся только изменённые файлы. Фоновая задача синхронизирует репозитории каждые sync_interval секунд; инструменты могут в любой момент принудительно запустить синхронизацию или полную переиндексацию.

• Плавная деградация. Сбои изолированы в рамках репозитория и фиксируются в состоянии; «сломанный» репозиторий не блокирует ни остальные, ни сервер.

• stdout протокольно чист. Все логи идут в 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, примерно десятки МБ каждая, однократно) и выполняет первичную синхронизацию всех настроенных репозиториев.

Конфигурация

Файл конфигурации: ~/.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-hex SHA полностью пропускает сетевой fetch).

• Домены/исключения репозитория: индекс должен вносить только то, что должен вносить репозиторий — например, domains = ["vhdl"] для репозитория, где только IP-ядра, а exclude = ["sim"] — чтобы пропускать файлы, предназначенные только для симуляции.

• Смена моделей эмбеддингов меняет размерность плотного вектора; сервер честно и внятно останавливается вместо того, чтобы портить индекс (удалите коллекцию или data_dir и переиндексируйте).

Использование

Запуск сервера

$ uvx vhdl-rag-mcp

Сервер обслуживает MCP через stdio, пока хост не закроет соединение; фоновая задача синхронизирует все репозитории каждые sync_interval секунд. Одиночка, блокировка одного экземпляра (data_dir/server.lock) предотвращает одновременное использование одного каталога данных двумя серверами.

Подключение к 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 (gold, approved, project, legacy), а также symbols: list[str] — ограничьте результаты чанками, которые ссылаются на один из перечисленных идентификаторов. Результаты выдаются в виде Markdown с указанием источника, скором и встречающимися идентификаторами; содержимое обёрнуто по домену.

Пример сценария работы агента:

1. search_knowledge("asynchronous reset conventions") → раздел документации плюс VHDL-процессы, реализующие сброс.

2. search_vhdl("reset", symbols=["rst_n"]) → каждый VHDL-чанк, в котором упоминается rst_n.

3. get_source("company-standards", "rtl/reset_ctl.vhd", 12, 40) → точное строки, которые можно взять.

Эксплуатация

• Каталог данных (data_dir): коллекции Qdrant, рабочие trees репозиториев (<name>/), состояние синхронизации (state/repositories.json), файл журнала (logs/vhdl-mcp.log) и файл блокировки. Удаление каталога сбрасывает индекс.

• Состояние и повторные попытки: indexed_commit репозитория продвигается только после полного успеха обновления индекса; при сбое синхронизации остаётся предыдущий коммит, и следующая синхронизация повторяет тот же diff. last_sync_error видно через repository_status.

• Удаление репозитория из конфига: при следующем запуске сервер обнаружит его в состоянии и автоматически удалит все его чанки и его состояние.

• Журналы: stderr + logs/vhdl-rag-mcp.log (ротация, 3×5 МБ). Для подробного вывода LSP/git/эмбеддингов — log_level = "DEBUG".

Разработка

$ 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

Тестовый набор полностью автономен: локальные git-remotes по file://, скрипт фейкового 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