Context7 Agent 插件中的 context7-mcp 技能：让 AI 编码助手按需拉取最新库文档的四步工作流

在 AI 编码助手与 LLM 的应用场景中，训练数据过期导致"幻觉 API"是一个普遍问题。本文以 Context7 仓库中可移植 Agent 插件的技能定义文件 SKILL.md 为核心，完整解析 context7-mcp 技能的触发条件、"解析库 ID → 选择最佳匹配 → 拉取文档 → 组织回答"四步工作流与查询准则，并结合 MCP 服务器实现、pi 包的工具定义 等仓库源码，说明每个参数（libraryName、query、libraryId）在真实工具链中的校验、别名容错与底层调用关系。读完本文，你将能够独立编写或复用 Context7 文档检索技能，并为自己的 Agent 客户端配置 MCP 接入。

技能是什么：SKILL.md 的结构与元数据

context7-mcp 技能位于 Agent 插件 plugins/agent-plugins/context7/ 目录的 skills/context7-mcp/ 下。整个插件遵循 Agent Plugins 1.0.0 规范的固定布局：根目录的 plugin.json 是插件清单（name: context7、作者 Upstash、MIT 协议、关键字 documentation / context / mcp / library-docs），mcp.json 声明 MCP 服务器，skills/ 目录下存放技能。插件 README 明确指出："This is the entire plugin"——兼容客户端只读取这两个固定位置的配置文件，支持 skills 的客户端会在 skills/ 下自动发现本技能。

SKILL.md 采用 YAML frontmatter + Markdown 正文的标准技能格式：

---
name: context7-mcp
description: Fetches current, version-specific library documentation and code examples
  through the Context7 MCP server. ...
---

其中 name 是技能的唯一标识，description 则是技能的路由依据：LLM 客户端在判断"当前对话是否该激活这个技能"时，主要依赖描述文本的语义匹配。这也是撰写技能描述时信息密度要求高的原因。

触发策略：何时用、何时不用

SKILL.md 的 description 字段是全文档最浓缩的部分，它实际上定义了两条边界——正向触发条件与负向排除条件：

正向触发（满足即应激活）：

• 用户询问任何库、框架、SDK、API、CLI 工具或云服务的问题，包括 API 语法、配置、安装说明、版本迁移、CLI 用法和库相关的调试；
• 需要生成调用第三方库的代码；
• 用户指定了版本，例如 "Next.js 15"、"React 19"；
• 即使是 React、Vue、Next.js、Prisma、Supabase、Express、Tailwind、Django、Spring Boot 这类众所周知的库也要用，因为训练数据可能未反映近期变更；
• 对库文档查询，优先于 web search。

负向排除（以下场景明确不用）：重构、从零写脚本、调试业务逻辑、代码评审、通用编程概念，以及用户已经提供了相关文档的情况。

这条触发策略与 MCP 服务器自身的 instructions 完全一致。在 packages/mcp/src/index.ts 中，服务器注册时写入的说明同样是："Use this server to fetch current documentation whenever the user asks about a library... Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts." 从源码结构看，技能描述、服务器 instructions、以及 rules/context7-mcp.md 规则文件三处表述高度同源——这是有意为之的"三重复诵"：技能负责让 Agent 知道"何时"调用，instructions 负责在 MCP 握手时告诉模型"这个服务器是干什么的"，rules 则面向不加载 skills 的客户端。

SKILL.md 正文的 "When to Use This Skill" 一节给出了四类典型触发场景：

场景	示例
安装与配置类问题	"How do I configure Next.js middleware?"
涉及库的代码生成	"Write a Prisma query for..."
API 参考类问题	"What are the Supabase auth methods?"
提及具体框架	React、Vue、Svelte、Express、Tailwind 等

四步工作流：resolve → select → query → use

Step 1：调用 resolve-library-id 解析库 ID

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

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

这一点在 pi 包的工具实现 中可以得到印证：Params 使用 typebox 定义了 query 与 libraryName 两个必填字符串字段，execute 内部调用 searchLibraries(params.query, params.libraryName)，无结果时返回错误文本，有结果时用 formatSearchResults 格式化列表。MCP 服务端的同名工具（index.ts）则使用 zod 定义同样两个字段，并在参数描述中给出了关键的使用细节：

