Context7 for GitHub Copilot CLI：基于 MCP 技能自动检索库文档的 resolve-library-id 与 query-docs 工作流

本文以 Context7 仓库中 GitHub Copilot CLI 插件自带的 context7-mcp 技能（Skill）文档为主体，完整还原「何时触发技能 → 解析库 ID → 拉取文档 → 组织答案」的四步检索工作流，并结合 Context7 MCP Server 的源码，深入讲解 resolve-library-id 与 query-docs 两个 MCP 工具的参数语义、服务端行为（限次、超时、错误处理、参数别名重写）与版本固定（version pinning）技巧。读完本文，你可以在 Copilot CLI 中获得不依赖过时训练数据的库文档能力，并理解该技能背后每一次工具调用的真实链路。

背景：为什么 Copilot CLI 需要 Context7 技能

AI 编码助手回答库相关问题时，往往依赖训练数据中的旧版本 API，容易产生“幻觉 API”——方法名、参数、配置项与当前版本不符。Context7 的解法是：让 Agent 在回答前先通过 MCP（Model Context Protocol）工具实时拉取源仓库中最新的文档与代码示例。

在 Copilot CLI 场景下，该能力由仓库中 plugins/copilot/context7 目录下的插件整体提供，插件由四部分组成：

• MCP Server：连接 Context7 文档服务，暴露 resolve-library-id 与 query-docs 两个工具；
• Skills：即本文主角 SKILL.md，当用户问到库/框架/API 时自动触发文档检索；
• Agents：docs-researcher 子代理，在独立上下文中执行检索，避免污染主对话；
• Commands：/context7:docs 手动查询命令。

本文聚焦其中的 Skill，其余组件仅作为工作流的延伸入口简要提及。

安装与前置配置

安装插件

按插件 README（plugins/copilot/context7/README.md）的说明，在 Copilot CLI 中执行：

copilot plugin marketplace add upstash/context7
copilot plugin install context7@context7-marketplace

也可以在交互式会话中用 /plugin marketplace add upstash/context7 与 /plugin install context7@context7-marketplace 完成相同操作（见 GitHub Copilot CLI 客户端文档）。

插件如何接入 MCP Server

查看 plugins/copilot/context7/.mcp.json 可知，插件并不在本地起 stdio 进程，而是直连 Context7 的托管 HTTP 端点：

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "${CONTEXT7_API_KEY:-}"
      }
    }
  }
}

两点值得注意：

1. URL 与插件声明：plugin.json 中以 "mcpServers": ".mcp.json" 指向上面这份 MCP 配置，name 为 context7，skills 指向 skills/ 目录——也就是说 SKILL.md 与 MCP 配置是同一插件包里的两个组成部分，安装即同时生效。

2. API Key 是环境变量注入：Authorization 头取自 ${CONTEXT7_API_KEY:-}。不设置 key 时以匿名身份连接、共享匿名的速率限制；创建 API key 后需导出环境变量再重启 Copilot CLI：

   # e.g. in ~/.zshrc or ~/.bashrc
   export CONTEXT7_API_KEY="your-api-key"
   

   这与 MCP Server 源码一致：stdio 模式从 --api-key 参数或 CONTEXT7_API_KEY 环境变量读取密钥（见 packages/mcp/src/index.ts），HTTP 模式则通过 Authorization 等请求头解析（见 packages/mcp/src/index.ts）。API key 应以 ctx7sk 前缀开头（源码错误提示见 packages/mcp/src/lib/api.ts）。

技能定义：何时触发 SKILL.md

技能的元数据在 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.
---

根据 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 等

核心原则一句话：当用户问库、框架、API 参考或要代码示例时，用 Context7 拉取最新文档，而不是依赖训练数据。这也与 MCP Server 在 instructions 中向所有客户端下发的总则一致（packages/mcp/src/index.ts）：即使用户问的是 React、Next.js 这类“你觉得你懂的”知名库，也应优先查文档而非凭记忆作答；反之，重构、从零写脚本、业务逻辑调试、代码评审等场景不使用该工具。

四步检索工作流（技能正文）

SKILL.md 主体把一次文档检索拆成四个步骤。下面逐步展开，并标注每一步对应的服务端实现。

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

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

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

服务端参数细节（来自 packages/mcp/src/index.ts 的 Zod schema）：

• libraryName（string，必填）：应使用带正确标点的官方库名，例如 Next.js 而不是 nextjs、Three.js 而不是 threejs；
• query（string，必填）：用户想完成的事，Context7 API 会用它对候选库做相关性排序。描述中明确要求不要在 query 中携带 API key、密码等敏感信息；
• 调用频率约束：工具描述中硬性规定 Do not call this tool more than 3 times per question——同一问题最多调用 3 次，找不到就用已有最佳结果。

