SKILL 10 / MCP · DEEP DIVE

文档检索类 MCP：治训练截止日期这个病

Context7 拆解 · 一方文档服务 · 什么时候不如直接把文档贴进去

2026-09-11 · BigCat

模型言之凿凿地写了一个参数名，你去查，没有这个参数。它不是在编——它记得的那一版，是它训练截止那天的那一版。

相关 → Skill 09 MCP Server 榜单（上期给的是全景与 Context 税，本期只钻文档检索这一条线）

// WHY THIS MATTERS

文档检索类 MCP 是所有 server 里最没有争议的一类：它不改你的文件、不调用付费 API、不需要写权限，只把一段官方文档搬进上下文。它治的病也很单一——模型知识有截止日期，而你依赖的库每周都在发版。

这一类里最出名的是 Context7（据 GitHub 仓库页 2026-09 约 6.19 万 star、MIT）。但本期要说的重点是：Context7 这种「什么库都能查」的聚合服务，和微软、AWS、Cloudflare、Anthropic 自己跑的一方文档服务，是两种东西。前者覆盖广、索引质量不由你掌控；后者窄、但那就是原文。九个可以今天就装上的条目在下面，最后一节回答那个最该问的问题：什么时候这些一个都不用装。

// 01

它替你干掉什么：干掉「我去翻一下文档再回来告诉你」

论断：它替掉的不是搜索引擎，是你在对话中途切出去、复制一段文档、再贴回来的那三十秒。真正的收益不在省时间，在于模型拿到的是带版本号的原文，而不是它对某个旧版本的记忆。

第一条立刻能跑的用法

# ① 官方零鉴权的那个，拿来先验通链路（Claude Code 文档全文检索）
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
claude mcp list          # 期望看到 ✔ Connected

# ② Context7：一条命令装完，会问你选 CLI+Skills 还是 MCP 模式
npx ctx7 setup --claude  # 需 Node 18+；OAuth 登录后自动生成 API key
npx ctx7 remove          # 后悔了就这条

# 手工接 MCP 模式的话是这个地址，key 走 Authorization 头
https://mcp.context7.com/mcp

# 第一句话这么问（斜杠语法直接点名库，跳过匹配步骤）：
用 Supabase 实现邮箱密码注册。use library /supabase/supabase
# 想要特定版本，把版本号说进去就行：「Next.js 14 的 middleware 怎么配」

两个细节值得注意。其一，ctx7 setup 现在提供两种模式：CLI + Skills（装一个 skill，教 agent 去跑 ctx7 library / ctx7 docs 命令，完全不用 MCP）或传统 MCP 模式。这是本系列反复讲的那件事的活例子——同一个能力，既可以做成 server，也可以做成 skill 加一个 CLI。其二，官方 README 明说 API key「recommended」而非必需，免费 key 换的是更高的速率上限。

失败模式：装完不加触发规则，然后抱怨「它根本不用」。Context7 官方给的解法是往 CLAUDE.md 里加一句「需要库/API 文档、生成代码、配置步骤时，总是使用 Context7，不必等我明说」；ctx7 setup 走 skill 路线时会自动配好这条，手工接 MCP 的话得自己写。
一手源 · upstash/context7 README（命令与工具名均抄自此处） · Claude Code · Connect to MCP servers（claude-code-docs 那条命令的出处）
// 02

机制：它凭什么有效——因为它把「查」拆成了两步

论断：这类 server 几乎都是同一个形状：先把自然语言里的库名解析成一个稳定 ID，再拿这个 ID 加你的问题去取片段。有效的不是抓取，是第二步做了检索而不是整页塞进来。
Context7 的两个工具（抄自官方 README） ────────────────────────────────────────────────────────────── resolve-library-id query + libraryName → /vercel/next.js query-docs libraryId + query → 相关文档片段 ────────────────────────────────────────────────────────────── 同一形状在别家的名字 Microsoft Learn microsoft_docs_search → microsoft_docs_fetch AWS Docs search_documentation → read_documentation GitMCP search_*_documentation → fetch_*_documentation Ref ref_search_documentation → ref_read_url ────────────────────────────────────────────────────────────── 先定位、后取回。取回那步永远带着你的问题。

为什么非得带着问题去取

因为整页文档动辄两三万 token，而模型只需要其中一段。Ref 的作者把这件事说得最直白：「Models get dumber as you put in more tokens」，所以它只返回一页里最相关的约 5k token，而不是常见的 20k+ 整页（据其 GitHub README，2026-09）。Microsoft Learn 干脆把这个旋钮交给你：在端点后面加 ?maxTokenBudget=2000，搜索结果会被截断到你给的预算内。

