Context7 Agent Plugin：让任意 Agent 客户端通过 MCP 实时获取版本化库文档的便携式插件

Context7 Agent Plugin 是 Context7 仓库中面向 Agent Plugins 规范 1.0.0 实现的便携式插件：它不绑定任何特定客户端，任何兼容该规范的 Agent 客户端都能用同一条安装命令获得"按查询时从源码仓库拉取真实文档"的能力，从而绕开 LLM 训练数据过时、幻觉出不存在 API 的问题。读完本文，你将理解该插件的完整文件结构与清单字段、OAuth 2.1 认证链路的工作方式、resolve-library-id 与 query-docs 两个 MCP 工具的标准调用流程，以及为什么在这种规范形态下 API Key 方案不可行、哪些组件必须留在各客户端专属插件中。

插件解决什么问题，以及它包含什么

AI 编码助手依赖训练数据，而训练数据会过时——助手会自信地引用已被删除的 API、已改名的参数。Context7 的做法是在查询时直接从源码仓库获取真实文档。这个插件把该能力封装成了最小形态的可分发单元，README（plugins/agent-plugins/context7/README.md）将其拆解为两个组件：

组件	位置	说明
MCP 服务器	mcp.json	基于 Streamable HTTP 的远程 Context7 服务器，通过 OAuth 授权
Skill	skills/context7-mcp/	当你询问某个库时触发文档检索

context7/
├── plugin.json
├── mcp.json
├── skills/
│   └── context7-mcp/
│       └── SKILL.md
├── LICENSE
└── README.md

这就是整个插件的全部文件。Agent Plugins 规范使用固定位置（fixed locations），因此任何兼容客户端读取的都是同两个文件：根目录的 plugin.json（插件清单）与 mcp.json（MCP 服务器配置）；支持 Skill 的客户端则会在 skills/ 目录下发现技能。

清单与 MCP 配置：逐字段解读

plugin.json：一个刻意"空"的扩展区

plugin.json 的实际内容如下：

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "context7",
  "version": "1.0.0",
  "description": "Up-to-date documentation lookup. Pull version-specific documentation and code examples directly from source repositories into your LLM context.",
  "author": {
    "name": "Upstash",
    "email": "[e-mail]",
    "url": "https://upstash.com"
  },
  "homepage": "https://context7.com",
  "repository": "https://github.com/upstash/context7",
  "license": "MIT",
  "keywords": ["documentation", "context", "mcp", "library-docs"]
}

注意其中没有任何组件路径声明——没有 agents、commands、mcpServers 之类的字段。这是规范约束而非疏忽：Agent Plugins 1.0 的 plugin.json 采用闭合 schema（closed schema），顶层只允许 $schema、name、version、description、author、homepage、repository、license、keywords、extensions 十个字段，与 Codex/Copilot 清单可以自定义组件路径不同。

mcp.json：唯一的 MCP 声明

mcp.json 的全部内容：

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "context7": {
      "type": "streamable-http",
      "url": "https://mcp.context7.com/mcp/oauth"
    }
  }
}

只有三行有效配置：服务器名为 context7，传输类型为 streamable-http（流式 HTTP），端点为 https://mcp.context7.com/mcp/oauth。刻意没有 headers 字段——原因见下文认证章节。另外值得注意的是，插件没有设置 extensions 命名空间：按规范，客户端私有数据应放在客户端自己定义的逆向域名键（reverse-domain key）下，本插件不声明任何客户端专属数据，以换取最大可移植性。

Skill：Agent 如何知道"该查文档了"

skills/context7-mcp/SKILL.md 是插件的行为层。其 frontmatter 中的 description 是一份精确的触发条件清单，定义了激活与不激活的边界：

• 激活：用户询问库/框架/SDK/API/CLI 工具/云服务的问题，包括 API 语法、配置、安装步骤、版本迁移、CLI 用法与库专属调试；生成调用第三方库的代码时；用户提到具体版本（如 "Next.js 15"、"React 19"）时。即便对 React、Vue、Next.js、Prisma、Supabase、Express、Tailwind、Django、Spring Boot 这类知名库也应使用——因为训练数据可能不反映近期变更；查库文档时优先于网络搜索。
• 不激活：重构、从零写脚本、调试业务逻辑、代码审查、通用编程概念，或用户已经提供了相关文档。

Skill 正文规定了标准的四步文档检索工作流：

1. 解析库 ID：调用 resolve-library-id，传 libraryName（从用户问题中提取的库名）与 query（要查找的内容，用于提升相关性排序）。
2. 选择最佳匹配：优先名字精确或最接近的匹配；更高的 benchmark 分数代表文档质量更好；用户提到版本时优先版本专属 ID。
3. 拉取文档：调用 query-docs，传 libraryId（如 /vercel/next.js）与限定为单一概念的 query。若问题横跨多个独立概念（如路由、鉴权、缓存各一），就对同一库 ID 分多次调用 query-docs，除非问题问的是这些概念之间的交互——合并查询会稀释排序，每个主题都只返回浅层结果。
4. 使用文档：用拉取到的信息作答、附上文档中的代码示例、在相关时注明库版本。

指南还强调：每次查询只覆盖一个主题；多个匹配时优先官方主包而非社区 fork。

安装

