Context7 context7-mcp 技能详解：让 AI Agent 用 MCP 两步获取最新库文档的工作流

skills/context7-mcp/SKILL.md 是 Context7 仓库中面向 AI 编码代理（Agent）的技能定义文件，它规定了当用户询问库、框架、API 参考或索要代码示例时，Agent 应如何通过 Context7 MCP 的 resolve-library-id 与 query-docs 两个工具获取当前最新的文档，而不是依赖可能过时的训练数据。读完本文，你将理解该技能的触发条件、四步检索工作流、查询质量准则，以及 MCP 服务端源码（packages/mcp/src/index.ts）如何从参数校验、容错别名重写到底层 API 调用完整支撑这套工作流。

技能定位：为什么需要 context7-mcp 技能

技能文件采用标准的 SKILL.md 结构，以 YAML frontmatter 声明元信息：

---
name: context7-mcp
description: This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.
---

其核心宗旨一句话概括：当用户问库、框架或需要代码示例时，用 Context7 拉取最新文档，而不是依赖训练数据。这源于一个大模型固有的问题——训练语料有截止日期，API 语法、配置项、版本行为随时在变。技能文件在正文开篇即要求 Agent「use Context7 to fetch current documentation instead of relying on training data」，把「主动查文档」从可选行为变成强制行为。

触发条件：何时激活该技能

技能文档明确列出了四类应激活该技能的场景：

• 用户提出安装或配置类问题（例如 "How do I configure Next.js middleware?"）；
• 用户请求涉及某个库的代码（例如 "Write a Prisma query for..."）；
• 用户需要 API 参考（例如 "What are the Supabase auth methods?"）；
• 用户点名具体框架（React、Vue、Svelte、Express、Tailwind 等）。

值得注意的反面清单在 MCP 服务端的工具说明中定义得更完整：服务端 instructions 字段声明该服务器适用于「用户询问库、框架、SDK、API、CLI 工具或云服务——即使是你熟悉的 React、Next.js、Prisma、Express、Tailwind、Django、Spring Boot」，包括 API 语法、配置、版本迁移、库相关调试、安装步骤与 CLI 用法；同时明确不适用于重构、从零写脚本、业务逻辑调试、代码审查和通用编程概念（见 packages/mcp/src/index.ts）。技能文件与工具描述在这点上互为补充：前者回答「何时激活」，后者回答「何时不要用」。

四步检索工作流

第一步：解析库 ID（resolve-library-id）

调用 resolve-library-id 工具，传入两个参数：

• libraryName：从用户问题中提取的库名；
• query：要在这个库的文档中查找什么（用于提升相关性排序）。

从源码看，该工具的输入用 Zod 定义，并且对参数有严格约束。libraryName 要求使用「带正确标点的官方库名——例如用 'Next.js' 而不是 'nextjs'、'Customer.io' 而不是 'customerio'」；query 则说明其「会被发送到 Context7 API 处理，不得包含 API key、密码、凭据、个人数据或专有代码等敏感信息」（见 packages/mcp/src/index.ts）。

工具返回的每个候选库都携带结构化字段：

• Library ID：Context7 兼容标识符，格式为 /org/project；
• Name：库或包名；
• Description：简短描述；
• Code Snippets：可用代码示例数量；
• Source Reputation：权威性指示（High / Medium / Low / Unknown）；
• Benchmark Score：文档质量指标（100 为最高分）；
• Versions：可用版本列表（如有）。用户指定版本时，版本 ID 格式为 /org/project/version。

工具描述中还有一条硬约束：每个问题最多调用 3 次，若 3 次后仍未找到目标，使用已有最佳结果（packages/mcp/src/index.ts）。

第二步：选出最佳匹配

技能文档给出三条选型判据：

1. 与用户所问名称精确或最接近的匹配优先；
2. Benchmark Score 更高表示文档质量更好；
3. 用户提到版本时（如 "React 19"），优先选择版本专属 ID，例如 /vercel/next.js/v14.3.0-canary.87 而非 /vercel/next.js。

完整的选型过程在工具描述中进一步细化为五步：分析查询意图、按名称相似度（精确匹配优先）选库、按描述相关性、按文档覆盖率（Code Snippet 数量更多者优先）、按 Source Reputation（High/Medium 更权威）、按 Benchmark Score 综合决策；若有多个好匹配则说明但继续用最相关的一个，若无好匹配则明确告知并建议优化查询，遇到歧义查询应请求澄清（packages/mcp/src/index.ts）。

第三步：拉取文档（query-docs）

调用 query-docs 工具，传入：

• libraryId：第二步选定的 Context7 库 ID（例如 /vercel/next.js）；
• query：要在文档中查找的内容，限定在单一概念范围内。

技能文档在此强调了一个关键的检索策略：如果用户的问题横跨多个独立概念（如同时涉及路由、认证和缓存），应当对同一 libraryId 按概念分别调用 query-docs，除非问题问的正是这些概念之间的相互作用——因为合并式查询会稀释排序信号，导致每个话题都只返回浅层结果。这一策略同样写入了 query-docs 的 query 参数描述，其中给出了正反例：好查询如 "How to set up authentication with JWT in Express.js"；坏查询如过于含糊的 "auth"、"hooks"，或过于宽泛的 "routing and auth and caching in Next.js"（packages/mcp/src/index.ts）。与 resolve-library-id 一样，query-docs 也有每个问题最多 3 次的调用上限（packages/mcp/src/index.ts）。

第四步：使用文档

将拉取到的文档融入回答：使用当前、准确的信息回答用户问题；附上文档中相关的代码示例；在相关时标注库版本。

准则汇总（Guidelines）

