MCP 服务器

tech-doc-mcp

Provides local technical documentation with hybrid search (semantic + BM25) for AI agents, ensuring access to up-to-date framework docs.

README

tech-doc-mcp

本地技术文档 MCP 服务器 —— 为 AI Agent 提供最新框架文档的实时混合搜索能力。

解决 LLM 训练数据滞后导致的过时 API 调用问题:把框架官方文档爬取到本地,经 LLM 清洗、分块、建立向量索引(基于去代码正文),通过 MCP 协议暴露给 Claude Code 等 Agent,查询时返回最新、可溯源的文档片段。

特性

混合搜索 —— ChromaDB 语义检索为主干,关键词按 presence + 饱和做乘性加权重排(boost-only),兼顾语义相关与精确 API 名匹配。设计依据见 docs/search-fusion-redesign.md
抗代码噪声 —— 向量基于去代码正文,关键词在含代码全文上按"是否出现"而非"出现几次"计分,免疫代码符号高频膨胀
面向 Agent 的极简工具 —— 只需 4 个 MCP 工具即可覆盖搜索/阅读/浏览
LLM 文档清洗 —— 自动把爬虫原始 HTML/Markdown 清洗为干净正文,3 并发 + 指数退避重试
多源多版本共存 —— 每个文档源独立 Collection,新旧版本并存,搜索取最新版本
OpenAI 兼容 —— LLM 与 Embedding 均走 OpenAI 兼容接口,可自由替换服务商

架构

文档处理管线:
  docs/{source}/raw/*.md          ← 爬虫原始输出
         │  cleaner.py (LLM 清洗)
         ▼
  docs/{source}/clean/*.md        ← 干净 Markdown
         │  loader → chunker → embedding → ChromaDB
         ▼
  data/chroma/                    ← 向量索引 + 全文存储

搜索链路 (Agent 视角):
  search_docs(query, source, keywords, limit)
    ├─ query    → ChromaDB 语义搜索 → top-N 候选(主干)
    ├─ keywords → 候选内 presence + 饱和计分(boost-only)
    └─ 乘性融合 sem·(1+λ·kw) → 按 path 去重 → top-K 返回

安装

需要 Python 3.12+ 和 uv。

git clone git@github.com:cy-wwyy/tech_doc_mcp.git
cd tech_doc_mcp
uv sync

配置

复制模板并填入你的 API Key(支持 ${ENV_VAR} 占位符):

cp config.yaml.example config.yaml   # LLM 与 Embedding 的 api_base/model/dimensions
cp .env.example .env                 # 填入 LLM_API_KEY / EMBEDDING_API_KEY

llm —— 文档清洗用(如 DeepSeek、任意 OpenAI 兼容接口)
embedding —— 向量化用,dimensions 需与所选模型匹配

使用

本项目有两个完全独立的阶段,角色和目标不同——别混淆:

阶段	谁来做	目标
① 构建文档库	维护者(开发阶段)	爬取 → 清洗 → 索引 → 启动服务,产出可搜索的文档库
② 检索文档	最终用户(使用阶段)	Claude Code 连上已配好的 MCP,日常对话中实时查最新文档

阶段 ① 只在新增/更新文档源时做一次;做完之后,所有使用者都停留在阶段 ②。

阶段一 · 构建文档库(维护者)

把某个框架官网变成本地可搜索的索引。两种方式二选一:

方式 A:对话驱动(推荐) —— 配好 skill 后全程自然语言,无需记命令。

一次性配置 skill(把仓库里的 skills/add-docs 挂到 Claude Code 技能目录):

mkdir -p .claude/skills
# 软链接（推荐，仓库更新后自动同步）；或用 cp -r 复制
ln -s ../../skills/add-docs .claude/skills/add-docs

之后对话即可:

你说	Agent 做的事
`/add-docs fastapi` 或 `/add-docs https://...`	分析站点结构 → 生成爬虫脚本 → 爬取到 `docs/{source}/raw/`
“清洗 fastapi 文档”	调用 `cleaner` 把 `raw/` → `clean/`
“把 fastapi 索引一下”	执行 `index`,分块 + embedding 写入 ChromaDB
“启动文档服务”	拉起 MCP Server,供阶段 ② 检索

方式 B:手动 CLI —— 逐条执行等价命令:

# 1. 爬取文档源 → docs/{source}/raw/（脚本由 skills/add-docs 工作流生成）
uv run python scripts/crawlers/<script>.py

# 2. LLM 清洗 raw/ → clean/
uv run python -m tech_doc_mcp.processor.cleaner <source_name>

# 3. 索引 clean/ → 分块 → embedding → ChromaDB
uv run tech-doc-mcp index <source> --version 0.1.0

# 4. 启动 MCP Server（默认 streamable-http://127.0.0.1:8000）
uv run tech-doc-mcp serve

阶段二 · 检索文档(最终用户)

前提:阶段 ① 已产出索引,且 MCP Server 正在 serve。

把本地 MCP Server 加入 Claude Code 的 MCP 配置后,日常编码对话中 Agent 会自动调用以下工具查最新文档,使用者无感、无需记任何命令:

工具	用途
`list_sources()`	列出已索引的文档源(name / version / chunks)
`search_docs(query, source, keywords=None, limit=10)`	混合搜索,返回 rank / path / score / text
`read_doc(path, source)`	读取完整页面(最多 8000 字符)
`list_docs(source, path=None)`	浏览目录结构