• libraryName 要求使用官方规范写法——例如 "Next.js" 而非 "nextjs"、"Customer.io" 而非 "customerio"、"Three.js" 而非 "threejs"；
• query 会被发送到 Context7 API 做相关度排序，因此不要在其中包含 API 密钥、密码、凭证、个人数据或专有代码等敏感信息。

值得一提的是 MCP 服务端对 LLM 常见"参数幻觉"的容错处理。在 index.ts 中，aliasArgs 预处理函数会在 zod 校验之前重写被模型写错的参数名：全局别名将 userQuery、question 统一改写为 query；针对 query-docs 还有工具级别名，将 context7CompatibleLibraryID、libraryID、libraryName 改写为 libraryId。源码注释解释了动机："LLM clients often echo phrasing from tool descriptions instead of the literal schema keys, which trips Zod validation before the tool runs." 也就是说，即使模型把参数名写成了描述文本里的措辞，请求也不会在校验阶段直接失败——这是理解"技能文档为什么要反复强调参数名"的工程背景。

Step 2：从候选中选择最佳匹配

resolve-library-id 返回的是候选列表，模型需要从中挑选。SKILL.md 给出三条选择依据：

1. 与用户所问库名的精确或最近似名称匹配；
2. Benchmark 分数更高表示文档质量更好；
3. 用户提到版本时（如 "React 19"），优先选择版本化 ID。

这与工具自身的 description 中的 "Selection Process" 相互印证（pi 包 prompts.ts 逐字复制了 MCP 服务端的工具描述）。完整的评分维度包括：

• Library ID：Context7 兼容标识符，格式为 /org/project；
• Code Snippets：可用代码示例数量，覆盖度越高越好；
• Source Reputation：权威度指标（High / Medium / Low / Unknown），High 或 Medium 更可信；
• Benchmark Score：质量指标，100 为最高分；
• Versions：可选版本列表，若用户指定了版本应选用 /org/project/version 形式（例如 /vercel/next.js/v14.3.0-canary.87，该格式见 query-docs 的 libraryId 参数描述）。

description 中还包含两条行为约束值得注意：每个问题最多调用 3 次 resolve-library-id，找不到就用已有最佳结果；对于模糊问题，应先请求澄清而不是猜测。此外，若用户在问题中已直接给出 /org/project 形式的库 ID，则可跳过本步骤直接进入 Step 3。

Step 3：调用 query-docs 拉取文档

确定库 ID 后，调用 query-docs 工具，参数为：

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

SKILL.md 在此处给出了一条核心准则：当用户问题横跨多个不同概念（例如路由、鉴权、缓存）时，应对每个概念单独发起一次 query-docs 调用，复用同一个库 ID；除非问题本身在问这些概念之间的相互作用。原因是"组合查询会稀释排序，导致每个主题都只得到肤浅的结果"。

这条准则在 query-docs 的 query 参数描述 中被进一步具象化为正反例：

• 好的查询："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"。

服务端同样声明"每个问题最多调用 3 次"（index.ts）。pi 包的 query-docs 工具实现 则展示了这条链路的另一端：参数经 typebox 校验后，fetchLibraryContext(params.query, params.libraryId) 直接向 Context7 API 发起请求，返回文本即文档内容。从 packages/mcp/src/lib/api.ts 的实现还能看到底层细节：单次 API 调用有 60 秒超时上限（注释说明生产流量 p99.9 约 3.2 秒），并且对错误状态码有明确语义——429 为限流或配额超限、404 为库 ID 不存在、401 提示 API key 应以 ctx7sk 前缀开头。这些行为决定了实际调试时如何区分"库没收录"与"配额用尽"两类失败。

Step 4：将文档融入回答

拉取到文档后的使用规范：

• 用当前且准确的信息回答用户问题；
• 从文档中纳入相关代码示例；
• 在相关处注明库的版本。

这三条把"检索"与"生成"衔接起来：技能的目的不是把文档原样贴给用户，而是让模型的输出建立在与用户指定版本一致的 API 事实上。

