项目简介

Context7 是一个由 Upstash 开发的文档检索平台，旨在为 AI 编码助手和开发工具提供最新、最准确的库文档和代码示例。该项目解决了大型语言模型训练数据过时的问题，通过直接从源代码仓库获取最新文档，确保 AI 助手能够基于真实、准确的信息回答开发者的技术问题。

Context7 的核心价值主张在于：即使是你认为非常熟悉的库（如 React、Next.js、Prisma 等），也应该使用 Context7 来获取文档，因为模型的训练数据可能不反映最新的 API 变化和最佳实践。

资料来源：packages/mcp/src/index.ts:13-18

核心功能

文档检索工具

Context7 MCP 服务器提供两个主要工具：

资料来源：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

架构概览

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 获取 API Key。获取后，可通过环境变量或配置文件进行设置。

MCP 服务器安装

#### 全局安装

npm install -g @upstash/context7-mcp

#### 项目级安装

npm install @upstash/context7-mcp

资料来源：packages/mcp/package.json:19-24

Claude Code 插件安装

对于 Claude Code 用户，可通过插件市场安装：

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 客户端，包括：

资料来源：i18n/README.ko.md:28-30

快速入门指南

标准工作流程

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 工具用于命令行环境：

npm install -g @upstash/context7-cli

#### 可用命令

资料来源：packages/cli/src/commands/generate.ts:45-65

设置命令

ctx7 setup 命令支持多种智能体的自动配置：

ctx7 setup [agent] --scope [global|local]

支持的智能体：

资料来源：packages/cli/src/setup/agents.ts:10-60

AI SDK 集成

Vercel AI SDK 工具

对于使用 Vercel AI SDK 的开发者，Context7 提供了专门的工具包：

npm install @upstash/context7-tools-ai-sdk @upstash/context7-sdk ai zod

与 generateText 配合使用

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 智能体

包还提供了预配置的智能体：

import { Context7Agent } from "@upstash/context7-tools-ai-sdk";

资料来源：packages/tools-ai-sdk/README.md:28-45

文档研究员智能体

Context7 提供了专门的 docs-researcher 智能体配置，用于专注的文档研究：

概述

Context7 CLI（ctx7）是 Context7 文档系统的命令行客户端，为 AI 编码助手提供实时文档检索能力。通过 CLI，用户可以快速查询库文档、配置智能代理、管理 API 认证，并在各种开发环境中集成 Context7 功能。

CLI 支持两种主要使用模式：

• CLI + Skills 模式 — 安装技能引导代理使用 ctx7 命令获取文档（无需 MCP）
• MCP 模式 — 注册 Context7 MCP 服务器，使代理能够原生调用文档工具

资料来源：README.md

安装与初始化

快速安装

使用 npx 直接运行或通过全局安装：

# 使用 npx 直接运行
npx ctx7 setup

# 全局安装
npm install -g @upstash/context7-cli

# 安装后直接运行
ctx7 setup

初始化配置

ctx7 setup 命令完成以下任务：

1. OAuth 认证 — 自动打开浏览器完成身份验证
2. API Key 生成 — 创建用于编程访问的 API 密钥
3. 技能安装 — 选择目标代理并安装相应技能

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

命令参考

setup — 初始化设置

初始化 Context7 CLI 并配置认证和代理。

ctx7 setup [选项]

支持的代理类型：

资料来源：packages/cli/src/setup/agents.ts

docs — 文档查询

查询指定库的文档。

ctx7 docs <library-id> [查询词]

参数说明：

使用示例：

# 查询 Next.js 文档
ctx7 docs /vercel/next.js middleware

# 查询特定版本的文档
ctx7 docs /vercel/next.js/v14 app router

# 交互式选择库并查询
ctx7 docs

交互式流程：

CLI 会展示一个可搜索的库列表，包含以下元数据：

资料来源：packages/cli/src/commands/docs.ts

generate — 代码生成

根据文档生成代码示例。

ctx7 generate [选项] <描述>

选项：

工作流程：

