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

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

【免费下载链接】context7Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors项目地址: https://gitcode.com/gh_mirrors/co/context7

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。

【免费下载链接】context7Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors项目地址: https://gitcode.com/gh_mirrors/co/context7