Grounded Code MCP

接地代码MCP

   

将你的AI编码代理放在你真正信任的书籍、标准和文档中。

本地人 主控程序 该服务器允许Claude Code、OpenCode和其他AI编码助手检索您的个人知识库——您的书籍、标准文档、官方文档和精选参考文献。代理不会仅从训练数据中生成答案，而是首先搜索您的来源。

______________________________________________________________________

我为什么建造这个

当AI编码助手推理的上下文与您的实际标准（而不是平均训练数据）相匹配时，它们会产生更有用的输出。我在对面工作。NET、Python、Rust、边缘AI和联邦安全域。每个都有我信任的权威来源：具体的书籍、NIST标准、官方框架文件、内部工程指南。

该项目使任何MCP兼容代理都可以搜索这些源。代理在响应之前查询知识库，将其答案基于我明确选择的来源。结果是反映我的偏好和标准的输出，而不是通用的平均值。

关键设计决策：

• 完全本地——嵌入通过Ollama运行，向量存储在Qdrant中。没有数据离开机器。
• 精心策划的21个域名集合，每个都代表了对信任内容的深思熟虑的选择。
• 增量——SHA-256变化检测意味着重新摄取只处理变化的内容。
• 分层配置——共享项目配置+每台机器用户覆盖，在启动时深度合并。

______________________________________________________________________

建筑

Documents (PDF, DOCX, HTML, MD, EPUB…)   RELATIONSHIPS.md files
        │                                         │
        ▼ (optional — run once on a GPU machine)  │
   [ convert → .md sidecars ]                     │
        │                                         │
        ▼                                         ▼
   [ Docling Parser ]                    [ GraphBuilder parser ]
        │                                         │
        ▼                                         │
   [ Semantic Chunker ]                           │
        │                                         │
        ▼                                         ▼
   [ Ollama Embedder ]               [ NetworkX DiGraph (JSON) ]
        │                                         │
        ▼                                         │
   [ Qdrant / ChromaDB ]─────────────────────────┘
        │                    vector + graph
        ▼
   [ FastMCP Server ]          ← 5 MCP tools: search_knowledge, search_code_examples,
        │                         list_collections, list_sources, get_source_info
        ▼
Claude Code / OpenCode / any MCP client

该管道有三个独立的流程。 convert 是一个生成Markdown sidecar的一次性GPU步骤。 ingest 读取那些sidecar（或者在没有sidecar的情况下直接解析文档），并将块追加到向量存储中。 graph_builder 解析 RELATIONSHIPS.md 从知识源中提取文件，并构建一个持久的概念图。MCP服务器作为由MCP客户端管理的持久子进程运行。

______________________________________________________________________

特性

• 概念图（RAG图） --从中提取的NetworkX DiGraph RELATIONSHIPS.md 每个知识源中的文件；捕获概念之间的命名关系，并支持图遍历增强检索和向量搜索
• 多格式摄取 --PDF、DOCX、PPTX、HTML、Markdown、AsciiDoc、EPUB文档
• GPU加速预转换 — convert 命令将二进制文档处理为Markdown sidecar；随后的 ingest runs读取sidecar并完全跳过Docling，使摄取CPU仅在第一次通过后快速进行
• 碰撞隔离批量转换 --每个文件都在其自己的子流程中转换；文档PDF崩溃不会中止整个批处理
• 代码感知分块 --保留代码块、表和标题层次结构
• 本地嵌入 --Ollama与雪花-实际嵌入2（1024维，8K上下文）
• 双矢量存储 --Qdrant（主要）或ChromaDB（无Docker回退）
• 增量更新 --SHA-256哈希跳过未更改的文件
• 17个精选系列 --覆盖。NET、Python、Rust、架构、安全、AI/ML、边缘、机器人等
• 私人收藏 --通过用户配置添加自己的源代码，而无需接触项目
• 分层配置 --项目 config.toml 深度融合 ~/.config/grounded-code-mcp/config.toml