graph TD
    A[运行 generate 命令] --> B[搜索相关库]
    B --> C{用户选择库}
    C -->|无选择| D[结束]
    C -->|选择库| E[生成澄清问题]
    E --> F[获取用户回答]
    F --> G[生成代码]
    G --> H[返回代码和说明]

用户可以从搜索结果中选择多个库，CLI 会显示每个库的详细信息，包括代码片段数量和星标数。

资料来源：packages/cli/src/commands/generate.ts

skill — 技能管理

管理已安装的 Context7 技能。

ctx7 skill [子命令]

子命令：

list 输出示例：

Skill:       context7-mcp
Repo:        /upstash/context7
Installs:    1.2k - 1.5k
Trust:       9.8
Description: Fetch up-to-date library documentation using Context7

安装计数格式化：

资料来源：packages/cli/src/commands/skill.ts

remove — 卸载清理

从代理配置中移除 Context7 集成。

ctx7 remove [选项]

注意： 在 v0.4.2 版本中，CLI 改进了对格式错误的 MCP 配置文件的处理。如果配置文件（如 ~/.claude.json）存在 JSON 语法错误，CLI 会跳过该文件而非崩溃。

资料来源：packages/cli/src/commands/remove.ts

auth — 认证管理

管理 API 认证信息。

ctx7 auth [子命令]

资料来源：packages/cli/src/commands/auth.ts

配置与存储

配置存储位置

CLI 默认将配置存储在 ~/.context7/ 目录：

# 配置文件位置
~/.context7/
├── cli-state.json
└── api-key

已知限制： 当前 CLI 未完全遵循 XDG Base Directory 规范（相关 Issue #2638）。用户期望将 CLI 状态存储在 ~/.config/context7/ 等 XDG 标准位置，而非硬编码的 ~/.context7/。

API 配置

API 端点配置在源码中定义：

资料来源：packages/cli/src/constants.ts

API 请求工具

CLI 使用统一的 API 请求工具处理所有后端通信：

interface ApiConfig {
  baseUrl: string;
  apiKey?: string;
  timeout?: number;
}

// 认证头自动注入
headers: {
  "Authorization": `Bearer ${apiKey}`,
  "Content-Type": "application/json"
}

资料来源：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

技能安装路径

技能文件命名规范：context7-mcp/

资料来源：packages/cli/src/setup/templates.ts

工作流程图

完整文档查询流程

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: 显示文档结果

多代理集成架构

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 #59）— 用户希望能够自建文档后端
• 文档版本控制（Issue #45）— 支持特定版本标签的文档检索

相关资源

参见

• MCP 服务器参考 — MCP 协议集成详细说明
• SDK 集成指南 — 编程方式访问 Context7 API
• AI SDK 工具 — Vercel AI SDK 集成包
• 故障排除指南 — 常见问题与解决方案

概述

Context7 MCP（Model Context Protocol）服务器是连接 AI 编码助手与文档服务的桥梁。该服务器基于 Model Context Protocol SDK 构建，为 AI 助手提供实时的、版本特定的库文档访问能力。

MCP 服务器的核心价值在于解决 LLM 的训练数据过时问题：

• 无 Context7：LLM 依赖过时的训练数据，产生幻觉 API 和过时代码示例
• 有 Context7：直接从源码仓库拉取最新文档，注入到 LLM 上下文

资料来源：README.md

概述

Context7 项目提供了两个核心 TypeScript 包，用于将文档检索能力集成到 AI 应用中：

解决的问题

LLM 依赖于过时或泛化的训练数据来回答关于第三方库的问题，这会导致：

• 基于数年前训练数据生成的代码示例
• 不存在但被"幻觉"出的 API
• 针对旧版本包的通用答案

Context7 SDK 通过提供最新的、版本特定的文档和代码示例来解决这些问题。

资料来源：packages/sdk/README.md:1-20

概述

Context7 提供与多种 AI 编码助手的深度集成，使这些助手能够在对话过程中自动获取最新的库文档和代码示例。通过 Context7，AI 助手可以访问来自源代码仓库的实时、准确的文档信息，有效解决 LLM 训练数据过时和幻觉 API 的问题。 资料来源：plugins/claude/context7/README.md:1-5

