# https://github.com/upstash/context7 项目说明书
生成时间：2026-05-28 10:07:33 UTC
## 目录
- [概述与快速入门](#page-1)
- [CLI 参考指南](#page-2)
- [MCP 服务器架构](#page-3)
- [TypeScript SDK 与 AI SDK 工具](#page-4)
- [AI 编码助手集成](#page-5)
- [pi.dev 扩展集成](#page-6)
- [多客户端配置参考](#page-7)
- [库管理与维护](#page-8)
- [企业部署指南](#page-9)
- [安全与认证](#page-10)
## 概述与快速入门
### 相关页面
相关主题：[MCP 服务器架构](#page-3), [AI 编码助手集成](#page-5)
相关源码文件
以下源码文件用于生成本页说明：
- [package.json](https://github.com/upstash/context7/blob/main/package.json) - 项目元数据和关键词
- [packages/mcp/src/index.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts) - MCP 服务器核心实现
- [packages/mcp/mcpb/manifest.json](https://github.com/upstash/context7/blob/main/packages/mcp/mcpb/manifest.json) - MCP 工具清单
- [packages/cli/src/setup/templates.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/setup/templates.ts) - CLI 模板和工具说明
- [packages/cli/src/setup/agents.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/setup/agents.ts) - 智能体配置
- [plugins/claude/context7/README.md](https://github.com/upstash/context7/blob/main/plugins/claude/context7/README.md) - Claude Code 插件文档
- [plugins/cursor/context7/agents/docs-researcher.md](https://github.com/upstash/context7/blob/main/plugins/cursor/context7/agents/docs-researcher.md) - 文档研究员智能体
- [packages/tools-ai-sdk/README.md](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/README.md) - AI SDK 集成文档
# 概述与快速入门
## 项目简介
Context7 是一个由 Upstash 开发的文档检索平台，旨在为 AI 编码助手和开发工具提供最新、最准确的库文档和代码示例。该项目解决了大型语言模型训练数据过时的问题，通过直接从源代码仓库获取最新文档，确保 AI 助手能够基于真实、准确的信息回答开发者的技术问题。
Context7 的核心价值主张在于：**即使是你认为非常熟悉的库（如 React、Next.js、Prisma 等），也应该使用 Context7 来获取文档**，因为模型的训练数据可能不反映最新的 API 变化和最佳实践。
资料来源：[packages/mcp/src/index.ts:13-18]()
## 核心功能
### 文档检索工具
Context7 MCP 服务器提供两个主要工具：
| 工具名称 | 功能描述 | 输入参数 |
|---------|---------|---------|
| `resolve-library-id` | 将包/产品名称解析为 Context7 兼容的库 ID | `libraryName`：库名称；`query`：用户问题 |
| `query-docs` | 获取特定库的文档和代码示例 | `libraryId`：库 ID；`query`：查询内容 |
资料来源：[packages/mcp/mcpb/manifest.json:4-11]()
### 适用场景
Context7 适用于以下场景：
- **API 语法和参数查询**：查找特定函数或方法的使用方式
- **配置和设置指导**：库的配置选项和初始化方法
- **版本迁移帮助**：从一个版本升级到另一个版本时的变更说明
- **库特定的调试支持**：特定库的错误处理和最佳实践
- **CLI 工具使用**：命令行工具的子命令和选项说明
资料来源：[packages/cli/src/setup/templates.ts:15-22]()
### 不适用场景
Context7 不适用于以下场景：
- 代码重构和重写
- 从零开始编写业务逻辑脚本
- 调试业务逻辑问题
- 代码审查
- 通用编程概念学习
资料来源：[packages/mcp/src/index.ts:21-24]()
## 架构概览
```mermaid
graph TD
A[用户请求] --> B{MCP 客户端}
B --> C[Claude Code]
B --> D[Cursor]
B --> E[VS Code]
B --> F[其他 MCP 客户端]
C --> G[Claude Code 插件]
D --> H[Cursor 插件]
G --> I[Context7 MCP Server]
H --> I
E --> I
F --> I
I --> J[resolve-library-id 工具]
I --> K[query-docs 工具]
J --> L[Context7 API]
K --> L
L --> M[文档索引数据库]
M --> N[源代码仓库]
N --> O[文档解析服务]
O --> M
```
## 安装与配置
### 获取 API Key
在使用 Context7 之前，需要从 [context7.com](https://context7.com) 获取 API Key。获取后，可通过环境变量或配置文件进行设置。
### MCP 服务器安装
#### 全局安装
```bash
npm install -g @upstash/context7-mcp
```
#### 项目级安装
```bash
npm install @upstash/context7-mcp
```
资料来源：[packages/mcp/package.json:19-24]()
### Claude Code 插件安装
对于 Claude Code 用户，可通过插件市场安装：
```bash
claude plugin marketplace add upstash/context7
claude plugin install context7-plugin@context7-marketplace
```
安装完成后，插件会自动注册：
- **MCP 服务器**：连接 Claude Code 到 Context7 文档服务
- **Skills**：自动触发文档查询
- **Agents**：专门的 `docs-researcher` 智能体用于文档研究
- **Commands**：`/context7:docs` 命令用于手动文档查询
资料来源：[plugins/claude/context7/README.md:12-24]()
### 常用 MCP 客户端
Context7 支持 30 多个 MCP 客户端，包括：
| 客户端类型 | 安装难度 | 功能完整度 |
|-----------|---------|-----------|
| Claude Code | 简单（插件市场） | 完整 |
| Cursor | 简单（插件） | 完整 |
| VS Code (Cline) | 中等 | 完整 |
| Gemini CLI | 中等 | 完整 |
| Continue | 中等 | 完整 |
资料来源：[i18n/README.ko.md:28-30]()
## 快速入门指南
### 标准工作流程
```mermaid
graph LR
A[用户问题] --> B[resolve-library-id]
B --> C{选择最佳匹配}
C --> D[query-docs]
D --> E[返回文档结果]
E --> F[AI 回答用户问题]
```
### 步骤一：解析库 ID
当用户询问关于某个库的问题时，首先调用 `resolve-library-id` 工具：
```
输入: "next.js"
输出: {
id: "/vercel/next.js",
name: "Next.js",
versions: ["v15.1.8", "v14.2.0", ...],
benchmarkScore: 95,
description: "The React Framework for the Web"
}
```
选择最佳匹配时考虑以下因素：
1. **名称匹配度**：官方或最接近的包名
2. **基准评分**：数值越高表示文档质量越好
3. **代码片段数量**：越多表示覆盖越全面
4. **来源声誉**：优先选择 High/Medium 级别的来源
5. **版本适用性**：用户指定版本时优先选择对应版本 ID
资料来源：[plugins/cursor/context7/agents/docs-researcher.md:18-31]()
### 步骤二：查询文档
获得库 ID 后，调用 `query-docs` 工具获取具体文档：
```
输入: {
libraryId: "/vercel/next.js",
query: "app router middleware"
}
输出: 相关文档片段和代码示例
```
### 步骤三：回答用户问题
基于获取的文档内容，提供包含代码示例的准确回答。
## CLI 工具
### ctx7 命令行工具
Context7 提供 `ctx7` CLI 工具用于命令行环境：
```bash
npm install -g @upstash/context7-cli
```
#### 可用命令
| 命令 | 功能 |
|------|------|
| `ctx7 setup` | 配置 Context7 与各种智能体（Claude Code、Gemini CLI 等） |
| `ctx7 generate` | 交互式生成代码并自动获取相关文档 |
| `ctx7 remove` | 移除 Context7 配置 |
| `ctx7 skill` | 管理自定义技能 |
资料来源：[packages/cli/src/commands/generate.ts:45-65]()
### 设置命令
`ctx7 setup` 命令支持多种智能体的自动配置：
```bash
ctx7 setup [agent] --scope [global|local]
```
支持的智能体：
| 智能体 | 项目路径 | 全局路径 |
|--------|---------|---------|
| claude | `.claude` | `~/.claude` |
| gemini | `.gemini/settings.json` | `~/.gemini/settings.json` |
| codex | `.codex` | `~/.codex` |
| pi | - | `~/.pi` |
资料来源：[packages/cli/src/setup/agents.ts:10-60]()
## AI SDK 集成
### Vercel AI SDK 工具
对于使用 Vercel AI SDK 的开发者，Context7 提供了专门的工具包：
```bash
npm install @upstash/context7-tools-ai-sdk @upstash/context7-sdk ai zod
```
### 与 generateText 配合使用
```typescript
import { resolveLibrary, getLibraryDocs } from "@upstash/context7-tools-ai-sdk";
import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";
const { text } = await generateText({
model: openai("gpt-4o"),
prompt: "How do I use React Server Components?",
tools: {
resolveLibrary: resolveLibrary(),
getLibraryDocs: getLibraryDocs(),
},
stopWhen: stepCountIs(5),
});
```
### Context7Agent 智能体
包还提供了预配置的智能体：
```typescript
import { Context7Agent } from "@upstash/context7-tools-ai-sdk";
```
资料来源：[packages/tools-ai-sdk/README.md:28-45]()
## 文档研究员智能体
Context7 提供了专门的 `docs-researcher` 智能体配置，用于专注的文档研究：
```markdown
---
name: docs-researcher
description: 轻量级智能体，用于获取库文档而不污染主对话上下文
---
```
该智能体的工作流程：
1. **识别库**：从用户问题中提取库/框架名称
2. **解析库 ID**：调用 `resolve-library-id`
3. **选择最佳匹配**：基于名称、评分、版本等因素
4. **获取文档**：调用 `query-docs`
5. **返回答案**：提供简洁、可操作的答案和代码示例
资料来源：[plugins/cursor/context7/agents/docs-researcher.md:1-35]()
## 常见问题与故障排除
### 身份验证问题
如果遇到 API Key 相关错误：
1. 确认已从 [context7.com](https://context7.com) 获取有效 API Key
2. 检查环境变量 `UPSTASH_CONTEXT7_API_KEY` 是否正确设置
3. 确认 API Key 未过期
### 文档未找到
如果 `resolve-library-id` 返回空结果或找不到库：
1. 检查库名称拼写是否正确
2. 尝试使用官方包名（如 "Next.js" 而非 "nextjs"）
3. 确认该库已被 Context7 索引
### MCP 配置问题
在 Claude Code 等智能体中配置 MCP 时：
1. 确保 MCP 配置文件格式正确（JSON）
2. 检查智能体的已知路径是否存在
3. 使用 `ctx7 setup` 命令可自动处理配置
资料来源：[plugins/claude/context7/README.md:25-35]()
## 隐私与安全
Context7 MCP Server 作为开源项目（MIT 许可证），遵循以下原则：
- 仅在用户明确请求时获取文档
- 不会自动收集用户代码
- API 请求通过 HTTPS 加密传输
- 支持自定义 API 端点配置
资料来源：[packages/mcp/src/index.ts:8-14]()
## 相关信息
- [API 参考文档](./api-reference) - REST API 详细说明
- [库添加指南](./adding-libraries) - 如何向 Context7 提交新库
- [故障排除](./troubleshooting) - 常见问题与解决方案
- [开发者指南](./developer) - 本地运行 Context7 MCP
- [所有 MCP 客户端](./all-clients) - 30+ 客户端安装指南
---
## CLI 参考指南
### 相关页面
相关主题：[概述与快速入门](#page-1), [AI 编码助手集成](#page-5)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/cli/src/commands/generate.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/commands/generate.ts)
- [packages/cli/src/commands/skill.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/commands/skill.ts)
- [packages/cli/src/commands/remove.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/commands/remove.ts)
- [packages/cli/src/commands/setup.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/commands/setup.ts)
- [packages/cli/src/utils/api.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/utils/api.ts)
- [packages/cli/src/constants.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/constants.ts)
- [packages/cli/src/setup/agents.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/setup/agents.ts)
- [skills/context7-cli/SKILL.md](https://github.com/upstash/context7/blob/main/skills/context7-cli/SKILL.md)
# CLI 参考指南
## 概述
Context7 CLI（`ctx7`）是 Context7 文档系统的命令行客户端，为 AI 编码助手提供实时文档检索能力。通过 CLI，用户可以快速查询库文档、配置智能代理、管理 API 认证，并在各种开发环境中集成 Context7 功能。
CLI 支持两种主要使用模式：
- **CLI + Skills 模式** — 安装技能引导代理使用 `ctx7` 命令获取文档（无需 MCP）
- **MCP 模式** — 注册 Context7 MCP 服务器，使代理能够原生调用文档工具
资料来源：[README.md](https://github.com/upstash/context7/blob/main/README.md)
## 安装与初始化
### 快速安装
使用 `npx` 直接运行或通过全局安装：
```bash
# 使用 npx 直接运行
npx ctx7 setup
# 全局安装
npm install -g @upstash/context7-cli
# 安装后直接运行
ctx7 setup
```
### 初始化配置
`ctx7 setup` 命令完成以下任务：
1. **OAuth 认证** — 自动打开浏览器完成身份验证
2. **API Key 生成** — 创建用于编程访问的 API 密钥
3. **技能安装** — 选择目标代理并安装相应技能
```mermaid
graph TD
A[运行 ctx7 setup] --> B{是否已认证?}
B -->|否| C[启动 OAuth 认证流程]
C --> D[浏览器打开认证页面]
D --> E[用户授权]
E --> F[生成 API Key]
B -->|是| F
F --> G[选择代理类型]
G --> H[安装对应技能]
H --> I[配置完成]
```
资料来源：[packages/cli/src/commands/setup.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/commands/setup.ts)
## 命令参考
### setup — 初始化设置
初始化 Context7 CLI 并配置认证和代理。
```bash
ctx7 setup [选项]
```
| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--cli` | 布尔 | `false` | 仅安装 CLI + Skills 模式 |
| `--mcp` | 布尔 | `false` | 仅安装 MCP 模式 |
| `--global` | 布尔 | `false` | 全局安装（所有项目） |
| `--project` | 布尔 | `false` | 仅当前项目安装 |
| `--agent` | 字符串 | - | 指定代理类型 |
**支持的代理类型：**
| 代理 | 配置文件路径 | 说明 |
|------|-------------|------|
| `claude` | `.claude/` | Anthropic Claude Code |
| `gemini` | `.gemini/` | Google Gemini CLI |
| `cursor` | `.cursor/` | Cursor IDE |
| `windsurf` | `.windsurf/` | Windsurf IDE |
| `codestral` | `.codestral/` | Codestral IDE |
| `power` | - | Power 编码代理 |
资料来源：[packages/cli/src/setup/agents.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/setup/agents.ts)
### docs — 文档查询
查询指定库的文档。
```bash
ctx7 docs [查询词]
```
**参数说明：**
| 参数 | 必需 | 说明 |
|------|------|------|
| `library-id` | 是 | Context7 库 ID，格式为 `/org/project` 或 `/org/project/version` |
| `查询词` | 否 | 用于相关性排序的搜索查询 |
**使用示例：**
```bash
# 查询 Next.js 文档
ctx7 docs /vercel/next.js middleware
# 查询特定版本的文档
ctx7 docs /vercel/next.js/v14 app router
# 交互式选择库并查询
ctx7 docs
```
**交互式流程：**
CLI 会展示一个可搜索的库列表，包含以下元数据：
| 字段 | 说明 |
|------|------|
| `Library` | 库名称和上下文7链接 |
| `Source` | 源代码仓库链接 |
| `Snippets` | 可用代码片段数量 |
| `Stars` | GitHub 星标数（如适用） |
| `Description` | 库描述 |
资料来源：[packages/cli/src/commands/docs.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/commands/docs.ts)
### generate — 代码生成
根据文档生成代码示例。
```bash
ctx7 generate [选项] <描述>
```
**选项：**
| 选项 | 说明 |
|------|------|
| `--model <模型>` | 指定使用的 AI 模型 |
| `--no-stream` | 禁用流式输出 |
| `--json` | 输出 JSON 格式 |
**工作流程：**
```mermaid
graph TD
A[运行 generate 命令] --> B[搜索相关库]
B --> C{用户选择库}
C -->|无选择| D[结束]
C -->|选择库| E[生成澄清问题]
E --> F[获取用户回答]
F --> G[生成代码]
G --> H[返回代码和说明]
```
用户可以从搜索结果中选择多个库，CLI 会显示每个库的详细信息，包括代码片段数量和星标数。
资料来源：[packages/cli/src/commands/generate.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/commands/generate.ts)
### skill — 技能管理
管理已安装的 Context7 技能。
```bash
ctx7 skill [子命令]
```
**子命令：**
| 子命令 | 说明 |
|--------|------|
| `list` | 列出已安装的技能 |
| `install ` | 安装指定技能 |
| `remove ` | 移除指定技能 |
**`list` 输出示例：**
```
Skill: context7-mcp
Repo: /upstash/context7
Installs: 1.2k - 1.5k
Trust: 9.8
Description: Fetch up-to-date library documentation using Context7
```
**安装计数格式化：**
| 范围 | 显示格式 |
|------|---------|
| 0-99 | 精确数字 |
| 100-999 | `1.2k - 1.5k` |
| 1000+ | `10.5k - 12.3k` |
资料来源：[packages/cli/src/commands/skill.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/commands/skill.ts)
### remove — 卸载清理
从代理配置中移除 Context7 集成。
```bash
ctx7 remove [选项]
```
| 选项 | 说明 |
|------|------|
| `--all` | 移除所有代理的 Context7 配置 |
| `--agent <名称>` | 指定要清理的代理 |
| `--global` | 清理全局配置 |
**注意：** 在 v0.4.2 版本中，CLI 改进了对格式错误的 MCP 配置文件的处理。如果配置文件（如 `~/.claude.json`）存在 JSON 语法错误，CLI 会跳过该文件而非崩溃。
资料来源：[packages/cli/src/commands/remove.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/commands/remove.ts)
### auth — 认证管理
管理 API 认证信息。
```bash
ctx7 auth [子命令]
```
| 子命令 | 说明 |
|--------|------|
| `login` | 启动 OAuth 登录流程 |
| `logout` | 清除认证信息 |
| `status` | 查看当前认证状态 |
| `key` | 管理 API 密钥 |
资料来源：[packages/cli/src/commands/auth.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/commands/auth.ts)
## 配置与存储
### 配置存储位置
CLI 默认将配置存储在 `~/.context7/` 目录：
| 文件 | 说明 |
|------|------|
| `cli-state.json` | CLI 状态和认证信息 |
| `api-key` | API 密钥文件 |
```bash
# 配置文件位置
~/.context7/
├── cli-state.json
└── api-key
```
**已知限制：** 当前 CLI 未完全遵循 XDG Base Directory 规范（相关 Issue #2638）。用户期望将 CLI 状态存储在 `~/.config/context7/` 等 XDG 标准位置，而非硬编码的 `~/.context7/`。
### API 配置
API 端点配置在源码中定义：
| 环境 | 端点 |
|------|------|
| 生产环境 | `https://context7.com/api` |
| 本地开发 | `http://localhost:8080/api` |
资料来源：[packages/cli/src/constants.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/constants.ts)
### API 请求工具
CLI 使用统一的 API 请求工具处理所有后端通信：
```typescript
interface ApiConfig {
baseUrl: string;
apiKey?: string;
timeout?: number;
}
// 认证头自动注入
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
}
```
资料来源：[packages/cli/src/utils/api.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/utils/api.ts)
## 技能（Skill）配置
### CLI Skills 模式
当选择 CLI + Skills 模式时，CLI 会安装一个技能定义文件，该文件指导代理如何调用 `ctx7` 命令获取文档。
**默认回退模板：**
```
Use the `ctx7` CLI to fetch current documentation whenever the user asks about a library,
framework, SDK, API, CLI tool, or cloud service
Steps:
1. `ctx7 docs` with the library name
2. Pick the best match by relevance
3. `ctx7 docs` with the selected library ID
4. Answer using the fetched docs
```
### 技能安装路径
| 作用域 | 安装路径 |
|--------|---------|
| 全局 | `~/.agents/skills/` |
| 项目 | `./.agents/skills/` |
技能文件命名规范：`context7-mcp/`
资料来源：[packages/cli/src/setup/templates.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/setup/templates.ts)
## 工作流程图
### 完整文档查询流程
```mermaid
sequenceDiagram
participant User
participant CLI
participant API
participant DocSource
User->>CLI: ctx7 docs /vercel/next.js middleware
CLI->>API: GET /api/library/vercel/next.js
API->>DocSource: 获取最新文档索引
DocSource-->>API: 文档数据
API-->>CLI: 结构化文档响应
CLI->>CLI: 相关性排序
CLI-->>User: 显示文档结果
```
### 多代理集成架构
```mermaid
graph TB
subgraph Claude Code
C1[.claude/]
C2[AGENTS.md]
C3[skills/context7-mcp]
end
subgraph Gemini CLI
G1[.gemini/settings.json]
G2[GEMINI.md]
G3[skills/context7-mcp]
end
subgraph Cursor
P1[.cursor/mcp.json]
P2[agents/docs-researcher]
end
subgraph Context7
S[ctx7 CLI]
M[MCP Server]
API[context7.com/api]
end
C1 --> S
G1 --> S
P1 --> M
S --> API
M --> API
```
## 常见问题与故障排除
### 认证问题
**症状：** 运行 `ctx7 setup` 时认证失败
**解决方案：**
1. 检查网络连接
2. 清除旧配置：`ctx7 auth logout`
3. 重新运行：`ctx7 setup`
### MCP 配置解析错误
**症状：** `ctx7 remove` 命令因 JSON 解析错误崩溃
**解决：** v0.4.2+ 版本已修复，CLI 会跳过格式错误的配置文件继续执行。
### 库搜索无结果
**症状：** 搜索特定库名称无匹配结果
**可能原因：**
- 库尚未被 Context7 索引
- 库名称拼写错误
- 需要使用完整组织名称（如 `/microsoft/typescript` 而非 `/ts`）
### 速率限制
CLI 使用速率限制保护服务：
| 认证状态 | 限制 |
|---------|------|
| 未认证 | 较低限制 |
| 已认证（免费） | 中等限制 |
| 已认证（付费） | 较高限制 |
建议获取 API Key 以获得更好的使用体验。
## 相关功能特性
### 请求的功能（社区反馈）
| 功能 | Issue | 状态 |
|------|-------|------|
| `--dry-run` 配置验证标志 | #2677 | 待实现 |
| XDG 规范兼容目录 | #2638 | 待实现 |
| 离线文档支持 | #320 | 待实现 |
| 私有文档支持 | #34 | 待实现 |
### 社区讨论热点
- **自托管选项**（Issue #59）— 用户希望能够自建文档后端
- **文档版本控制**（Issue #45）— 支持特定版本标签的文档检索
## 相关资源
| 资源 | 链接 |
|------|------|
| Context7 官网 | https://context7.com |
| API 文档 | https://context7.com/docs/api-guide |
| 仪表板 | https://context7.com/dashboard |
| 问题反馈 | https://github.com/upstash/context7/issues |
| 支持邮箱 | context7@upstash.com |
## 参见
- [MCP 服务器参考](./mcp-server.md) — MCP 协议集成详细说明
- [SDK 集成指南](./sdk-integration.md) — 编程方式访问 Context7 API
- [AI SDK 工具](./ai-sdk-tools.md) — Vercel AI SDK 集成包
- [故障排除指南](./troubleshooting.md) — 常见问题与解决方案
---
## MCP 服务器架构
### 相关页面
相关主题：[TypeScript SDK 与 AI SDK 工具](#page-4), [概述与快速入门](#page-1)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/mcp/src/index.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts)
- [packages/mcp/src/lib/api.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/lib/api.ts)
- [packages/mcp/src/lib/auth/auth-prompt.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/lib/auth/auth-prompt.ts)
- [packages/mcp/src/lib/sessionStore.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/lib/sessionStore.ts)
- [packages/mcp/src/lib/redis.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/lib/redis.ts)
- [packages/mcp/src/lib/jwt.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/lib/jwt.ts)
- [packages/mcp/schema/context7.json](https://github.com/upstash/context7/blob/main/packages/mcp/schema/context7.json)
- [packages/mcp/mcpb/manifest.json](https://github.com/upstash/context7/blob/main/packages/mcp/mcpb/manifest.json)
# MCP 服务器架构
## 概述
Context7 MCP（Model Context Protocol）服务器是连接 AI 编码助手与文档服务的桥梁。该服务器基于 [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk) 构建，为 AI 助手提供实时的、版本特定的库文档访问能力。
MCP 服务器的核心价值在于解决 LLM 的训练数据过时问题：
- **无 Context7**：LLM 依赖过时的训练数据，产生幻觉 API 和过时代码示例
- **有 Context7**：直接从源码仓库拉取最新文档，注入到 LLM 上下文
资料来源：[README.md](https://github.com/upstash/context7/blob/main/README.md)
---
## 系统架构
### 整体架构图
```mermaid
graph TD
subgraph "AI 编码助手"
A[Claude Code / Cursor / Gemini CLI]
end
subgraph "MCP 服务器"
B[Context7 MCP Server]
C[Express HTTP Server]
D[Tool Handlers]
E[Authentication Layer]
F[Session Store]
G[Redis Client]
end
subgraph "外部服务"
H[Context7 API]
I[Redis Cloud]
end
A <--> B
B <--> C
C <--> D
C <--> E
E <--> F
F <--> G
G <--> I
B <--> H
style A fill:#e1f5fe
style H fill:#fff3e0
style I fill:#f3e5f5
```
### 核心组件
| 组件 | 文件位置 | 职责 |
|------|----------|------|
| MCP Server | `src/index.ts` | 协议实现、工具注册、服务端初始化 |
| Express Server | `src/index.ts` | HTTP 传输层、路由处理 |
| Tool Handlers | `src/lib/` | 处理 `resolve-library-id` 和 `query-docs` 工具调用 |
| Auth Layer | `src/lib/auth/` | JWT 验证、会话管理 |
| Redis Client | `src/lib/redis.ts` | 会话存储（使用 Upstash Redis） |
资料来源：[packages/mcp/src/index.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts)
---
## 传输协议
MCP 服务器支持两种传输方式：
### 1. STDIO 模式
适用于本地开发和标准输入/输出通信：
```json
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"]
}
}
}
```
### 2. HTTP + SSE 模式
适用于远程部署和需要网络通信的场景：
```json
{
"mcpServers": {
"context7": {
"command": "context7-mcp",
"args": ["--transport", "http"],
"env": {
"CONTEXT7_API_KEY": "your-api-key",
"PORT": "3000"
}
}
}
}
```
资料来源：[packages/mcp/src/index.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts)
---
## 工具定义
MCP 服务器暴露两个核心工具：
### resolve-library-id
解析库名称为 Context7 兼容的库 ID。
```typescript
server.registerTool(
"resolve-library-id",
{
title: "Resolve Context7 Library ID",
description: `Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.
You MUST call this function before 'Query Documentation' tool to obtain a valid Context7-compatible library ID UNLESS the user explicitly provides a library ID in the format '/org/project' or '/org/project/version' in their query.`
}
);
```
**输入参数**：
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| libraryName | string | 是 | 库名称（如 "react", "next.js"） |
| query | string | 是 | 用户问题全文（用于相关性排序） |
**返回结果**：
| 字段 | 说明 |
|------|------|
| id | Context7 库 ID（格式：`/org/project` 或 `/org/project/version`） |
| name | 库名称 |
| description | 简短描述 |
| codeSnippets | 可用代码示例数量 |
| benchmarkScore | 基准评分（用于选择最佳匹配） |
资料来源：[packages/mcp/src/index.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts)
### query-docs
查询特定库的文档。
```typescript
server.registerTool(
"query-docs",
{
title: "Query Documentation",
description: `Retrieves and queries up-to-date documentation and code examples from Context7.`
}
);
```
**输入参数**：
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| libraryId | string | 是 | Context7 库 ID（来自 resolve-library-id） |
| query | string | 是 | 具体查询内容 |
**返回结果**：
- 相关文档片段
- 代码示例
- 文档来源链接
**选择最佳匹配库的建议**：
1. 精确名称匹配优先
2. 基准评分（benchmark score）越高越好
3. 官方/主库优先于社区分支
4. 版本特定 ID 优先（如用户提及版本）
资料来源：[packages/mcp/mcpb/manifest.json](https://github.com/upstash/context7/blob/main/packages/mcp/mcpb/manifest.json)
---
## 认证与授权
### 认证流程
```mermaid
sequenceDiagram
participant Client as AI 编码助手
participant MCP as Context7 MCP Server
participant Redis as Upstash Redis
participant API as Context7 API
Client->>MCP: 初始化连接
MCP->>MCP: 检查环境变量 CONTEXT7_API_KEY
alt 有 API Key
MCP->>API: 使用 Bearer Token 认证
API-->>MCP: 认证成功
else 无 API Key
MCP->>MCP: 生成临时会话
MCP->>Redis: 存储会话数据
Note over Redis: 限流：IP 级别
end
Client->>MCP: 调用工具
MCP->>API: 转发请求
API-->>MCP: 返回文档
MCP-->>Client: 工具响应
```
### JWT 处理
MCP 服务器使用 `jose` 库处理 JWT token：
```typescript
import { SignJWT, jwtVerify } from "jose";
const secret = new TextEncoder().encode(process.env.CONTEXT7_API_KEY);
const token = await new SignJWT({ ...payload })
.setProtectedHeader({ alg: "HS256" })
.sign(secret);
```
资料来源：[packages/mcp/src/lib/jwt.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/lib/jwt.ts)
### 会话存储
会话数据存储在 Upstash Redis 中：
```typescript
interface Session {
id: string;
createdAt: number;
rateLimit: {
remaining: number;
resetAt: number;
};
}
const session = await sessionStore.create();
```
**存储位置**：使用 `sessionStore.ts` 管理会话生命周期
**限流策略**：
- 无 API Key：基于 IP 地址的限流
- 有 API Key：更高的请求限额
资料来源：[packages/mcp/src/lib/sessionStore.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/lib/sessionStore.ts)
---
## 数据流
### 文档查询完整流程
```mermaid
flowchart LR
subgraph "步骤 1: 库解析"
A[用户问题] --> B[提取库名称]
B --> C[resolve-library-id]
C --> D{多结果?}
D -->|是| E[按名称/评分选择]
D -->|否| F[使用唯一结果]
E --> G[库 ID]
F --> G
end
subgraph "步骤 2: 文档查询"
G --> H[query-docs]
H --> I[Context7 API]
I --> J[相关性排序]
J --> K[返回文档片段]
end
subgraph "步骤 3: 上下文注入"
K --> L[组装工具响应]
L --> M[返回给 AI 助手]
end
```
### 错误处理
| 错误类型 | 处理方式 | 用户反馈 |
|----------|----------|----------|
| 库未找到 | 返回空结果集 | 提示无可用文档 |
| API 超时 | 重试一次 | 返回超时错误 |
| 限流触发 | 等待后重试 | 提示速率限制 |
| 认证失败 | 检查 API Key | 提示配置问题 |
---
## 配置选项
### 环境变量
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `CONTEXT7_API_KEY` | - | Context7 API 密钥（推荐设置以获得更高限流） |
| `PORT` | `3000` | HTTP 服务器端口 |
| `CONTEXT7_TRANSPORT` | `stdio` | 传输协议：`stdio` 或 `http` |
| `CONTEXT7_BASE_URL` | `https://context7.com/api` | API 基础 URL |
### MCP 配置文件
```json
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"],
"env": {
"CONTEXT7_API_KEY": "your-key-here"
}
}
}
}
```
---
## 服务发现与安装
### 自动检测的编码助手
MCP 服务器自动检测以下编码助手并提供集成：
| 编码助手 | 配置文件路径 | 说明 |
|----------|--------------|------|
| Claude Code | `~/.claude.json` | 全局或项目级配置 |
| Gemini CLI | `~/.gemini/settings.json` | 全局配置 |
**自动检测逻辑**：
```typescript
gemini: {
detect: {
projectPaths: [join(".gemini", "settings.json")],
globalPaths: [join(homedir(), ".gemini", "settings.json")],
configKey: "mcpServers"
}
}
```
资料来源：[packages/cli/src/setup/agents.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/setup/agents.ts)
### CLI 安装
```bash
npx ctx7 setup
```
该命令执行以下操作：
1. OAuth 认证
2. 生成 API 密钥
3. 选择安装模式（CLI + Skills 或 MCP）
4. 配置目标编码助手
---
## 安全考虑
### 已知安全问题
社区报告了以下安全问题：
#### 1. 提示注入风险
`query-docs` 响应中可能包含非文档内容。攻击者可能在文档中注入提示指令。
> ⚠️ **注意**：从不受信任的源获取的文档内容应该进行过滤验证。
相关 Issue：
- [#2663](https://github.com/upstash/context7/issues/2663)：非文档 "system notice" 被注入到响应中
- [#2673](https://github.com/upstash/context7/issues/2673)：HubSpot 文档库中出现提示注入内容
#### 2. 配置验证
当前版本增强了配置文件解析的容错性：
```typescript
// ctx7@0.4.2 更新
// 处理格式错误的 MCP 配置文件时优雅降级
// 之前：SyntaxError 导致命令崩溃
// 现在：跳过格式错误的文件继续执行
```
资料来源：[packages/mcp/src/index.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts)
### 安全最佳实践
1. **API Key 管理**：妥善保管 `CONTEXT7_API_KEY`，避免提交到版本控制
2. **内容验证**：对返回的文档内容进行安全过滤
3. **限流监控**：监控 API 调用频率，及时发现异常
---
## 平台兼容性
| 平台 | 支持状态 |
|------|----------|
| macOS (darwin) | ✅ 支持 |
| Windows (win32) | ✅ 支持 |
| Linux | ✅ 支持 |
| Node.js | >= v18.0.0 |
资料来源：[packages/mcp/mcpb/manifest.json](https://github.com/upstash/context7/blob/main/packages/mcp/mcpb/manifest.json)
---
## 常见问题
### 1. 如何验证 MCP 配置？
当前 CLI 不提供 `--dry-run` 参数直接验证配置。建议：
- 使用 `ctx7 setup` 重新配置
- 检查环境变量是否正确设置
- 查看 CLI 输出中的错误信息
> 📌 相关功能请求：[#2677](https://github.com/upstash/context7/issues/2677) - 添加 `--dry-run` 标志
### 2. 支持离线/气隙环境吗？
当前版本需要互联网访问 Context7 API。
> 📌 相关功能请求：[#320](https://github.com/upstash/context7/issues/320) - 离线文档支持
### 3. 如何处理自托管需求？
目前不支持自托管文档后端，所有请求都经过 `context7.com/api`。
> 📌 相关功能请求：[#59](https://github.com/upstash/context7/issues/59) - 自托管文档后端选项
### 4. 如何使用版本特定的文档？
在库 ID 中指定版本：
```typescript
// 使用 Next.js 15
libraryId: "/vercel/next.js/v15.1.8"
// 使用 React 19
libraryId: "/facebook/react/v19.0.0"
```
> 📌 相关功能请求：[#45](https://github.com/upstash/context7/issues/45) - 文档版本控制
---
## 相关资源
| 资源 | 链接 |
|------|------|
| Context7 官网 | https://context7.com |
| MCP 包 (npm) | https://www.npmjs.com/package/@upstash/context7-mcp |
| SDK 包 (npm) | https://www.npmjs.com/package/@upstash/context7-sdk |
| AI SDK 工具包 | https://www.npmjs.com/package/@upstash/context7-tools-ai-sdk |
| 问题反馈 | https://github.com/upstash/context7/issues |
| 安全漏洞报告 | https://github.com/upstash/context7/security/advisories/new |
---
## 另请参阅
- [CLI 命令参考](../cli/commands.md) - `ctx7` CLI 详细用法
- [SDK 集成指南](../sdk/README.md) - 使用 Context7 SDK
- [Vercel AI SDK 集成](../tools-ai-sdk/README.md) - AI SDK 工具和代理
- [插件安装指南](../plugins/README.md) - 为编码助手安装插件
---
## TypeScript SDK 与 AI SDK 工具
### 相关页面
相关主题：[MCP 服务器架构](#page-3), [pi.dev 扩展集成](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/sdk/src/client.ts](https://github.com/upstash/context7/blob/main/packages/sdk/src/client.ts)
- [packages/sdk/src/commands/types.ts](https://github.com/upstash/context7/blob/main/packages/sdk/src/commands/types.ts)
- [packages/sdk/src/utils/format.ts](https://github.com/upstash/context7/blob/main/packages/sdk/src/utils/format.ts)
- [packages/sdk/src/commands/get-context/index.ts](https://github.com/upstash/context7/blob/main/packages/sdk/src/commands/get-context/index.ts)
- [packages/sdk/src/commands/search-library/index.ts](https://github.com/upstash/context7/blob/main/packages/sdk/src/commands/search-library/index.ts)
- [packages/sdk/README.md](https://github.com/upstash/context7/blob/main/packages/sdk/README.md)
- [packages/tools-ai-sdk/src/index.ts](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/index.ts)
- [packages/tools-ai-sdk/src/tools/resolve-library-id.ts](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/tools/resolve-library-id.ts)
- [packages/tools-ai-sdk/src/tools/query-docs.ts](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/tools/query-docs.ts)
- [packages/tools-ai-sdk/src/agents/context7.ts](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/agents/context7.ts)
- [packages/tools-ai-sdk/src/prompts/system.ts](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/prompts/system.ts)
- [packages/tools-ai-sdk/README.md](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/README.md)
- [packages/sdk/CHANGELOG.md](https://github.com/upstash/context7/blob/main/packages/sdk/CHANGELOG.md)
- [packages/tools-ai-sdk/CHANGELOG.md](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/CHANGELOG.md)
# TypeScript SDK 与 AI SDK 工具
## 概述
Context7 项目提供了两个核心 TypeScript 包，用于将文档检索能力集成到 AI 应用中：
| 包名 | 用途 | 依赖关系 |
|------|------|---------|
| `@upstash/context7-sdk` | HTTP/REST 客户端，直接调用 Context7 API | 无 |
| `@upstash/context7-tools-ai-sdk` | Vercel AI SDK 兼容工具和代理 | 依赖 `@upstash/context7-sdk` |
### 解决的问题
LLM 依赖于过时或泛化的训练数据来回答关于第三方库的问题，这会导致：
- 基于数年前训练数据生成的代码示例
- 不存在但被"幻觉"出的 API
- 针对旧版本包的通用答案
Context7 SDK 通过提供最新的、版本特定的文档和代码示例来解决这些问题。
资料来源：[packages/sdk/README.md:1-20](https://github.com/upstash/context7/blob/main/packages/sdk/README.md)
---
## 架构概览
```mermaid
graph TD
A[开发者应用] --> B{@upstash/context7-tools-ai-sdk}
B --> C{@upstash/context7-sdk}
C --> D[Context7 API]
D --> E[文档数据库]
F[Vercel AI SDK] --> B
G[AI Agent] --> B
H[generateText / streamText] --> B
```
### 包结构关系
```
@upstash/context7-tools-ai-sdk
├── resolveLibraryId() → 工具函数
├── queryDocs() → 工具函数
└── Context7Agent → 预配置代理
↓
@upstash/context7-sdk
├── searchLibrary() → 搜索库
└── getContext() → 获取文档
↓
Context7 API (context7.com)
```
资料来源：[packages/tools-ai-sdk/README.md:1-15](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/README.md)
---
## 安装与配置
### 安装
```bash
# 仅 SDK
npm install @upstash/context7-sdk
# SDK + AI SDK 工具
npm install @upstash/context7-tools-ai-sdk @upstash/context7-sdk ai zod
```
资料来源：[packages/sdk/README.md:30-40](https://github.com/upstash/context7/blob/main/packages/sdk/README.md)
### 环境变量
| 变量名 | 必需 | 说明 |
|--------|------|------|
| `CONTEXT7_API_KEY` | 是 | 从 [Context7](https://context7.com) 获取的 API 密钥 |
当未在代码中显式传递 `apiKey` 时，SDK 会自动从环境变量中读取。
资料来源：[packages/tools-ai-sdk/src/tools/resolve-library-id.ts:15-20](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/tools/resolve-library-id.ts)
---
## @upstash/context7-sdk 核心 API
### 初始化客户端
```typescript
import { Context7 } from "@upstash/context7-sdk";
const client = new Context7({
apiKey: "",
});
```
资料来源：[packages/sdk/README.md:45-50](https://github.com/upstash/context7/blob/main/packages/sdk/README.md)
### 数据类型
#### Library 接口
```typescript
export interface Library {
/** Context7 库 ID (如 "/facebook/react") */
id: string;
/** 库显示名称 */
name: string;
/** 库描述 */
description: string;
/** 可用的文档片段数量 */
totalSnippets: number;
/** 来源信誉评分 (0-10) */
trustScore: number;
/** 质量指标评分 (0-100) */
benchmarkScore: number;
/** 可用版本/标签 */
versions?: string[];
}
```
资料来源：[packages/sdk/src/commands/types.ts:1-35](https://github.com/upstash/context7/blob/main/packages/sdk/src/commands/types.ts)
#### Documentation 接口
```typescript
export interface Documentation {
/** 文档片段标题 */
title: string;
/** 文档内容 (可能包含 Markdown 格式的代码块) */
content: string;
/** 片段来源 URL 或标识符 */
source: string;
}
```
资料来源：[packages/sdk/src/commands/types.ts:37-50](https://github.com/upstash/context7/blob/main/packages/sdk/src/commands/types.ts)
### searchLibrary - 搜索库
搜索 Context7 数据库中的库。
```typescript
const libraries = await client.searchLibrary(
"I need to build a UI with components",
"react"
);
console.log(libraries[0].id); // "/facebook/react"
```
**参数说明：**
| 参数 | 类型 | 说明 |
|------|------|------|
| `query` | `string` | 用户查询，用于相关性排序 |
| `libraryName` | `string` | 库名称（可选） |
| `options.type` | `"json" \| "txt"` | 返回格式，默认 `"json"` |
**返回值：**
返回 `Library[]` 数组，每个库包含 `id`、`name`、`description`、`totalSnippets`、`trustScore`、`benchmarkScore`、`versions` 等字段。
资料来源：[packages/sdk/README.md:52-60](https://github.com/upstash/context7/blob/main/packages/sdk/README.md)
### getContext - 获取文档
根据查询获取相关文档。
```typescript
const docs = await client.getContext("How do I use hooks?", "/facebook/react");
console.log(docs[0].title, docs[0].content);
```
**参数说明：**
| 参数 | 类型 | 说明 |
|------|------|------|
| `query` | `string` | 用户问题 |
| `libraryId` | `string` | Context7 库 ID (格式: `/org/project`) |
| `options.type` | `"json" \| "txt"` | 返回格式，默认 `"json"` |
**返回值：**
返回 `Documentation[]` 数组，包含 `title`、`content`、`source` 字段。`content` 可能包含 Markdown 格式的代码块。
资料来源：[packages/sdk/README.md:62-68](https://github.com/upstash/context7/blob/main/packages/sdk/README.md)
---
## @upstash/context7-tools-ai-sdk AI SDK 工具
### 工具函数概览
| 函数名 | 用途 | 输入模式 |
|--------|------|----------|
| `resolveLibraryId()` | 将库名解析为 Context7 库 ID | `{ query: string, libraryName?: string }` |
| `queryDocs()` | 获取特定库的文档 | `{ libraryId: string, query: string }` |
资料来源：[packages/tools-ai-sdk/README.md:20-30](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/README.md)
### resolveLibraryId 工具
将库名解析为 Context7 兼容的库 ID。
```typescript
import { resolveLibraryId } from "@upstash/context7-tools-ai-sdk";
import { tool } from "ai";
const resolveTool = resolveLibraryId();
// 或带配置
const resolveToolWithConfig = resolveLibraryId({ apiKey: "your-key" });
```
**输入 Schema：**
| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `query` | `string` | 是 | 用户的原始问题，用于相关性排序 |
| `libraryName` | `string` | 否 | 要搜索的库名称 |
**返回示例：**
```json
{
"id": "/vercel/next.js",
"name": "Next.js",
"description": "The React Framework for Production",
"versions": ["v15.1.8", "v14.2.0"],
"benchmarkScore": 98
}
```
资料来源：[packages/tools-ai-sdk/src/tools/resolve-library-id.ts:1-60](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/tools/resolve-library-id.ts)
### queryDocs 工具
使用库 ID 获取文档。
```typescript
import { queryDocs } from "@upstash/context7-tools-ai-sdk";
const docsTool = queryDocs();
// 或带配置
const docsToolWithConfig = queryDocs({ apiKey: "your-key" });
```
**输入 Schema：**
| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `libraryId` | `string` | 是 | Context7 库 ID (如 `/mongodb/docs`) |
| `query` | `string` | 是 | 用户的完整问题 |
资料来源：[packages/tools-ai-sdk/src/tools/query-docs.ts:1-55](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/tools/query-docs.ts)
---
## 使用模式
### 与 generateText 配合使用
```typescript
import { resolveLibraryId, queryDocs } from "@upstash/context7-tools-ai-sdk";
import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";
const { text } = await generateText({
model: openai("gpt-4o"),
prompt: "How do I use React Server Components?",
tools: {
resolveLibraryId: resolveLibraryId(),
queryDocs: queryDocs(),
},
stopWhen: stepCountIs(5),
});
console.log(text);
```
资料来源：[packages/tools-ai-sdk/README.md:35-52](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/README.md)
### 使用 Context7Agent
提供预配置的代理，可直接用于 AI SDK 工作流。
```typescript
import { Context7Agent } from "@upstash/context7-tools-ai-sdk/agent";
```
代理遵循关键工作流程：
1. **始终** 首先调用 `resolveLibraryId` 获取库 ID
2. 从结果中选择**最佳匹配**库
3. 使用选中的库 ID 调用 `queryDocs`
4. 使用获取的文档回答用户问题
资料来源：[packages/tools-ai-sdk/src/prompts/system.ts:15-40](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/prompts/system.ts)
### 代理选择最佳库的依据
| 优先级 | 条件 |
|--------|------|
| 1 | 官方来源（如 React 的 `/reactjs/react.dev`） |
| 2 | 名称相似度 |
| 3 | 来源信誉（High/Medium 优先） |
| 4 | 代码片段覆盖率（越高越好） |
| 5 | Benchmark 评分（越高越好） |
资料来源：[packages/tools-ai-sdk/src/prompts/system.ts:25-35](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/prompts/system.ts)
---
## 工作流程图
```mermaid
sequenceDiagram
participant User as 用户
participant AI as AI 模型
participant Tools as Context7 Tools
participant SDK as Context7 SDK
participant API as Context7 API
User->>AI: 询问关于库的问题
AI->>Tools: resolveLibraryId(libraryName)
Tools->>SDK: searchLibrary()
SDK->>API: GET /search
API-->>SDK: 库列表
SDK-->>Tools: Library[]
Tools-->>AI: 库列表
AI->>AI: 选择最佳库
AI->>Tools: queryDocs(libraryId, query)
Tools->>SDK: getContext()
SDK->>API: GET /context
API-->>SDK: Documentation[]
SDK-->>Tools: Documentation[]
Tools-->>AI: 文档片段
AI-->>User: 基于文档的回答
```
---
## 配置选项
### Context7ToolsConfig
```typescript
interface Context7ToolsConfig {
/** API 密钥，如不提供则从环境变量读取 */
apiKey?: string;
}
```
### Context7AgentConfig
```typescript
interface Context7AgentConfig {
/** API 密钥，如不提供则从环境变量读取 */
apiKey?: string;
}
```
资料来源：[packages/tools-ai-sdk/src/tools/types.ts](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/tools/types.ts)
---
## 版本历史
### @upstash/context7-sdk
| 版本 | 变更 |
|------|------|
| 0.3.0 | 将 `searchLibrary` 和 `getContext` 的默认响应类型从 `"txt"` 改为 `"json"` |
| 0.2.0 | 简化 API：替换 `getDocs()` 为 `getContext()`，更新 `searchLibrary()` 参数 |
| 0.1.0 | 初始版本发布 |
资料来源：[packages/sdk/CHANGELOG.md:1-25](https://github.com/upstash/context7/blob/main/packages/sdk/CHANGELOG.md)
### @upstash/context7-tools-ai-sdk
| 版本 | 变更 |
|------|------|
| 0.2.3 | 改进 resolve library id 工具提示格式 |
| 0.2.2 | 将 zod 从 3.x 升级到 4.x |
| 0.2.1 | 升级 ai 依赖到 >=6.0.0，兼容 AI SDK v6 |
| 0.2.0 | 工具重命名以匹配 MCP 命名约定；SDK 默认响应类型改为 JSON |
| 0.1.0 | 初始版本发布 |
资料来源：[packages/tools-ai-sdk/CHANGELOG.md:1-40](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/CHANGELOG.md)
---
## 常见问题与故障排除
### API 密钥配置
**问题：** 工具返回认证错误
**解决方案：** 确保设置 `CONTEXT7_API_KEY` 环境变量，或在初始化时显式传递：
```typescript
const client = new Context7({ apiKey: "your-key" });
// 或
const tool = resolveLibraryId({ apiKey: "your-key" });
```
### 库 ID 格式
**问题：** `queryDocs` 返回空结果
**解决方案：** 确保使用正确的库 ID 格式 `/org/project`，例如：
- ✅ `/facebook/react`
- ✅ `/vercel/next.js`
- ❌ `react` 或 `facebook/react`
### 响应格式选择
**问题：** 需要文本格式而非 JSON
**解决方案：** 显式指定 `type: "txt"`：
```typescript
const docs = await client.getContext(query, libraryId, { type: "txt" });
const libraries = await client.searchLibrary(query, name, { type: "txt" });
```
### 速率限制
AI SDK 工具描述中包含速率限制指导，详情参见工具的 `description` 字段。
资料来源：[packages/tools-ai-sdk/src/tools/query-docs.ts:15-20](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/tools/query-docs.ts)
---
## 导出清单
### @upstash/context7-sdk 导出
```typescript
// 主入口
export { Context7 };
// 类型
export type { Context7Config, Library, Documentation, GetContextOptions, SearchLibraryOptions };
```
### @upstash/context7-tools-ai-sdk 导出
```typescript
// 主入口
export { resolveLibraryId, queryDocs } from "./tools";
// Agent
export { Context7Agent } from "./agents/context7";
// 类型
export type { Context7ToolsConfig, Context7AgentConfig };
```
资料来源：[packages/tools-ai-sdk/src/index.ts](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/index.ts)
---
## 相关链接
| 资源 | 链接 |
|------|------|
| Context7 官网 | https://context7.com |
| SDK 官方文档 | https://github.com/upstash/context7#readme |
| Claude Code 插件 | [plugins/claude/context7/README.md](https://github.com/upstash/context7/blob/main/plugins/claude/context7/README.md) |
| MCP 服务器 | [packages/mcp/README.md](https://github.com/upstash/context7/blob/main/packages/mcp/README.md) |
| CLI 工具 | [packages/cli/README.md](https://github.com/upstash/context7/blob/main/packages/cli/README.md) |
---
## See Also
- [MCP 服务器集成](./mcp-server.md) - 如何将 Context7 MCP 工具与 AI 应用集成
- [CLI 工具](./cli-usage.md) - 使用 ctx7 命令行工具
- [Claude Code 插件](./claude-code-plugin.md) - 在 Claude Code 中使用 Context7
- [PI Coding Agent 集成](./pi-integration.md) - Context7 PI 扩展
---
## AI 编码助手集成
### 相关页面
相关主题：[概述与快速入门](#page-1), [CLI 参考指南](#page-2)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/cli/src/setup/agents.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/setup/agents.ts)
- [packages/cli/src/setup/templates.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/setup/templates.ts)
- [plugins/claude/context7/README.md](https://github.com/upstash/context7/blob/main/plugins/claude/context7/README.md)
- [plugins/claude/context7/agents/docs-researcher.md](https://github.com/upstash/context7/blob/main/plugins/claude/context7/agents/docs-researcher.md)
- [plugins/claude/context7/skills/context7-mcp/SKILL.md](https://github.com/upstash/context7/blob/main/plugins/claude/context7/skills/context7-mcp/SKILL.md)
- [plugins/cursor/context7/skills/context7-mcp/SKILL.md](https://github.com/upstash/context7/blob/main/plugins/cursor/context7/skills/context7-mcp/SKILL.md)
- [plugins/context7-power/POWER.md](https://github.com/upstash/context7/blob/main/plugins/context7-power/POWER.md)
- [packages/mcp/src/index.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts)
- [packages/tools-ai-sdk/README.md](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/README.md)
- [packages/tools-ai-sdk/src/prompts/system.ts](https://github.com/upstash/context7/blob/main/packages/tools-ai-sdk/src/prompts/system.ts)
- [packages/pi/skills/context7-docs/SKILL.md](https://github.com/upstash/context7/blob/main/packages/pi/skills/context7-docs/SKILL.md)
- [skills/context7-mcp/SKILL.md](https://github.com/upstash/context7/blob/main/skills/context7-mcp/SKILL.md)
- [skills/context7-cli/SKILL.md](https://github.com/upstash/context7/blob/main/skills/context7-cli/SKILL.md)
# AI 编码助手集成
## 概述
Context7 提供与多种 AI 编码助手的深度集成，使这些助手能够在对话过程中自动获取最新的库文档和代码示例。通过 Context7，AI 助手可以访问来自源代码仓库的实时、准确的文档信息，有效解决 LLM 训练数据过时和幻觉 API 的问题。 资料来源：[plugins/claude/context7/README.md:1-5]()
Context7 支持两种集成模式：
| 集成模式 | 描述 | 适用场景 |
|---------|------|---------|
| **MCP (Model Context Protocol)** | 注册 Context7 MCP 服务器，使 AI 助手可以原生调用文档查询工具 | 支持 MCP 协议的编码助手 |
| **CLI + Skills** | 安装技能指南，引导代理使用 `ctx7` CLI 命令获取文档 | 不支持 MCP 的编码助手 |
## 工作流程
Context7 集成的核心工作流程遵循标准的文档检索模式：
```mermaid
graph TD
A[用户提问关于某库/框架] --> B[resolve-library-id 解析库标识符]
B --> C{库 ID 已提供?}
C -->|是| D[直接使用提供的库 ID]
C -->|否| E[从解析结果中选择最佳匹配]
E --> F[query-docs 查询文档]
D --> F
F --> G[返回文档片段和代码示例]
G --> H[AI 助手基于最新文档回答]
B -.->|返回| I[库 ID、名称、版本、质量分数]
F -.->|返回| J[相关文档片段、代码示例、出处]
```
**关键步骤说明：**
1. **解析库标识符** - 使用 `resolve-library-id` 工具搜索 Context7 数据库，获取匹配的库 ID、版本信息和质量评分
2. **选择最佳匹配** - 根据官方来源、名称相似度、基准分数等因素选择最合适的库
3. **查询文档** - 使用 `query-docs` 工具获取与用户问题相关的文档片段和代码示例
4. **生成回答** - AI 助手基于获取的最新文档生成准确的回答
资料来源：[plugins/claude/context7/agents/docs-researcher.md:1-30]()
## 支持的 AI 编码助手
### MCP 服务器模式
MCP 模式通过 Model Context Protocol 实现与编码助手的集成，支持以下助手：
| 编码助手 | 插件/配置位置 | MCP 支持状态 |
|---------|--------------|-------------|
| **Claude Code** | `plugins/claude/context7/` | ✅ 完整支持 |
| **Cursor** | `plugins/cursor/context7/` | ✅ 完整支持 |
| **OpenCode** | `plugins/opencode/context7/` | ✅ 完整支持 |
| **Codex** | `packages/cli/src/setup/agents.ts` | ✅ 完整支持 |
| **Gemini CLI** | `packages/cli/src/setup/agents.ts` | ✅ 完整支持 |
| **Windsurf** | `packages/cli/src/setup/agents.ts` | ✅ 完整支持 |
| **Pi** | `packages/pi/` | ✅ 完整支持 |
### CLI + Skills 模式
对于不支持 MCP 协议的编码助手，Context7 提供了 CLI + Skills 模式，通过技能文件引导代理使用命令行工具：
```mermaid
graph LR
A[AI 代理] -->|读取技能文件| B[context7-cli Skill]
B -->|指导| C[使用 ctx7 CLI 命令]
C -->|执行| D[ctx7 query <库名> <问题>]
D -->|返回| E[文档结果]
E -->|解析| A
```
资料来源：[skills/context7-cli/SKILL.md:1-20]()
## Claude Code 集成详解
### 插件结构
Claude Code 插件位于 `plugins/claude/context7/`，包含以下组件：
| 组件 | 文件路径 | 功能描述 |
|-----|---------|---------|
| **MCP 服务器** | `.claude-plugin/` | 注册 `resolve-library-id` 和 `query-docs` 工具 |
| **技能** | `skills/context7-mcp/SKILL.md` | 自动触发文档查询的工作流指导 |
| **代理** | `agents/docs-researcher.md` | 专门的文档研究代理 |
| **命令** | - | `/context7:docs` 手动文档查询命令 |
### 安装方式
通过 Claude Code 插件市场安装：
```bash
claude plugin marketplace add upstash/context7
claude plugin install context7-plugin@context7-marketplace
```
资料来源：[plugins/claude/context7/README.md:15-20]()
### 文档研究员代理
`docs-researcher` 是一个轻量级代理，专门用于获取库文档而不污染主要对话上下文：
```markdown
---
name: docs-researcher
description: Lightweight agent for fetching library documentation...
model: sonnet
---
You are a documentation researcher specializing in fetching
up-to-date library and framework documentation from Context7.
```
代理遵循以下工作流程：
1. 从用户问题中识别目标库
2. 调用 `resolve-library-id` 解析库 ID
3. 根据名称匹配度、基准分数选择最佳库
4. 调用 `query-docs` 获取文档
5. 返回聚焦的回答和代码示例
资料来源：[plugins/claude/context7/agents/docs-researcher.md:1-40]()
## Cursor 集成详解
### 插件结构
Cursor 插件位于 `plugins/cursor/context7/`，提供与 Claude Code 相似的功能：
| 组件 | 文件路径 | 功能描述 |
|-----|---------|---------|
| **MCP 配置** | `.cursor/plugin.json` | Cursor 的 MCP 服务器配置 |
| **技能** | `skills/context7-mcp/SKILL.md` | 自动文档查询工作流 |
### 工作流程
```mermaid
graph TD
A[用户在 Cursor 中提问] --> B{Cursor 检测到库/框架请求}
B -->|是| C[激活 context7-mcp 技能]
C --> D[调用 resolve-library-id]
D --> E[显示匹配的库列表]
E --> F[AI 自动选择最佳匹配]
F --> G[调用 query-docs]
G --> H[获取文档片段]
H --> I[生成基于文档的回答]
B -->|否| J[常规对话处理]
```
Cursor 的 `docs-researcher` 代理与 Claude Code 版本功能一致，专门用于聚焦的文档检索任务。
资料来源：[plugins/cursor/context7/skills/context7-mcp/SKILL.md:1-25]()
## AI SDK 集成
### @upstash/context7-tools-ai-sdk
`@upstash/context7-tools-ai-sdk` 包提供了与 [Vercel AI SDK](https://ai-sdk.dev/) 兼容的工具和代理：
```typescript
import { resolveLibrary, getLibraryDocs } from "@upstash/context7-tools-ai-sdk";
import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";
const { text } = await generateText({
model: openai("gpt-4o"),
prompt: "How do I use React Server Components?",
tools: {
resolveLibrary: resolveLibrary(),
getLibraryDocs: getLibraryDocs(),
},
stopWhen: stepCountIs(5),
});
```
资料来源：[packages/tools-ai-sdk/README.md:20-35]()
### 提供的工具
| 工具名称 | 功能 | 参数 |
|---------|------|------|
| `resolveLibrary` | 搜索 Context7 数据库查找正确的库 ID | `libraryName`: 库名称 |
| `getLibraryDocs` | 获取特定库的文档，支持主题过滤 | `libraryId`, `query` |
### AI SDK 代理
包还提供了预配置的 `Context7Agent`，用于创建文档感知的代理：
```typescript
import { Context7Agent } from "@upstash/context7-tools-ai-sdk";
```
资料来源：[packages/tools-ai-sdk/README.md:35-45]()
### 系统提示词
AI SDK 包内置了专门设计的系统提示词：
```typescript
export const AGENT_PROMPT = `You are a documentation search assistant powered by Context7.
CRITICAL WORKFLOW - YOU MUST FOLLOW THESE STEPS:
Step 1: ALWAYS start by calling 'resolveLibraryId' with the library name...
Step 2: Analyze the results and select the BEST library ID...
Step 3: Call 'queryDocs' with the selected library ID...
Step 4: Provide a clear answer with code examples...`;
```
资料来源：[packages/tools-ai-sdk/src/prompts/system.ts:1-30]()
## MCP 服务器集成
### 服务器工具
Context7 MCP 服务器注册了两个核心工具：
#### resolve-library-id
**功能**：将包/产品名称解析为 Context7 兼容的库 ID
**输入参数**：
| 参数 | 类型 | 必需 | 描述 |
|-----|------|-----|------|
| `libraryName` | string | 是 | 要搜索的库名称 |
| `query` | string | 是 | 用户的完整问题（提高相关性排名） |
**返回结果**：
```json
{
"id": "/vercel/next.js",
"name": "Next.js",
"versions": ["v15.1.8", "v14.2.0"],
"description": "...",
"totalSnippets": 1234,
"trustScore": 0.95
}
```
#### query-docs
**功能**：获取特定库的文档，按与问题的相关性排名
**输入参数**：
| 参数 | 类型 | 必需 | 描述 |
|-----|------|-----|------|
| `libraryId` | string | 是 | Context7 兼容的库 ID（如 `/mongodb/docs`、`/vercel/next.js`） |
| `query` | string | 是 | 用于获取相关文档的问题或任务 |
资料来源：[packages/mcp/src/index.ts:50-100]()
### 服务器配置
MCP 服务器的默认配置：
```json
{
"name": "Context7",
"version": "0.x.x",
"websiteUrl": "https://context7.com",
"description": "Context7 provides up-to-date documentation and code examples..."
}
```
资料来源：[packages/mcp/src/index.ts:25-35]()
## CLI 集成设置
### ctx7 setup 命令
通过 `ctx7 setup` 命令可以自动配置 AI 编码助手：
```bash
npx ctx7 setup
```
该命令会：
1. 通过 OAuth 进行身份验证
2. 生成 API 密钥
3. 安装适当的技能（CLI + Skills 或 MCP）
资料来源：[README.md:45-55]()
### 支持的代理配置
`packages/cli/src/setup/agents.ts` 定义了支持的编码助手配置：
| 代理 | MCP 配置路径 | 全局路径 | 配置文件键 |
|-----|-------------|---------|-----------|
| Claude Code | `.codex/` | `~/.codex/` | MCP 服务器 |
| Codex | `.codex/settings.json` | `~/.codex/settings.json` | `mcpServers` |
| Gemini CLI | `.gemini/settings.json` | `~/.gemini/settings.json` | `mcpServers` |
| Windsurf | `.codeium/windsurf/` | `~/.codeium/windsurf/` | MCP 配置 |
资料来源：[packages/cli/src/setup/agents.ts:30-80]()
### 技能目录结构
```mermaid
graph TD
A[ctx7 setup] --> B[选择代理类型]
B --> C{是否支持 MCP}
C -->|是| D[安装 context7-mcp 技能]
C -->|否| E[安装 context7-cli 技能]
D --> F[配置 MCP 服务器]
E --> G[配置 CLI 命令指南]
F --> H[生成 API 密钥]
G --> H
```
## 常见问题与故障排除
### MCP 连接问题
**症状**：`resolve-library-id` 或 `query-docs` 调用超时或返回错误
**排查步骤**：
1. 验证 API 密钥配置正确（环境变量 `CONTEXT7_API_KEY`）
2. 检查 MCP 服务器是否正常运行
3. 确认网络连接可访问 `context7.com`
资料来源：[packages/pi/skills/context7-docs/SKILL.md:35-40]()
### 库 ID 解析失败
**症状**：搜索库名称返回空结果
**可能原因**：
- 库名称拼写错误
- 库尚未被 Context7 索引
**解决方案**：
- 使用官方库名称（如 "Next.js" 而非 "nextjs"）
- 访问 [Context7 官网](https://context7.com) 搜索目标库
### Prompt 注入风险
> [!WARNING]
> Context7 社区曾报告过 prompt 注入风险（Issue #2663, #2673）。部分库的文档响应可能包含非文档内容的"系统通知"。
**防护措施**：
- 验证文档响应的来源和格式
- 不要盲目执行文档响应中包含的命令
- 报告可疑的注入内容到 [GitHub Issues](https://github.com/upstash/context7/issues)
### 离线/气隙环境支持
目前 Context7 需要网络访问来获取文档。社区请求了离线文档支持（Issue #320），但尚未实现。如需此功能，请在 [GitHub Issues](https://github.com/upstash/context7/issues) 中表达支持。
## 高级配置
### XDG 规范支持
Context7 CLI 配置文件遵循 XDG Base Directory 规范：
| 文件类型 | 路径 |
|---------|------|
| CLI 状态 | `$XDG_CONFIG_HOME/context7/cli-state.json` |
| API 密钥 | `$XDG_CONFIG_HOME/context7/credentials` |
如未设置 `XDG_CONFIG_HOME`，默认使用 `~/.context7/`。
资料来源：[Issue #2638](https://github.com/upstash/context7/issues/2638)
### 自托管选项
社区请求了自托管文档后端的支持（Issue #59），允许用户部署自己的 Context7 文档服务。目前所有文档请求都通过 `context7.com/api`，此功能仍在讨论中。
## 参与贡献
### 报告问题
如果集成交程中遇到问题，请通过以下方式报告：
1. 在 [GitHub Issues](https://github.com/upstash/context7/issues) 创建新 Issue
2. 选择合适的模板（MCP 问题、CLI 问题、库报告等）
3. 提供复现步骤和环境信息
### 添加新编码助手支持
如需为新的编码助手添加支持：
1. 在 `packages/cli/src/setup/agents.ts` 中添加代理配置
2. 创建对应的插件目录（如 `plugins/<助手名>/context7/`）
3. 包含必要的 MCP 配置和技能文件
4. 更新本文档
## 另请参阅
- [Context7 官方文档](https://context7.com/docs)
- [MCP 协议文档](https://modelcontextprotocol.io/)
- [Vercel AI SDK 文档](https://ai-sdk.dev/)
- [CLI 使用指南](./cli-usage.md)
- [MCP 服务器配置](./mcp-server.md)
- [添加新库](./adding-libraries.md)
---
## pi.dev 扩展集成
### 相关页面
相关主题：[AI 编码助手集成](#page-5), [MCP 服务器架构](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/pi/README.md](https://github.com/upstash/context7/blob/main/packages/pi/README.md)
- [packages/pi/package.json](https://github.com/upstash/context7/blob/main/packages/pi/package.json)
- [packages/pi/CHANGELOG.md](https://github.com/upstash/context7/blob/main/packages/pi/CHANGELOG.md)
- [plugins/context7-power/POWER.md](https://github.com/upstash/context7/blob/main/plugins/context7-power/POWER.md)
- [packages/pi/lib/tools/query-docs.ts](https://github.com/upstash/context7/blob/main/packages/pi/lib/tools/query-docs.ts)
- [packages/pi/lib/tools/resolve-library-id.ts](https://github.com/upstash/context7/blob/main/packages/pi/lib/tools/resolve-library-id.ts)
- [packages/pi/prompts/c7-docs.md](https://github.com/upstash/context7/blob/main/packages/pi/prompts/c7-docs.md)
- [packages/pi/skills/context7-docs/SKILL.md](https://github.com/upstash/context7/blob/main/packages/pi/skills/context7-docs/SKILL.md)
# pi.dev 扩展集成
## 概述
`@upstash/context7-pi` 是 Context7 官方为 [pi coding agent](https://pi.dev) 提供的扩展集成包。该扩展使 pi 代理能够通过调用 Context7 的文档检索工具，获取最新的库文档、API 参考和代码示例。
资料来源：[packages/pi/README.md:1-8]()
### 核心功能
该扩展为 pi 代理添加了以下能力：
| 功能类型 | 名称 | 说明 |
|---------|------|------|
| 工具 | `resolve-library-id` | 将包/产品名称转换为 Context7 库 ID |
| 工具 | `query-docs` | 根据解析的库 ID 获取文档和代码示例 |
| 技能 | `context7-docs` | 指导代理何时使用文档检索工具 |
| 命令 | `/c7-docs` | 手动执行文档查询的斜杠命令 |
资料来源：[packages/pi/README.md:21-26]()
### 版本历史
| 版本 | 发布类型 | 变更说明 |
|------|----------|----------|
| 0.1.0 | 初始版本 | 正式发布，支持 resolve-library-id 和 query-docs 工具，集成 context7-docs 技能，暴露 /c7-docs 斜杠命令 |
资料来源：[packages/pi/CHANGELOG.md](https://github.com/upstash/context7/blob/main/packages/pi/CHANGELOG.md)
## 安装与配置
### 安装步骤
使用 npm 安装 Context7 扩展包：
```bash
pi install npm:@upstash/context7-pi
```
资料来源：[packages/pi/README.md:10]()
### 身份验证
扩展包在无需认证的情况下即可使用，系统将基于 IP 进行速率限制。如需更高的配额限制，需从 [context7.com/dashboard](https://context7.com/dashboard) 获取免费 API 密钥，并将其导出为环境变量：
```bash
export CONTEXT7_API_KEY=ctx7sk_...
```
资料来源：[packages/pi/README.md:12-18]()
建议将环境变量配置在 shell 启动文件（如 `.bashrc` 或 `.zshrc`）中，以确保 pi 每次启动时都能读取到密钥。
## 架构设计
### 组件交互流程
```mermaid
graph TD
A[用户提问] --> B{pi agent}
B --> C[context7-docs skill]
C --> D[resolve-library-id 工具]
D --> E[Context7 API]
E --> F[库 ID 列表]
F --> G[query-docs 工具]
G --> E
E --> H[相关文档片段]
H --> I[pi agent 回答]
I --> J[用户获得答案]
subgraph "手动命令模式"
K[/c7-docs 命令] --> L[resolve-library-id]
L --> M[query-docs]
M --> N[返回结果]
end
```
### 工具说明
#### resolve-library-id 工具
`resolve-library-id` 工具用于将包或产品名称解析为 Context7 兼容的库标识符。
**输入参数：**
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `libraryName` | string | 是 | 要搜索的库名称 |
| `query` | string | 是 | 用户的完整问题，用于相关性排序 |
**输出示例：**
```json
{
"id": "/vercel/next.js",
"name": "Next.js",
"versions": ["v15.1.8", "v14.2.0", ...],
"description": "The React Framework for the Web"
}
```
资料来源：[packages/pi/lib/tools/resolve-library-id.ts](https://github.com/upstash/context7/blob/main/packages/pi/lib/tools/resolve-library-id.ts)
#### query-docs 工具
`query-docs` 工具根据 Context7 兼容的库 ID 获取文档内容。
**输入参数：**
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `libraryId` | string | 是 | 精确的 Context7 库 ID（如 `/mongodb/docs`、`/vercel/next.js`） |
| `query` | string | 是 | 用于获取相关文档的问题或任务描述 |
**输出内容：**
返回与查询相关的文档片段，包含代码示例和 API 参考信息。
资料来源：[packages/pi/lib/tools/query-docs.ts](https://github.com/upstash/context7/blob/main/packages/pi/lib/tools/query-docs.ts)
## 使用方式
### 自动模式
安装扩展后，当用户向 pi 代理询问关于库、框架、SDK、API、CLI 工具或云服务的问题时，代理会自动调用相关工具获取最新文档。
**适用场景：**
- API 语法和配置问题
- 版本迁移指导
- 库特定的调试帮助
- 设置说明和安装指南
- CLI 工具使用方法
**示例问题：**
```
如何配置 Next.js 15 的身份验证？
如何在 React 中使用 Server Components？
Prisma 中关系定义的标准语法是什么？
```
资料来源：[plugins/context7-power/POWER.md:16-25]()
### 手动命令模式
使用 `/c7-docs` 斜杠命令手动触发文档查询：
```
/c7-docs <库名称> <问题>
```
**使用示例：**
```
/c7-docs next.js 如何设置中间件
/c7-docs react useEffect 的最佳实践
```
资料来源：[packages/pi/README.md:35-36]()
## 技能系统
### context7-docs 技能
`context7-docs` 技能是指示 pi 代理何时以及如何使用 Context7 文档工具的指导文件。技能内容包含：
1. **触发条件**：指导代理在用户询问库、框架、SDK、API、CLI 工具或云服务时主动使用 Context7
2. **工具调用流程**：明确两阶段调用顺序（先 resolve-library-id，后 query-docs）
3. **选择策略**：如何从多个匹配结果中选择最合适的库
资料来源：[packages/pi/skills/context7-docs/SKILL.md](https://github.com/upstash/context7/blob/main/packages/pi/skills/context7-docs/SKILL.md)
### 技能配置参数
| 参数 | 说明 |
|------|------|
| `libraryName` | 库名称提取自用户问题 |
| `query` | 用户的完整问题（提高相关性排名） |
## 工作流程详解
### 标准文档查询流程
```mermaid
sequenceDiagram
participant U as 用户
participant P as pi agent
participant S as context7-docs skill
participant R as resolve-library-id
participant Q as query-docs
participant C as Context7 API
U->>P: 询问库相关问题
P->>S: 检查技能触发条件
S-->>P: 确认需要使用 Context7
P->>R: 调用 resolve-library-id
R->>C: 查询库 ID
C-->>R: 返回匹配列表
R-->>P: 返回库信息
P->>Q: 选择最佳匹配，调用 query-docs
Q->>C: 查询文档
C-->>Q: 返回相关文档片段
Q-->>P: 返回文档内容
P->>U: 基于文档生成回答
```
### 库选择策略
当 `resolve-library-id` 返回多个匹配结果时，应按以下优先级进行选择：
| 优先级 | 条件 | 说明 |
|--------|------|------|
| 1 | 精确名称匹配 | 与用户询问的库名称完全或最接近匹配 |
| 2 | 描述相关性 | 描述内容与用户需求的相关程度 |
| 3 | 代码片段数量 | 包含更多代码示例的库优先 |
| 4 | 源代码声誉 | 优先选择官方/主要的包而非社区分支 |
| 5 | 基准评分 | 评分越高越可靠 |
资料来源：[packages/pi/prompts/c7-docs.md](https://github.com/upstash/context7/blob/main/packages/pi/prompts/c7-docs.md)
## 速率限制与配额
### 认证模式
| 模式 | 限制类型 | 说明 |
|------|----------|------|
| 无认证 | 基于 IP | 适用于尝鲜和测试 |
| API Key | 基于配额 | 在 [context7.com/dashboard](https://context7.com/dashboard) 注册获取更高配额 |
资料来源：[packages/pi/README.md:12-18]()
### 常见错误处理
| 错误类型 | 可能原因 | 解决方案 |
|----------|----------|----------|
| 429 Rate Limited | 请求频率超出限制 | 减少请求频率或升级 API Key |
| 401 Unauthorized | API Key 无效或过期 | 检查 CONTEXT7_API_KEY 环境变量 |
| 404 Library Not Found | 库 ID 不存在 | 使用 resolve-library-id 重新搜索正确 ID |
## 与其他 MCP 客户端的兼容性
Context7 为多种编码代理提供官方扩展支持，包括：
| 客户端/代理 | 集成方式 | 主要工具 |
|-------------|----------|----------|
| **pi (pi.dev)** | @upstash/context7-pi | resolve-library-id, query-docs |
| Claude Code | MCP Server + Skill | resolve-library-id, query-docs |
| Cursor | MCP Server + Agent | resolve-library-id, query-docs |
| Vercel AI SDK | @upstash/context7-tools-ai-sdk | resolveLibrary, getLibraryDocs |
所有客户端的工具描述、错误消息格式和线缆协议保持一致，确保 LLM 能够获得统一的体验。
资料来源：[packages/pi/CHANGELOG.md](https://github.com/upstash/context7/blob/main/packages/pi/CHANGELOG.md)
## 隐私与安全
- Context7 扩展遵循 Context7 的[隐私政策](https://upstash.com/trust/context7addendum.pdf)
- API 请求通过 HTTPS 加密传输
- 建议通过 `CONTEXT7_API_KEY` 环境变量配置认证信息，避免硬编码
资料来源：[plugins/context7-power/POWER.md:49-51]()
## 故障排除
### 常见问题
**Q: 扩展安装后没有响应？**
1. 确认 pi 重启后已加载扩展
2. 检查环境变量 `CONTEXT7_API_KEY` 是否正确设置
3. 查看 pi 日志中的错误信息
**Q: 文档查询返回空结果？**
1. 确认库名称拼写正确
2. 尝试使用更通用的搜索词
3. 某些新加入的库可能需要等待索引更新
**Q: 如何验证 API Key 配置？**
目前版本暂无 `--dry-run` 配置验证标志。如遇配置问题，请访问 [context7.com/dashboard](https://context7.com/dashboard) 检查 Key 状态。
## 相关资源
- [Context7 官方文档](https://context7.com/docs)
- [pi coding agent 官网](https://pi.dev)
- [@upstash/context7-pi 发布说明](https://github.com/upstash/context7/releases/tag/%40upstash%2Fcontext7-pi%400.1.0)
- [Context7 客户端列表](https://context7.com/docs/resources/all-clients)
## 参见
- [MCP 服务器配置](./mcp-server-configuration)
- [CLI 安装指南](./cli-installation)
- [Vercel AI SDK 集成](./ai-sdk-integration)
- [库添加指南](./adding-libraries)
---
## 多客户端配置参考
### 相关页面
相关主题：[AI 编码助手集成](#page-5), [MCP 服务器架构](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/resources/all-clients.mdx](https://github.com/upstash/context7/blob/main/docs/resources/all-clients.mdx)
- [packages/mcp/mcpb/context7.mcpb](https://github.com/upstash/context7/blob/main/packages/mcp/mcpb/context7.mcpb)
- [packages/mcp/smithery.yaml](https://github.com/upstash/context7/blob/main/packages/mcp/smithery.yaml)
- [plugins/context7-power/mcp.json](https://github.com/upstash/context7/blob/main/plugins/context7-power/mcp.json)
- [plugins/claude/context7/.mcp.json](https://github.com/upstash/context7/blob/main/plugins/claude/context7/.mcp.json)
- [plugins/cursor/context7/mcp.json](https://github.com/upstash/context7/blob/main/plugins/cursor/context7/mcp.json)
- [packages/mcp/src/index.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts)
- [packages/cli/src/setup/agents.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/setup/agents.ts)
# 多客户端配置参考
本文档详细介绍 Context7 如何与各种 AI 编码助手和客户端集成，涵盖配置方法、认证机制以及工具注册流程。
## 概述
Context7 通过 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 提供统一的文档查询能力，支持 30+ 种不同的 AI 编码客户端。系统设计采用双模式架构：
- **CLI + Skills 模式**：通过 `ctx7` 命令行工具和安装的技能引导代理获取文档（无需 MCP）
- **MCP 模式**：注册 Context7 MCP 服务器，使代理可以直接调用文档工具
资料来源：[README.md:1-30](https://github.com/upstash/context7/blob/main/README.md)
## 支持的客户端
### 官方集成客户端
| 客户端 | 类型 | 安装方式 | 配置文件位置 |
|--------|------|----------|--------------|
| Claude Code | 代理式 IDE | `claude plugin install` | `~/.claude.json` 或项目 `.mcp.json` |
| Cursor | AI 代码编辑器 | 插件市场 | `.cursor/mcp.json` |
| pi | 编码代理 | `pi install` | 自动配置 |
| Gemini CLI | Google CLI | `ctx7 setup` | `.gemini/settings.json` |
| Codex | OpenAI CLI | `ctx7 setup` | `.codex/AGENTS.md` |
### MCP 协议兼容客户端
通过标准 MCP 配置，以下客户端均可使用 Context7：
| 客户端 | 配置文件 | 说明 |
|--------|----------|------|
| VS Code (Cline) | `.vscode/mcp.json` | VS Code MCP 扩展 |
| Zed | `~/.config/zed/mcp.json` | Zed 编辑器 |
| Smithery | smithery.yaml | MCP 客户端市场 |
| Continue | `continue/config.json` | VS Code/JetBrains 扩展 |
资料来源：[docs/resources/all-clients.mdx](https://github.com/upstash/context7/blob/main/docs/resources/all-clients.mdx)
## MCP 工具接口
Context7 MCP 服务器提供两个核心工具：
### resolve-library-id
解析包名或产品名为 Context7 兼容的库 ID。
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `libraryName` | string | 是 | 要搜索的库名称 |
| `query` | string | 是 | 用于相关性排序的用户问题 |
**返回结果**：
```json
{
"libraries": [{
"id": "/vercel/next.js",
"name": "Next.js",
"description": "The React Framework for the Web",
"totalSnippets": 2847,
"versions": ["v15.1.8", "v14.2.0"]
}]
}
```
### query-docs
根据已解析的库 ID 查询文档。
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `libraryId` | string | 是 | Context7 库 ID（如 `/vercel/next.js`） |
| `query` | string | 是 | 用户的问题，用于相关性排序 |
资料来源：[packages/mcp/src/index.ts:30-80](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts)
## 配置架构
```mermaid
graph TD
A[用户运行 ctx7 setup] --> B{选择模式}
B -->|CLI + Skills| C[安装 Skill 文件]
B -->|MCP| D[生成 MCP 配置文件]
C --> E[代理识别用户问题]
D --> F[MCP 服务器启动]
E --> G[执行 ctx7 命令]
F --> H[MCP 工具调用]
G --> I[resolve-library-id]
H --> I
I --> J[query-docs]
J --> K[返回文档内容]
```
### 代理检测机制
CLI 安装过程会自动检测当前开发环境支持的客户端：
```typescript
const AGENT_CONFIGS = {
claude: {
name: "claude",
displayName: "Claude Code",
detect: {
projectPaths: [".claude"],
globalPaths: [join(homedir(), ".claude")],
},
mcp: {
projectPaths: [".mcp.json"],
globalPaths: [join(homedir(), ".claude.json")],
}
},
cursor: {
name: "cursor",
displayName: "Cursor",
detect: {
projectPaths: [".cursor"],
globalPaths: [join(homedir(), ".cursor")],
}
}
};
```
资料来源：[packages/cli/src/setup/agents.ts:1-60](https://github.com/upstash/context7/blob/main/packages/cli/src/setup/agents.ts)
## 各客户端配置详解
### Claude Code 配置
Claude Code 通过插件系统集成 Context7：
```bash
# 添加市场并安装插件
claude plugin marketplace add upstash/context7
claude plugin install context7-plugin@context7-marketplace
```
**MCP 配置示例**（`.mcp.json`）：
```json
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"],
"env": {
"CONTEXT7_API_KEY": "ctx7sk_..."
}
}
}
}
```
资料来源：[plugins/claude/context7/.mcp.json](https://github.com/upstash/context7/blob/main/plugins/claude/context7/.mcp.json)
**可用资源**：
- **agents/docs-researcher.md**：轻量级代理，用于获取库文档
- **Skills**：自动触发文档查找的技能文件
### Cursor 配置
Cursor 使用标准的 MCP 配置文件：
```json
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"],
"env": {
"CONTEXT7_API_KEY": "ctx7sk_..."
}
}
}
}
```
资料来源：[plugins/cursor/context7/mcp.json](https://github.com/upstash/context7/blob/main/plugins/cursor/context7/mcp.json)
### pi 代理配置
pi 是 Context7 官方支持的编码代理：
```bash
# 安装
pi install npm:@upstash/context7-pi
# 认证（可选，用于更高配额）
export CONTEXT7_API_KEY=ctx7sk_...
```
**注册的工具**：
- `resolve-library-id` - 库 ID 解析
- `query-docs` - 文档查询
- `context7-docs` skill - 技能指导
- `/c7-docs` 斜杠命令
资料来源：[packages/pi/README.md](https://github.com/upstash/context7/blob/main/packages/pi/README.md)
### Smithery 配置
Smithery 是一个 MCP 客户端市场，支持一键安装：
```yaml
# smithery.yaml
name: Context7
packageUrl: npm:@upstash/context7-mcp
installationCommand: npx -y @upstash/context7-mcp
```
资料来源：[packages/mcp/smithery.yaml](https://github.com/upstash/context7/blob/main/packages/mcp/smithery.yaml)
### Power 模式配置
Context7 提供专门的 Power 插件：
```json
{
"name": "context7",
"displayName": "Context7",
"description": "Find up-to-date documentation, API references, and code examples for libraries, frameworks, SDKs, and developer tools using Context7."
}
```
**使用场景**：
- 用户询问库的设置或配置问题
- 请求涉及特定库或框架的代码
- 需要 API 参考或当前文档
- 版本迁移、库特定调试或 CLI 使用
资料来源：[plugins/context7-power/POWER.md](https://github.com/upstash/context7/blob/main/plugins/context7-power/POWER.md)
## 认证机制
### API Key 配置
```bash
# 方式 1：环境变量
export CONTEXT7_API_KEY=ctx7sk_xxxxxxxxxxxx
# 方式 2：CLI 交互式认证
npx ctx7 setup
```
### 无认证使用
Context7 支持无 API Key 使用，采用 IP 限流：
- 无认证：标准 IP 限流
- 有 API Key：更高配额
```typescript
// MCP 服务器认证处理
const auth = {
type: "bearer",
token: process.env.CONTEXT7_API_KEY || ""
};
```
资料来源：[packages/mcp/src/index.ts:1-30](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts)
## 工具描述与指令
MCP 服务器会返回详细的工具描述和系统指令：
```typescript
instructions: `Use this server to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot.
Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.`
```
**调用流程**：
1. 使用 `resolve-library-id` 解析库名
2. 从结果中选择最佳匹配（精确名称、描述相关性、代码片段数、来源信誉度、基准分数）
3. 使用 `query-docs` 获取具体文档
资料来源：[packages/mcp/src/index.ts:30-80](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts)
## 常见问题
### 配置文件路径
| 操作系统 | 客户端 | 默认路径 |
|----------|--------|----------|
| macOS/Linux | Claude Code | `~/.claude.json` |
| macOS/Linux | Cursor | `~/.cursor/mcp.json` |
| Windows | Claude Code | `%USERPROFILE%/.claude.json` |
### 速率限制
- **无 API Key**：基于 IP 的速率限制
- **有 API Key**：更高调用配额
- 建议：开发环境使用免费 Key，生产环境申请更高配额
### 库 ID 格式
Context7 使用统一的库 ID 格式：
```
/org/project # 主版本
/org/project@version # 指定版本（如 /vercel/next.js@v14.2.0）
```
## 故障排除
### MCP 连接失败
1. 检查 MCP 配置文件的 JSON 语法
2. 确认 `npx -y @upstash/context7-mcp` 可正常执行
3. 验证环境变量 `CONTEXT7_API_KEY` 设置正确
### 工具调用超时
大型文档库（如超过 100 万 token）可能需要更长的响应时间：
- 检查网络连接
- 考虑使用更具体的查询词
- 等待库刷新完成后再试
### 库未找到
确保使用正确的库名：
- 使用官方库名（如 "Next.js" 而非 "nextjs"）
- 检查版本号是否正确
- 访问 [context7.com](https://context7.com) 确认库已收录
## See Also
- [官方文档](https://context7.com/docs)
- [API 参考](https://context7.com/docs/api-guide)
- [添加新库](https://context7.com/docs/adding-libraries)
- [故障排除指南](https://context7.com/docs/resources/troubleshooting)
- [开发者指南](https://context7.com/docs/resources/developer)
---
## 库管理与维护
相关源码文件
以下源码文件用于生成本页说明：
- [docs/adding-libraries.mdx](https://github.com/upstash/context7/blob/main/docs/adding-libraries.mdx)
- [docs/library-updates.mdx](https://github.com/upstash/context7/blob/main/docs/library-updates.mdx)
- [docs/howto/claiming-libraries.mdx](https://github.com/upstash/context7/blob/main/docs/howto/claiming-libraries.mdx)
- [docs/howto/verification.mdx](https://github.com/upstash/context7/blob/main/docs/howto/verification.mdx)
- [docs/api-guide.mdx](https://github.com/upstash/context7/blob/main/docs/api-guide.mdx)
# 库管理与维护
本文档介绍 Context7 平台中库（Library）的管理、维护和更新流程。Context7 通过索引来自全球开发者社区的文档库，为 AI 编码助手提供实时、准确的文档查询能力。
## 概述
Context7 的库管理系统是整个平台的核心组件。它负责：
- **库注册**：将新的文档库提交到 Context7 进行索引
- **库认领**：允许官方维护者认领和管理其库的页面
- **库验证**：确保库文档的准确性和完整性
- **库更新**：处理文档刷新和迁移请求
```mermaid
graph TD
A[用户/维护者] --> B[库注册请求]
A --> C[库认领请求]
A --> D[库更新请求]
B --> E[系统验证]
C --> F[所有权验证]
D --> G[文档刷新]
E --> H{验证结果}
F --> I{认领成功}
G --> J[重新索引]
H -->|通过| K[库上线]
H -->|失败| L[返回错误]
```
## 库提交与注册
### 提交流程
开发者可以通过两种方式向 Context7 提交库文档：
1. **通过 GitHub 仓库提交**：适用于开源项目
2. **通过网站 URL 提交**：适用于托管文档网站
### 提交要求
| 要求类别 | 具体内容 |
|---------|---------|
| 文档格式 | 支持 MDX、Markdown、HTML 等格式 |
| 文档结构 | 建议包含 README、使用指南、API 参考 |
| 代码示例 | 建议提供可运行的代码片段 |
| 元数据 | 需要提供库名称、描述、官方链接 |
资料来源：[docs/adding-libraries.mdx]()
### 提交配置
库的配置通过 `context7.json` 文件定义，放置在仓库根目录：
```json
{
"name": "Library Name",
"description": "Brief description of the library",
"source": "github",
"github": {
"owner": "organization",
"repo": "repository",
"branch": "main"
},
"documentation": {
"baseUrl": "./docs",
"filePatterns": ["**/*.mdx", "**/*.md"]
}
}
```
### 大型库的特殊处理
对于超过 1GB 的大型库，系统无法自动刷新。维护者需要手动提交刷新请求：
> 参见社区讨论：[/chkp-antonr/checkpoint-api-ref](https://github.com/upstash/context7/issues/2674) - 该库大小为 3,408,440 tokens，需要手动触发刷新。
资料来源：[docs/library-updates.mdx]()
## 库认领与所有权
### 认领流程
官方库维护者可以通过认领流程获得其库页面的管理权限。
```mermaid
sequenceDiagram
participant 申请者
participant Context7系统
participant 原始维护者
申请者->>Context7系统: 提交认领请求
Context7系统->>原始维护者: 发送验证邮件
原始维护者->>Context7系统: 确认转让
Context7系统->>申请者: 授予管理权限
```
### 认领条件
| 条件类型 | 说明 |
|---------|------|
| 官方身份 | 需要是 GitHub/GitLab 仓库的组织成员 |
| 文档链接 | 必须在仓库中添加指定的验证链接 |
| 响应时间 | 需在规定时间内完成验证 |
资料来源：[docs/howto/claiming-libraries.mdx]()
### 库迁移
当库文档从旧仓库迁移到新仓库时，需要提交迁移请求：
1. 更新 Context7 页面指向新文档位置
2. 归档旧仓库或设置重定向
3. 通知用户新的文档地址
> 参见社区讨论：[racletteJs 库迁移请求](https://github.com/upstash/context7/issues/2665) - 该框架将文档从独立仓库移入 monorepo。
## 库验证
### 验证类型
| 验证类型 | 描述 | 触发条件 |
|---------|------|---------|
| 自动验证 | 系统自动检查文档完整性 | 每次索引更新 |
| 人工验证 | 社区成员或官方审核 | 用户提交验证请求 |
| 定期验证 | 定期质量检查 | 系统定时任务 |
### 验证清单
库验证通常检查以下项目：
- [ ] README 文件是否完整
- [ ] API 文档是否覆盖所有公开接口
- [ ] 代码示例是否可运行
- [ ] 版本信息是否准确
- [ ] 文档是否与实际代码同步
> 参见社区讨论：[Carbon Design System 验证请求](https://github.com/upstash/context7/issues/2626) - 报告缺少 README 和组件文档。
### 验证请求提交
用户可以通过 GitHub Issue 提交验证请求：
```
Library ID: /org/project
Library Name: [名称]
Context7 Page: https://context7.com/org/project
Docs URL: [文档地址]
Description: [问题描述]
```
资料来源：[docs/howto/verification.mdx]()
## 库更新与刷新
### 自动更新机制
Context7 系统会定期自动刷新已注册的库文档。刷新频率取决于：
| 库类型 | 刷新频率 |
|-------|---------|
| 高活跃度库 | 每日 |
| 中活跃度库 | 每周 |
| 低活跃度库 | 每月 |
### 手动刷新请求
当库文档发生重大更新时，维护者可以提交手动刷新请求：
1. 在 [GitHub Issues](https://github.com/upstash/context7/issues) 创建新 Issue
2. 选择 "Refresh request" 模板
3. 提供库的 Context7 ID
4. 说明需要刷新的原因
> 参见社区讨论：[/openai/openai-cookbook 刷新请求](https://github.com/upstash/context7/issues/2672) - 因新版本更新触发的文档刷新。
### 更新通知
库更新完成后，系统会：
1. 更新 Context7 网站上的文档内容
2. 重新计算库的 token 数量
3. 更新版本信息
## 网站类型库的特殊处理
### 自定义域名问题
对于托管在自定义域名上的文档网站，可能存在索引问题：
| 问题类型 | 症状 | 解决方案 |
|---------|------|---------|
| 索引数量不足 | 只索引了部分页面 | 检查 robots.txt 设置 |
| 爬取失败 | 无法访问网站 | 确认网站可访问性 |
| 路径问题 | 相对路径解析失败 | 使用绝对路径 |
> 参见社区讨论：[自定义域名索引问题](https://github.com/upstash/context7/issues/2681) - 同站点在 Vercel.app 可正常索引 163 页，自定义域名仅索引 4 页。
### Vercel 部署建议
对于 Vercel 托管的文档网站：
1. 使用 Vercel 提供的默认域名进行初始配置
2. 确认 Base URL 设置正确
3. 等待系统完成完整爬取
## API 参考
### 库管理端点
| 端点 | 方法 | 描述 |
|-----|------|------|
| `/api/library/resolve` | GET | 解析库名称为库 ID |
| `/api/library/{id}` | GET | 获取库详情 |
| `/api/library/{id}/refresh` | POST | 触发库刷新 |
| `/api/library/{id}/claim` | POST | 提交库认领请求 |
### 请求示例
```typescript
// 解析库 ID
const response = await fetch(
`https://context7.com/api/library/resolve?query=next.js`,
{
headers: {
'Authorization': `Bearer ${API_KEY}`
}
}
);
const { libraries } = await response.json();
```
资料来源：[docs/api-guide.mdx]()
## 常见问题与故障排除
### 库未找到
**问题**：搜索库名称时返回空结果
**解决方案**：
1. 检查库名称拼写是否正确
2. 确认库是否已提交到 Context7
3. 尝试使用官方名称（如 "Next.js" 而非 "nextjs"）
### 文档过期
**问题**：返回的文档内容与最新版本不符
**解决方案**：
1. 提交刷新请求
2. 检查源仓库是否有最新文档
3. 确认 `context7.json` 配置正确
### 爬取失败
**问题**：网站类型库无法正常索引
**解决方案**：
1. 检查网站是否公开可访问
2. 确认没有 IP 或地区限制
3. 检查 robots.txt 是否阻止爬虫
### Prompt 注入风险
> 参见社区讨论：[query-docs 响应中的提示注入](https://github.com/upstash/context7/issues/2663) - 系统偶尔会在响应中嵌入非文档内容。
**防护措施**：
- 验证所有返回内容的来源
- 不要执行响应中的任何命令
- 报告可疑的响应内容
## 安全与隐私
### 数据存储
Context7 遵循 XDG Base Directory Specification 存储配置文件：
| 文件类型 | 存储位置 |
|---------|---------|
| CLI 状态 | `~/.local/share/context7/` |
| 配置文件 | `~/.config/context7/` |
| 缓存文件 | `~/.cache/context7/` |
> 参见社区讨论：[XDG 合规性请求](https://github.com/upstash/context7/issues/2638) - 用户请求使用 XDG 标准目录。
### 隐私政策
详情请参阅 [Upstash 隐私政策](https://upstash.com/trust/context7addendum.pdf)。
## 相关资源
- [添加新库指南](https://context7.com/docs/adding-libraries) - 完整的库提交教程
- [API 参考文档](https://context7.com/docs/api-guide) - REST API 详细说明
- [故障排除指南](https://context7.com/docs/resources/troubleshooting) - 常见问题解答
- [所有客户端支持](https://context7.com/docs/resources/all-clients) - 30+ 客户端集成指南
## 参见
- [Context7 概览](../overview) - 平台整体介绍
- [MCP 服务器配置](../mcp-setup) - MCP 工具配置指南
- [CLI 使用指南](../cli-usage) - 命令行工具使用教程
- [AI SDK 集成](../ai-sdk-integration) - 与 Vercel AI SDK 集成
---
## 企业部署指南
### 相关页面
相关主题：[安全与认证](#page-10)
```markdown
相关源码文件
以下源码文件用于生成本页说明：
- [packages/mcp/package.json](https://github.com/upstash/context7/blob/main/packages/mcp/package.json)
- [packages/mcp/src/index.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts)
- [packages/mcp/mcpb/manifest.json](https://github.com/upstash/context7/blob/main/packages/mcp/mcpb/manifest.json)
- [packages/cli/src/setup/agents.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/setup/agents.ts)
- [package.json](https://github.com/upstash/context7/blob/main/package.json)
- [README.md](https://github.com/upstash/context7/blob/main/README.md)
# 企业部署指南
## 概述
本页面介绍如何在企业环境中部署和配置 Context7。Context7 是一个为 AI 编码助手提供最新库文档的服务，支持通过 MCP（Model Context Protocol）或 CLI 模式与各种编码代理集成。
> **注意**：目前官方仓库中尚未提供独立的企业部署文档（如 `docs/enterprise/` 目录），本指南基于现有代码库架构和企业用户常见需求编写。
## 部署架构
Context7 支持两种主要的部署模式：
```mermaid
graph TD
A[企业用户] --> B{MCP 模式}
A --> C{CLI + Skills 模式}
B --> D[Context7 MCP Server]
D --> E[context7.com API]
C --> F[ctx7 CLI]
F --> E
G[Claude Code] --> B
H[Cursor] --> B
I[VS Code] --> B
J[pi Agent] --> B
style E fill:#f9f,stroke:#333
style D fill:#bbf,stroke:#333
```
### MCP 模式
MCP 模式通过 Model Context Protocol 注册文档查询工具，适合支持 MCP 的编码代理：
- **工具**：`resolve-library-id` - 解析库名称为 Context7 兼容的库 ID
- **工具**：`query-docs` - 获取特定库的文档和代码示例
资料来源：[packages/mcp/src/index.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts)
### CLI + Skills 模式
CLI 模式安装一个指导代理使用 `ctx7` CLI 获取文档的技能，无需 MCP 支持：
```bash
npx ctx7 setup
```
该命令会进行 OAuth 认证、生成 API 密钥并安装适当的技能。
资料来源：[README.md](https://github.com/upstash/context7/blob/main/README.md)
## 主流代理集成配置
### 支持的代理平台
| 代理平台 | MCP 配置路径 | 全局配置路径 | 传输方式 |
|---------|-------------|-------------|---------|
| Claude Code | `.codex/settings.json` | `~/.claude.json` | stdio / HTTP |
| Gemini CLI | `.gemini/settings.json` | `~/.gemini/settings.json` | stdio / HTTP |
资料来源：[packages/cli/src/setup/agents.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/setup/agents.ts)
### Claude Code 插件安装
```bash
claude plugin marketplace add upstash/context7
claude plugin install context7-plugin@context7-marketplace
```
安装后提供：
- **MCP Server** - 连接 Claude Code 到 Context7 文档服务
- **Skills** - 自动触发文档查询
- **Agents** - 专用的 `docs-researcher` 代理
- **Commands** - `/context7:docs` 手动文档查询
资料来源：[plugins/claude/context7/README.md](https://github.com/upstash/context7/blob/main/plugins/claude/context7/README.md)
### Cursor IDE 集成
提供专用的 `docs-researcher` 代理，用于在不干扰主对话上下文的情况下获取库文档。
## MCP 服务器配置
### 服务器端点
MCP 服务器默认连接到 `https://context7.com/api`：
```json
{
"name": "Context7",
"version": "SERVER_VERSION",
"websiteUrl": "https://context7.com",
"description": "Context7 provides up-to-date documentation and code examples for libraries and frameworks."
}
```
资料来源：[packages/mcp/src/index.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts)
### 工具注册
MCP 服务器注册以下工具：
| 工具名称 | 功能 | 输入参数 |
|---------|------|---------|
| `resolve-library-id` | 将库名称解析为 Context7 库 ID | `libraryName`, `query` |
| `query-docs` | 获取特定库的文档 | `libraryId`, `query` |
### MCP 清单配置
```json
{
"compatibility": {
"platforms": ["darwin", "win32", "linux"],
"runtimes": {
"node": ">=v18.0.0"
}
}
}
```
资料来源：[packages/mcp/mcpb/manifest.json](https://github.com/upstash/context7/blob/main/packages/mcp/mcpb/manifest.json)
## API 密钥管理
### 获取 API 密钥
1. 访问 [context7.com/dashboard](https://context7.com/dashboard) 获取免费 API 密钥
2. 无密钥使用时适用基于 IP 的速率限制
### 环境变量配置
```bash
export CONTEXT7_API_KEY=ctx7sk_...
```
对于 pi 编码代理，需要在 shell 配置文件中设置此环境变量。
### MCP 认证配置
MCP 配置支持两种认证传输方式：
```typescript
// stdio 模式
buildEntry: (auth, transport) =>
transport === "stdio" ? stdioEntry(auth) : withHeaders({ httpUrl: mcpUrl(auth) }, auth)
```
资料来源：[packages/cli/src/setup/agents.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/setup/agents.ts)
## 企业环境考虑
### 防火墙和网络要求
Context7 MCP 需要访问以下端点：
| 端点 | 用途 |
|-----|------|
| `https://context7.com` | 主网站和文档 |
| `https://context7.com/api` | MCP API 服务 |
### 数据隐私
- 文档查询仅传输查询文本和库标识符
- 不上传用户代码
- 隐私政策：https://upstash.com/trust/context7addendum.pdf
### 速率限制
| 认证状态 | 速率限制 |
|---------|---------|
| 无 API 密钥 | 基于 IP 的限制 |
| 有 API 密钥 | 更高的请求配额 |
## 常见问题
### MCP 配置解析错误
在 `ctx7 remove` 命令执行期间，如果 MCP 配置文件格式不正确（如手动的 `~/.claude.json`），系统现在会跳过无法解析的文件而非崩溃：
```
ctx7@0.4.2 patch: Handle malformed MCP config files gracefully during agent detection.
```
资料来源：[ctx7@0.4.2 Release Notes](https://github.com/upstash/context7/releases/tag/ctx7%400.4.2)
### 库文档过期
大型库的文档可能无法自动刷新：
| 库 | 大小 | 状态 |
|---|-----|------|
| `/chkp-antonr/checkpoint-api-ref` | 3,408,440 tokens | 需要手动刷新 |
| `/openai/openai-cookbook` | 1,319,667 tokens | 已重新解析 |
### 提示注入防护
系统会定期处理 `query-docs` 响应中的提示注入问题。建议在使用外部库文档时实施适当的内容过滤。
## 相关资源
| 资源 | 链接 |
|-----|------|
| 官方文档 | https://context7.com/docs |
| MCP 客户端列表 | https://context7.com/docs/resources/all-clients |
| 故障排除指南 | https://context7.com/docs/resources/troubleshooting |
| API 参考 | https://context7.com/docs/api-guide |
| GitHub 仓库 | https://github.com/upstash/context7 |
## 参见
- [MCP 服务器部署](../mcp/deployment.md) - MCP 服务器详细配置
- [CLI 安装指南](../cli/installation.md) - ctx7 CLI 工具安装
- [SDK 集成](../sdk/overview.md) - 编程式 SDK 使用
- [编码代理插件](../plugins/overview.md) - 各 IDE 插件详情
---
## 安全与认证
### 相关页面
相关主题：[企业部署指南](#page-9)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/security/overview.mdx](https://github.com/upstash/context7/blob/main/docs/security/overview.mdx)
- [docs/security/auth-and-access-control.mdx](https://github.com/upstash/context7/blob/main/docs/security/auth-and-access-control.mdx)
- [docs/security/data-privacy.mdx](https://github.com/upstash/context7/blob/main/docs/security/data-privacy.mdx)
- [docs/security/data-safety.mdx](https://github.com/upstash/context7/blob/main/docs/security/data-safety.mdx)
- [docs/security/infrastructure.mdx](https://github.com/upstash/context7/blob/main/docs/security/infrastructure.mdx)
- [docs/security/compliance-and-reporting.mdx](https://github.com/upstash/context7/blob/main/docs/security/compliance-and-reporting.mdx)
- [docs/security/best-practices.mdx](https://github.com/upstash/context7/blob/main/docs/security/best-practices.mdx)
- [packages/mcp/src/lib/auth/auth-prompt.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/lib/auth/auth-prompt.ts)
- [packages/mcp/src/lib/encryption.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/lib/encryption.ts)
- [packages/mcp/src/lib/jwt.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/lib/jwt.ts)
- [packages/cli/src/utils/auth.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/utils/auth.ts)
- [docs/howto/api-keys.mdx](https://github.com/upstash/context7/blob/main/docs/howto/api-keys.mdx)
# 安全与认证
本文档详细介绍 Context7 的安全架构、认证机制和访问控制策略。Context7 通过多层安全措施保护用户数据和 API 访问安全，包括 API Key 认证、JWT Token 验证、数据加密传输以及严格的访问控制策略。
## 概述
Context7 的安全体系旨在为 AI 编码助手提供可靠的文档检索服务，同时确保用户数据的机密性和完整性。系统采用行业标准的安全协议，包括传输层加密、API 密钥管理和细粒度的访问控制。
核心安全特性包括：
| 安全特性 | 描述 |
|---------|------|
| API Key 认证 | 通过 `CONTEXT7_API_KEY` 环境变量进行身份验证 |
| JWT Token 验证 | MCP 服务器使用 JWT 进行请求验证 |
| 传输层加密 | 所有 API 通信使用 HTTPS/TLS 加密 |
| 配置文件加密 | 本地配置和敏感数据加密存储 |
资料来源：[docs/security/overview.mdx](https://github.com/upstash/context7/blob/main/docs/security/overview.mdx)
## 认证机制
### API Key 认证
Context7 支持通过 API Key 进行身份验证。用户需要在 [Context7 仪表盘](https://context7.com/dashboard) 生成 API Key，并在使用 CLI 或 SDK 时通过环境变量配置。
#### 环境变量配置
```bash
# 设置 Context7 API Key
export CONTEXT7_API_KEY=ctx7sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
API Key 采用 `ctx7sk_` 前缀格式，用于标识 Context7 服务密钥类型。在 MCP 工具调用和 CLI 命令中，系统会自动读取该环境变量进行认证。
资料来源：[docs/howto/api-keys.mdx](https://github.com/upstash/context7/blob/main/docs/howto/api-keys.mdx)
#### CLI 认证流程
CLI 工具支持两种认证方式：
1. **OAuth 认证** - 通过 `ctx7 setup` 命令启动交互式 OAuth 流程
2. **API Key 认证** - 直接使用环境变量中的 API Key
```bash
# 启动交互式设置
npx ctx7 setup
# CLI 会自动检测 CONTEXT7_API_KEY 环境变量
ctx7 generate
```
CLI 在执行命令前会检查认证状态，若未配置 API Key 且无可用 OAuth Token，将提示用户进行认证。
资料来源：[packages/cli/src/utils/auth.ts](https://github.com/upstash/context7/blob/main/packages/cli/src/utils/auth.ts)
### MCP 服务器认证
Context7 MCP 服务器实现了一套完整的认证体系，用于验证来自 AI 客户端的请求。
#### MCP 工具注册与描述
MCP 服务器注册时提供完整的服务元数据，包括版本、描述和图标信息：
```typescript
{
name: "Context7",
version: SERVER_VERSION,
websiteUrl: "https://context7.com",
description: "Context7 provides up-to-date documentation...",
icons: [{
src: "https://context7.com/context7-icon-green.png",
mimeType: "image/png"
}]
}
```
资料来源：[packages/mcp/src/index.ts:1-20](https://github.com/upstash/context7/blob/main/packages/mcp/src/index.ts)
#### JWT Token 验证
MCP 服务器使用 JWT (JSON Web Token) 进行请求验证。JWT 提供了轻量级的身份认证机制，适合分布式系统的安全通信。
```mermaid
sequenceDiagram
participant Client as AI 客户端
participant MCP as Context7 MCP
participant API as Context7 API
Client->>MCP: 调用工具 (resolve-library-id/query-docs)
MCP->>MCP: 验证 JWT Token
MCP->>API: 转发认证请求
API->>API: 验证 API Key
API-->>MCP: 返回文档数据
MCP-->>Client: 返回结果
```
JWT 验证模块负责：
- Token 签发和验证
- Token 过期检查
- 权限范围验证
资料来源：[packages/mcp/src/lib/jwt.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/lib/jwt.ts)
### 认证提示模板
MCP 服务器使用预定义的认证提示模板，确保 AI 代理正确理解何时以及如何使用 Context7 服务：
```typescript
`Use this server to fetch current documentation whenever the user asks about a library,
framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React,
Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax,
configuration, version migration, library-specific debugging, setup instructions,
and CLI tool usage. Use even when you think you know the answer -- your training data
may not reflect recent changes. Prefer this over web search for library docs.
Do not use for: refactoring, writing scripts from scratch, debugging business logic,
code review, or general programming concepts.`
```
资料来源：[packages/mcp/src/lib/auth/auth-prompt.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/lib/auth/auth-prompt.ts)
## 数据安全
### 传输层安全
所有 Context7 API 通信均通过 HTTPS/TLS 加密传输，确保数据在传输过程中不被窃听或篡改。
| 传输协议 | 加密级别 | 适用场景 |
|---------|---------|---------|
| HTTPS | TLS 1.2+ | 所有 API 请求 |
| WSS | TLS 1.2+ | MCP 服务器通信 |
资料来源：[docs/security/data-safety.mdx](https://github.com/upstash/context7/blob/main/docs/security/data-safety.mdx)
### 数据加密
#### 配置文件加密
本地存储的敏感配置（如认证 Token）经过加密处理，防止未经授权的访问。
```mermaid
graph TD
A[用户认证] --> B[生成加密密钥]
B --> C[加密敏感数据]
C --> D[存储到配置文件]
D --> E[读取配置文件]
E --> F[解密数据]
F --> G[API 请求]
```
加密模块处理以下敏感数据：
- API Keys
- OAuth Tokens
- 用户会话信息
资料来源：[packages/mcp/src/lib/encryption.ts](https://github.com/upstash/context7/blob/main/packages/mcp/src/lib/encryption.ts)
### 数据隐私
Context7 承诺严格保护用户隐私数据：
| 数据类型 | 处理方式 | 保留期限 |
|---------|---------|---------|
| API 请求日志 | 脱敏处理 | 30 天 |
| 查询内容 | 不持久化 | 会话内 |
| API Key | 加密存储 | 直至用户删除 |
资料来源：[docs/security/data-privacy.mdx](https://github.com/upstash/context7/blob/main/docs/security/data-privacy.mdx)
## 访问控制
### MCP 工具权限
Context7 MCP 服务器实现了基于工具的访问控制策略：
| 工具名称 | 所需权限 | 功能描述 |
|---------|---------|---------|
| `resolve-library-id` | API Key | 解析库名称到 Context7 ID |
| `query-docs` | API Key | 查询文档内容 |
#### 工具使用约束
```typescript
// 工具调用前的权限检查流程
1. 验证 JWT Token 有效性
2. 检查 API Key 配额限制
3. 验证请求来源
4. 记录审计日志
```
资料来源：[docs/security/auth-and-access-control.mdx](https://github.com/upstash/context7/blob/main/docs/security/auth-and-access-control.mdx)
### 速率限制
Context7 对 API 请求实施速率限制以防止滥用：
| 认证方式 | 请求限制 | 适用场景 |
|---------|---------|---------|
| IP 限流（无 API Key） | 较低配额 | 试用/评估 |
| API Key 认证 | 更高配额 | 正式使用 |
用户可免费获取 API Key 以获得更高的请求配额。
资料来源：[packages/pi/README.md](https://github.com/upstash/context7/blob/main/packages/pi/README.md)
## 基础设施安全
### 安全架构
Context7 部署在安全的基础设施上，采用多层次的安全防护：
```mermaid
graph TB
subgraph 边界层
A[CDN/DDoS 防护] --> B[WAF 防火墙]
end
subgraph 应用层
B --> C[API 网关]
C --> D[认证服务]
C --> E[MCP 服务]
end
subgraph 数据层
E --> F[(文档数据库)]
D --> G[(用户数据)]
end
subgraph 监控层
H[安全监控] --> I[日志审计]
I --> J[告警系统]
end
```
资料来源：[docs/security/infrastructure.mdx](https://github.com/upstash/context7/blob/main/docs/security/infrastructure.mdx)
### 隐私政策与合规
Context7 遵循严格的隐私保护原则：
- **数据最小化**：仅收集服务必需的数据
- **目的限制**：数据仅用于提供服务
- **安全存储**：采用行业标准加密算法
- **用户控制**：用户可删除其账户数据
详细信息请参阅 [Upstash 隐私政策附录](https://upstash.com/trust/context7addendum.pdf)。
资料来源：[plugins/context7-power/POWER.md](https://github.com/upstash/context7/blob/main/plugins/context7-power/POWER.md)
## 最佳实践
### 安全使用指南
#### 1. API Key 管理
```bash
# ✓ 推荐：在 shell 配置文件中设置
echo 'export CONTEXT7_API_KEY=ctx7sk_xxxx' >> ~/.bashrc
# ✗ 不推荐：将 Key 硬编码在代码中
# export CONTEXT7_API_KEY=ctx7sk_xxxx # 危险！
```
#### 2. 环境变量配置
确保 API Key 不会意外泄露到版本控制系统：
```bash
# .gitignore
.env
.env.local
.env.*.local
```
#### 3. MCP 配置安全
当使用 MCP 客户端时，确保配置文件权限正确：
```bash
# 设置配置文件权限为仅所有者可读
chmod 600 ~/.config/context7/config.json
```
#### 4. 敏感数据保护
- 禁止在 `query-docs` 的 `query` 参数中传递 API Keys、密码或个人数据
- 避免在查询中包含专有代码
```typescript
// ✓ 安全
const docs = await queryDocs({
libraryId: "/vercel/next.js",
query: "How to configure middleware?"
});
// ✗ 危险 - 不要这样做
const docs = await queryDocs({
libraryId: "/internal/api",
query: "SELECT * FROM users WHERE password='secret123'"
});
```
资料来源：[packages/pi/skills/context7-docs/SKILL.md](https://github.com/upstash/context7/blob/main/packages/pi/skills/context7-docs/SKILL.md)
### 常见安全问题与解决方案
| 问题 | 原因 | 解决方案 |
|-----|------|---------|
| 认证失败 | API Key 未设置或过期 | 重新生成 API Key 并更新环境变量 |
| MCP 连接错误 | 配置文件格式损坏 | 验证 JSON 语法，使用 `--dry-run` 检查配置 |
| 速率限制触发 | 请求过于频繁 | 添加延迟或升级到更高配额 |
| Token 解析错误 | JWT 格式不正确 | 检查认证流程是否完整 |
资料来源：[docs/security/best-practices.mdx](https://github.com/upstash/context7/blob/main/docs/security/best-practices.mdx)
## CLI 安全配置
### 配置文件位置
CLI 工具将认证状态存储在本地配置中：
| 平台 | 配置路径 |
|-----|---------|
| macOS/Linux | `~/.context7/` |
| Windows | `%USERPROFILE%\.context7\` |
> **注意**：当前实现使用 `~/.context7/` 目录，这不符合 XDG Base Directory Specification。社区已提出 [XDG 合规性改进建议](https://github.com/upstash/context7/issues/2638)，建议将配置存储在 `$XDG_CONFIG_HOME/context7` 目录。
### 认证状态管理
```bash
# 检查当前认证状态
ctx7 status
# 重新认证
ctx7 setup
# 移除认证（从所有代理）
ctx7 remove
```
`ctx7 remove` 命令会智能检测已安装 Context7 的代理，包括 Claude Code、Codex 等，并从相应配置中移除 Context7 相关设置。该命令能够优雅处理格式损坏的配置文件。
资料来源：[ctx7@0.4.2 发行说明](https://github.com/upstash/context7/releases/tag/ctx7%400.4.2)
## 安全报告与支持
### 漏洞报告
若发现安全漏洞，请通过以下方式报告：
- **安全邮箱**：context7@upstash.com
- **GitHub Security Advisory**：使用 GitHub 的安全报告功能
请勿在公开 Issue 中讨论安全漏洞。
### 合规报告
Context7 提供以下合规相关文档：
- SOC 2 Type II 合规状态
- GDPR 合规说明
- 数据处理协议 (DPA)
资料来源：[docs/security/compliance-and-reporting.mdx](https://github.com/upstash/context7/blob/main/docs/security/compliance-and-reporting.mdx)
## 相关文档
- [API 密钥指南](https://github.com/upstash/context7/blob/main/docs/howto/api-keys.mdx)
- [故障排除](https://context7.com/docs/resources/troubleshooting)
- [本地开发指南](https://context7.com/docs/resources/developer)
- [所有 MCP 客户端](https://context7.com/docs/resources/all-clients)
## 另请参阅
- [Context7 MCP 服务器](../mcp-server/index) - MCP 集成指南
- [CLI 安装与配置](../cli/index) - 命令行工具使用
- [AI SDK 集成](../ai-sdk/index) - Vercel AI SDK 工具
---
---
## Doramagic 踩坑日志
项目：upstash/context7
摘要：发现 32 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: Prompt-injection content appended to `query-docs` response (HubSpot Developer Documentation l...。
## 1. 安全/权限坑 · 失败模式：security_permissions: Prompt-injection content appended to `query-docs` response (HubSpot Developer Documentation l...
- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: Prompt-injection content appended to `query-docs` response (HubSpot Developer Documentation library)
- 对用户的影响：Developers may expose sensitive permissions or credentials: Prompt-injection content appended to `query-docs` response (HubSpot Developer Documentation library)
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Prompt-injection content appended to `query-docs` response (HubSpot Developer Documentation library). Context: Observed during installation or first-run setup.
- 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/upstash/context7/issues/2673
- 证据：failure_mode_cluster:github_issue | fmev_f91ad7c65b248ade2db4a9cc8ca70e1f | https://github.com/upstash/context7/issues/2673 | Prompt-injection content appended to `query-docs` response (HubSpot Developer Documentation library)
## 2. 安全/权限坑 · 失败模式：security_permissions: query-docs response embeds non-doc "system notice" with auto-approve install command — prompt...
- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: query-docs response embeds non-doc "system notice" with auto-approve install command — prompt injection vector
- 对用户的影响：Developers may expose sensitive permissions or credentials: query-docs response embeds non-doc "system notice" with auto-approve install command — prompt injection vector
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: query-docs response embeds non-doc "system notice" with auto-approve install command — prompt injection vector. Context: Observed during installation or first-run setup.
- 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/upstash/context7/issues/2663
- 证据：failure_mode_cluster:github_issue | fmev_d54367d6cbfefa30a08d27c872533e44 | https://github.com/upstash/context7/issues/2663 | query-docs response embeds non-doc "system notice" with auto-approve install command — prompt injection vector
## 3. 安全/权限坑 · 来源证据：Prompt-injection content appended to `query-docs` response (HubSpot Developer Documentation library)
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Prompt-injection content appended to `query-docs` response (HubSpot Developer Documentation library)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_40a4551a10c541ff9aeb4cfa33ad689e | https://github.com/upstash/context7/issues/2673 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. 安全/权限坑 · 来源证据：Use XDG-compliant directories for storing Context7 files
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Use XDG-compliant directories for storing Context7 files
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4cf92b43e1694ab6bbd96e6eb63188dd | https://github.com/upstash/context7/issues/2638 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。
## 5. 安全/权限坑 · 来源证据：[Feature]: Add --dry-run flag to CLI for config validation
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature]: Add --dry-run flag to CLI for config validation
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_621e348546d94e81b343d02ef9f86cf5 | https://github.com/upstash/context7/issues/2677 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。
## 6. 安全/权限坑 · 来源证据：query-docs response embeds non-doc "system notice" with auto-approve install command — prompt injection vector
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：query-docs response embeds non-doc "system notice" with auto-approve install command — prompt injection vector
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_31d3961fd88444a68e1ea5035a28dcac | https://github.com/upstash/context7/issues/2663 | 来源类型 github_issue 暴露的待验证使用条件。
## 7. 身份坑 · 仓库名和安装名不一致
- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `context7` 与安装入口 `ctx7` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令：`npx ctx7`
- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | github_repo:955620917 | https://github.com/upstash/context7 | repo=context7; install=ctx7
## 8. 安装坑 · 来源证据：Verification Request: Glyph
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Verification Request: Glyph
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_cedef8266f434c77aebb4e590501196a | https://github.com/upstash/context7/issues/2682 | 来源类型 github_issue 暴露的待验证使用条件。
## 9. 配置坑 · 失败模式：configuration: Update Request: Library Migration racletteJs
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Update Request: Library Migration racletteJs
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Update Request: Library Migration racletteJs
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Update Request: Library Migration racletteJs. Context: Observed during version upgrade or migration.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_2c347e165f54805473e465e7e0398a8c | https://github.com/upstash/context7/issues/2665 | Update Request: Library Migration racletteJs
## 10. 配置坑 · 失败模式：configuration: Use XDG-compliant directories for storing Context7 files
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Use XDG-compliant directories for storing Context7 files
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Use XDG-compliant directories for storing Context7 files
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Use XDG-compliant directories for storing Context7 files. Context: Observed when using linux
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_6c1bf0512a4906da8a1af4d73f35184f | https://github.com/upstash/context7/issues/2638 | Use XDG-compliant directories for storing Context7 files
## 11. 配置坑 · 失败模式：configuration: [Bug]: Website crawl on custom domain indexes 4 pages; same site on vercel.app indexes 163
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: [Bug]: Website crawl on custom domain indexes 4 pages; same site on vercel.app indexes 163
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Bug]: Website crawl on custom domain indexes 4 pages; same site on vercel.app indexes 163
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Website crawl on custom domain indexes 4 pages; same site on vercel.app indexes 163. Context: Observed when using node, windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_cf0a4398e41bcdc31ff4a54804f705f1 | https://github.com/upstash/context7/issues/2681 | [Bug]: Website crawl on custom domain indexes 4 pages; same site on vercel.app indexes 163
## 12. 配置坑 · 失败模式：configuration: [Feature]: Add --dry-run flag to CLI for config validation
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: [Feature]: Add --dry-run flag to CLI for config validation
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Feature]: Add --dry-run flag to CLI for config validation
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature]: Add --dry-run flag to CLI for config validation. Context: Observed when using python
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_1003d3ce04124045d36427fda6180af5 | https://github.com/upstash/context7/issues/2677 | [Feature]: Add --dry-run flag to CLI for config validation
## 13. 配置坑 · 失败模式：configuration: ctx7@0.4.2
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: ctx7@0.4.2
- 对用户的影响：Upgrade or migration may change expected behavior: ctx7@0.4.2
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: ctx7@0.4.2. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_8566011c4ad7959f3c4ad09f0dea72a1 | https://github.com/upstash/context7/releases/tag/ctx7%400.4.2 | ctx7@0.4.2
## 14. 配置坑 · 来源证据：Update Request: Library Migration racletteJs
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Update Request: Library Migration racletteJs
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_b15f74c0680c4cf5b53ce7e4da0df998 | https://github.com/upstash/context7/issues/2665 | 来源类型 github_issue 暴露的待验证使用条件。
## 15. 能力坑 · 来源证据：[MCP]: Denoland/docs needs update
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[MCP]: Denoland/docs needs update
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_debfaf266fd74a53baae4cf56589d2ac | https://github.com/upstash/context7/issues/2676 | 来源类型 github_issue 暴露的待验证使用条件。
## 16. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:955620917 | https://github.com/upstash/context7 | README/documentation is current enough for a first validation pass.
## 17. 运行坑 · 失败模式：runtime: @upstash/context7-mcp@2.2.3
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: @upstash/context7-mcp@2.2.3
- 对用户的影响：Upgrade or migration may change expected behavior: @upstash/context7-mcp@2.2.3
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: @upstash/context7-mcp@2.2.3. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_48fc6634a7304c52ab1e26fb17c817e7 | https://github.com/upstash/context7/releases/tag/%40upstash/context7-mcp%402.2.3 | @upstash/context7-mcp@2.2.3
## 18. 运行坑 · 失败模式：runtime: [MCP]: Denoland/docs needs update
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: [MCP]: Denoland/docs needs update
- 对用户的影响：Developers may hit a documented source-backed failure mode: [MCP]: Denoland/docs needs update
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [MCP]: Denoland/docs needs update. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_9c885767bfcd78d407b62db196ab9a24 | https://github.com/upstash/context7/issues/2676 | [MCP]: Denoland/docs needs update
## 19. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:955620917 | https://github.com/upstash/context7 | last_activity_observed missing
## 20. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:955620917 | https://github.com/upstash/context7 | no_demo; severity=medium
## 21. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:955620917 | https://github.com/upstash/context7 | no_demo; severity=medium
## 22. 安全/权限坑 · 来源证据：Library Report: /websites/web-components_carbondesignsystem - Missing or incorrect documentation.
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Library Report: /websites/web-components_carbondesignsystem - Missing or incorrect documentation.
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_053b3caa9572424e97c4ab81ac3a2599 | https://github.com/upstash/context7/issues/2626 | 来源类型 github_issue 暴露的待验证使用条件。
## 23. 安全/权限坑 · 来源证据：Refresh request for /chkp-antonr/checkpoint-api-ref
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Refresh request for /chkp-antonr/checkpoint-api-ref
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ee044fbcf8fc46c2bfd5a96483da9a6e | https://github.com/upstash/context7/issues/2674 | 来源类型 github_issue 暴露的待验证使用条件。
## 24. 安全/权限坑 · 来源证据：Refresh request for /openai/openai-cookbook
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Refresh request for /openai/openai-cookbook
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_b41ac081e0c144b994655e88462144c7 | https://github.com/upstash/context7/issues/2672 | 来源类型 github_issue 暴露的待验证使用条件。
## 25. 安全/权限坑 · 来源证据：[Bug]: Website crawl on custom domain indexes 4 pages; same site on vercel.app indexes 163
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Website crawl on custom domain indexes 4 pages; same site on vercel.app indexes 163
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3b6ec47887ab47ce8bfea65ab60efec3 | https://github.com/upstash/context7/issues/2681 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 26. 能力坑 · 失败模式：capability: Refresh request for /openai/openai-cookbook
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Refresh request for /openai/openai-cookbook
- 对用户的影响：Developers may hit a documented source-backed failure mode: Refresh request for /openai/openai-cookbook
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Refresh request for /openai/openai-cookbook. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_c5c210d2a977e6da6e6c5cc934bb3abe | https://github.com/upstash/context7/issues/2672 | Refresh request for /openai/openai-cookbook
## 27. 能力坑 · 失败模式：conceptual: Library Report: /websites/web-components_carbondesignsystem - Missing or incorrect documentat...
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: Library Report: /websites/web-components_carbondesignsystem - Missing or incorrect documentation.
- 对用户的影响：Developers may hit a documented source-backed failure mode: Library Report: /websites/web-components_carbondesignsystem - Missing or incorrect documentation.
- 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_c75ebf806e90a52fafb8080cf4dc77af | https://github.com/upstash/context7/issues/2626 | Library Report: /websites/web-components_carbondesignsystem - Missing or incorrect documentation.
## 28. 能力坑 · 失败模式：conceptual: Refresh request for /chkp-antonr/checkpoint-api-ref
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: Refresh request for /chkp-antonr/checkpoint-api-ref
- 对用户的影响：Developers may hit a documented source-backed failure mode: Refresh request for /chkp-antonr/checkpoint-api-ref
- 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_b26139deccf5120940bf34c0a9284cbd | https://github.com/upstash/context7/issues/2674 | Refresh request for /chkp-antonr/checkpoint-api-ref
## 29. 能力坑 · 失败模式：conceptual: Verification Request: Glyph
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: Verification Request: Glyph
- 对用户的影响：Developers may hit a documented source-backed failure mode: Verification Request: Glyph
- 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_87c3e9d32d8fef201f043c01eac4e615 | https://github.com/upstash/context7/issues/2682 | Verification Request: Glyph
## 30. 运行坑 · 失败模式：performance: @upstash/context7-mcp@2.2.5
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: @upstash/context7-mcp@2.2.5
- 对用户的影响：Upgrade or migration may change expected behavior: @upstash/context7-mcp@2.2.5
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: @upstash/context7-mcp@2.2.5. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_release | fmev_dd9cf41d263617b2a4f41e00b7a9862c | https://github.com/upstash/context7/releases/tag/%40upstash/context7-mcp%402.2.5 | @upstash/context7-mcp@2.2.5
## 31. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:955620917 | https://github.com/upstash/context7 | issue_or_pr_quality=unknown
## 32. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:955620917 | https://github.com/upstash/context7 | release_recency=unknown