Context7 源码分析：技术架构、MCP 运行原理与检索链路

AI 参与说明（Agent：Codex）：本文由 Codex 根据 Context7 官方仓库、官方产品文档与固定提交的本地源码协助整理和校验。资料核验于 2026-08-27，源码基线为提交 9a384f0，其中 @upstash/context7-mcp 版本为 4.0.3。本文实际完成 monorepo build、typecheck、MCP / CLI / Pi tests 与 SDK HTTP 定向测试；需要 Context7 key 或 Amazon Bedrock credential 的完整 live suite 仅记录环境边界，不把缺少凭据视作项目缺陷。本文未使用 Pro private source，也未部署 Enterprise On-Premise。托管后端、套餐能力和限额会持续变化，涉及购买或生产接入时仍应以实时 Dashboard、Plans 页面和目标版本源码为准。

先说结论

Context7 的公开仓库不是一套可以从源码完整复刻的 Documentation Retrieval / Retrieval-Augmented Generation（RAG）后端。它更准确的定位是一个开源交付层 monorepo：把同一套 Context7 托管 API 接入 MCP Client、命令行、TypeScript 应用、Vercel AI SDK、Pi 和 OpenCode。真正负责抓取、解析、索引与检索的 API backend、parsing engine 和 crawling engine 没有出现在仓库中，官方也明确说明这些组件是私有实现。开源边界说明

packages/mcp 因而不是一个本地向量数据库，也不在本机执行 embedding、文档切片或 rerank。它是一个很薄但并不简单的 MCP protocol facade：

1. 向 Agent 暴露 resolve-library-id 与 query-docs 两个只读工具。
2. 规范化模型容易写错的参数名，并用 Zod 校验输入。
3. 从 stdio 或 HTTP 请求中组装认证、客户端身份与 transport context。
4. 把工具调用转换为托管 API 的两个 GET 请求。
5. 把搜索结果或文档文本重新包装成 MCP Tool Result。

这意味着“本地运行 Context7 MCP”只是在本地运行协议适配层，默认仍会访问 https://context7.com/api。如果要求源码、文档、embedding 和检索都不离开内网，需要评估官方单独提供的 Enterprise On-Premise，而不是把 npm MCP 包误认为完整自托管方案。API 默认地址 On-Premise 能力边界

1. 分析范围与证据等级

本文把结论分成两类：

• 源码可证实：工具名、参数、路由、header、超时、认证分支、错误返回和 package 依赖等，均可直接定位到固定提交。
• 架构推断：公开 API 后面必然存在搜索与文档检索服务；源码注释把调用称为 vector query 和 reranked context，On-Premise 文档也列出了 parser、indexing pipeline 与 local vector storage。但公开仓库无法证明 Context7 Cloud 具体使用哪一种 vector database、embedding model、chunking algorithm 或 reranker，因此本文不会替官方补齐这些实现细节。API client 注释 On-Premise 组件

一个尤其重要的阅读原则是：以运行源码和 MCP 协商结果为准，不能只看 package README。在这个提交中，packages/mcp/README.md 的 Available Tools 仍写着旧的 get-library-docs、topic 和 page 接口，但源码实际注册的是 query-docs(libraryId, query)；集成测试也断言服务端只列出 resolve-library-id 与 query-docs。旧 README 片段 实际工具注册 集成测试断言

2. Monorepo 边界：同一 API 的多种交付形态