底层链路：工具处理器调用 searchLibraries(query, libraryName, ctx)（packages/mcp/src/index.ts），后者对 Context7 后端发起 GET 请求 ${CONTEXT7_API_BASE_URL}/v2/libs/search，附带 60 秒超时（packages/mcp/src/lib/api.ts）。若返回结果为空，工具直接把错误文本（如限流提示）返回给客户端，并可能触发登录引导（maybeElicitAuthSignIn）。

Step 2：选择最佳匹配

从解析结果中选择库 ID，SKILL.md 给出的判据是：

• 与用户所问精确或最接近的名称匹配；
• 更高的 benchmark score 表示更好的文档质量；
• 用户提到版本时（如 "React 19"），优先选版本特定的 ID。

服务端返回的每条候选结果实际包含更多可参考的维度，格式化输出逻辑见 formatSearchResults（packages/mcp/src/lib/utils.ts），每条结果包含：

• Library ID：/org/project 格式的 Context7 兼容 ID；
• Name / Description：库名与简介；
• Code Snippets：可用代码示例数量（文档覆盖度）;
• Source Reputation：权威性指标（High / Medium / Low / Unknown）;
• Benchmark Score：质量指标，100 为最高分；
• Versions：可用版本列表，格式 /org/project/version。

工具描述同时给出了更完整的选型过程：名称相似度（精确匹配优先）→ 描述与意图的相关性 → 代码片段数量 → Source Reputation → Benchmark Score；多个优质候选时择一继续，无合适匹配时明确说明并建议细化查询。SKILL.md 的 "Prefer official sources" 原则与此呼应：多个匹配时优先官方/主包，而非社区 fork。

Step 3：用 query-docs 拉取文档

选定 ID 后调用 query-docs：

• libraryId：选中的 Context7 库 ID（如 /vercel/next.js，或带版本的 /vercel/next.js/v15.1.8）；
• query：要查的内容，限定为单一概念。

服务端参数说明（packages/mcp/src/index.ts）对 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'。

SKILL.md 对此有同样的规定，并给出了明确的拆分策略：若用户问题跨多个独立概念（如路由 + 认证 + 缓存），用同一个 libraryId 对每个概念各发一次 query-docs；除非问题本身就是问这些概念如何相互作用——混合查询会稀释排序、导致每个主题都只能拿到浅层结果。同样地，同一问题内 query-docs 最多调用 3 次。

底层链路：工具处理器调用 fetchLibraryContext({ query, libraryId }, ctx)（packages/mcp/src/index.ts），后端接口为 GET ${CONTEXT7_API_BASE_URL}/v2/context（packages/mcp/src/lib/api.ts）。注意一个防御性细节：resolve-library-id 的工具描述明确 You MUST call this function before 'Query Documentation' tool，除非用户已经直接给出了 /org/project 或 /org/project/version 格式的 ID——此时可跳过解析步骤直查。/context7:docs 命令的 "How It Works" 也按此实现（library 参数以 / 开头即直接作为 ID 使用，见 commands/docs.md）。

Step 4：组织并回答

把拉到的文档融入最终回复：

• 用当前、准确的信息回答用户问题；
• 附上文档中的相关代码示例；
• 在相关时标注库版本（版本敏感 API 尤其重要）。

源码视角：两个工具在服务端的健壮性设计

阅读 packages/mcp/src/index.ts 可以发现几个直接提升“LLM 客户端可用性”的实现细节，它们解释了技能为什么能在真实对话中稳定跑通：

1. 参数别名重写（aliasing）

LLM 客户端经常照抄工具描述里的措辞，而不是 schema 的字段名，导致 Zod 校验在工具执行前就失败。服务端在 schema 前挂了一层 z.preprocess(aliasArgs(...))（packages/mcp/src/index.ts）：

• 全局别名：query 接受 userQuery、question；
• query-docs 专属别名：libraryId 接受 context7CompatibleLibraryID、libraryID、libraryName（因为 libraryName 是 resolve-library-id 的规范参数名，在 query-docs 上出现时按幻觉处理并重写）。

也就是说，即使 Agent 传错了字段名，请求也会被透明纠正——这是技能“Step 1 → Step 3”在真实模型输出下仍高成功率的底层保障之一。

2. 错误与限流的处理

所有 API 调用统一 60 秒超时，失败时 parseErrorResponse 按状态码转成可读信息（packages/mcp/src/lib/api.ts）：

