AI导哈

AI编码助手知识库

一个本地化的MCP服务器，为AI编码助手提供检索访问个人知识库的能力，使AI生成的代码基于用户信任的书籍、标准文档和参考资料。

  • by michaelalber
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 michaelalber/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 --在本地运行嵌入模型：

ollama serve
ollama pull snowflake-arctic-embed2

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

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

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

安装

产量（pipx——推荐）：

pipx install "grounded-code-mcp[all] @ 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 ".[all,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

开源代码 (~/.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 <subcommand> --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

工具

工具 说明
grounded_search 在所有（或一个）集合中进行矢量搜索——返回带有分数和源路径的散文块
grounded_search_code 使用可选语言过滤器进行仅代码块搜索
grounded_list_sources 列出每个摄入的文档——用于发现可用的内容
grounded_source_info 特定源的元数据：块计数、SHA-256、摄取日期
grounded_query_graph 图遍历——查找概念关系和链接源

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 ".[all]" --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/ 将子目录添加到集合名称中。

目录 收藏 属于这里的东西
sources/internal internal 工程标准——XP、TDD、CI/CD、DDD、OWASP、NIST AI
sources/patterns patterns 设计模式——GoF、CQRS、清洁架构、DI
sources/architecture architecture 软件架构——DDIA、SRE、12因子、C4、arc42
sources/systems-thinking systems_thinking 系统思维——草地、反馈回路、混沌工程
sources/ui-ux ui_ux 用户体验定律，尼尔森，WCAG 2.2，ARIA，美国WDS，英国政府
sources/dotnet dotnet .NET/C、ASP。NET核心、实体框架、Telerik用户界面
sources/python python Python、FastAPI、Pydantic、FastMCP、pytest、cosmicpython
sources/databases databases SQL、PostgreSQL、关系理论
sources/edge-ai edge_ai 人工智能工程、RAG、嵌入式、LLM应用设计、人工智能代理
sources/automation automation PLC、OPC UA、MODBUS、ICS安全、Raspberry Pi
sources/php php PHP手册，Laravel（5.5/6.x/12.x）
sources/javascript javascript JS/TS、Vue 2/3、jQuery、ECMAScript规范
sources/gov gov NIST 800-53/171/218、美国能源部、零信任、人工智能RMF、CUI
sources/robotics robotics ROS 2、MuJoCo、Isaac Lab、LeRobot、VLA模型
sources/rust rust Rust所有权、async/Tokio、Cargo、错误处理、Axum
sources/api-design api_design REST API设计-Zalando、Google AIP、Microsoft指南

在中添加私人收藏 ~/.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 用于收集工作流和依赖关系注释。

技术栈

组件 选项 注释
MCP框架 FastMCP >=3.2.0
文档解析 文档处理 布局感知；处理复杂的PDF
矢量存储 Qdrant/ChromaDB Qdrant初级；ChromaDB作为Docker免费回退
概念图 NetworkX DiGraph 持久化为JSON；支持BFS遍历、路径查找、域/源过滤
嵌入 Ollama+雪花-实际嵌入2 1024昏暗，8K上下文，完全本地
配置 TOML+Pydantic 深度合并分层配置
CLI 点击+丰富
测试 pytest 398次测试
绒布 褶边
类型检查 mypy
安全扫描 土匪

安全

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

故障排除

症状 修复
Ollama connection error ollama serve + curl http://localhost:11434/api/tags 验证
Qdrant connection error curl http://localhost:6333/healthz 验证容器是否正在运行
摄取OOM/GPU崩溃 一次运行一个摄取——并行文档作业耗尽VRAM；或奔跑 convert 首先，摄取仅限于CPU
convert 在特定文件上失败 每个文件都在独立的子进程中运行；stderr显示原因；仅使用文件路径重新运行以进行调试
convert 在没有GPU加速的情况下运行缓慢 安装 flash-attn 并设置 cuda_use_flash_attention2 = true 在 [docling] （仅安培+）
搜索未返回任何结果 grounded-code-mcp status 验证摄入情况；尝试 --min-score 0.3
相关性得分低 只传递一个简单的集合后缀，而不是完整的 grounded_* 姓名

作者

迈克尔·K·阿尔伯 — github/michaelalber

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

相关项目：

  • ai工具包 --Claude Code、OpenCode和Pi的103个技能、49个代理和22个斜线命令
  • pi包 --具有硬件路由、RAG集成和项目类型自动检测功能的特定域Pi线束，用于本地Ollama推理

许可证

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

相关 MCP