Context7 是什么 · 全景与阅读地图

30 秒导读： Context7 解决一个具体痛点——大模型脑子里的库文档是「过期的」，写出来的 API 常常是幻觉。它做的事就一句话：把某个库最新版的官方文档，实时抓下来塞进你这次提问的上下文里。对外它只暴露两步操作：resolve-library-id（把库名解析成一个标准 ID）→ query-docs（用这个 ID 取文档）。本仓库是一个 monorepo，里面 5 个包（sdk / mcp / cli / tools-ai-sdk / pi）全都是围着同两个后端 HTTP 端点转的「客户端分发层」；真正的爬虫、解析、检索后端是私有的、不在这个仓库里。

本章是整套文档的入口和路由：只讲「这是什么、大盘怎么转、该去读哪一章」，不进任何实现细节。细节全部留给 01–05 章。

1. 这是什么（零基础也能懂）

1.1 它要解决的痛点

大语言模型（LLM）的知识来自训练数据，而训练数据有个截止日期。库和框架却天天在更新。于是你让 AI 帮你写代码时，经常撞上三件事（README「❌ Without Context7」小节，README.md:11-18）：

给的代码示例是一年前的老写法；
编出根本不存在的 API（俗称「幻觉 API」）；
对着你实际用的新版本，回你一段泛泛的旧答案。

1.2 它做的事（一句话）

Context7 把「这个库当前版本的官方文档和代码示例」直接抓进你这次 prompt 的上下文里（README.md:19-37）。不用切浏览器、不用自己贴文档、不会再幻觉出不存在的 API。

1.3 用起来什么样

最小的用法就是在你的问题后面加一句 use context7：

Create a Next.js middleware that checks for a valid JWT in cookies
and redirects unauthenticated users to `/login`. use context7

如果你已经明确知道要哪个库，可以直接给它的 Context7 ID，跳过搜索这一步（README.md:63-73）：

Implement basic authentication with Supabase. use library /supabase/supabase for API and docs.

那个 /supabase/supabase、/vercel/next.js 形式的字符串，就是 Context7 里一个库的唯一 ID（格式 /org/project，带版本时是 /org/project/version）。理解整个系统的钥匙，就是这个 ID。

1.4 对外只有两步操作

不管你用哪种接入方式，Context7 对 AI 暴露的能力永远是这两步（README.md:99-114）：

步骤	MCP 工具名	CLI 命令	干什么
① 找库	`resolve-library-id`	`ctx7 library <name> <query>`	把一个自然的库名（"Next.js"）解析成标准 ID（`/vercel/next.js`），并列出候选让你挑
② 取文档	`query-docs`	`ctx7 docs <libraryId> <query>`	用标准 ID + 一个具体问题，取回精排后的相关文档片段

一句话直觉： 把它当成「给 AI 用的、按需加载的库文档缓存」——先查目录页找到书的书号（resolve），再按书号+问题翻到相关那几页（query）。为什么非要分两步？因为「库名」是模糊的（"react" 可能指官方、镜像、教程站……），必须先消歧到一个确定的 ID，取文档才不会取错书。

2. 顶层全景（monorepo 怎么转）

2.1 一张图看清全貌

先说怎么读这张图：中间竖线是边界——线左边是本仓库（5 个客户端包），线右边是私有后端（不在这个仓库里）。所有客户端最终都汇到同两个 HTTP 端点。