一条容易被忽略的性质：索引不在你手里

Context7 的 README 自己写着两句很重要的免责：库文档是社区贡献的，无法保证准确、完整与安全；开源的只是 MCP server 本体，API 后端、解析引擎、爬虫引擎都是私有的。这不是黑它——这是所有聚合型服务的共同结构：你查到的东西好不好，取决于别人的爬虫那天抓到了什么。一方服务（learn.microsoft.com、AWS、Cloudflare、code.claude.com）没有这个问题，因为文档和服务是同一家出的。

失败模式：把「Context7 说没有」当成「这个库没有这个 API」。它答不上来有三种可能——库没被收录、收录了但那一页没被抓到、抓到了但检索没命中。三种都不是「不存在」。
进阶资源 · ref-tools/ref-tools-mcp（token 效率那段论述的出处） · MicrosoftDocs/mcp（maxTokenBudget 的文档）
// 03

真实用法与边界：九个条目，分三层装

论断：不要按「哪个 star 多」选，按你要查的东西归谁管选。一方文档服务能查到的，就别让聚合服务转一手。

第一层 · 一方官方（能查到就优先用它）

第二层 · 通用聚合（覆盖广，索引是别人的）

第三层 · 仓库型（没有官方文档站的时候）

失败模式：三层一起装，于是同一个问题有四个工具抢着答，模型每次挑一个，你永远不知道这次答案来自一方文档还是某个爬虫的缓存。同一层里只留一个是这一类的基本纪律。
进阶资源 · GitMCP（各客户端配置片段齐全） · Microsoft Learn CLI：npx @microsoft/learn-cli search（不装 MCP 也能用同一套工具）
// 04

代价与替代品：什么时候不如直接贴文档

论断：文档检索的开销不在工具定义，在返回值——每次命中都往上下文里灌几千 token 的陌生文本。如果你反复查的是同一份文档的同一段，检索就是在为一件本该缓存的事持续付费。

三种不装任何东西的做法

诚实的代价

诚实的代价：这一类是最容易「装了感觉很爽、其实没改变什么」的。真正的判据只有一条——过去一周，你有没有因为它而少犯一次版本错误？答不上来就摘掉。
进阶资源 · Claude Code · MCP 参考（作用域、鉴权、禁用） · code.claude.com/docs/llms.txt（一份真实的 llms.txt）

// 一页选购卡

先装这三个：① claude-code-docs（claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp，零鉴权，顺带验通你的 MCP 链路）；② context7（npx ctx7 setup --claude，并在 CLAUDE.md 加那句触发规则）；③ 你主力云厂商的那一个——Azure/.NET 选 https://learn.microsoft.com/api/mcp，AWS 选 uvx awslabs.aws-documentation-mcp-server@latest，Cloudflare 选 https://mcp.cloudflare.com/mcp。

按需再加：gitmcp.io/{owner}/{repo}（啃一个没文档的仓库那几天）· mcp.deepwiki.com/mcp（陌生大仓库先看地图）· Ref（只有当你要检索的是私有文档时才值那个 key）。

明确别装：同一层里的第二个（一方文档服务已覆盖就别再挂聚合服务）· 任何只为「万一要查」而装的 · 抄自旧博客的 @upstash/context7-mcp 老命令。

一句话判据：查的东西归谁管，就用谁家的服务；查不到归属的才上聚合；同一页要查五次的，直接贴。

// 术语表

training cutoff（训练截止日期）
模型参数里知识的最后更新时间。它之后发布的 API、改名的参数、废弃的写法，模型一概不知道，却会用旧版本的样子自信地写出来。
library ID（库标识）
聚合服务给每个库分配的稳定地址，如 /vercel/next.js。在提示里直接点名它，可以跳过模糊匹配那一步。
first-party docs server（一方文档服务）
文档的作者自己跑的检索服务。与聚合服务的区别不在功能，在于中间没有第三方爬虫。
token budget（token 预算）
限制单次返回体量的旋钮。Microsoft Learn 的 ?maxTokenBudget=2000 是少见的把它直接暴露给用户的例子。
llms.txt
放在站点或文档根路径的 Markdown 索引文件，用一份带链接的清单告诉模型这个站有哪些页。不需要任何 server。
injection surface（注入面）
任何把外部不可信文本送进上下文的通道。文档检索按定义就是一条。

// 延伸阅读