Context7 支持两种集成模式：

工作流程

Context7 集成的核心工作流程遵循标准的文档检索模式：

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 实现与编码助手的集成，支持以下助手：

CLI + Skills 模式

对于不支持 MCP 协议的编码助手，Context7 提供了 CLI + Skills 模式，通过技能文件引导代理使用命令行工具：

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/，包含以下组件：

安装方式

通过 Claude Code 插件市场安装：

claude plugin marketplace add upstash/context7
claude plugin install context7-plugin@context7-marketplace

资料来源：plugins/claude/context7/README.md:15-20

文档研究员代理

docs-researcher 是一个轻量级代理，专门用于获取库文档而不污染主要对话上下文：

概述

@upstash/context7-pi 是 Context7 官方为 pi coding agent 提供的扩展集成包。该扩展使 pi 代理能够通过调用 Context7 的文档检索工具，获取最新的库文档、API 参考和代码示例。

资料来源：packages/pi/README.md:1-8

核心功能

该扩展为 pi 代理添加了以下能力：

资料来源：packages/pi/README.md:21-26

版本历史

资料来源：packages/pi/CHANGELOG.md

安装与配置

安装步骤

使用 npm 安装 Context7 扩展包：

pi install npm:@upstash/context7-pi

资料来源：packages/pi/README.md:10

身份验证

扩展包在无需认证的情况下即可使用，系统将基于 IP 进行速率限制。如需更高的配额限制，需从 context7.com/dashboard 获取免费 API 密钥，并将其导出为环境变量：

export CONTEXT7_API_KEY=ctx7sk_...

资料来源：packages/pi/README.md:12-18

建议将环境变量配置在 shell 启动文件（如 .bashrc 或 .zshrc）中，以确保 pi 每次启动时都能读取到密钥。

架构设计

组件交互流程

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 兼容的库标识符。

输入参数：

输出示例：

{
  "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

#### query-docs 工具

query-docs 工具根据 Context7 兼容的库 ID 获取文档内容。

输入参数：

输出内容：

返回与查询相关的文档片段，包含代码示例和 API 参考信息。

资料来源：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

技能配置参数

工作流程详解

标准文档查询流程

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 返回多个匹配结果时，应按以下优先级进行选择：

资料来源：packages/pi/prompts/c7-docs.md

速率限制与配额

认证模式

资料来源：packages/pi/README.md:12-18

常见错误处理

与其他 MCP 客户端的兼容性

Context7 为多种编码代理提供官方扩展支持，包括：

所有客户端的工具描述、错误消息格式和线缆协议保持一致，确保 LLM 能够获得统一的体验。

资料来源：packages/pi/CHANGELOG.md

隐私与安全

• Context7 扩展遵循 Context7 的隐私政策
• 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 检查 Key 状态。

相关资源

• Context7 官方文档
• pi coding agent 官网
• @upstash/context7-pi 发布说明
• Context7 客户端列表

参见

• MCP 服务器配置
• CLI 安装指南
• Vercel AI SDK 集成
• 库添加指南

概述

Context7 通过 Model Context Protocol (MCP) 提供统一的文档查询能力，支持 30+ 种不同的 AI 编码客户端。系统设计采用双模式架构：

• CLI + Skills 模式：通过 ctx7 命令行工具和安装的技能引导代理获取文档（无需 MCP）
• MCP 模式：注册 Context7 MCP 服务器，使代理可以直接调用文档工具

资料来源：README.md:1-30

支持的客户端

官方集成客户端

MCP 协议兼容客户端

通过标准 MCP 配置，以下客户端均可使用 Context7：

资料来源：docs/resources/all-clients.mdx

MCP 工具接口

Context7 MCP 服务器提供两个核心工具：

resolve-library-id

解析包名或产品名为 Context7 兼容的库 ID。

返回结果：

{
  "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 查询文档。

资料来源：packages/mcp/src/index.ts:30-80

配置架构

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 安装过程会自动检测当前开发环境支持的客户端：

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

各客户端配置详解

Claude Code 配置

Claude Code 通过插件系统集成 Context7：

# 添加市场并安装插件
claude plugin marketplace add upstash/context7
claude plugin install context7-plugin@context7-marketplace

MCP 配置示例（.mcp.json）：

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {
        "CONTEXT7_API_KEY": "ctx7sk_..."
      }
    }
  }
}

