Context7 OpenCode 插件实战：一条命令为 OpenCode 接入 Context7 MCP 服务器与文档技能

Context7 OpenCode 插件（@upstash/context7-opencode）用于解决 AI 编码助手的典型痛点：训练数据过时与 API 幻觉。它通过一条命令为 OpenCode 注册托管的 Context7 MCP 服务器（提供 context7_resolve-library-id 与 context7_query-docs 两个工具），并自动安装 context7-mcp 技能，让你在询问库、框架用法时自动拉取源头仓库中的最新文档。读完本文，你可以完成插件的安装、API Key / OAuth 两种鉴权方式的配置，并理解插件修改 OpenCode 配置的底层机制与覆盖规则。

插件包含什么

安装插件后，OpenCode 会新增两类能力，两者都是**增量（additive）**注入：

• MCP Server：托管的 Context7 服务器，暴露 context7_resolve-library-id（检索库并返回 Context7 兼容 ID）和 context7_query-docs（按问题相关性排序拉取文档）两个工具；
• Skill：context7-mcp 技能，当你的提问涉及某个库（如 React、Next.js、Prisma、Supabase）时自动触发文档检索。

从源码结构看，插件本体只有一个入口文件 packages/opencode/src/index.ts，其中定义了托管端点常量与服务器名：

const MCP_BASE_URL = "https://mcp.context7.com";
const MCP_URL = `${MCP_BASE_URL}/mcp`;
const MCP_OAUTH_URL = `${MCP_BASE_URL}/mcp/oauth`;
const MCP_SERVER_NAME = "context7";

（见 src/index.ts）没有 API Key 时走 OAuth 端点（/mcp/oauth），有 API Key 时走普通端点（/mcp）并用请求头鉴权。

安装

在项目目录中执行：

opencode plugin @upstash/context7-opencode

该命令会安装插件并将其写入 OpenCode 配置。也可以手动编辑 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@upstash/context7-opencode"]
}

安装后重启 OpenCode。首次文档查询时，OpenCode 会自动打开浏览器窗口让你通过 OAuth 登录 Context7，从而使用你账户对应的速率限制。

鉴权：OAuth 默认，API Key 可覆盖

插件的鉴权优先级在 src/index.ts 中一行代码即可确认：

const apiKey = nonEmptyString(options?.apiKey) ?? nonEmptyString(process.env.CONTEXT7_API_KEY);

即插件选项 apiKey 优先于环境变量 CONTEXT7_API_KEY，两者都缺省时走 OAuth 流程。

环境变量方式（适合无头机器）

OAuth 是默认方式且无需配置。如果要在无浏览器的机器上使用 API Key，可在 Context7 dashboard 创建密钥后，启动 OpenCode 前导出：

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

插件会自动拾取 CONTEXT7_API_KEY 并以 Authorization 请求头发送，跳过 OAuth 流程。

插件选项方式

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [["@upstash/context7-opencode", { "apiKey": "your-api-key" }]]
}

从源码看，Context7PluginOptions 接口只声明了可选的 apiKey 字段（src/index.ts），这是插件目前暴露的唯一配置项。

插件如何改写 OpenCode 配置

核心逻辑在 applyContext7Config 函数（src/index.ts）：

function applyContext7Config(config: Config, apiKey: string | undefined): void {
  config.mcp ??= {};
  config.mcp[MCP_SERVER_NAME] ??= apiKey
    ? {
        type: "remote",
        url: MCP_URL,
        enabled: true,
        headers: { Authorization: `Bearer ${apiKey}` },
        oauth: false,
      }
    : { type: "remote", url: MCP_OAUTH_URL, enabled: true };

  const withSkills = config as ConfigWithSkills;
  withSkills.skills ??= {};
  const skillPaths = (withSkills.skills.paths ??= []);
  if (!skillPaths.includes(SKILLS_DIR)) {
    skillPaths.push(SKILLS_DIR);
  }
}

这段代码解释了 README 中“覆盖规则”的成因：

