Context7 OpenCode 插件的 context7-mcp Skill：让 AI 编码助手检索最新库文档的完整工作流

Context7 OpenCode 插件的 context7-mcp Skill：让 AI 编码助手检索最新库文档的完整工作流

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

context7-mcp是 Context7 官方 OpenCode 插件（packages/opencode）内置的核心 Skill，它教会 AI 助手在用户询问库、框架、API 参考或需要代码示例时，主动调用 Context7 MCP 工具检索最新文档，而不是依赖可能过时的训练数据。读完本文，你将理解该 Skill 的触发条件、"解析库 ID → 选择匹配 → 拉取文档 → 生成回答"四步工作流中每一步的参数设计与取舍原因，并能结合插件源码（packages/opencode/src/index.ts）与 MCP Server 实现（packages/mcp/src/index.ts）完整复现这套文档检索方案。

一、Skill 是什么：一段写给 Agent 的操作规程

Skill 本质是一份带 YAML frontmatter 的 Markdown 文件，由 OpenCode 加载后注入 Agent 的上下文，作为其"何时该查文档、怎么查文档"的行为规范。位于 packages/opencode/skills/context7-mcp/SKILL.md 的文件结构如下：

--- 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. ---

• name是 Skill 的唯一标识，与仓库中其他客户端插件（如 plugins/agent-plugins/context7、plugins/cursor/context7）共用的context7-mcp命名保持一致，方便用户跨工具迁移习惯。
• description同时承担两个职责：向用户说明用途，以及向模型提供触发判据——用户询问库/框架/API 参考、需要代码示例，或提到具体框架（React、Vue、Next.js、Prisma、Supabase 等）时激活。

Skill 正文开宗明义地给出核心原则：

当用户询问库、框架或需要代码示例时，使用 Context7 获取当前文档，而不是依赖训练数据（"When the user asks about libraries, frameworks, or needs code examples, use Context7 to fetch current documentation instead of relying on training data."）。

这一原则同样出现在 MCP Server 的 instructions 与规则文件中：rules/context7-mcp.md 进一步细化了"即使你认为自己知道答案也应使用，因为训练数据可能不反映近期变更"，并明确了负面清单——重构、从零写脚本、调试业务逻辑、代码审查或通用编程概念不应触发该 Skill。

二、触发条件：四类应当激活 Skill 的用户提问

Skill 将激活场景归纳为四类典型提问模式：

这四类场景与 docs/clients/opencode.mdx 中的用法示例相互印证，例如：

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

安装插件后无需任何额外指令，Skill 会基于description自动触发；也可以显式调用（"use context7 to show me how to set up middleware in Next.js 15"），或在项目的AGENTS.md中加入"When you need to search docs, use Context7."来强化倾向。

三、四步工作流：从提问到文档的完整调用链

Skill 正文把检索过程拆成四个步骤，每一步都绑定到 MCP Server 暴露的具体工具上。以下逐步骤展开，并结合源码中的输入 Schema 与输出格式做纵深说明。

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

Skill 要求调用resolve-library-id并传入两个参数（该工具的正式注册与 Schema 定义见 packages/mcp/src/index.ts）：

• libraryName：从用户问题中提取的库名。源码 Schema 特别强调使用带正确标点的官方名称——例如用'Next.js'而非'nextjs'、'Three.js'而非'threejs'，因为官方名称的匹配准确度更高；
• query：要在该库文档中查找的内容。它会被发送到 Context7 API 用于按相关性排序检索结果。Schema 同时声明了一条安全边界：不要在 query 中包含 API 密钥、密码、凭据、个人数据或专有代码等敏感信息。

这一步的底层调用是searchLibraries(query, libraryName, ctx)（见 packages/mcp/src/index.ts），即向 Context7 的库数据库发起搜索。若结果为空，工具会返回错误文本（如No libraries found matching the provided name.），并可能触发 OAuth 登录引导（maybeElicitAuthSignIn）提示用户完成认证。

Step 2：从解析结果中选出最佳匹配

resolve-library-id返回的每个候选库包含五个可比较的字段（输出格式示例见 docs/agentic-tools/ai-sdk/tools/resolve-library-id.mdx）：

