Context7 MCP 规则文件解析：让 AI 编码 Agent 自动获取最新库文档的 resolve-library-id 与 query-docs 工作流

规则文件 是 Context7 提供给 AI 编码 Agent（Claude Code、Cursor、Codex 等）的一条使用守则：当用户询问任何库、框架、SDK、API、CLI 工具或云服务时，Agent 必须优先调用 Context7 MCP 的 resolve-library-id 和 query-docs 两个工具拉取实时文档，而不是依赖可能过时的训练数据。读完本文，你将理解这条规则的适用边界、四步查文档流程、库 ID 的选取标准，以及它在 MCP 服务端源码 中的落地方式——工具描述、参数别名容错、调用次数限制都与你写进 Agent 配置的内容一一对应。

一、这条规则解决什么问题

规则文件的第一段明确了触发条件，原文要点如下：

• 触发场景：用户询问库、框架、SDK、API、CLI 工具或云服务时，都要用 Context7 MCP 获取当前文档——包括 React、Next.js、Prisma、Express、Tailwind、Django、Spring Boot 这类“人人都熟”的知名库。具体涵盖 API 语法、配置、版本迁移、库相关的调试、安装配置说明和 CLI 工具用法；
• 为什么不能靠模型记忆：即使 Agent 自认为知道答案，也应查询——训练数据可能未反映近期变更；
• 优先级：对于库文档类问题，优先于网络搜索。

规则同时划定了负面清单，以下场景不应使用：重构（refactoring）、从零写脚本、调试业务逻辑、代码审查，以及通用编程概念。

这条边界与 MCP 服务端内置的 instructions 完全一致。在 MCP 服务器入口 中，服务器注册时携带的 instructions 字段内容与规则文件开头两段几乎逐字相同——也就是说，即使 Agent 没有加载规则文件，MCP 协议握手时也会从服务端收到同样的“何时该用、何时不该用”的指引。规则文件相当于把这份指引前置到 Agent 的配置层，让 Agent 在决定要不要调工具之前就完成判断。

规则文件还通过 ctx7 setup 分发：CLI 以 MCP 模式配置 Agent 时，会在 Agent 的 rules 目录写入这条规则文件、在 skills 目录写入 context7-mcp skill，并写入 MCP 服务器配置（.mcp.json / .cursor/mcp.json / .opencode.json 等），实现“一条命令完成规则 + 技能 + 服务器”的完整接线。

二、四步工作流程：从库名到可引用的文档

规则文件的 Steps 部分定义了严格的调用顺序，每一步都有明确的输入输出：

步骤 1：总是先调 resolve-library-id

除非用户直接提供了 /org/project 格式的精确库 ID，否则第一步必须是用库名 + 想在文档中查什么两个参数调用 resolve-library-id。

从服务端源码看（工具注册处），该工具的输入只有两个字段，且都带强约束的描述文本：

参数	说明（服务端 schema 定义）
query	想在库文档中查什么。用于按“用户想完成的事”给库结果排序；禁止包含 API 密钥、密码、凭据、个人数据或专有代码等敏感信息
libraryName	要搜索的库名。要求使用带正确标点的官方名称——例如写 Next.js 而不是 nextjs，Customer.io 而不是 customerio，Three.js 而不是 threejs

服务端还有一段值得注意的容错实现：LLM 客户端经常“照抄”工具描述里的措辞而不是 schema 的字面键名（比如传 userQuery 或 question），这类幻觉参数会先被 Zod 校验拦下。因此源码在 schema 外层包了一层 参数别名重写：query 的别名 userQuery/question，以及 query-docs 中 libraryId 的别名 context7CompatibleLibraryID/libraryID/libraryName，都会在验证前被静默映射回规范键名。这是“规则文档教 Agent 规范调用”与“服务端兜底非法调用”的双层防线。

步骤 2：按五个维度挑选最佳匹配

规则要求从返回结果中按以下优先级选出 ID 格式为 /org/project 的最佳库：

1. 精确名称匹配（exact name match）；
2. 描述相关性（description relevance）；
3. 代码片段数量（code snippet count）——越多说明文档覆盖越全；
4. 来源信誉（source reputation），High/Medium 优先；
5. 基准分（benchmark score），越高越好。

这五个维度直接来自服务端工具描述中的“Selection Process”（工具描述原文）。每个候选库的返回字段在 ai-sdk 版工具文档 中给出了完整示例：

- Title: React Documentation
- Context7-compatible library ID: /reactjs/react.dev
- Description: The library for web and native user interfaces
- Code Snippets: 1250
- Source Reputation: High
- Benchmark Score: 98
- Versions: 19.0.0, 18.3.1, 18.2.0
----------
- Title: React Native
- Context7-compatible library ID: /facebook/react-native
- Description: A framework for building native applications using React
- Code Snippets: 890
- Source Reputation: High
- Benchmark Score: 95
- Versions: 0.76.0, 0.75.4

规则同时给出了结果不理想时的补救策略：换一种库名或改写查询再试（例如用 next.js 而不是 nextjs）；如果用户提到了具体版本，应改用版本特定的 ID。此外，服务端在工具描述末尾写死了调用预算：同一个问题最多调用 3 次 resolve-library-id，3 次后仍找不到就采用手头最好的结果（对应源码）——这是对“反复试探式搜索”的明确约束。

步骤 3：用 query-docs 按单一概念查询

选定库 ID 后，用 query-docs 传入 libraryId + 要在文档中查什么，且查询应限定在单一概念内。规则与 queryDocs 工具文档 对此的表述一致：