根目录是一个 pnpm workspace，工作区只包含 packages/*；根命令使用 recursive build / test，各 package 独立发布，没有一个共享的“Context7 backend package”。workspace 配置 根 package scripts

这些边界可以从 package 依赖中得到直接验证：MCP package 依赖 @modelcontextprotocol/server、@modelcontextprotocol/node、Express、JOSE、Undici 和 Zod；Vercel AI SDK package 才通过 workspace dependency 使用 @upstash/context7-sdk。MCP package manifest AI SDK package manifest

由此还能看出一个有意的差异：MCP server 允许 anonymous access，并把上游失败转成便于 LLM 阅读的文本；TypeScript SDK 则在构造时要求 API key，HTTP non-2xx 会抛出 Context7Error。二者复用的是 wire API，不是同一段 client implementation。MCP API wrapper SDK client SDK HTTP 错误处理

3. High-level 技术架构

flowchart TD
  U["用户提出 library / API 问题"] --> A["Agent Harness"]
  A --> M["MCP Client"]
  A --> C["ctx7 CLI / TypeScript SDK / AI SDK / Pi"]

  subgraph OSS["公开仓库中的交付层"]
    M -->|"local stdio"| LS["@upstash/context7-mcp 本地进程"]
    M -->|"remote HTTP"| HS["@upstash/context7-mcp HTTP handler"]
    LS --> T["resolve-library-id / query-docs"]
    HS --> T
    C --> R["REST API client"]
    T --> R
  end

  subgraph PRIVATE["未包含在公开仓库中的服务层"]
    R --> S["GET /api/v2/libs/search"]
    R --> Q["GET /api/v2/context"]
    S --> I["API backend / search index"]
    Q --> I
    P["parsing + crawling + indexing pipeline"] --> I
    D["public / private documentation sources"] --> P
  end

  I --> O["候选 library 或相关文档文本"]
  O --> A
  A --> Z["模型结合检索内容生成最终答案"]

图中的关键分界是：MCP server 返回的是检索材料，不是替用户生成最终技术答案。模型仍要选择 library、调用工具、阅读返回内容并组织回答。反过来，library 匹配、snippet search 和 rerank 也不是由模型在 MCP process 内完成，而是委托给 Context7 API。

对 Cloud 部署内部结构，公开源码只能支持到这一步。Enterprise On-Premise 文档展示了 Web App、API server、parser 与 local key-value / vector storage 的组合，但这是 On-Premise 产品说明，不能无证据地等同为 Context7 Cloud 的真实部署拓扑。On-Premise 架构文档

4. packages/mcp 如何启动

入口文件先用 Commander 解析三个参数：--transport 默认 stdio，--port 默认 3000，--api-key 可选。它只接受 stdio 与 http；HTTP 模式禁止 --api-key，因为认证必须来自每个 HTTP request 的 header；stdio 模式则禁止 --port。CLI 参数与互斥校验

4.1 stdio：一个进程、一份初始化状态

stdio 模式从 --api-key 或 CONTEXT7_API_KEY 读取 key，并为进程生成一个 UUID 作为 session ID。serveStdio() 接管标准输入输出；MCP initialize 完成后，服务端保存 client name / version。后续工具调用优先读取现代协议 request envelope 中的 client info，旧客户端才回退到 initialize 阶段保存的全局信息。stdio 启动路径 context 合并顺序

这条路径适合 Client 负责拉起子进程的本地集成。它没有 HTTP client IP，但会把固定到进程的 mcp-session-id、API key、client info 与 stdio transport 标识传给上游。

4.2 HTTP：每个请求创建 server，保持无状态

HTTP 模式用 Express 提供 /mcp、/mcp/oauth、/ping 与 OAuth discovery routes。核心 MCP adapter 分为两层：

1. createMcpHandler(() => createMcpServer()) 生成 Web-standard handler。
2. toNodeHandler() 把它适配为 Node / Express request handler。

源码明确选择 stateless serving：每个请求创建新的 McpServer，不保存 MCP-Session-Id，也没有 session store；现代 2026-07-28 traffic 由 SDK 原生处理，2025-era client 走 stateless legacy fallback。keepAliveMs: 0 则关闭 SSE heartbeat，让挂起的 stream 最终能被 gateway idle timeout 回收。HTTP adapter 与无状态设计

HTTP 请求自己的 apiKey、client IP、User-Agent 与 transport 被放入 AsyncLocalStorage<ClientContext>。工具 handler 执行时再合并 MCP envelope 的 client info；因此并发请求不必依赖可串线的 module-level globals。每请求 context

5. Tool registration：两步工作流不是服务端状态机

createMcpServer() 用 MCP SDK 的 McpServer 注册 metadata、instructions 和 capabilities。它声明 prompts / resources capabilities，但实际集合为空，使那些无条件执行 list 请求的 Client 收到空数组，而不是 method not found。真正注册的能力只有两个 read-only、idempotent、open-world tools。server 初始化

工具 description 要求先 resolve、再 query；Skills 也重复这条规则。但 query-docs handler 不检查“本 session 是否调用过 resolve”，HTTP 又是无状态的。因此这不是服务端 enforced workflow，而是一份给模型的调用协议：用户已经提供精确 /org/project[/version] 时，可以直接 query；否则依赖模型遵守 instructions。两个 handlers

5.1 参数 alias 是对模型错误的兼容层

模型有时会照着自然语言描述生成 userQuery、question、libraryID 或 context7CompatibleLibraryID，而不是 schema 的 canonical keys。源码在 Zod preprocess 阶段复制参数并改写 alias：

• 所有工具把 userQuery / question 改成 query。
• query-docs 额外把 context7CompatibleLibraryID、libraryID，甚至 libraryName 改成 libraryId。
• 如果 canonical key 已存在，则 canonical value 优先。

把兼容放在 schema preprocess 中，意味着 stdio、HTTP、modern 和 legacy protocol 都共享同一行为；集成测试正好覆盖这四种组合。alias 实现 端到端 alias 测试

这个设计提高了对 LLM tool call 的容错率，但也说明 schema 不是唯一 contract。做自动化审计或 client generation 时，应以 tools/list 返回的 canonical schema 为准，不要主动依赖 alias。

6. 一次检索请求的源码级链路

6.1 resolve-library-id

1. MCP SDK 解析 Tool Call，Zod preprocess 修正参数并完成校验。
2. handler 通过 getClientContext(toolCtx) 取得当前 request context。
3. searchLibraries(query, libraryName, ctx) 构造 GET /api/v2/libs/search，把两个值放入 URLSearchParams。
4. generateHeaders(ctx) 附带 server version、认证与 client metadata。
5. 上游返回 JSON；MCP server 只负责格式化。trustScore >= 7 显示为 High，>= 4 显示为 Medium，其余为 Low / Unknown；benchmarkScore、versions 和 source 只在存在时输出。
6. tool 返回 Available Libraries 文本，让模型自己选择最匹配 ID。

search 请求实现 结果格式化

这里传入 query 的目的不是补充展示文本，而是让托管端按用户意图参与 library ranking。例如输入 React 时，搜索目标究竟是 React 文档、React Native 还是某个同名包，仅靠 library name 不一定足够。真正的 ranking 算法在私有 backend 中，MCP source 没有本地打分代码。

6.2 query-docs

1. handler 获取 context 后调用 fetchLibraryContext({ query, libraryId }, ctx)。
2. API client 构造 GET /api/v2/context。
3. 成功时直接读取 response.text()，不解析、重排或压缩内容。
4. handler 把这段文本放进单个 { type: "text" } content item。

context 请求实现 tool result 包装

因此，MCP 层所谓“retrieval”实质是传递 libraryId + natural-language query，并接收 backend 已整理好的 context。源码没有证明 MCP process 自己执行 semantic search。若返回材料缺失，应该先检查 library ID、version 与 query 粒度，而不是在本地 MCP server 中寻找 vector index。

7. Client context、认证与 telemetry header

generateHeaders() 会按实际 context 生成这些上游 header：header 生成代码

HTTP 的 /mcp 允许匿名访问；有 credential 时也会继续透传。/mcp/oauth 要求 credential，缺失或 JWT 校验失败会在进入 MCP handler 前返回 HTTP 401 和 JSON-RPC error code -32001。OAuth discovery 通过 WWW-Authenticate 与 /.well-known/oauth-protected-resource 暴露。HTTP auth 分支

JWT validation 支持三条 issuer 路径：Microsoft Entra v2、Context7 Enterprise-Managed Auth（EMA）以及默认 interactive OAuth issuer。Entra 会按 audience 从 Context7 API 取得 tenant / required scope 配置并缓存五分钟，然后用 tenant JWKS 验签；EMA 和普通 OAuth 则使用各自的 remote JWKS。JWT validation

普通 API key 不是 JWT，MCP process 不在本地验证其格式或有效性，只负责透传；最终错误由 API response 体现。HTTP key extraction 接受标准 Authorization，也兼容若干 legacy header spelling。实际配置应优先使用 Authorization: Bearer ...，因为 CLI setup 和官方示例都以它为 canonical form。key extraction setup 生成 Authorization header

7.1 一个自托管时容易忽略的 IP 边界

HTTP handler 会从 X-Forwarded-For 选择第一个非 private / local IP；找不到 public IP 时回退到列表第一项。之后使用 AES-256-CBC 加密再发给 API。IP 选择

固定提交中 CLIENT_IP_ENCRYPTION_KEY 未设置时会使用源码内的默认常量；自定义 key 若不是 64 位 hex，函数甚至会退回原始 IP。由此得到的工程建议是：自托管 HTTP gateway 时显式设置独立的 32-byte hex key，限制可信 reverse proxy，并在隐私评估中把 client IP 视为会离开 MCP process 的 metadata。IP 加密实现

8. Response 与 error path：失败不一定是 MCP Error

MCP wrapper 对 Agent 做了一个很有影响的选择：上游 API 错误大多被转换成正常的 text content，而不是 isError: true 的 Tool Result。

每个 API call 使用 AbortSignal.timeout(60_000)，MCP wrapper 没有 retry。searchLibraries 用 { results: [], error } 表示失败，fetchLibraryContext 用 { data: errorMessage }；两个 tool handlers 随后都照常返回 text content。error mapping 与 timeout search / context catch path

对 Agent Harness 的直接影响是：不能只检查 transport 成功或 isError；还要识别 Rate limited、Invalid API key、Documentation not found 等内容，并明确告诉用户为什么没有拿到文档。官方 find-docs skill 也要求 quota 用尽时不得静默回退到 training data。find-docs error guidance

API response 还可能通过 X-Context7-Auth-Prompt: 1 要求提示 anonymous user 登录。MCP server 把这个信号写到 mutable ClientContext，然后异步发起 form-mode elicitation；它不阻塞 tool result，也不会替用户执行 setup command。由于现代协议与 stateless HTTP 没有相应的 push-style capability，这个 soft prompt 实际只面向声明 elicitation capability 的 2025-era stdio client。prompt signal auth elicitation 边界

9. MCP SDK 在这里承担什么

@modelcontextprotocol/server 与 @modelcontextprotocol/node 2.0.0 承担 protocol mechanics：server metadata、tool schema derivation、tools/list / tools/call dispatch、stdio serving、modern / legacy HTTP compatibility，以及 Web handler 到 Node handler 的适配。Context7 自己的代码集中在 tool semantics、API bridging、context propagation 与 auth routes。SDK imports SDK 固定版本

能力分层可以概括为：

• MCP SDK 解决“怎样可靠接收和返回 MCP message”。
• Context7 MCP package 解决“这两个工具怎样映射到 API、怎样携带 caller context”。
• Context7 backend 解决“library 怎样匹配、哪些 snippet 与 query 相关”。
• Agent Harness 解决“何时调用、选哪个结果、怎样把 context 变成最终回答”。

这也解释了为什么换成 CLI、TypeScript SDK 或 Pi extension 后，检索能力依然存在：它们绕过 MCP protocol，但最终仍调用相同的 hosted API。

10. 实际怎么用

10.1 优先使用 ctx7 setup

CLI 在固定提交中要求 Node.js 18 或更高；如果选择 local stdio MCP，实际启动的 @upstash/context7-mcp@4.0.3 还要求 Node.js >=20.18.1。CLI engine MCP engine

npx ctx7@latest setup

交互流程会让用户选择两种模式：

• MCP server：默认配置 hosted HTTP；加 --stdio 才改为本地 npm process。
• CLI + Skills：不注册 MCP server，安装 find-docs skill，让 Agent 调用 ctx7 library / ctx7 docs。

需要把配置限定到当前项目时使用 --project；不应在公开仓库写入真实 key。没有显式传入 --api-key 或 --oauth 时，setup 会发起登录并生成 API key；--oauth 只适用于 hosted HTTP，不能与 --stdio 同用。setup mode 与参数 认证与 mode selection HTTP / stdio setup 分支

如果只是快速手动接入 remote MCP，核心配置是：

URL: https://mcp.context7.com/mcp
Header: Authorization: Bearer YOUR_API_KEY

希望 MCP Client 自己完成 OAuth 时，把 URL 改为 https://mcp.context7.com/mcp/oauth；OAuth 只支持 remote HTTP。API key 不应直接写入会提交的 config，优先使用 Agent Harness 的 secret / environment reference 能力。OAuth 使用边界

10.2 不用 MCP：直接走 CLI

# 第一步：用正式名称和真实意图查 ID
npx ctx7@latest library "Next.js" "How does Route Handler caching work?"

# 第二步：选择输出中的精确 ID，再查一个主题
npx ctx7@latest docs /vercel/next.js "How does Route Handler caching work?"

如果已经知道 ID，可以跳过第一步；如果用户指定版本，应从 resolve output 选择 version-specific ID。需要给脚本消费时加 --json。CLI source 会在 TTY 中显示 spinner，在 pipe / non-TTY 场景输出干净文本。CLI commands 实现 query command

10.3 应用内直接使用 TypeScript SDK

当调用方本来就是服务端 TypeScript 程序，没必要为了两个 API operation 再引入 MCP：

pnpm add @upstash/context7-sdk@0.3.1
export CONTEXT7_API_KEY='ctx7sk-...'

import { Context7 } from "@upstash/context7-sdk";

const context7 = new Context7();

const candidates = await context7.searchLibrary(
  "How does Route Handler caching work?",
  "Next.js",
  { type: "json" },
);

const selected = candidates[0];
if (!selected) throw new Error("No matching library");

const docs = await context7.getContext(
  "How does Route Handler caching work?",
  selected.id,
  { type: "txt" },
);

console.log(docs);

固定版本的 SDK 默认使用 https://context7.com/api，要求 API key，network exception 使用 exponential backoff retry；HTTP non-2xx 则直接抛 Context7Error，这与 MCP wrapper 的“把错误当文本返回”不同。SDK public methods SDK retry / response path

11. 怎样把 Context7 用好

Context7 的质量上限不只取决于 index，也取决于调用方是否给出可检索的 query。官方 Skills 与 tool descriptions 反复强调以下实践：context7-mcp skill find-docs query guidance

1. 先确定 corpus，再检索内容。不知道 ID 时先 resolve；知道 /org/project[/version] 时直接 query。
2. library name 使用官方拼写。Next.js 比 nextjs 更容易匹配正确项目。
3. resolve 也要带用户意图。libraryName 解决名称，query 帮助候选排序，不要只传一个泛化词。
4. 一个 query 聚焦一个概念。把 routing、auth、cache 拆开；只有问题本身就在讨论它们的交互时才合并。
5. 指定版本。只说产品名通常得到当前 indexed version；维护旧项目时应选择 resolve output 中的 version-specific ID。
6. 优先第一方 source。综合 exact name、description、snippet coverage、Source Reputation 与 Benchmark Score，而不是机械选择结果第一项。
7. 不要把秘密放进 query。API key、password、credential、个人数据和 proprietary code 都不应作为检索词发送。
8. 限制重复调用。官方 instruction 建议每个问题对同一工具最多调用三次；失败后解释原因，不要无限改写 query。
9. 核对来源与适用版本。Context7 返回的是相关材料，不是正确性证明；项目 README 也声明 community-contributed docs 无法保证完整性与安全性。官方 disclaimer

一个好的 Agent prompt 可以直接包含 ID、版本和单一目标：

使用 Context7 的 /vercel/next.js/v15.1.8 文档，查询 Route Handler 中
GET response caching 的当前默认行为。只回答 caching，不展开 auth；给出来源版本。

12. 三个官方 Skills，以及它们与 setup 的关系

Skills 是 instruction layer，不是新的数据通道。它们解决“Agent 何时想起 Context7、怎样形成高质量参数”；真正的数据仍经 MCP 或 CLI / REST 取得。

context7-cli skill 总览 setup 输出物说明 MCP skill 安装实现 find-docs 安装实现

setup 实际形成三层配置：

1. Access layer：MCP config 或可执行的 ctx7 CLI。
2. Trigger layer：rule 告诉 Agent 哪类问题应自动使用 Context7。
3. Procedure layer：Skill 规定 resolve、选择候选、query、处理失败的步骤。

只装 MCP config 而没有 rule / skill，工具虽然可用，模型未必主动调用；只装 skill 而没有 MCP 或 CLI/network permission，Agent 知道流程也无法取得文档。理解这三层，比把“安装成功”简化为是否出现两个 tool 更准确。

12.1 Context7 Power 不是第四个 Skill

仓库还包含 plugins/context7-power/POWER.md 与 mcp.json。它把 hosted MCP connection 和几乎同样的两步检索 procedure 打包成支持 Power 格式的 plugin；概念上更接近“连接配置 + instruction bundle”，并不是 ctx7 setup 会安装的第四个 Agent Skill。Context7 Power

12.2 注意 Skill 与 CLI 的版本漂移

固定提交已经出现几处可验证的 drift：

• find-docs 每次执行 npx ctx7@latest，所以运行版本并不由安装 Skill 时的版本锁定。
• setup 优先从远程 GitHub source 下载 rule / skill，再回退到 bundle；同一 CLI version 在不同日期可能得到不同 instruction content。模板下载策略
• context7-cli reference 仍列出已经从当前 ctx7 setup --help 移除的 --universal；当前公开 CLI 页面也保留了这个过期例子。过期 setup reference 当前 CLI 文档
• ctx7 skills command tree 在源码中已 hidden，并明确标记为将在下一个 major release 停止工作的 deprecated compatibility window；不要把旧 Skill Hub 当作长期稳定 API。Skill Hub deprecation

生产环境应记录 ctx7 --version、实际安装的 SKILL.md 内容和 MCP tools/list 结果；CI 中不要无审查地依赖 @latest。发现 README、Skill 与 command help 不一致时，以目标版本 --help、runtime schema 和 source 为准。

13. Pro 用户视角：把额度转化为稳定的工程能力

API key 不是 Pro 专属，anonymous MCP 也能使用低额度。Pro 真正增加的是 private sources、team collaboration、Teamspace Rules，以及调用达到套餐内额度后继续服务的能力。以下价格与额度按 2026-08-27 的实时页面整理，购买前仍应重新核对：Pro 标价为 $10 / seat / month，每个 seat 每月包含 5,000 次 API calls；超出后不会阻断，而是按 $10 / 1,000 次计费。private repository parsing 另按 $5 / 1M tokens计费。因此页面顶部的 “Unlimited API Calls” 表示可付费持续调用，不是固定月费内无限使用。Context7 Plans & Pricing

13.1 Pro 的推荐接入顺序

对 Codex 等支持 remote MCP 的 Agent，优先建立 authenticated connection，确认使用的是 Pro 所属 teamspace，再接入 private sources：

# 交互式配置 Codex；默认会完成 device login 并创建一把 API key
npx ctx7@latest setup --codex --mcp

# Client 支持 remote OAuth 时，可避免把长期 key 写进 MCP config
npx ctx7@latest setup --codex --mcp --oauth

官方 Codex 指南说明，Codex CLI、Desktop 与 IDE extension 共用 ~/.codex/config.toml；安装后应新开 task / thread，让 MCP tools 与 Skill 重新加载。Context7 for Codex

固定提交的默认 setup 流程会先走 OAuth Device Authorization Flow，再调用 Dashboard API 创建一把 ctx7-cli-<random> key，并把 key 作为 literal Bearer header 写入 MCP config；stdio 模式则把 key 写进 process arguments。ctx7 remove 和 ctx7 logout 只清理本地状态，不会自动 revoke Dashboard 中已经生成的 key。setup 创建 key config 写入形式

因此应在安装后完成三项检查：

1. Dashboard 中确认 key 属于预期 teamspace，而不是 personal project。
2. 给开发机、CI 和共享服务分别创建 key，以便独立统计和 revoke。
3. 检查 Agent config 是否会进入 Git；不支持 secret reference 时，优先 OAuth endpoint，或把包含 key 的配置严格留在用户级目录。

13.2 用 private sources 建立内部文档入口

Pro / Enterprise 可添加 GitHub、GitLab、Bitbucket、generic Git、Confluence 与 OpenAPI private sources。Owner / Admin 可以 add、refresh、remove，Developer 只能查看；对文档稀少的仓库可以显式开启 Generate docs。Add Private Sources

建议先把维护良好的 docs/、API reference 和架构决策纳入索引，再考虑源码生成。仓库根目录可用 context7.json 收窄 parsing 范围：

{
  "$schema": "https://context7.com/schema/context7.json",
  "projectTitle": "Internal Platform SDK",
  "description": "SDK contracts and production integration guides",
  "folders": ["docs", "guides"],
  "excludeFolders": ["dist", "fixtures", "archive", "node_modules"],
  "excludeFiles": ["CHANGELOG.md"],
  "rules": ["Examples must target the current stable API"]
}

这样做既减少噪声，也降低 private parsing tokens。新增 source 与 refresh 时会对处理的 tokens 计费，但 refresh 中未变化的 cached pages 免费；因此应在 release、重要文档更新或发现过期材料后刷新，而不是机械地高频 refresh。Private Sources 的刷新与配置

开源 MCP package 自身没有 private-repository connector。它只是把 key、library ID 与 query 传给 hosted API；private source 的连接、parsing、权限与索引都属于 backend capability。本地启动 MCP 不会把这些处理移到本机。

13.3 Teamspace：权限边界明确，计费文档暂有冲突

角色分为 Owner、Admin、Developer；三者都能创建 API keys，但只有 Owner / Admin 可以管理成员、library access 与 private sources。Pro Teamspace 指南当前给出的成员上限是 10。Manage Your Teamspace

需要特别注意，官方页面在 seat billing 上存在直接冲突：Teamspace 指南写“只有 owner 需要 paid plan，受邀成员不需要自己的 subscription”；同一天的 Plans 页面却写“每位 teamspace member 都算一个 seat”，且 5,000 次包含额度按 seat 分配、不能跨成员共享。涉及实际扣费时，应以 Dashboard checkout / invoice 与 Plans 页面 为准，并在邀请成员前核对，而不要依据其中任一段静态说明自行推断。

production setup 因而不应只问“Agent 有没有 key”，还应问：key 属于哪个 teamspace、谁负责 revoke、哪些角色可维护 sources，以及新增成员会如何改变当月 seats 与 included calls。

13.4 Policies：把来源治理放到服务端

每个使用 teamspace API key 的 search 和 MCP request 都会经过 teamspace Policies。Owner / Admin 可以整体开关 public repositories、websites、llms.txt、Confluence、uploaded files、Notion 与 private sources，也可按 verification、trust、freshness、stars、backlinks 等筛选，或改为手工 allowlist。Manage Policies

过滤后的 search response 会设置 searchFilterApplied，MCP formatter 再把提示写进候选结果。过滤提示格式化

这条链路的架构含义是：Policy enforcement 不在本地 Agent，也不在开源 MCP process，而在 API backend。不要把 prompt 中的“只用官方文档”当成 access control；组织级约束应落到 Policies。比较稳妥的初始策略是优先 verified / High trust / recent sources，再给团队确实依赖的小众 library 加 exception。

13.5 Teamspace Rules：把团队约定与文档一起返回

Teamspace Rules 是 Pro / Enterprise 能力。Global Rules 会 prepend 到每一次文档结果，library-specific Rules 只影响指定 library；只有 Owner / Admin 可写，Developer 只读。Manage Rules

适合写入 Rules 的内容是稳定、可执行且与技术栈有关的约束，例如“Next.js 只使用 App Router”“TypeScript 必须开启 strict mode”。不要把会快速变化的版本号、一次性迁移任务或 secrets 写进去。Rules 会改变 Agent 看到的 context，但不是 authorization；权限仍由 Teamspace role、source access 和 Policies 控制。

13.6 Usage 与成本：重点看四个指标

Dashboard Overview 将用量拆成 Requests、Parsing Tokens、Seats 和 Cost。Pro / Enterprise 按 billing date 每月重置统计；超额 requests、private parsing 与 seats 是三类不同成本。Monitor Usage

比较实用的治理方式是：

• 在 Agent instruction 中限制同一问题的无效重复调用，先 resolve 一次并复用准确 ID。
• 应用侧调用 REST / SDK 时缓存 library resolution 与稳定文档结果，并对 429 做明确处理。
• 用不同 key 区分本地开发、CI 与共享 Agent，结合 Dashboard 定位异常增长。
• private source 只索引必要目录，在有意义的变更后 refresh。

13.7 Query privacy：Pro 并不等于零数据外发

官方说明原始 prompt、代码和 conversation history 留在 AI assistant 一侧；发给 Context7 的是 Agent 重新组织的 query、libraryName / libraryId、credential、client metadata、transport，以及 HTTP 模式下处理过的 IP。服务端会把 query 交给 OpenAI、Gemini 或 Anthropic 等 provider 做 reranking，并匿名存储 query 用于 benchmark 与质量改进。Data Privacy

这里的“不会发送源码”主要依赖 tool description 要求 Agent 脱敏，不是本地的强制 DLP：MCP source 最终会把收到的 query 原样写入 URLSearchParams。因此不要把内部代码、客户名称、漏洞细节、token 或凭据复制进 query；应抽象成 library + API + technical goal。关闭 query storage 是 Enterprise control，Pro 当前没有同等开关。

即使 private source 权限正确，query、client metadata 和检索结果仍参与 hosted request。对“代码、文档与 embedding 绝不能离开环境”的场景，Pro Cloud private sources 与 Enterprise On-Premise 不是同一安全边界；后者应单独做 license、identity、LLM provider、backup 与 network egress review。On-Premise 定位

14. 设计取舍与源码阅读后的判断

14.1 做得好的地方

• 两个工具维持很小的 public interface，把 library disambiguation 与 content retrieval 分开。
• 同一 Zod preprocess 覆盖所有 transport 和 protocol era，对 LLM 参数漂移很实用。
• HTTP 使用 AsyncLocalStorage 隔离 request context，并明确保持 stateless，扩容边界清楚。
• proxy、custom CA、OAuth discovery、JWT issuer 分流和 client info propagation 都进入了生产路径，而不是只停留在 demo。
• 集成测试使用真实 build binary、本地 stub API、HTTP / stdio 和 modern / legacy 四种组合，验证的不是单个函数，而是 wire behavior。集成测试范围

14.2 需要调用方理解的代价

• “先 resolve 再 query”主要靠 prompt / skill 约束，不是 server-side state validation。
• API failure 通常仍是 successful Tool Result；监控若只统计 MCP protocol errors，会低估失败率。
• local MCP 不是 offline mode，默认 API endpoint 仍在 Context7 Cloud。
• MCP wrapper 与 TypeScript SDK 各自维护 HTTP client，retry、anonymous access 与 error semantics 不一致。
• package README 在固定提交中存在旧工具名，升级或生成 client 时必须重新看 tools/list 与 source。
• keepAliveMs: 0 是经历 long-lived hung stream 后的显式运行策略；若把代码部署到不同 gateway，应同时评估 backend timeout、stream idle timeout 和取消语义，不能只照搬单个数值。关闭 heartbeat 的原因

14.3 源码审计发现的实现与文档漂移

这类 drift 不影响“Context7 可以工作”的结论，却会影响集成代码和维护判断：

• MCP / Pi 的当前工具名是 resolve-library-id、query-docs；Vercel AI SDK exports 是 resolveLibraryId、queryDocs；CLI 则是 ctx7 library、ctx7 docs。packages/tools-ai-sdk/README.md 仍使用已经不存在的 resolveLibrary 与 getLibraryDocs。当前 AI SDK exports 过期 README 示例
• 只有 tools-ai-sdk 复用了 TypeScript SDK；CLI 与 Pi 都各自实现 REST、auth 和 formatting。修复一个 adapter 不会自动修复另外两个，名称与 error semantics 漂移正是这种重复的直接代价。
• SDK 只在 fetch 抛出 network exception 时 retry，不会 retry HTTP 429 / 5xx；而 retry: false 被换算成 attempts: 1，循环条件又是 i <= attempts，按控制流看仍可能执行两次 fetch。这是一项源码推断，现有测试没有覆盖该 rejected-fetch 分支，不能写成已经被 test 证明的 bug。SDK retry 配置与循环
• AI SDK tools 捕获 SDK exception 后返回普通字符串；MCP 与 Pi 也倾向把上游失败包装成普通 text result。应用若要做可靠重试与 SLO，必须增加自己的 machine-readable error classification。
• setup 写 JSONC 时先去掉 comments，再把整个对象序列化为 JSON，可能丢失原注释和格式；执行前应备份人工维护的 Agent config。MCP config writer

15. 本地复现与验证

以下命令对应本文锁定的提交；MCP package 要求 Node.js >=20.18.1：

git clone https://github.com/upstash/context7.git
cd context7
git checkout 9a384f099011d6299df530fd8d7a22510b2004d5
corepack enable
pnpm install --frozen-lockfile

# 编译 MCP package
pnpm --filter @upstash/context7-mcp build

# unit + integration；integration 会打开本机 loopback port
pnpm --filter @upstash/context7-mcp test

本文环境的验证结果如下：

所以根目录 pnpm test 并不是没有外部条件的 hermetic test：SDK 与 AI SDK 的部分 tests 会访问 live services，并依赖 repository secrets。外部 fork 或本地 clone 若没有相同 credential，不能把整仓测试失败直接解释为功能回归。

integration suite 会先 build 真实 dist/index.js，再启动本地 stub Context7 API，分别用 Streamable HTTP 与 stdio client、modern 2026-07-28 与 legacy protocol 完成 tool listing、schema、alias、client info 和端到端 request 断言；它不会把测试 query 发给生产 Context7 API。测试 harness 四种组合断言

如果还不熟悉 MCP 的 Host、Client、Server 与 Tool Router 分工，可先阅读站内的 MCP 在聊天应用中的基本原理：Server、Tools 与调用流程。

参考资料

• Context7 repository：固定提交
• packages/mcp/src/index.ts
• packages/mcp/src/lib/api.ts
• packages/mcp/src/lib/encryption.ts
• packages/mcp/src/lib/jwt.ts
• packages/mcp/test/integration.test.ts
• skills/context7-mcp/SKILL.md
• skills/context7-cli/SKILL.md
• skills/find-docs/SKILL.md
• Context7 API Guide source
• Private Sources source
• Teamspace source
• Policies source
• Context7 Plans & Pricing（实时）
• Context7 for Codex（实时）
• Manage Rules（实时）
• Monitor Usage（实时）
• Data Privacy（实时）