______________________________________________________________________

先决条件

奥拉玛 --在本地运行嵌入模型：

ollama serve
ollama pull snowflake-arctic-embed2

Qdrant --矢量存储（推荐）：

docker run -d -p 6333:6333 qdrant/qdrant

ChromaDB支持无Docker回退(provider = "chromadb" 在配置中）。

______________________________________________________________________

安装

产量（pipx——推荐）：

pipx install git+https://github.com/michaelalber/grounded-code-mcp.git

发展：

git clone https://github.com/michaelalber/grounded-code-mcp.git
cd grounded-code-mcp
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"

开发工具(pytest, ruff, mypy)逃离 .venv/bin/。对所有运行时命令使用pipx二进制文件。

______________________________________________________________________

配置

config.toml （提交到仓库）定义了共享设置。机器特定的超控进入 ~/.config/grounded-code-mcp/config.toml --在创业时深度合并。

cp config.toml.example ~/.config/grounded-code-mcp/config.toml

最小用户配置：

[ollama]
host = "http://localhost:11434"

[vectorstore]
qdrant_url = "http://localhost:6333"

私人收藏 --添加源代码而不接触项目配置：

# ~/.config/grounded-code-mcp/config.toml
[collections]
"sources/my-team-docs" = "team_docs"

看 贡献.md 对于完整的收集工作流程。

______________________________________________________________________

用法

预转换文档（GPU加速）

convert 在二进制源（PDF、DOCX、EPUB、PPTX）上运行Docling，并编写 .md 每个源代码旁边的sidecar文件。当存在侧车时， ingest 直接读取它并跳过Docling步骤——使重复摄取快速且仅占用CPU。

grounded-code-mcp convert                          # all collections
grounded-code-mcp convert --collection rust        # one collection
grounded-code-mcp convert path/to/file.pdf         # single file
grounded-code-mcp convert --force                  # re-convert even if sidecar already exists
grounded-code-mcp convert --dry-run                # list files that would be converted
grounded-code-mcp convert --no-ocr                 # disable OCR regardless of config

跑 convert 之前 ingest 在GPU机器上。每个文件都在一个独立的子流程中转换——Docling PDF崩溃不会中止整个批处理。

可选：闪光注意2 --在安装了CUDA工具包的Ampere+GPU上：

pip install flash-attn --no-build-isolation

然后启用 ~/.config/grounded-code-mcp/config.toml:

[docling]
cuda_use_flash_attention2 = true

摄入文件

grounded-code-mcp ingest                        # all collections
grounded-code-mcp ingest --collection python    # one collection
grounded-code-mcp ingest --force                # ignore manifest, re-ingest everything

避免并行摄取作业——当没有sidecar时，Docling使用GPU；并发作业会导致CUDA OOM。

检查状态

grounded-code-mcp status

从CLI搜索

接受所有搜索命令 --json 发出机器可读的输出——对于不能使用MCP的shell脚本和AI代理非常有用。

散文搜索：

grounded-code-mcp search "async HTTP request"
grounded-code-mcp search "dependency injection" --collection patterns
grounded-code-mcp search "error handling" -n 10 --min-score 0.4
grounded-code-mcp search "CQRS" --collection architecture --json   # JSON output

代码示例搜索：

grounded-code-mcp search-code "async context manager" --language python
grounded-code-mcp search-code "repository pattern" --language csharp -n 3 --json

列出并检查来源：

grounded-code-mcp list-sources                         # all collections
grounded-code-mcp list-sources --collection python     # one collection
grounded-code-mcp list-sources --json                  # JSON output

grounded-code-mcp source-info sources/python/cosmicpython.pdf
grounded-code-mcp source-info sources/python/cosmicpython.pdf --json

查询概念图：

grounded-code-mcp query-graph CQRS
grounded-code-mcp query-graph "clean architecture" --depth 2 --domain patterns
grounded-code-mcp query-graph CQRS --json

启动MCP服务器

grounded-code-mcp serve                                                     # stdio (default)
grounded-code-mcp serve --transport streamable-http --host 127.0.0.1 --port 4242
grounded-code-mcp serve --debug

连接到MCP客户端

克劳德代码：

claude mcp add --transport stdio --scope user grounded-code-mcp -- grounded-code-mcp serve

OpenCode (~/.config/opencode/opencode.json):

{
  "mcp": {
    "grounded-code-mcp": {
      "type": "local",
      "command": ["grounded-code-mcp", "serve"],
      "enabled": true
    }
  }
}

Pi.dev --看 Pi.dev扩展 在......下面

______________________________________________________________________

MCP工具

五个工具暴露于该代理。传递裸集合后缀——服务器在前面添加 grounded_ 自动。

search_knowledge

在所有集合或特定集合内搜索文档。

search_knowledge(
    query: str,                  # search query — 2–6 content words work best
    collection: str | None = None,  # bare suffix, e.g. "python", "rust", "internal"
    n_results: int = 5,
    min_score: float = 0.3,      # 0–1; raise to 0.5+ for tighter relevance
) -> list[dict]

search_code_examples

查找代码密集的块——当您需要实现模式而不是散文时非常有用。

search_code_examples(
    query: str,                  # e.g. "async HTTP client", "repository pattern"
    language: str | None = None, # e.g. "python", "csharp", "rust"
    n_results: int = 5,
) -> list[dict]

list_collections

list_collections() -> list[dict]  # returns name + document count per collection

list_sources

list_sources(
    collection: str | None = None,  # optional filter
) -> list[dict]  # returns path, type, chunk count per source

get_source_info

get_source_info(
    source_path: str,  # path returned by list_sources
) -> dict  # title, type, chunks, ingestion date

______________________________________________________________________

Pi.dev扩展

TypeScript扩展 pi.dev 这将知识库暴露为五个可搜索的工具。每个工具运行 grounded-code-mcp --json 作为一个子进程，它将解析后的JSON返回到pi的上下文中——不需要MCP，完全本地。

安装

选项A-pi安装（推荐）

pi install /path/to/grounded-code-mcp/skill/extensions

这将注册扩展并将路径写入 ~/.pi/settings.json 自动。证实 pi list.

选项B——安装前测试

pi -e /path/to/grounded-code-mcp/skill/extensions/index.ts

选项C-git包（来自pi内部）

/install git:codeberg.org/michaelkalber/grounded-code-mcp?path=skill

工具

pi中的示例用法

Search for FastAPI dependency injection patterns
→ grounded_search(query="dependency injection", collection="python")

Find Python async context manager examples
→ grounded_search_code(query="async context manager", language="python")

What documentation is indexed?
→ grounded_list_sources()

How does CQRS relate to clean architecture?
→ grounded_query_graph(concept="CQRS", depth=2)

传递裸集合后缀——服务器在前面添加 grounded_ 自动。

______________________________________________________________________

概念图（RAG图）

除了向量嵌入，接地代码mcp还从以下内容构建了一个概念图 RELATIONSHIPS.md 每个知识源中的文件。该图是一个有向NetworkX DiGraph 持久化为JSON——它捕获概念之间的命名关系，并支持图遍历增强检索：通过遍历图而不仅仅是余弦距离来查找相关概念。

关系.md格式

同一文件支持两种格式：

引用格式 （通用）：

"Concept A" → enables → "Concept B" [source-slug] [domain] [type] [optional description]

括号格式 （由蒸馏源使用，谓词标准化为小写）：

(Concept A) --[PREDICATE]--> (Concept B)

三元组可能以裸线或围栏代码块的形式出现。任何关系名称都可以接受——没有固定的满列表。

构建图形

# Validate without writing
python -m graph.graph_builder --input sources/ --dry-run

# Build and persist (default: graph/concept_graph.json)
python -m graph.graph_builder --input sources/

# Point to a specific output file
GRAPH_JSON_PATH=/path/to/graph.json python -m graph.graph_builder --input sources/

每次运行都是幂等的：在插入新节点之前，源的节点会被替换，因此在相同的输入上重新运行会产生相同的结果。

______________________________________________________________________

图形RAG--CLI参考

所有命令都使用 grounded-code-mcp 通过安装二进制文件 pipx。更改任何代码后，请使用重新安装 pipx install . --force.

# Full reingest — rebuilds Qdrant vectors and concept graph for all sources
grounded-code-mcp ingest --force

# Single source reingest + graph rebuild (targets one subdirectory)
grounded-code-mcp ingest --force sources/rust

# Full graph rebuild from all RELATIONSHIPS.md files (no reingest)
grounded-code-mcp build-graph

# Graph rebuild for a single source directory (no reingest)
grounded-code-mcp build-graph sources/rust

# Validate graph triples without writing (dry run, full sources)
grounded-code-mcp build-graph --dry-run

# Dry run for a single source
grounded-code-mcp build-graph --dry-run sources/rust

# Seed starter RELATIONSHIPS.md files for sources that are missing them
python -m graph.seed_graph

# Seed a single source by slug
python -m graph.seed_graph --source rust

# Dry run — preview what seed_graph would generate without writing
python -m graph.seed_graph --dry-run

# Direct graph query (CLI, not MCP) — explore the graph from the shell
python -m graph.graph_builder --input sources/ --dry-run

Env被推翻了。 --将图形指向非默认位置：

GRAPH_JSON_PATH=/path/to/graph.json grounded-code-mcp build-graph

MCP工具 --从AI助手会话中查询图形：

query_graph(concept="cqrs", depth=2, domain="architecture")

返回匹配的节点、关系（三元组）、链接的源代码段以及概念邻域的简单英文摘要。

______________________________________________________________________

集合

17个精心策划的收藏，涵盖了我工作的领域。每个收藏都映射了一个 sources/ 将子目录添加到集合名称中。

在中添加私人收藏 ~/.config/grounded-code-mcp/config.toml --它们与项目列表合并，而不是替换它。

______________________________________________________________________

发展

.venv/bin/pytest                                      # run tests
.venv/bin/pytest --cov=grounded_code_mcp              # with coverage
.venv/bin/ruff check src/ tests/                      # lint
.venv/bin/ruff format --check src/ tests/             # format check
.venv/bin/mypy src/                                   # type check
.venv/bin/bandit -r src/ -c pyproject.toml            # security scan

所有闸门同时打开：

.venv/bin/pytest && .venv/bin/ruff format --check src/ tests/ && .venv/bin/ruff check src/ tests/ && .venv/bin/mypy src/ && .venv/bin/bandit -r src/ -c pyproject.toml

看 贡献.md 用于收集工作流和依赖关系注释。

______________________________________________________________________

技术栈

______________________________________________________________________

安全

• 通过allowlist进行文件类型验证（PDF、DOCX、PPTX、HTML、Markdown、AsciiDoc、EPUB）
• 通过魔术字节或UTF-8验证进行MIME类型验证
• 文件大小限制（可配置；默认500 MB以支持大型供应商PDF）
• 文件名净化——防止路径遍历
• 在系统边界验证所有输入
• 通过以下方式在CI中进行依赖性漏洞扫描 pip-audit

______________________________________________________________________

故障排除

______________________________________________________________________

作者

迈克尔·K·阿尔伯 —

软件工程师正在工作。NET、Python、Rust、边缘AI和联邦安全域。我构建的工具使人工智能辅助开发更加脚踏实地，更加固执己见，更符合重要的工程标准。

相关项目：

• ai工具包 --Claude Code、OpenCode和Pi的技能、代理和斜线命令

______________________________________________________________________

许可证

麻省理工学院——见 许可证 了解详情。