本仓库 = 客户端分发层                    │   私有后端（不在本仓库）
（packages/*，都是"壳"）                 │   README 免责声明第 2 条
                                        │   README.md:136
  ┌─────────────┐                       │
  │ mcp  (旗舰) │──┐                    │
  │ MCP 服务器  │  │                    │
  └─────────────┘  │                    │
  ┌─────────────┐  │   都调用           │  ┌────────────────────┐
  │ cli  (ctx7) │──┤   同两个端点       │  │  context7.com/api   │
  └─────────────┘  ├──────────────────────▶│                    │
  ┌─────────────┐  │                    │  │ v2/libs/search  ①  │
  │ tools-ai-sdk│──┤                    │  │  → 按库名搜候选     │
  └─────────────┘  │                    │  │                    │
  ┌─────────────┐  │                    │  │ v2/context      ②  │
  │ pi (pi.dev) │──┤                    │  │  → 按 ID 取文档     │
  └─────────────┘  │                    │  └─────────┬──────────┘
  ┌─────────────┐  │                    │            │
  │ sdk (底座)  │──┘                    │  爬虫/解析/检索引擎
  │ 封装 HTTP   │                       │  （私有，本仓库没有）
  └─────────────┘                       │

2.2 五个包各干什么

包	npm 名	角色一句话	详见
`sdk`	`@upstash/context7-sdk`	最底座：把两个端点封装成 `searchLibrary` / `getContext` 两个方法，带重试、分页头解析	01
`mcp`	`@upstash/context7-mcp`	旗舰：MCP 服务器，把两步暴露成 `resolve-library-id` / `query-docs` 两个 MCP 工具，支持 stdio + HTTP 传输、OAuth、匿名/登录	02
`cli`	`ctx7`	命令行：`ctx7 library` / `ctx7 docs` 查文档，`ctx7 setup` 一键接入各家 agent，OAuth 登录	03
`tools-ai-sdk`	`@upstash/context7-tools-ai-sdk`	给 Vercel AI SDK 用的现成 tools + 预置 Agent + 共享系统提示词	04
`pi`	`@upstash/context7-pi`	pi.dev 编码 agent 的官方扩展，同样注入这两个工具	04

这五个包由 pnpm workspaces 统一管理（package.json:6 的 "workspaces": ["packages/*"]）。

pi 在哪讲： 它是 AI-SDK 那套两工具的又一层极薄载体，因此归在 04 章 §5 里讲；05 章讲的是另一类东西——Skills / Plugins / Rules 分发物与 context7-power（Amp）。

2.3 「客户端分发层 vs 私有后端」这条边界

这是理解整个仓库最重要的一件事：你在这里看到的都是「壳」，不是「核」。

README 免责声明第 2 条把话说死了（README.md:136）：本仓库只托管 MCP 服务器的源码；支撑它的 API 后端、解析引擎、爬虫引擎是私有的，不属于本仓库。

所以：文档到底怎么被爬下来、怎么切片、怎么按你的 query 精排——这些「智能」都发生在墙那边。本仓库这 5 个包的共同工作，是把这份智能用各种姿势分发到各类 AI agent 里，并把两步工作流讲清楚给模型听。

2.4 后端的两个端点

墙那边对外就两个 HTTP 端点，全仓库所有客户端都只跟它们打交道：

端点	对应操作	谁在调
`GET .../v2/libs/search?query=&libraryName=`	① 搜库（resolve）	SDK `SearchLibraryCommand`（`packages/sdk/src/commands/search-library/index.ts:23`）；MCP `searchLibraries`（`packages/mcp/src/lib/api.ts:116`）
`GET .../v2/context?query=&libraryId=`	② 取文档（query）	SDK `GetContextCommand`（`packages/sdk/src/commands/get-context/index.ts:22`）；MCP `fetchLibraryContext`（`packages/mcp/src/lib/api.ts:149`）

两者的基址都是 https://context7.com/api（SDK 里 DEFAULT_BASE_URL，packages/sdk/src/client.ts:12；MCP 里 CONTEXT7_API_BASE_URL，packages/mcp/src/lib/constants.ts:14）。

注意区分两个域名：面向 MCP 客户端的入口是 https://mcp.context7.com/mcp（server.json:56）；而取数据的后端 API 是 context7.com/api。前者是「协议门面」，后者是「数据源」。

3. 主线走一遍（一次 'use context7' 的旅程）

不进代码，只走高层。假设你在 Cursor 里问「Next.js 14 的 middleware 怎么写？use context7」：

你: "Next.js 14 middleware 怎么写？ use context7"
        │
        ▼
① 模型决定调 resolve-library-id(libraryName="Next.js", query="...middleware...")
        │            └─ 工具描述强制它：取文档前必须先 resolve（除非你直接给了 /org/project）
        ▼
   后端 v2/libs/search → 返回候选库列表
   （每个候选带：ID、描述、Code Snippets 数、Source Reputation、Benchmark Score、版本）
        │
        ▼
② 模型按「名字匹配 + 权威度 + 片段覆盖 + 分数」挑一个 ID
   看到你说了 "14" → 选带版本的 /vercel/next.js/v14...
        │
        ▼
③ 模型调 query-docs(libraryId="/vercel/next.js/...", query="how to write middleware")
        │
        ▼
   后端 v2/context → 返回精排后的文档 + 代码片段（纯文本，可分页）
        │
        ▼
④ 模型拿着最新真实文档，写出不会幻觉的 middleware 代码回答你

关键点：「挑哪个 ID」这个判断是模型做的，不是代码做的。 代码只负责把候选列表连同一堆打分信号（权威度、片段数、benchmark 分）喂给模型，判断逻辑被写进了工具描述的提示词里（见 §6）。

4. 两种交付模式（怎么把它装进你的 agent）

README 明确说「Works in two modes」（README.md:39-42）。这是用户接入 Context7 的两条岔路：

维度	MCP 模式	CLI + Skills 模式
原理	注册一个 Context7 MCP 服务器，agent 原生调 `resolve-library-id` / `query-docs` 工具	装一个 Skill，引导 agent 去跑 `ctx7` 命令行取文档
需要 MCP 支持吗	需要（agent 得会说 MCP 协议）	不需要（只要 agent 能执行 shell 命令）
主要包	`packages/mcp`	`packages/cli` + `skills/`
一键装	`npx ctx7 setup --mcp`	`npx ctx7 setup --cli`
适合	Cursor、Claude Code 等原生支持 MCP 的客户端	不支持 MCP、但能跑命令的 agent

两种模式都由同一个入口命令 npx ctx7 setup 引导选择（README.md:49-57）：它走 OAuth 登录、生成 API key、按你的 agent 写好配置，还能用 --cursor / --claude / --opencode 指定目标。两种模式的机制细节在 05 章。

5. 阅读地图（建议顺序）

这套文档分 6 个文件。推荐这样读：

先读本章 index.md —— 建立全局直觉（你正在这）。
01-sdk-api-contract.md —— 从最底层开始：客户端到底怎么跟后端那两个端点对话（HTTP、重试、分页、命令模式）。这是理解上面所有包的地基。
02-mcp-server.md —— 旗舰。两个工具怎么注册、stdio vs HTTP 双传输、每请求上下文、鉴权与安全。想懂 Context7 的精华看这章。
03-cli.md —— ctx7 命令行：查文档 + setup 一键接入 + OAuth。
04-ai-sdk-tools-agent.md —— 给 Vercel AI SDK 的 tools/Agent、跨端复用的那套提示词怎么设计，以及 pi.dev 扩展这层极薄封装。
05-delivery-skills-plugins.md —— 分发层：Skills / Plugins / Rules，以及两种交付模式的落地。

赶时间的话：读 index（本章）+ 02（MCP 旗舰） 就能讲清楚 Context7 是什么、妙在哪。

6. 巧妙之处（先建立直觉，细节留给后续章节）

这些是读完整套文档要带走的「精华」。本章只点出「妙在哪」，实现细节在对应章。

6.1 「两步工作流」作为唯一契约

整个产品对外就 resolve → query 两步，从 SDK 到 MCP 到 CLI 到 AI-SDK 全都是这两步的不同包装。契约极简，是它能同时接 30+ 客户端的根本原因。先消歧再取数，也从设计上避免了「取错库」。

6.2 工具描述里藏着提示词工程

resolve-library-id 的「描述」根本不是一句话说明，而是一整篇给模型的作业指导：怎么分析 query、按什么维度选库、返回格式怎么写、甚至「一个问题最多调我 3 次」（packages/mcp/src/index.ts:138-170）。判断智能被写进了描述，而不是代码。query-docs 的 query 参数描述还教模型「一次只问一个概念，别把 routing+auth+caching 塞一个 query」（packages/mcp/src/index.ts:236-240）。→ 02 章

6.3 参数别名纠偏（对抗模型幻觉）

模型经常不照 schema 的字段名传参，而是照着描述里的措辞瞎编（比如传 context7CompatibleLibraryID 而不是 libraryId），这会在工具真正执行前就被 Zod 校验挡下。Context7 在传输层加了一个 onmessage 钩子，在 JSON-RPC 消息进入校验前，把这些幻觉别名改写回规范字段名（GLOBAL_ALIASES / TOOL_ALIASES / installTransportArgAliasing，packages/mcp/src/index.ts:281-328）。这是「迁就模型行为」的务实设计。→ 02 章

6.4 客户端 IP 加密后再上报

HTTP 模式下，MCP 服务器把调用方的 IP 用 AES-256-CBC 加密后才放进 mcp-client-ip 头发给后端（encryptClientIp / generateHeaders，packages/mcp/src/lib/encryption.ts:14-43）。后端能拿去做限流/去重，又不必看到明文 IP。→ 02 章

6.5 匿名 → 登录的 elicitation 引导

匿名用户限额较低。后端想提示他登录时，会在响应里带一个 X-Context7-Auth-Prompt: 1 头；MCP 服务器读到后，用 MCP 的 elicitation（向用户弹表单）能力弹出一个「要不要登录」的选择框（readPromptSignal @ packages/mcp/src/lib/api.ts:97-101；maybeElicitAuthSignIn @ packages/mcp/src/lib/auth/auth-prompt.ts:66）。妙在：这条提示是发给人看的、走 UI 通道，不进模型读的工具结果，所以不会触发模型的 prompt-injection 防护，也不污染上下文。→ 02 章

7. 顶层代码地图（导航索引）

想直接跳进源码时，从这张表起步。符号名比行号更抗漂移，可用来 grep。

你想看什么	文件	关键符号
monorepo 布局 / 5 个包	`package.json`	`workspaces: ["packages/*"]`
对外的产品叙事、两种模式、免责声明	`README.md`	"Works in two modes"、Disclaimer 第 2 条
MCP 包的分发元数据（npm/mcpb/remote）	`server.json`	`packages`、`remotes`
SDK 对外门面（两个方法）	`packages/sdk/src/client.ts`	`Context7`、`searchLibrary`、`getContext`
SDK 端点①：搜库	`packages/sdk/src/commands/search-library/index.ts`	`SearchLibraryCommand`（`v2/libs/search`）
SDK 端点②：取文档	`packages/sdk/src/commands/get-context/index.ts`	`GetContextCommand`（`v2/context`）
SDK 底层 HTTP（重试/分页头）	`packages/sdk/src/http/index.ts`	`HttpClient`、`extractTxtResponseHeaders`
MCP 两个工具的注册与描述	`packages/mcp/src/index.ts`	`registerTool("resolve-library-id" / "query-docs")`
MCP 双传输 / HTTP 路由 / 会话	`packages/mcp/src/index.ts`	`main`、`handleMcpRequest`、`StreamableHTTPServerTransport`
MCP 参数别名纠偏	`packages/mcp/src/index.ts`	`installTransportArgAliasing`、`GLOBAL_ALIASES`、`TOOL_ALIASES`
MCP 调后端两个端点	`packages/mcp/src/lib/api.ts`	`searchLibraries`、`fetchLibraryContext`
MCP 客户端 IP 加密 + 请求头	`packages/mcp/src/lib/encryption.ts`	`encryptClientIp`、`generateHeaders`
MCP 登录引导（elicitation）	`packages/mcp/src/lib/auth/auth-prompt.ts`	`maybeElicitAuthSignIn`
CLI 入口与命令注册	`packages/cli/src/index.ts`	`program`、`registerDocsCommands`、`registerSetupCommand`
CLI 查文档命令	`packages/cli/src/commands/docs.ts`	`resolveCommand`、`getReputationLabel`
AI-SDK 共享提示词	`packages/tools-ai-sdk/src/prompts/system.ts`	`AGENT_PROMPT`、`RESOLVE_LIBRARY_ID_DESCRIPTION`
pi.dev 扩展入口	`packages/pi/extensions/context7.ts`	`context7`（`registerTool`）
交付层：Skills / Plugins / Rules	`skills/`、`plugins/`、`rules/`	`SKILL.md`、各 agent 的 `mcp.json` / `.mcp.json`

本章只做导航与直觉。任何一个格子背后的「为什么这么写、怎么实现的」，都请顺着上面的链接进对应章节。

1. 这是什么（零基础也能懂）​

1.1 它要解决的痛点​

1.2 它做的事（一句话）​

1.3 用起来什么样​

1.4 对外只有两步操作​

2. 顶层全景（monorepo 怎么转）​

2.1 一张图看清全貌​

2.2 五个包各干什么​

2.3 「客户端分发层 vs 私有后端」这条边界​

2.4 后端的两个端点​

3. 主线走一遍（一次 'use context7' 的旅程）​

4. 两种交付模式（怎么把它装进你的 agent）​

5. 阅读地图（建议顺序）​

6. 巧妙之处（先建立直觉，细节留给后续章节）​

6.1 「两步工作流」作为唯一契约​

6.2 工具描述里藏着提示词工程​

6.3 参数别名纠偏（对抗模型幻觉）​

6.4 客户端 IP 加密后再上报​

6.5 匿名 → 登录的 elicitation 引导​

7. 顶层代码地图（导航索引）​