用你所在客户端的插件命令安装该目录即可。具体命令因客户端而异，但所有合规客户端都接受插件目录路径：

<your-agent> plugin install ./plugins/agent-plugins/context7

如果客户端支持远程源，也可以直接从仓库安装。由于清单和 MCP 配置都位于规范固定位置，同一份目录对任何兼容客户端都是可用的。

认证机制：为什么是 OAuth 2.1 而不是 API Key

首次连接发生了什么

插件指向的端点是 https://mcp.context7.com/mcp/oauth，走 OAuth 2.1 授权。首次连接的完整链路是：

1. 客户端发起连接，服务器返回 401 并携带 WWW-Authenticate 头；
2. 客户端根据该头发现授权服务器，执行动态客户端注册（Dynamic Client Registration）——即插件无需预先注册任何 client id；
3. 客户端打开浏览器让用户批准访问，支持 PKCE（S256）；
4. 令牌由客户端存储。

整个过程中用户无需在任何地方粘贴密钥，本仓库中也不落盘任何 secret。

为什么不用 API Key？

仓库里确实存在 API Key 方案：Claude Code 与 Copilot CLI 的专属插件在其 .mcp.json 中使用了占位符注入请求头，例如 plugins/claude/context7/.mcp.json 与 plugins/copilot/context7/.mcp.json 都写有：

"Authorization": "${CONTEXT7_API_KEY:-}"

plugins/claude/context7/README.md 的说明是：不设 key 时插件匿名连接并共享匿名速率限制；导出 CONTEXT7_API_KEY 环境变量后再启动客户端即可使用自己的配额。

但这一模式不可移植到 Agent Plugins 形态。README 给出了规范层面的两条硬约束：

• Agent Plugins 1.0 的清单刻意没有凭据字段；
• 客户端不得对 url 或头的名称、值做 ${VAR} 占位符展开；
• 头的值属于"可见的包数据"（visible package data），插件不得在其中嵌入 secret。

因此 "Authorization": "${CONTEXT7_API_KEY}" 这种在客户端专属插件中有效的写法，在通用插件中无法承载。OAuth 是在该形态下让用户认证自己的账户的唯一方式——这正是本插件选择 OAuth 端点的原因。

客户端支持度：OAuth 是客户端的职责

此规范版本中授权完全由客户端管理：不能执行 OAuth 流程的客户端会连接不上该服务器。规范把这视为单一服务器的连接失败，而非插件损坏，所以 Skill 仍然会加载。如果所在客户端不支持 OAuth，应改用 plugins/ 目录下该客户端的专属插件（如 plugins/claude/context7/、plugins/copilot/context7/），它们通过 API Key 环境变量走各自的配置机制。

可用的两个 MCP 工具

连接成功后，插件暴露两个工具，恰好对应 Skill 四步流程的第 1、3 步：

resolve-library-id

搜索库并返回 Context7 兼容的标识符，如 /vercel/next.js。入参 libraryName 与 query（后者用于改善排序）。

query-docs

按已解析的库 ID 拉取文档，且每次调用限定一个概念。多概念问题应复用同一个 library ID 拆分多次调用——这一约束直接写在 SKILL.md 的调用指南里，目的是避免复合查询稀释排序、导致每个主题都只得到浅层结果。

可移植性边界：1.0 规范下不能装进这个插件的东西

README 的 "Notes on Portability" 一节划清了该插件的能力边界，值得逐条理解：

1. 闭合 schema 限制：顶层只允许十个字段（前文已列），组件路径无法在清单中声明。作为对照，本仓库中 plugins/copilot/context7/plugin.json 这样的 Copilot 专属清单则显式声明了 "agents": "agents/"、"skills": "skills/"、"commands": "commands/"、"mcpServers": ".mcp.json"——这些字段在 Agent Plugins 1.0 清单中都不存在。
2. 不使用 extensions 命名空间：客户端专属数据应挂在客户端自定义的逆向域名键下，本插件不声明任何此类键。
3. 命令、Agent、hooks、rules 不是 1.0 的便携式组件类型：所以 /context7:docs 命令与 docs-researcher agent 留在各客户端专属插件里（例如 plugins/claude/context7/agents/docs-researcher.md、plugins/copilot/context7/agents/docs-researcher.agent.md），而不进入这个通用插件。

从仓库结构看，这也解释了 plugins/ 目录的组织方式：agent-plugins/context7/ 是跨客户端的最小公共子集（MCP 服务器 + Skill），而 claude/、codex/、copilot/、cursor/ 等子目录各自叠加了命令、agent、rules 等客户端专属组件；plugins/context7-power/mcp.json 一类更细的变体则服务于特定组合场景。

小结：何时选这个插件

• 你的客户端兼容 Agent Plugins 1.0 且支持 OAuth 流 → 直接 plugin install 本插件目录，零密钥配置，认证绑定你自己的账户；
• 你的客户端不支持 OAuth（例如只认环境变量）→ 改用对应客户端专属插件并按其 README 导出 CONTEXT7_API_KEY；
• 需要 /context7:docs 斜杠命令或 docs-researcher 子代理 → 这些能力在 1.0 规范下不便携，去客户端专属插件中获取。

无论走哪条路径，核心能力一致：让 Agent 在查询时拿到来源仓库中的当前版本文档，而不是训练时的快照。