HTTP 状态	返回给 Agent 的信息
429	限流/配额超限；无 key 时提示去 dashboard 创建免费 key，有 key 时提示升级套餐
404	该库 ID 不存在，建议换一个 library ID
401	API key 无效，提示 key 应以 ctx7sk 开头
其他	Request failed with status <code>. Please try again later.

另外，当 /v2/context 返回空文本（文档未解析或未定型）时，服务端会返回一条明确指引：很可能是用了无效的库 ID，请改用 resolve-library-id 重新解析（packages/mcp/src/lib/api.ts）——这把“Step 3 失败后回到 Step 1”的恢复路径直接写进了返回值。

3. 工具注解

两个工具都注册了 MCP 注解：readOnlyHint: true、destructiveHint: false、openWorldHint: true、idempotentHint: true（packages/mcp/src/index.ts），即声明为只读、可重复、面向外部世界的安全工具，客户端可据此放心自动调用。

实战：调用形态与版本固定

自然语言触发（技能自动生效）

安装插件后无需说 “use context7”，直接问即可：

How do I set up authentication in Next.js 15?
Show me React Server Components examples
What's the Prisma syntax for relations?

也可以显式调用或跳过解析直接给 ID：

use context7 to show me how to set up middleware in Next.js 15
use context7 with /supabase/supabase for authentication docs

手动命令 /context7:docs

commands/docs.md 定义了手动查询入口，格式为：

/context7:docs <library> [query]

• library：库名，或以 / 开头的 Context7 ID（给 ID 可跳过解析步骤）；
• query：可选但推荐；每个独立概念单独执行一次命令（除非问的是概念间如何交互）。

示例：

/context7:docs react hooks
/context7:docs next.js authentication
/context7:docs prisma relations
/context7:docs /vercel/next.js/v15.1.8 app router
/context7:docs /supabase/supabase row level security

版本固定（Version Pinning）

要拿到特定版本的文档，把版本拼进库 ID 即可：

/vercel/next.js/v15.1.8
/supabase/supabase/v2.45.0
/context7:docs /facebook/react/v19.0.0 use hook

resolve-library-id 的返回结果本身就携带 versions 列表，便于挑选与项目一致的版本。对应 SKILL.md 的 "Version awareness" 原则：用户提到 "Next.js 15"、"React 19" 时，只要解析步骤返回了版本特定 ID，就应优先使用。

docs-researcher 子代理：保持主上下文干净

当你处于长任务中、不希望文档工具调用塞满主对话上下文时，可改用插件自带的 docs-researcher 子代理。它执行与本文技能完全相同的四步流程（识别库 → 解析 ID → 选最佳匹配 → 拉取文档），但在独立上下文中运行、只返回精炼答案：

copilot --agent docs-researcher -p "look up Supabase auth methods"

选择建议（来自 客户端文档）：上下文已很长/想避免膨胀时用 Agent；上下文尚短、希望文档直接可见于对话时用内联工具（即本文的技能）。

技能准则速查

将 SKILL.md 的 Guidelines 与服务端约束合并成一张速查表：

准则	说明	依据
查询要具体	query 描述清楚要查什么，但每次只针对一个概念	SKILL.md "Be specific"
一个 query 一个主题	多主题拆成多次 query-docs（复用同一 libraryId）；“概念如何交互”类问题除外	SKILL.md "One topic per query" + 工具描述
版本意识	用户提到版本时优先版本特定 ID（/org/project/version）	SKILL.md "Version awareness"
优先官方源	多个匹配时选官方/主包，不选社区 fork	SKILL.md "Prefer official sources"
限次	resolve-library-id 与 query-docs 各自同一问题最多 3 次	工具描述（packages/mcp/src/index.ts）
可跳过解析	用户已给出 /org/project[/version] 格式 ID 时可直接 query-docs	工具描述
用尽信息作答	结合拉取文档回答，附代码示例并标注版本	SKILL.md Step 4

小结

Copilot CLI 插件中的 context7-mcp 技能把“查最新库文档”沉淀为一条可自动触发的固定工作流：resolve-library-id（带 libraryName + query 做相关性排序）→ 按名称/评分/版本选 ID → 每个概念一次 query-docs → 用带版本信息的最新文档作答。结合 MCP Server 源码可以看到，限次约束、60 秒超时、状态码可读化、参数别名重写与失败回退指引共同保证了这条工作流在真实 LLM 客户端上的可靠性。理解这条链路后，无论是编写自己的 Agent 技能、还是在 Copilot CLI 中配合 /context7:docs 与 docs-researcher 子代理使用，你都能更精确地控制“查什么、查哪一版、怎么拆查询”。