Context7 context7-mcp 技能详解让 AI Agent 用 MCP 两步获取最新库文档的工作流【免费下载链接】context7Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors项目地址: https://gitcode.com/gh_mirrors/co/context7skills/context7-mcp/SKILL.md是 Context7 仓库中面向 AI 编码代理Agent的技能定义文件它规定了当用户询问库、框架、API 参考或索要代码示例时Agent 应如何通过 Context7 MCP 的resolve-library-id与query-docs两个工具获取当前最新的文档而不是依赖可能过时的训练数据。读完本文你将理解该技能的触发条件、四步检索工作流、查询质量准则以及 MCP 服务端源码packages/mcp/src/index.ts如何从参数校验、容错别名重写到底层 API 调用完整支撑这套工作流。技能定位为什么需要 context7-mcp 技能技能文件采用标准的 SKILL.md 结构以 YAML frontmatter 声明元信息--- 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. ---其核心宗旨一句话概括当用户问库、框架或需要代码示例时用 Context7 拉取最新文档而不是依赖训练数据。这源于一个大模型固有的问题——训练语料有截止日期API 语法、配置项、版本行为随时在变。技能文件在正文开篇即要求 Agent「use Context7 to fetch current documentation instead of relying on training data」把「主动查文档」从可选行为变成强制行为。触发条件何时激活该技能技能文档明确列出了四类应激活该技能的场景用户提出安装或配置类问题例如 How do I configure Next.js middleware?用户请求涉及某个库的代码例如 Write a Prisma query for...用户需要API 参考例如 What are the Supabase auth methods?用户点名具体框架React、Vue、Svelte、Express、Tailwind 等。值得注意的反面清单在 MCP 服务端的工具说明中定义得更完整服务端instructions字段声明该服务器适用于「用户询问库、框架、SDK、API、CLI 工具或云服务——即使是你熟悉的 React、Next.js、Prisma、Express、Tailwind、Django、Spring Boot」包括 API 语法、配置、版本迁移、库相关调试、安装步骤与 CLI 用法同时明确不适用于重构、从零写脚本、业务逻辑调试、代码审查和通用编程概念见 packages/mcp/src/index.ts。技能文件与工具描述在这点上互为补充前者回答「何时激活」后者回答「何时不要用」。四步检索工作流第一步解析库 IDresolve-library-id调用resolve-library-id工具传入两个参数libraryName从用户问题中提取的库名query要在这个库的文档中查找什么用于提升相关性排序。从源码看该工具的输入用 Zod 定义并且对参数有严格约束。libraryName要求使用「带正确标点的官方库名——例如用 Next.js 而不是 nextjs、Customer.io 而不是 customerio」query则说明其「会被发送到 Context7 API 处理不得包含 API key、密码、凭据、个人数据或专有代码等敏感信息」见 packages/mcp/src/index.ts。工具返回的每个候选库都携带结构化字段Library IDContext7 兼容标识符格式为/org/projectName库或包名Description简短描述Code Snippets可用代码示例数量Source Reputation权威性指示High / Medium / Low / UnknownBenchmark Score文档质量指标100 为最高分Versions可用版本列表如有。用户指定版本时版本 ID 格式为/org/project/version。工具描述中还有一条硬约束每个问题最多调用 3 次若 3 次后仍未找到目标使用已有最佳结果packages/mcp/src/index.ts。第二步选出最佳匹配技能文档给出三条选型判据与用户所问名称精确或最接近的匹配优先Benchmark Score 更高表示文档质量更好用户提到版本时如 React 19优先选择版本专属 ID例如/vercel/next.js/v14.3.0-canary.87而非/vercel/next.js。完整的选型过程在工具描述中进一步细化为五步分析查询意图、按名称相似度精确匹配优先选库、按描述相关性、按文档覆盖率Code Snippet 数量更多者优先、按 Source ReputationHigh/Medium 更权威、按 Benchmark Score 综合决策若有多个好匹配则说明但继续用最相关的一个若无好匹配则明确告知并建议优化查询遇到歧义查询应请求澄清packages/mcp/src/index.ts。第三步拉取文档query-docs调用query-docs工具传入libraryId第二步选定的 Context7 库 ID例如/vercel/next.jsquery要在文档中查找的内容限定在单一概念范围内。技能文档在此强调了一个关键的检索策略如果用户的问题横跨多个独立概念如同时涉及路由、认证和缓存应当对同一 libraryId 按概念分别调用query-docs除非问题问的正是这些概念之间的相互作用——因为合并式查询会稀释排序信号导致每个话题都只返回浅层结果。这一策略同样写入了query-docs的 query 参数描述其中给出了正反例好查询如 How to set up authentication with JWT in Express.js坏查询如过于含糊的 auth、hooks或过于宽泛的 routing and auth and caching in Next.jspackages/mcp/src/index.ts。与resolve-library-id一样query-docs也有每个问题最多 3 次的调用上限packages/mcp/src/index.ts。第四步使用文档将拉取到的文档融入回答使用当前、准确的信息回答用户问题附上文档中相关的代码示例在相关时标注库版本。准则汇总Guidelines技能文档末尾的 Guidelines 是 Agent 执行该工作流时的行为红线逐条继承如下要具体描述要在库文档中查找什么但每条 query 只覆盖一个概念一个 query 一个主题把多主题问题拆成多次query-docs调用——库 ID 只解析一次然后按概念查询唯一例外是问题本身在问概念间如何交互版本感知用户提到版本Next.js 15、React 19时若解析步骤返回了版本专属 ID就使用它优先官方来源多个匹配存在时优先官方/主包而非社区分支。源码印证MCP 服务端如何支撑这套工作流技能文件描述的是「Agent 侧行为契约」而 Context7 MCP 服务端在实现上为这套契约提供了几层保障可以结合源码理解其设计动机。1. 参数别名重写抵御 LLM 的「幻觉参数名」。源码中有一张别名映射表全局层面query可被误写为userQuery、questionquery-docs层面libraryId可被误写成context7CompatibleLibraryID、libraryID甚至libraryName后者其实是resolve-library-id的合法参数。这些是 LLM 客户端从工具描述中「复述措辞」而非使用字面 schema 键名导致的。服务端在 Zod 校验前用z.preprocess(aliasArgs(...))把别名静默重写回规范键名使调用在工具运行前就能通过验证packages/mcp/src/index.ts。这意味着即使 Agent 按技能文档描述「用自己的话」传参工作流依然可用。2. 两个工具只读、幂等。两个工具均声明了readOnlyHint: true、idempotentHint: true、openWorldHint: true注解packages/mcp/src/index.ts符合「只查文档」的语义Agent 可以安全重试。3. 底层 API 调用与超时。工具执行后进入 packages/mcp/src/lib/api.tssearchLibraries请求{CONTEXT7_API_BASE_URL}/v2/libs/search并带上query与libraryName两个查询参数packages/mcp/src/lib/api.tsfetchLibraryContext请求/v2/context并带上query与libraryIdpackages/mcp/src/lib/api.ts。所有请求都有 60 秒的AbortSignal.timeout上限——源码注释说明这些向量查询 p99.9 约 3.2 秒60 秒是「宽松的上限」而非预期耗时packages/mcp/src/lib/api.ts。4. 失败语义对 Agent 是可操作的。API 错误会被翻译成面向 Agent 的指引429 提示配额/限流并区分有无 API key 的升级路径404 返回「该库不存在请尝试其他库 ID」/v2/context返回空内容时会提示「可能使用了无效的 library ID请用 resolve-library-id 重新获取有效 ID」packages/mcp/src/lib/api.ts 与 packages/mcp/src/lib/api.ts。这保证即使第三步失败Agent 也能按技能工作流回退到第一步重来而不是静默失败。与仓库中其他文档化入口的关系同一套「解析 ID → 查询文档」工作流在仓库中还有多个平行入口可对照参考但本文以 MCP 技能为核心CLI 技能skills/find-docs/SKILL.md用npx ctx7latest library name query与npx ctx7latest docs libraryId query两条命令实现同样的两步流程并额外提供认证方式CONTEXT7_API_KEY环境变量或npx ctx7latest login、配额错误的处理策略与常见错误清单如库 ID 必须带/前缀Cursor 规则文件rules/context7-mcp.md把相同的四步流程压缩为规则文件形式供 Cursor 等以 rules 驱动的客户端使用AI SDK 工具docs/agentic-tools/ai-sdk/tools/resolve-library-id.mdx 与 docs/agentic-tools/ai-sdk/tools/query-docs.mdx 面向 Vercel AI SDK 场景提供resolveLibraryId()/queryDocs()的 TypeScript 用法与输出格式示例同样支持版本专属 ID如/vercel/next.js/v14.3.0-canary.87。MCP 服务端本身的发布坐标可在 packages/mcp/package.json 中确认包名upstash/context7-mcpMCP 标识io.github.upstash/context7要求 Node.js ≥ 20.18.1默认以 stdio 传输运行--transport http时默认端口 3000API key 可通过--api-key参数或CONTEXT7_API_KEY环境变量提供packages/mcp/src/index.ts。小结一个可复制的 Agent 侧检索清单综合技能文档与源码Agent 在使用 context7-mcp 技能时应当遵守的执行清单为判断问题是否命中触发条件库/框架/API 参考/代码生成/点名框架命中则激活技能不要依赖训练数据作答调用resolve-library-id传官方写法的libraryName和体现用户意图的query单问最多 3 次按「名称精确匹配 描述相关性 代码片段覆盖 来源信誉 Benchmark 分数」选出最佳 ID用户指定版本时选版本专属 ID按概念拆分调用query-docs每条 query 单一主题、足够具体同样单问最多 3 次用返回文档作答附文档中的代码示例并标注版本失败时优先回退到第 2 步重新解析而不是静默降级为训练数据作答。这套「触发条件 两步工具调用 查询纪律 调用上限」的完整契约正是 skills/context7-mcp/SKILL.md 的全部价值所在它把一个可能过时的模型知识库替换成了每次会话实时更新的文档检索管道。【免费下载链接】context7Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors项目地址: https://gitcode.com/gh_mirrors/co/context7创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Context7 context7-mcp 技能详解：让 AI Agent 用 MCP 两步获取最新库文档的工作流
Context7 context7-mcp 技能详解让 AI Agent 用 MCP 两步获取最新库文档的工作流【免费下载链接】context7Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors项目地址: https://gitcode.com/gh_mirrors/co/context7skills/context7-mcp/SKILL.md是 Context7 仓库中面向 AI 编码代理Agent的技能定义文件它规定了当用户询问库、框架、API 参考或索要代码示例时Agent 应如何通过 Context7 MCP 的resolve-library-id与query-docs两个工具获取当前最新的文档而不是依赖可能过时的训练数据。读完本文你将理解该技能的触发条件、四步检索工作流、查询质量准则以及 MCP 服务端源码packages/mcp/src/index.ts如何从参数校验、容错别名重写到底层 API 调用完整支撑这套工作流。技能定位为什么需要 context7-mcp 技能技能文件采用标准的 SKILL.md 结构以 YAML frontmatter 声明元信息--- 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. ---其核心宗旨一句话概括当用户问库、框架或需要代码示例时用 Context7 拉取最新文档而不是依赖训练数据。这源于一个大模型固有的问题——训练语料有截止日期API 语法、配置项、版本行为随时在变。技能文件在正文开篇即要求 Agent「use Context7 to fetch current documentation instead of relying on training data」把「主动查文档」从可选行为变成强制行为。触发条件何时激活该技能技能文档明确列出了四类应激活该技能的场景用户提出安装或配置类问题例如 How do I configure Next.js middleware?用户请求涉及某个库的代码例如 Write a Prisma query for...用户需要API 参考例如 What are the Supabase auth methods?用户点名具体框架React、Vue、Svelte、Express、Tailwind 等。值得注意的反面清单在 MCP 服务端的工具说明中定义得更完整服务端instructions字段声明该服务器适用于「用户询问库、框架、SDK、API、CLI 工具或云服务——即使是你熟悉的 React、Next.js、Prisma、Express、Tailwind、Django、Spring Boot」包括 API 语法、配置、版本迁移、库相关调试、安装步骤与 CLI 用法同时明确不适用于重构、从零写脚本、业务逻辑调试、代码审查和通用编程概念见 packages/mcp/src/index.ts。技能文件与工具描述在这点上互为补充前者回答「何时激活」后者回答「何时不要用」。四步检索工作流第一步解析库 IDresolve-library-id调用resolve-library-id工具传入两个参数libraryName从用户问题中提取的库名query要在这个库的文档中查找什么用于提升相关性排序。从源码看该工具的输入用 Zod 定义并且对参数有严格约束。libraryName要求使用「带正确标点的官方库名——例如用 Next.js 而不是 nextjs、Customer.io 而不是 customerio」query则说明其「会被发送到 Context7 API 处理不得包含 API key、密码、凭据、个人数据或专有代码等敏感信息」见 packages/mcp/src/index.ts。工具返回的每个候选库都携带结构化字段Library IDContext7 兼容标识符格式为/org/projectName库或包名Description简短描述Code Snippets可用代码示例数量Source Reputation权威性指示High / Medium / Low / UnknownBenchmark Score文档质量指标100 为最高分Versions可用版本列表如有。用户指定版本时版本 ID 格式为/org/project/version。工具描述中还有一条硬约束每个问题最多调用 3 次若 3 次后仍未找到目标使用已有最佳结果packages/mcp/src/index.ts。第二步选出最佳匹配技能文档给出三条选型判据与用户所问名称精确或最接近的匹配优先Benchmark Score 更高表示文档质量更好用户提到版本时如 React 19优先选择版本专属 ID例如/vercel/next.js/v14.3.0-canary.87而非/vercel/next.js。完整的选型过程在工具描述中进一步细化为五步分析查询意图、按名称相似度精确匹配优先选库、按描述相关性、按文档覆盖率Code Snippet 数量更多者优先、按 Source ReputationHigh/Medium 更权威、按 Benchmark Score 综合决策若有多个好匹配则说明但继续用最相关的一个若无好匹配则明确告知并建议优化查询遇到歧义查询应请求澄清packages/mcp/src/index.ts。第三步拉取文档query-docs调用query-docs工具传入libraryId第二步选定的 Context7 库 ID例如/vercel/next.jsquery要在文档中查找的内容限定在单一概念范围内。技能文档在此强调了一个关键的检索策略如果用户的问题横跨多个独立概念如同时涉及路由、认证和缓存应当对同一 libraryId 按概念分别调用query-docs除非问题问的正是这些概念之间的相互作用——因为合并式查询会稀释排序信号导致每个话题都只返回浅层结果。这一策略同样写入了query-docs的 query 参数描述其中给出了正反例好查询如 How to set up authentication with JWT in Express.js坏查询如过于含糊的 auth、hooks或过于宽泛的 routing and auth and caching in Next.jspackages/mcp/src/index.ts。与resolve-library-id一样query-docs也有每个问题最多 3 次的调用上限packages/mcp/src/index.ts。第四步使用文档将拉取到的文档融入回答使用当前、准确的信息回答用户问题附上文档中相关的代码示例在相关时标注库版本。准则汇总Guidelines技能文档末尾的 Guidelines 是 Agent 执行该工作流时的行为红线逐条继承如下要具体描述要在库文档中查找什么但每条 query 只覆盖一个概念一个 query 一个主题把多主题问题拆成多次query-docs调用——库 ID 只解析一次然后按概念查询唯一例外是问题本身在问概念间如何交互版本感知用户提到版本Next.js 15、React 19时若解析步骤返回了版本专属 ID就使用它优先官方来源多个匹配存在时优先官方/主包而非社区分支。源码印证MCP 服务端如何支撑这套工作流技能文件描述的是「Agent 侧行为契约」而 Context7 MCP 服务端在实现上为这套契约提供了几层保障可以结合源码理解其设计动机。1. 参数别名重写抵御 LLM 的「幻觉参数名」。源码中有一张别名映射表全局层面query可被误写为userQuery、questionquery-docs层面libraryId可被误写成context7CompatibleLibraryID、libraryID甚至libraryName后者其实是resolve-library-id的合法参数。这些是 LLM 客户端从工具描述中「复述措辞」而非使用字面 schema 键名导致的。服务端在 Zod 校验前用z.preprocess(aliasArgs(...))把别名静默重写回规范键名使调用在工具运行前就能通过验证packages/mcp/src/index.ts。这意味着即使 Agent 按技能文档描述「用自己的话」传参工作流依然可用。2. 两个工具只读、幂等。两个工具均声明了readOnlyHint: true、idempotentHint: true、openWorldHint: true注解packages/mcp/src/index.ts符合「只查文档」的语义Agent 可以安全重试。3. 底层 API 调用与超时。工具执行后进入 packages/mcp/src/lib/api.tssearchLibraries请求{CONTEXT7_API_BASE_URL}/v2/libs/search并带上query与libraryName两个查询参数packages/mcp/src/lib/api.tsfetchLibraryContext请求/v2/context并带上query与libraryIdpackages/mcp/src/lib/api.ts。所有请求都有 60 秒的AbortSignal.timeout上限——源码注释说明这些向量查询 p99.9 约 3.2 秒60 秒是「宽松的上限」而非预期耗时packages/mcp/src/lib/api.ts。4. 失败语义对 Agent 是可操作的。API 错误会被翻译成面向 Agent 的指引429 提示配额/限流并区分有无 API key 的升级路径404 返回「该库不存在请尝试其他库 ID」/v2/context返回空内容时会提示「可能使用了无效的 library ID请用 resolve-library-id 重新获取有效 ID」packages/mcp/src/lib/api.ts 与 packages/mcp/src/lib/api.ts。这保证即使第三步失败Agent 也能按技能工作流回退到第一步重来而不是静默失败。与仓库中其他文档化入口的关系同一套「解析 ID → 查询文档」工作流在仓库中还有多个平行入口可对照参考但本文以 MCP 技能为核心CLI 技能skills/find-docs/SKILL.md用npx ctx7latest library name query与npx ctx7latest docs libraryId query两条命令实现同样的两步流程并额外提供认证方式CONTEXT7_API_KEY环境变量或npx ctx7latest login、配额错误的处理策略与常见错误清单如库 ID 必须带/前缀Cursor 规则文件rules/context7-mcp.md把相同的四步流程压缩为规则文件形式供 Cursor 等以 rules 驱动的客户端使用AI SDK 工具docs/agentic-tools/ai-sdk/tools/resolve-library-id.mdx 与 docs/agentic-tools/ai-sdk/tools/query-docs.mdx 面向 Vercel AI SDK 场景提供resolveLibraryId()/queryDocs()的 TypeScript 用法与输出格式示例同样支持版本专属 ID如/vercel/next.js/v14.3.0-canary.87。MCP 服务端本身的发布坐标可在 packages/mcp/package.json 中确认包名upstash/context7-mcpMCP 标识io.github.upstash/context7要求 Node.js ≥ 20.18.1默认以 stdio 传输运行--transport http时默认端口 3000API key 可通过--api-key参数或CONTEXT7_API_KEY环境变量提供packages/mcp/src/index.ts。小结一个可复制的 Agent 侧检索清单综合技能文档与源码Agent 在使用 context7-mcp 技能时应当遵守的执行清单为判断问题是否命中触发条件库/框架/API 参考/代码生成/点名框架命中则激活技能不要依赖训练数据作答调用resolve-library-id传官方写法的libraryName和体现用户意图的query单问最多 3 次按「名称精确匹配 描述相关性 代码片段覆盖 来源信誉 Benchmark 分数」选出最佳 ID用户指定版本时选版本专属 ID按概念拆分调用query-docs每条 query 单一主题、足够具体同样单问最多 3 次用返回文档作答附文档中的代码示例并标注版本失败时优先回退到第 2 步重新解析而不是静默降级为训练数据作答。这套「触发条件 两步工具调用 查询纪律 调用上限」的完整契约正是 skills/context7-mcp/SKILL.md 的全部价值所在它把一个可能过时的模型知识库替换成了每次会话实时更新的文档检索管道。【免费下载链接】context7Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors项目地址: https://gitcode.com/gh_mirrors/co/context7创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考