- Title: React Documentation - Context7-compatible library ID: /reactjs/react.dev - Description: The library for web and native user interfaces - Code Snippets: 1250 - Source Reputation: High - Benchmark Score: 98 - Versions: 19.0.0, 18.3.1, 18.2.0

Skill 给出的选择标准与源码中工具描述（Selection Process）完全一致，综合权衡五个维度：

1. 名称相似度——与用户所问的库精确或最接近名称匹配的优先；
2. 描述相关性——库描述与查询意图的吻合程度；
3. 文档覆盖度——Code Snippets 数量越多，可用文档越丰富；
4. 来源信誉——Source Reputation（High/Medium）更高的官方来源更权威；
5. 基准分数——Benchmark Score 是文档质量指标，100 为最高分，分数越高说明该库文档质量越好。

两条额外的决策规则值得注意：

• 版本优先：若用户提到了版本（如 "React 19"），在候选列表的Versions中存在时优先选择带版本的 ID（形如/org/project/version，例如/vercel/next.js/v14.3.0-canary.87）；
• 官方优先：多个匹配存在时，优先选择官方/主包而非社区 fork。

此外源码中的工具描述还包含一条频控约束：同一个问题内resolve-library-id最多调用 3 次，若 3 次仍不理想则使用已有最佳结果，避免无意义的重复检索。

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

选定库 ID 后，调用query-docs（工具注册与 Schema 见 packages/mcp/src/index.ts），传入：

• libraryId：选定的 Context7 库 ID（如/vercel/next.js）；
• query：要查找的内容，限定为单一概念（scoped to a single concept）。

这一步最容易出错的正是query的粒度。Skill 原文给出了明确判断标准：

如果用户的问题跨多个不同概念（例如路由、认证和缓存），则对每个概念各发起一次query-docs调用（使用同一个库 ID），除非问题恰好是关于这些概念之间如何交互的——合并查询会稀释排序信号，导致每个主题都只拿到浅层结果。

这一原则在 docs/agentic-tools/ai-sdk/tools/query-docs.mdx 中同样被写进工具描述，并给出了正反例：

# 好的 query（具体、单一主题） How to set up authentication with JWT in Express.js React useEffect cleanup function examples # 坏的 query（过于模糊） auth hooks # 坏的 query（过于宽泛） routing and auth and caching in Next.js

成功时query-docs返回按相关性排序的文档片段（含代码示例，底层调用fetchLibraryContext，见 packages/mcp/src/index.ts）；失败时返回带自愈提示的错误文本，指引 Agent 回到resolve-library-id重新获取有效 ID：

No documentation found for library "/invalid/library". This might have happened because you used an invalid Context7-compatible library ID. Use 'resolveLibraryId' to get a valid ID.

与第一步对称地，工具描述同样约束query-docs每问最多调用 3 次；需要更全面的文档时，正确做法是多主题各发一次查询，而不是在同一个 query 里堆砌主题。

Step 4：将文档融入回答

Skill 要求把拉取到的文档真正用于回答用户问题，具体做法有三条：

1. 使用当前、准确的信息回答用户的问题；
2. 附上文档中相关的代码示例；
3. 在相关时注明库的版本（版本化文档尤其重要）。

四、插件如何把 Skill 和 MCP Server 注入 OpenCode

理解 Skill 的前提是理解它如何被加载。packages/opencode/src/index.ts 是插件入口，它导出唯一的默认插件模块（注释明确说明其他导出会被旧版加载器当作第二个插件加载），核心逻辑在applyContext7Config中：

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"; 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); } }

从源码结构看，插件做了三件事：

1. 注册远程 MCP Server：服务名为context7。默认走 OAuth 端点（/mcp/oauth），首次文档检索时 OpenCode 会打开浏览器完成登录，从而使用账户的速率限额；
2. API Key 分支：apiKey取自插件选项（nonEmptyString(options?.apiKey)）或环境变量CONTEXT7_API_KEY，二者都缺省时才走 OAuth。提供 Key 时改为普通/mcp端点 +Authorization: Bearer <key>请求头并禁用 OAuth，适合无头机器；
3. 注册 Skill 目录：SKILLS_DIR指向插件包内的skills/目录（即本文件所在目录），通过skills.paths注入配置。源码中的注释特别说明：OpenCode 的Config类型尚未声明skills字段，但配置 Schema 实际接受它，因此这里用ConfigWithSkills做了类型扩展。