1. ??= 语义保证用户配置永远优先：config.mcp["context7"] ??= ... 意味着如果你的 opencode.json 已经定义了名为 context7 的 MCP 服务器，插件会原样保留你的定义，不会注入任何内容；
2. 有/无 API Key 生成不同的服务器配置：带 Key 时注入 headers: { Authorization: "Bearer ..." } 并显式设置 oauth: false，不带 Key 时指向 OAuth 端点；
3. 技能路径去重：SKILLS_DIR 指向插件包内的 skills/ 目录（发布物中包含 skills 文件，见 package.json 的 files 字段），仅在 skills.paths 尚未包含该路径时追加，因此重复加载不会产生重复技能。

另外，源码中有一处对旧版加载器的防御性注释：

/** Only the default export. Any other export is loaded as a second plugin by the legacy loader. */

说明该包刻意只保留默认导出，避免旧版插件加载器把其它导出当第二个插件重复执行。

使用方式：技能自动触发

context7-mcp 技能会在你询问库相关内容时自动触发，无需显式调用，例如：

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

技能的完整行为定义在 SKILL.md 中，其 frontmatter 的 description 明确了触发条件（询问库/框架/API 参考、需要代码示例、提到 React/Vue/Next.js/Prisma/Supabase 等框架），并规定了四步检索流程：

1. Step 1 — 解析库 ID：调用 resolve-library-id，传入 libraryName（从用户问题中提取）和 query（要在文档中查什么，用于提升相关性排序）；
2. Step 2 — 选择最佳匹配：依据名称精确度、benchmark 分数（分数越高文档质量越好）以及版本提示（如用户提到 “React 19” 时优先选版本化 ID）；
3. Step 3 — 拉取文档：调用 query-docs，传入 libraryId 与限定为单一概念的 query。若问题跨多个概念（如路由 + 鉴权 + 缓存），需对同一 libraryId 分别发起多次 query-docs，因为合并查询会稀释排序、使每个话题的结果都变浅；
4. Step 4 — 引用文档作答：用检索到的最新信息回答问题、附带文档中的代码示例、在相关时注明库版本。

技能还给出了两条重要准则：多个匹配时优先官方/主包而非社区 fork；提及版本时优先使用版本化的库 ID。

可用工具

context7_resolve-library-id

搜索库并返回 Context7 兼容标识符：

Input: "next.js"
Output: { id: "/vercel/next.js", name: "Next.js", versions: ["v15.1.8", "v14.2.0", ...] }

context7_query-docs

拉取特定库的文档，并按与问题的相关性排序：

Input: { libraryId: "/vercel/next.js", query: "app router middleware" }
Output: Relevant documentation snippets with code examples

这两个工具由托管的 Context7 MCP 服务器提供（服务器实现可参考 packages/mcp/src/index.ts，其中工具入参带有别名重写机制，用于纠正 LLM 客户端偶发的参数名幻觉，例如将 userQuery/question 归一为 query）。

版本钉选（Version Pinning）

要获取特定版本的文档，在库 ID 中追加版本号：

/vercel/next.js/v15.1.8
/supabase/supabase/v2.45.0

context7_resolve-library-id 工具会返回可用版本列表，便于你挑选与项目匹配的版本。

构建与发布形态

• 包名 @upstash/context7-opencode，当前版本 0.1.0，MIT 许可（见 package.json 与 CHANGELOG.md）；
• 构建配置 tsup.config.ts 显示：入口为 src/index.ts，仅产出 ESM（format: ["esm"]）、目标 node20、带类型声明与 sourcemap，@opencode-ai/plugin 被标记为 external；
• 依赖方面仅 @opencode-ai/plugin（^1.18.11）、tsup、typescript 等开发依赖，运行时无第三方运行时依赖。

小结与延伸阅读

该插件以极小的实现面完成了三件事：按 apiKey 有无生成两种 MCP 服务器配置、去重注入技能路径、并以 ??= 语义保证用户配置不受污染。安装后你只需自然语言提问，技能层会自动完成“解析库 ID → 选择匹配 → 分概念查询 → 引用作答”的完整链路。

• 仓库中 OpenCode 客户端的完整指南（含 npx ctx7 setup --opencode 替代方案、opencode mcp auth context7 预鉴权命令、AGENTS.md 配置提示等）见 docs/clients/opencode.mdx；
• 插件包内技能完整定义见 packages/opencode/skills/context7-mcp/SKILL.md；
• 插件入口与配置注入逻辑见 packages/opencode/src/index.ts。