技能准则详解：四条 Guidelines

SKILL.md 末尾的 Guidelines 是工作流的执行纪律：

1. Be specific（要具体）：描述要查什么，但每次查询只针对一个概念；
2. One topic per query（一题一查）：多主题问题拆成多次 query-docs 调用——库 ID 只解析一次，然后按概念逐个查询（概念间相互作用的问题除外）；
3. Version awareness（版本意识）：用户提到 "Next.js 15"、"React 19" 这类版本时，若解析结果中存在版本化库 ID 就应选用；
4. Prefer official sources（优先官方源）：存在多个匹配时，优先官方/主包而非社区 fork。

这四点与 MCP 服务端工具 description、rules/context7-mcp.md 的 Steps 一节构成同一套规则的三种载体形式（技能 / MCP instructions / 静态规则文件），覆盖了不同客户端的能力差异。

可移植性设计：为什么插件走 OAuth 而不是 API Key

理解这个技能如何被加载，还要理解它所在的 Agent 插件为何这样设计。mcp.json 只声明了一台远程服务器：

{
  "mcpServers": {
    "context7": {
      "type": "streamable-http",
      "url": "https://mcp.context7.com/mcp/oauth"
    }
  }
}

插件 README 的 "Why not an API key?" 一节给出了两条规范层面的硬约束：Agent Plugins 1.0 客户端不得展开 url 或请求头中的 ${VAR} 占位符；请求头值属于"可见的包数据"，插件不得在其中内嵌密钥。因此本仓库其他客户端专属插件中常见的 "Authorization": "${CONTEXT7_API_KEY}" 模式在此不可移植，OAuth 是唯一能让用户认证自己账号的方式。首次连接时服务器返回 401 与 WWW-Authenticate 头，客户端自行完成授权服务器发现、动态客户端注册（支持 PKCE S256）并打开浏览器授权，令牌由客户端保管——仓库中不出现任何密钥。

从源码结构看，这条远程链路对应的是 packages/mcp 中实现的同一套工具（resolve-library-id 与 query-docs 的描述文本、参数别名处理逻辑在 stdio/HTTP 两种传输下共用），而 pi 扩展 则是把同等能力内嵌为客户端原生工具的另一种形态——注释明确说明工具描述"copied verbatim from @upstash/context7-mcp"，目的是让 pi 与 MCP 客户端获得完全一致的模型指令。

另外两点可移植性限制值得了解（同样来自插件 README 的 "Notes on Portability"）：plugin.json 使用封闭 schema，不允许在清单里声明组件路径，客户端按固定位置发现文件；1.0 版本不支持 commands、agents、hooks、rules 作为可移植组件，因此 /context7:docs 命令和 docs-researcher agent 仍留在 plugins/claude/、plugins/copilot/ 等客户端专属插件中。若你的客户端不支持 OAuth 流程，规范将连接失败视为"单台服务器不可用"而非插件损坏——技能本身仍会加载，此时应改用对应的客户端专属插件。

小结：一份可直接对照的检查清单

综合 SKILL.md 与仓库源码，context7-mcp 技能的核心可归纳为一张执行清单：

1. 识别触发条件：涉及库/框架/SDK/CLI/云服务的文档或代码问题，即使库很知名也要触发；重构、业务逻辑调试、代码评审不触发；
2. resolve-library-id：libraryName 用官方规范写法，query 说明查找意图且不携带敏感信息；单问题最多调用 3 次；
3. 选择依据名称匹配、Snippet 覆盖度、Source Reputation、Benchmark Score，用户指定版本时选用 /org/project/version 形式 ID；
4. query-docs：一次调用只查一个概念，多概念拆多次调用；查询文本避免"auth"这类模糊词；
5. 回答时引用文档中的代码示例并注明库版本。

技能定义文件（SKILL.md）、MCP 服务端（packages/mcp/src/index.ts）、pi 工具实现（packages/pi/lib/tools/）与客户端规则文件（rules/context7-mcp.md）在仓库中保持了同一套措辞与约束，这保证了无论 Agent 走哪条接入路径，模型拿到的检索纪律都是一致的。