注册全部采用"增量、非覆盖"策略（??=语义）：若用户的opencode.json已定义了名为context7的 MCP Server，插件保持原样不动——这一点在 packages/opencode/README.md 中也有明确说明，同时保证了ctx7 setup与插件共存是安全的（OpenCode 只会加载一次context7-mcpSkill）。

安装与认证方式

按 packages/opencode/README.md 与 docs/clients/opencode.mdx：

opencode plugin @upstash/context7-opencode

安装后重启 OpenCode，并可通过opencode mcp auth context7提前完成 OAuth；跳过该命令则浏览器会在首次检索时自动打开。也可手工配置 opencode.json：

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

无头环境使用 API Key 时，两种方式等价（源码取值为"插件选项优先，环境变量兜底"）：

export CONTEXT7_API_KEY="your-api-key"

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

五、源码里的健壮性细节：别名重写与工具注解

Skill 教 Agent "该怎么调"，而 MCP Server 源码为"调错也能跑"兜底。值得关注的有两处：

1. 幻觉参数名的别名重写。LLM 客户端经常照抄工具描述中的措辞而非 Schema 的字面键名，导致 Zod 校验在工具执行前就失败。packages/mcp/src/index.ts 用一个z.preprocess步骤在校验前把别名重映射为规范键名：

const GLOBAL_ALIASES: AliasMap = { query: ["userQuery", "question"], }; const QUERY_DOCS_ALIASES: AliasMap = { libraryId: ["context7CompatibleLibraryID", "libraryID", "libraryName"], };

注意libraryName只在query-docs上被视为幻觉别名——因为它本身是resolve-library-id的规范参数名，工具级作用域避免了误改写。别名重写返回的是重映射副本，原始报文对象保持不变。

2. 工具注解（annotations）。两个工具都声明为只读、非破坏性、幂等：

annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true, idempotentHint: true, }

这让支持能力协商的客户端可以放心地缓存或并行化调用。

另外，两个工具均为远程调用 Context7 API（searchLibraries/fetchLibraryContext，实现于 packages/mcp/src/lib/api.ts），未认证时工具仍会返回结果但会触发maybeElicitAuthSignIn引导登录以获得账户速率限额。

六、实战建议与效果最大化

结合 Skill 的 Guidelines 与 docs/clients/opencode.mdx 的 Tips，实践中获得更好结果的要点：

• 提问要具体：说清楚"要做什么"而不仅仅是"哪个库"。例如 "How do I handle file uploads with the Supabase Storage API?" 优于 "How does Supabase storage work?"；
• 版本敏感：用户提到 "Next.js 15"、"React 19" 时，在 Step 1 的解析结果中选用版本化的库 ID，后续query-docs传入/org/project/version形式的 ID；
• 多概念拆分：路由 + 认证 + 缓存的问题拆成三次query-docs调用（同库 ID），仅当问题问的是"这些概念如何交互"时才合并；
• 善用直接 ID 跳过解析：若已知库 ID（如用户明确给出/supabase/supabase），可直接进入 Step 3，对应工具描述也声明了该例外（"UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version'"）。

七、小结

context7-mcpSkill 用一份紧凑的 Markdown 把 Context7 的文档检索能力接入了 OpenCode 这类 AI 编码助手：frontmatter 的description定义了触发边界，四步工作流（resolve-library-id→ 五维匹配选择 → 单概念query-docs→ 版本化引用回答）定义了调用序列，Guidelines 定义了参数粒度。而 packages/opencode 插件源码负责把这套 Skill 与远程 MCP Server 以增量方式注入 OpenCode 配置，packages/mcp Server 源码则用别名重写、调用频控与只读注解保证工作流在真实 LLM 调用下的鲁棒性。三者配合，让"训练数据过时导致的 API 幻觉"问题在 OpenCode 的编码会话中被系统性地消除。

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