资料来源：plugins/claude/context7/.mcp.json

可用资源：

• agents/docs-researcher.md：轻量级代理，用于获取库文档
• Skills：自动触发文档查找的技能文件

Cursor 配置

Cursor 使用标准的 MCP 配置文件：

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {
        "CONTEXT7_API_KEY": "ctx7sk_..."
      }
    }
  }
}

资料来源：plugins/cursor/context7/mcp.json

pi 代理配置

pi 是 Context7 官方支持的编码代理：

# 安装
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

Smithery 配置

Smithery 是一个 MCP 客户端市场，支持一键安装：

# smithery.yaml
name: Context7
packageUrl: npm:@upstash/context7-mcp
installationCommand: npx -y @upstash/context7-mcp

资料来源：packages/mcp/smithery.yaml

Power 模式配置

Context7 提供专门的 Power 插件：

{
  "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

认证机制

API Key 配置

# 方式 1：环境变量
export CONTEXT7_API_KEY=ctx7sk_xxxxxxxxxxxx

# 方式 2：CLI 交互式认证
npx ctx7 setup

无认证使用

Context7 支持无 API Key 使用，采用 IP 限流：

• 无认证：标准 IP 限流
• 有 API Key：更高配额

// MCP 服务器认证处理
const auth = {
  type: "bearer",
  token: process.env.CONTEXT7_API_KEY || ""
};

资料来源：packages/mcp/src/index.ts:1-30

工具描述与指令

MCP 服务器会返回详细的工具描述和系统指令：

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

常见问题

配置文件路径

速率限制

• 无 API Key：基于 IP 的速率限制
• 有 API Key：更高调用配额
• 建议：开发环境使用免费 Key，生产环境申请更高配额

库 ID 格式

Context7 使用统一的库 ID 格式：

/org/project           # 主版本
/org/project@version   # 指定版本（如 /vercel/[email protected]）

故障排除

MCP 连接失败

1. 检查 MCP 配置文件的 JSON 语法
2. 确认 npx -y @upstash/context7-mcp 可正常执行
3. 验证环境变量 CONTEXT7_API_KEY 设置正确

工具调用超时

大型文档库（如超过 100 万 token）可能需要更长的响应时间：

• 检查网络连接
• 考虑使用更具体的查询词
• 等待库刷新完成后再试

库未找到

确保使用正确的库名：

• 使用官方库名（如 "Next.js" 而非 "nextjs"）
• 检查版本号是否正确
• 访问 context7.com 确认库已收录

See Also

• 官方文档
• API 参考
• 添加新库
• 故障排除指南
• 开发者指南

概述

Context7 的库管理系统是整个平台的核心组件。它负责：

• 库注册：将新的文档库提交到 Context7 进行索引
• 库认领：允许官方维护者认领和管理其库的页面
• 库验证：确保库文档的准确性和完整性
• 库更新：处理文档刷新和迁移请求

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 提交：适用于托管文档网站

提交要求

资料来源：docs/adding-libraries.mdx

提交配置

库的配置通过 context7.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 - 该库大小为 3,408,440 tokens，需要手动触发刷新。

资料来源：docs/library-updates.mdx

库认领与所有权

认领流程

官方库维护者可以通过认领流程获得其库页面的管理权限。

sequenceDiagram
    participant 申请者
    participant Context7系统
    participant 原始维护者
    
    申请者->>Context7系统: 提交认领请求
    Context7系统->>原始维护者: 发送验证邮件
    原始维护者->>Context7系统: 确认转让
    Context7系统->>申请者: 授予管理权限

认领条件

资料来源：docs/howto/claiming-libraries.mdx

库迁移

当库文档从旧仓库迁移到新仓库时，需要提交迁移请求：

1. 更新 Context7 页面指向新文档位置
2. 归档旧仓库或设置重定向
3. 通知用户新的文档地址

参见社区讨论：racletteJs 库迁移请求 - 该框架将文档从独立仓库移入 monorepo。

库验证

验证类型

验证清单

库验证通常检查以下项目：

• [ ] README 文件是否完整
• [ ] API 文档是否覆盖所有公开接口
• [ ] 代码示例是否可运行
• [ ] 版本信息是否准确
• [ ] 文档是否与实际代码同步

参见社区讨论：Carbon Design System 验证请求 - 报告缺少 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 创建新 Issue
2. 选择 "Refresh request" 模板
3. 提供库的 Context7 ID
4. 说明需要刷新的原因

参见社区讨论：/openai/openai-cookbook 刷新请求 - 因新版本更新触发的文档刷新。

更新通知

库更新完成后，系统会：

1. 更新 Context7 网站上的文档内容
2. 重新计算库的 token 数量
3. 更新版本信息

网站类型库的特殊处理

自定义域名问题

对于托管在自定义域名上的文档网站，可能存在索引问题：

参见社区讨论：自定义域名索引问题 - 同站点在 Vercel.app 可正常索引 163 页，自定义域名仅索引 4 页。

Vercel 部署建议

对于 Vercel 托管的文档网站：

1. 使用 Vercel 提供的默认域名进行初始配置
2. 确认 Base URL 设置正确
3. 等待系统完成完整爬取

API 参考

库管理端点

请求示例

// 解析库 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 响应中的提示注入 - 系统偶尔会在响应中嵌入非文档内容。

防护措施：

• 验证所有返回内容的来源
• 不要执行响应中的任何命令
• 报告可疑的响应内容

安全与隐私

数据存储

Context7 遵循 XDG Base Directory Specification 存储配置文件：

参见社区讨论：XDG 合规性请求 - 用户请求使用 XDG 标准目录。

隐私政策

详情请参阅 Upstash 隐私政策。

相关资源

• 添加新库指南 - 完整的库提交教程
• API 参考文档 - REST API 详细说明
• 故障排除指南 - 常见问题解答
• 所有客户端支持 - 30+ 客户端集成指南

参见

• Context7 概览 - 平台整体介绍
• MCP 服务器配置 - MCP 工具配置指南
• CLI 使用指南 - 命令行工具使用教程
• AI SDK 集成 - 与 Vercel AI SDK 集成

概述

本页面介绍如何在企业环境中部署和配置 Context7。Context7 是一个为 AI 编码助手提供最新库文档的服务，支持通过 MCP（Model Context Protocol）或 CLI 模式与各种编码代理集成。

注意：目前官方仓库中尚未提供独立的企业部署文档（如 docs/enterprise/ 目录），本指南基于现有代码库架构和企业用户常见需求编写。

部署架构

Context7 支持两种主要的部署模式：

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

CLI + Skills 模式

CLI 模式安装一个指导代理使用 ctx7 CLI 获取文档的技能，无需 MCP 支持：

npx ctx7 setup

该命令会进行 OAuth 认证、生成 API 密钥并安装适当的技能。

资料来源：README.md

主流代理集成配置

支持的代理平台

资料来源：packages/cli/src/setup/agents.ts

Claude Code 插件安装

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

Cursor IDE 集成

提供专用的 docs-researcher 代理，用于在不干扰主对话上下文的情况下获取库文档。

MCP 服务器配置

服务器端点

MCP 服务器默认连接到 https://context7.com/api：

{
  "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

工具注册

MCP 服务器注册以下工具：

MCP 清单配置

{
  "compatibility": {
    "platforms": ["darwin", "win32", "linux"],
    "runtimes": {
      "node": ">=v18.0.0"
    }
  }
}

资料来源：packages/mcp/mcpb/manifest.json

API 密钥管理

获取 API 密钥

1. 访问 context7.com/dashboard 获取免费 API 密钥
2. 无密钥使用时适用基于 IP 的速率限制

环境变量配置

export CONTEXT7_API_KEY=ctx7sk_...

对于 pi 编码代理，需要在 shell 配置文件中设置此环境变量。

MCP 认证配置

MCP 配置支持两种认证传输方式：

// stdio 模式
buildEntry: (auth, transport) => 
  transport === "stdio" ? stdioEntry(auth) : withHeaders({ httpUrl: mcpUrl(auth) }, auth)

资料来源：packages/cli/src/setup/agents.ts

企业环境考虑

防火墙和网络要求

Context7 MCP 需要访问以下端点：

数据隐私

• 文档查询仅传输查询文本和库标识符
• 不上传用户代码
• 隐私政策：https://upstash.com/trust/context7addendum.pdf

速率限制

常见问题

MCP 配置解析错误

在 ctx7 remove 命令执行期间，如果 MCP 配置文件格式不正确（如手动的 ~/.claude.json），系统现在会跳过无法解析的文件而非崩溃：

[email protected] patch: Handle malformed MCP config files gracefully during agent detection.

资料来源：[email protected] Release Notes

库文档过期

大型库的文档可能无法自动刷新：

提示注入防护

系统会定期处理 query-docs 响应中的提示注入问题。建议在使用外部库文档时实施适当的内容过滤。

相关资源

参见

• MCP 服务器部署 - MCP 服务器详细配置
• CLI 安装指南 - ctx7 CLI 工具安装
• SDK 集成 - 编程式 SDK 使用
• 编码代理插件 - 各 IDE 插件详情

概述

Context7 的安全体系旨在为 AI 编码助手提供可靠的文档检索服务，同时确保用户数据的机密性和完整性。系统采用行业标准的安全协议，包括传输层加密、API 密钥管理和细粒度的访问控制。

核心安全特性包括：

资料来源：docs/security/overview.mdx

认证机制

API Key 认证

Context7 支持通过 API Key 进行身份验证。用户需要在 Context7 仪表盘 生成 API Key，并在使用 CLI 或 SDK 时通过环境变量配置。

#### 环境变量配置

# 设置 Context7 API Key
export CONTEXT7_API_KEY=ctx7sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API Key 采用 ctx7sk_ 前缀格式，用于标识 Context7 服务密钥类型。在 MCP 工具调用和 CLI 命令中，系统会自动读取该环境变量进行认证。

资料来源：docs/howto/api-keys.mdx

#### CLI 认证流程

CLI 工具支持两种认证方式：

1. OAuth 认证 - 通过 ctx7 setup 命令启动交互式 OAuth 流程
2. API Key 认证 - 直接使用环境变量中的 API Key

# 启动交互式设置
npx ctx7 setup

# CLI 会自动检测 CONTEXT7_API_KEY 环境变量
ctx7 generate

CLI 在执行命令前会检查认证状态，若未配置 API Key 且无可用 OAuth Token，将提示用户进行认证。

资料来源：packages/cli/src/utils/auth.ts

MCP 服务器认证

Context7 MCP 服务器实现了一套完整的认证体系，用于验证来自 AI 客户端的请求。

#### MCP 工具注册与描述

MCP 服务器注册时提供完整的服务元数据，包括版本、描述和图标信息：

{
  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

#### JWT Token 验证

MCP 服务器使用 JWT (JSON Web Token) 进行请求验证。JWT 提供了轻量级的身份认证机制，适合分布式系统的安全通信。

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

认证提示模板

MCP 服务器使用预定义的认证提示模板，确保 AI 代理正确理解何时以及如何使用 Context7 服务：

`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

数据安全

传输层安全

所有 Context7 API 通信均通过 HTTPS/TLS 加密传输，确保数据在传输过程中不被窃听或篡改。

资料来源：docs/security/data-safety.mdx

数据加密

#### 配置文件加密

本地存储的敏感配置（如认证 Token）经过加密处理，防止未经授权的访问。

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

数据隐私

Context7 承诺严格保护用户隐私数据：

资料来源：docs/security/data-privacy.mdx

访问控制

MCP 工具权限

Context7 MCP 服务器实现了基于工具的访问控制策略：

#### 工具使用约束

// 工具调用前的权限检查流程
1. 验证 JWT Token 有效性
2. 检查 API Key 配额限制
3. 验证请求来源
4. 记录审计日志

资料来源：docs/security/auth-and-access-control.mdx

速率限制

Context7 对 API 请求实施速率限制以防止滥用：

用户可免费获取 API Key 以获得更高的请求配额。

资料来源：packages/pi/README.md

基础设施安全

安全架构

Context7 部署在安全的基础设施上，采用多层次的安全防护：

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

隐私政策与合规

Context7 遵循严格的隐私保护原则：

• 数据最小化：仅收集服务必需的数据
• 目的限制：数据仅用于提供服务
• 安全存储：采用行业标准加密算法
• 用户控制：用户可删除其账户数据

详细信息请参阅 Upstash 隐私政策附录。

资料来源：plugins/context7-power/POWER.md

最佳实践

安全使用指南

#### 1. API Key 管理

# ✓ 推荐：在 shell 配置文件中设置
echo 'export CONTEXT7_API_KEY=ctx7sk_xxxx' >> ~/.bashrc

# ✗ 不推荐：将 Key 硬编码在代码中
# export CONTEXT7_API_KEY=ctx7sk_xxxx  # 危险！

#### 2. 环境变量配置

确保 API Key 不会意外泄露到版本控制系统：

# .gitignore
.env
.env.local
.env.*.local

#### 3. MCP 配置安全

当使用 MCP 客户端时，确保配置文件权限正确：

# 设置配置文件权限为仅所有者可读
chmod 600 ~/.config/context7/config.json

#### 4. 敏感数据保护

• 禁止在 query-docs 的 query 参数中传递 API Keys、密码或个人数据
• 避免在查询中包含专有代码

// ✓ 安全
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

常见安全问题与解决方案

资料来源：docs/security/best-practices.mdx

CLI 安全配置

配置文件位置

CLI 工具将认证状态存储在本地配置中：

注意：当前实现使用 ~/.context7/ 目录，这不符合 XDG Base Directory Specification。社区已提出 XDG 合规性改进建议，建议将配置存储在 $XDG_CONFIG_HOME/context7 目录。

认证状态管理

# 检查当前认证状态
ctx7 status

# 重新认证
ctx7 setup

# 移除认证（从所有代理）
ctx7 remove

ctx7 remove 命令会智能检测已安装 Context7 的代理，包括 Claude Code、Codex 等，并从相应配置中移除 Context7 相关设置。该命令能够优雅处理格式损坏的配置文件。

资料来源：[email protected] 发行说明

安全报告与支持

漏洞报告

若发现安全漏洞，请通过以下方式报告：

• 安全邮箱：[email protected]
• GitHub Security Advisory：使用 GitHub 的安全报告功能

请勿在公开 Issue 中讨论安全漏洞。

合规报告

Context7 提供以下合规相关文档：

• SOC 2 Type II 合规状态
• GDPR 合规说明
• 数据处理协议 (DPA)

资料来源：docs/security/compliance-and-reporting.mdx

相关文档

• API 密钥指南
• 故障排除
• 本地开发指南
• 所有 MCP 客户端

另请参阅

• Context7 MCP 服务器 - MCP 集成指南
• CLI 安装与配置 - 命令行工具使用
• AI SDK 集成 - Vercel AI SDK 工具

Pitfall Log / 踩坑日志

项目：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: [email protected]

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: [email protected]
• 对用户的影响：Upgrade or migration may change expected behavior: [email protected]
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [email protected]. 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 | [email protected]

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/[email protected]

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: @upstash/[email protected]
• 对用户的影响：Upgrade or migration may change expected behavior: @upstash/[email protected]
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: @upstash/[email protected]. 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/[email protected]

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/[email protected]

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: @upstash/[email protected]
• 对用户的影响：Upgrade or migration may change expected behavior: @upstash/[email protected]
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: @upstash/[email protected]. 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/[email protected]

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