• 好查询：How to set up authentication with JWT in Express.js、React useEffect cleanup function examples——具体、有细节、单主题；
• 差查询（太模糊）：auth、hooks 这类单词级查询；
• 差查询（太宽泛）：routing and auth and caching in Next.js——多主题混合。

关键原则：如果问题跨越多个不同概念（例如路由、认证、缓存），应针对同一 libraryId 分多次 query-docs 调用，每个概念一次；除非问题本身就是“这些概念如何交互”。原因是混合查询会稀释排序效果（dilute ranking），每个主题都只能拿到浅层结果。query-docs 同样受“每个问题最多 3 次”的预算约束（工具描述）。

版本场景下，库 ID 支持 /org/project/version 形式（如 /vercel/next.js/v14.3.0-canary.87），版本列表来自步骤 2 的解析结果，服务端 schema 中也直接以该格式举例（libraryId 字段描述）。

步骤 4：基于拉取的文档作答

最后一步只有四个字：用拉取到的文档来回答。配合 context7-mcp skill 中更细化的“Step 4”要求，还应做到：使用当前准确信息回答、附上文档中的相关代码示例、在相关时注明库版本、多个匹配时优先官方主包而非社区分支。

三、规则与配套工件的关系：规则、Skill、MCP 服务器三层分工

这条规则文件不是孤立的。同一个 Context7 仓库中，围绕“查文档”这件事存在三层互补工件，规则文件属于其中“Agent 行为约束”层：

工件	位置	作用
规则文件（本文主题）	rules/context7-mcp.md	告诉 Agent 何时该用 Context7、何时不该用，以及四步流程
CLI 版规则	rules/context7-cli.md	同一套流程的无 MCP 版本：用 npx ctx7@latest library <name> "<query>" 和 npx ctx7@latest docs <libraryId> "<query>" 替代两个 MCP 工具；额外要求每问不超过 3 条命令、查询不含敏感信息、配额报错时提示 ctx7 login 或设置 CONTEXT7_API_KEY
Skill	skills/context7-mcp/SKILL.md	以 frontmatter 声明触发条件（询问库/框架/API/代码示例时激活），把四步流程展开为可执行的技能说明
MCP 服务器	packages/mcp/src/index.ts	真正实现 resolve-library-id（内部调用 searchLibraries）与 query-docs（内部调用 fetchLibraryContext），见 lib/api.ts

两者（规则文件与 CLI 规则）的正面清单、负面清单完全对齐，区别只在“调 MCP 工具”还是“跑 CLI 命令”。选择哪一份取决于 Agent 的配置模式：ctx7 setup --mcp 写入 MCP 规则，ctx7 setup --cli 则安装引导 Agent 使用 ctx7 library / ctx7 docs 命令的 docs skill（见 CLI 文档 Setup 章节）。

四、落地实践：认证、限制与可验证细节

认证与额度

规则文件本身不处理认证，但整个工作流依赖额度。从源码与文档可确认的认证途径：

• 环境变量 CONTEXT7_API_KEY：stdio 模式下与 --api-key 标志二选一（启动参数解析）；ai-sdk 工具同样在缺省时回落到该环境变量（resolveLibraryId 文档）；
• 匿名使用：MCP 模式不带 key 时会走匿名档，命中更低速率限制；CLI 模式下 ctx7 library / ctx7 docs 免登录可用，登录（ctx7 login）或设 CONTEXT7_API_KEY 可提升限额（CLI 文档）。

工具语义标注

两个工具在服务端都声明了 readOnlyHint: true、destructiveHint: false、openWorldHint: true、idempotentHint: true（annotations 字段）——即只读、可重复调用、访问外部世界。这对 Agent 框架意味着这两个调用可以安全地并行或重试，不会产生副作用。

与规则的自检对齐

如果你正在维护自己的 Agent 配置，可以对照以下三点验证规则是否真正生效（依据均来自本仓库，路径可直接核对）：

1. 顺序：Agent 是否在没有拿到 /org/project 形式 ID 前就不调用 query-docs——服务端 query-docs 的描述明确要求先 resolve（对应描述），规则文件第 1 步也如此规定；
2. 查询质量：查询是否被拆成单一概念、是否为描述性语句而非单个词——规则与 schema 描述反复强调；
3. 调用预算：单个问题内 resolve-library-id 与 query-docs 各自不超过 3 次——规则文件中 CLI 版显式写明，MCP 版写在各工具描述里。

五、小结

rules/context7-mcp.md 用不到 10 行文本定义了一套完整的“文档新鲜度”保障机制：触发条件（任何库/框架/SDK/API/CLI/云服务问题，知名库也不例外）→ 边界（重构、从零写脚本、业务逻辑调试、代码审查、通用概念除外）→ 流程（resolve-library-id 解析 → 五维度选 ID → 单概念 query-docs → 基于文档作答）→ 约束（每问题各工具至多 3 次、版本查询用 /org/project/version、查询不含敏感信息）。

它与 MCP 服务端实现（工具描述、参数别名容错、只读标注）、context7-mcp skill、CLI 版规则 构成同一套语义的四种载体。理解这条规则的最佳方式是把它读成“Agent 与 Context7 之间的协议契约”：规则层约束 Agent 的决策，schema 层兜住 Agent 的表达误差，服务端层提供实时文档——三层叠加，才能把“训练数据滞后”这一根本问题转化为可执行、可验证的工程流程。