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/context7context7-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 将激活场景归纳为四类典型提问模式场景典型提问示例对应检索行为搭建与配置问题How do I configure Next.js middleware?解析 Next.js → 查 middleware 相关文档涉及库的代码生成Write a Prisma query for...解析 Prisma → 查模型/查询语法文档API 参考需求What are the Supabase auth methods?解析 Supabase → 查 auth API 文档提及具体框架React、Vue、Svelte、Express、Tailwind 等按提及的框架解析库 ID这四类场景与 docs/clients/opencode.mdx 中的用法示例相互印证例如How do I set up authentication in Next.js 15? Show me React Server Components examples Whats 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 解析库 IDSkill 要求调用resolve-library-id并传入两个参数该工具的正式注册与 Schema 定义见 packages/mcp/src/index.tslibraryName从用户问题中提取的库名。源码 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.0Skill 给出的选择标准与源码中工具描述Selection Process完全一致综合权衡五个维度名称相似度——与用户所问的库精确或最接近名称匹配的优先描述相关性——库描述与查询意图的吻合程度文档覆盖度——Code Snippets 数量越多可用文档越丰富来源信誉——Source ReputationHigh/Medium更高的官方来源更权威基准分数——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.jsquery要查找的内容限定为单一概念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重新获取有效 IDNo 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 要求把拉取到的文档真正用于回答用户问题具体做法有三条使用当前、准确的信息回答用户的问题附上文档中相关的代码示例在相关时注明库的版本版本化文档尤其重要。四、插件如何把 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); } }从源码结构看插件做了三件事注册远程 MCP Server服务名为context7。默认走 OAuth 端点/mcp/oauth首次文档检索时 OpenCode 会打开浏览器完成登录从而使用账户的速率限额API Key 分支apiKey取自插件选项nonEmptyString(options?.apiKey)或环境变量CONTEXT7_API_KEY二者都缺省时才走 OAuth。提供 Key 时改为普通/mcp端点 Authorization: Bearer key请求头并禁用 OAuth适合无头机器注册 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.mdxopencode 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_KEYyour-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 APIsearchLibraries/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考