Tech Doc

本地技术文档 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 [email protected]: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)	浏览目录结构

技术栈

FastMCP · ChromaDB · OpenAI SDK · BeautifulSoup / markdownify · httpx · Typer

项目文档

• skills/add-docs/SKILL.md —— 文档爬取工作流:站点分析 → 页面过滤 → 生成爬虫脚本
• ROADMAP.md —— 迭代路线图:已完成项 + 待处理项
• docs/DEVLOG.md —— 开发日志

说明

• 源文档(docs/*/raw、docs/*/clean)与索引数据(data/)不纳入版本库,可按上述流程重新生成。
• 项目处于 0.1.0 早期阶段,搜索质量验证体系、Web 管理界面、多源搜索等仍在规划中,详见 ROADMAP。

License

MIT