技能文档末尾的 Guidelines 是 Agent 执行该工作流时的行为红线，逐条继承如下：

• 要具体：描述要在库文档中查找什么，但每条 query 只覆盖一个概念；
• 一个 query 一个主题：把多主题问题拆成多次 query-docs 调用——库 ID 只解析一次，然后按概念查询；唯一例外是问题本身在问概念间如何交互；
• 版本感知：用户提到版本（"Next.js 15"、"React 19"）时，若解析步骤返回了版本专属 ID，就使用它；
• 优先官方来源：多个匹配存在时，优先官方/主包而非社区分支。

源码印证：MCP 服务端如何支撑这套工作流

技能文件描述的是「Agent 侧行为契约」，而 Context7 MCP 服务端在实现上为这套契约提供了几层保障，可以结合源码理解其设计动机。

1. 参数别名重写：抵御 LLM 的「幻觉参数名」。 源码中有一张别名映射表：全局层面 query 可被误写为 userQuery、question；query-docs 层面 libraryId 可被误写成 context7CompatibleLibraryID、libraryID 甚至 libraryName（后者其实是 resolve-library-id 的合法参数）。这些是 LLM 客户端从工具描述中「复述措辞」而非使用字面 schema 键名导致的。服务端在 Zod 校验前用 z.preprocess(aliasArgs(...)) 把别名静默重写回规范键名，使调用在工具运行前就能通过验证（packages/mcp/src/index.ts）。这意味着即使 Agent 按技能文档描述「用自己的话」传参，工作流依然可用。

2. 两个工具只读、幂等。 两个工具均声明了 readOnlyHint: true、idempotentHint: true、openWorldHint: true 注解（packages/mcp/src/index.ts），符合「只查文档」的语义，Agent 可以安全重试。

3. 底层 API 调用与超时。 工具执行后进入 packages/mcp/src/lib/api.ts：searchLibraries 请求 {CONTEXT7_API_BASE_URL}/v2/libs/search 并带上 query 与 libraryName 两个查询参数（packages/mcp/src/lib/api.ts）；fetchLibraryContext 请求 /v2/context 并带上 query 与 libraryId（packages/mcp/src/lib/api.ts）。所有请求都有 60 秒的 AbortSignal.timeout 上限——源码注释说明这些向量查询 p99.9 约 3.2 秒，60 秒是「宽松的上限」而非预期耗时（packages/mcp/src/lib/api.ts）。

4. 失败语义对 Agent 是可操作的。 API 错误会被翻译成面向 Agent 的指引：429 提示配额/限流并区分有无 API key 的升级路径；404 返回「该库不存在，请尝试其他库 ID」；/v2/context 返回空内容时会提示「可能使用了无效的 library ID，请用 resolve-library-id 重新获取有效 ID」（packages/mcp/src/lib/api.ts 与 packages/mcp/src/lib/api.ts）。这保证即使第三步失败，Agent 也能按技能工作流回退到第一步重来，而不是静默失败。

与仓库中其他文档化入口的关系

同一套「解析 ID → 查询文档」工作流在仓库中还有多个平行入口，可对照参考，但本文以 MCP 技能为核心：

• CLI 技能 skills/find-docs/SKILL.md：用 npx ctx7@latest library <name> "<query>" 与 npx ctx7@latest docs <libraryId> "<query>" 两条命令实现同样的两步流程，并额外提供认证方式（CONTEXT7_API_KEY 环境变量或 npx ctx7@latest login）、配额错误的处理策略与常见错误清单（如库 ID 必须带 / 前缀）；
• Cursor 规则文件 rules/context7-mcp.md：把相同的四步流程压缩为规则文件形式，供 Cursor 等以 rules 驱动的客户端使用；
• AI SDK 工具：docs/agentic-tools/ai-sdk/tools/resolve-library-id.mdx 与 docs/agentic-tools/ai-sdk/tools/query-docs.mdx 面向 Vercel AI SDK 场景，提供 resolveLibraryId() / queryDocs() 的 TypeScript 用法与输出格式示例，同样支持版本专属 ID（如 /vercel/next.js/v14.3.0-canary.87）。

MCP 服务端本身的发布坐标可在 packages/mcp/package.json 中确认：包名 @upstash/context7-mcp，MCP 标识 io.github.upstash/context7，要求 Node.js ≥ 20.18.1；默认以 stdio 传输运行（--transport http 时默认端口 3000），API key 可通过 --api-key 参数或 CONTEXT7_API_KEY 环境变量提供（packages/mcp/src/index.ts）。

小结：一个可复制的 Agent 侧检索清单

综合技能文档与源码，Agent 在使用 context7-mcp 技能时应当遵守的执行清单为：

1. 判断问题是否命中触发条件（库/框架/API 参考/代码生成/点名框架），命中则激活技能，不要依赖训练数据作答；
2. 调用 resolve-library-id，传官方写法的 libraryName 和体现用户意图的 query，单问最多 3 次；
3. 按「名称精确匹配 > 描述相关性 > 代码片段覆盖 > 来源信誉 > Benchmark 分数」选出最佳 ID，用户指定版本时选版本专属 ID；
4. 按概念拆分调用 query-docs，每条 query 单一主题、足够具体，同样单问最多 3 次；
5. 用返回文档作答，附文档中的代码示例并标注版本；失败时优先回退到第 2 步重新解析，而不是静默降级为训练数据作答。

这套「触发条件 + 两步工具调用 + 查询纪律 + 调用上限」的完整契约，正是 skills/context7-mcp/SKILL.md 的全部价值所在，它把一个可能过时的模型知识库，替换成了每次会话实时更新的文档检索管道。