vhdl-rag-mcp

一个 MCP（Model Context Protocol）服务器，为编码智能体提供对组织内 VHDL 代码、VHDL 相关文档以及通用源代码（C/C++、Python 等）的高质量语义搜索——全部相互交叉引用，且具备精确的源码归属。

通过 stdio 以 uvx vhdl-rag-mcp 方式运行。无需任何外部服务：Qdrant 以嵌入式方式运行，嵌入模型在本地运行（通过 FastEmbed 使用 ONNX）。

功能

• 三个索引域，一个服务器。 VHDL 源代码、文档（Markdown/reST/text）和通用代码（C/C++、Python 等）存放在三个 Qdrant 集合中，每个 chunk 均包含一个稠密向量（jina v2）和一个稀疏向量（BM25）。

• 混合搜索。 每次查询都运行 Qdrant 原生混合查询（稠密 + 稀疏，RRF 融合）：一次调用同时执行语义相似度匹配与精确标识符匹配。你只输入 rst_n 即可查到。

• VHDL 感知分块。 VHDL 文件按结构体（entity、architecture、process、package、function、component）分块，使用 vhdl_ls 语言服务器（documentSymbol 提供准确行号范围）；对于含语法错误的文件，则回退到结构化行扫描器；若仍失败则使用整个文件作为最后兜底，确保没有任何 VHDL 被遗漏。

• 其它内容同样是结构感知分块。 文档按标题区块分块；通用代码按顶层函数/类用 tree-sitter 分块（支持任何带文法的语言），并为未覆盖的顶层代码提供文件作用域 gap chunks。

• 交叉引用。 每个 chunk 的载荷都会存储其定义或引用的标识符（symbols）。搜索工具接受 symbols 过滤器，匹配任何引用给定标识符的 chunk——在文档 ↔ VHDL ↔ 测试代码之间建立连接（例如，找出所有含 fifo_write 的 VHDL process 和 C 函数）。

• 优先级感知排序。 存储仓库可带有 category（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/ 安装 release，让 vhdl_ls 在你的 PATH 中可用， 或将 data_dir 配置的 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 位十六进制 SHA 会完全跳卡口网络拉取）。

• 每仓库的 domains/excludes：只索引该仓库应贡献的范围——例如纯 IP 仓库用 domains = ["vhdl"]，跳过仿真相关文件用 exclude = ["模拟"]。

• 改变嵌入模型会改变稠密向量的维度；服务器会大声报错并提供可操作的提示，而不是破坏索引（此时需要删除 collection 或 data_dir 再重新索引）。

使用方法

运行服务器

$ uvx vhdl-rag-mcp

它通过 stdio 持续提供 MCP 服务，直到宿主关闭连接；后台任务每隔 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 （golden/approved/project/legacy）过滤，此外还有 symbols: list[str]—— 只返回引用了这些给定标识符的 chunk。结果以 Markdown 渲染，携带源码归属、得分及 被引用的标识符，并按 domain 进行内容分块。

示例智能体流程：

1. search_knowledge("asynchronous reset conventions") → 返回一个文档片段及 描述等你实现 VHDL processes。

2. search_vhdl("reset", symbols=["rst_n"]) → 返回所有触碰 rst_n 的 VHDL chunk。

3. get_source("company-standards", "rtl/reset_ctrl.vhd", 12, 40) → 返回需要复制 的确切行。

运维

• 数据目录（data_dir）：Qdrant 集合、每个仓库的 Git 工作树（<name>/）、同步 状态（state/.json）、日志文件（logs/vhdl-rag-mcp.log）和锁文件。删除 它将重置索引。

• 状态与重试：indexed_commit 只在仓库索引完全成功后才推进；失败的同步会保留 上一次提交，下一次同步会重试相同的 diff。last_sync_error 通过 repository_status 可见。

• 从配置中移除仓库：下次启动时，服务器检测后会自动删除该仓库的 所有分块和状态。

• 日志：stderr + logs/repositories.qdrant（轮转 3×5 MB）。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 remote、模拟 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