context7 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

context7 是一个面向大语言模型（Large Language Model，LLM）和人工智能代码编辑器的代码文档平台。它从源头获取较新的、与版本相关的文档和代码示例，并将这些内容放入模型上下文，以减少过时示例、虚构接口和版本不匹配问题。

根据仓库资料，项目使用 TypeScript 编写，采用 MIT 许可证，默认分支为 master。仓库当前提供的元信息包括 62203 个 Star 和 3015 个 Fork；这些数值来自题述仓库资料，未附带统计时间，因此不应视为持续更新的实时指标。

• 仓库：context7 GitHub 仓库
• 官网与文档：Context7 官网
• 主要接入方式：CLI 加 Skills，或模型上下文协议（Model Context Protocol，MCP）
• CLI 运行环境：Node.js 18 或更高版本
• 建议配置：获取 Context7 API Key 以提高速率限制

定位与目标用户

Context7 解决的是代码生成场景中的文档上下文问题，而不是通用的代码编辑器、编译器或运行时。它的核心路径是：用户在提示词中提出编程任务，Context7 根据库名称和版本取得文档，再把相关内容提供给代理或模型。

它面向需要让编码代理参考外部库文档的个人开发者、团队和 AI 代码编辑器用户。对于正在使用 Next.js、Cloudflare Workers、Supabase 等库或平台的用户，README 中给出了对应的提示词示例；这些示例说明了产品的使用方式，但不等同于对所有库均有相同覆盖范围的承诺。

核心功能

核心功能可以归纳为“按任务检索文档并注入上下文”。README 将它描述为从源头获取最新的、特定版本的文档和代码示例，然后直接放入提示词上下文；实际可用内容仍取决于 Context7 对相应库的收录与处理情况。

版本相关的文档检索

用户可以在提示词中直接写出库的版本，例如 README 使用了“如何配置 Next.js 14 middleware”的示例。触发条件是提示词中包含库、任务以及版本信息；Context7 据此匹配相应版本并返回文档内容。README 没有公布版本匹配算法、缓存策略、返回字段或检索延迟，因此这些实现细节不能由资料推断。

通过 Library ID 缩短匹配路径

当用户已经明确知道目标库时，可以在提示词中加入 Context7 ID，例如 /supabase/supabase。README 说明，斜杠语法用于明确指定要加载的库，使 Context7 可以跳过库匹配步骤，直接获取该库的文档。

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

该示例的输入是自然语言任务、库标识和文档用途；输出是供模型使用的相关 API 与文档上下文。资料没有提供 Library ID 的完整目录、校验规则或错误响应，遇到 ID 无法匹配时应以最新 README 和服务端反馈为准。

CLI 加 Skills 模式

CLI 加 Skills 模式不要求通过 MCP 调用文档工具。根据 README，ctx7 setup 会通过 OAuth 完成认证、生成 API Key，并安装用于引导代理使用 ctx7 CLI 命令的 Skill；用户可以选择 CLI 加 Skills 或 MCP 模式。

该模式的依赖关系是 Node.js、ctx7 CLI、认证流程和目标代码代理。README 明确支持通过 --cursor、--claude 或 --opencode 指定目标代理，但没有列出所有可选代理名称或每个代理的配置文件格式。

MCP 模式

MCP 模式将 Context7 MCP Server 注册到支持 MCP 的客户端，让客户端原生调用文档工具。README 给出的服务器地址为 https://mcp.context7.com/mcp，并要求通过 Authorization: Bearer YOUR_API_KEY 请求头传递 API Key。

MCP 客户端的具体配置格式取决于客户端，官方提供了面向其他客户端的配置说明页面。仓库资料没有给出完整的工具名称、参数模式、返回 JSON 结构或传输层错误码，因此不应自行补齐接口签名。

系统架构与关键模块

从仓库公开文件可以确认，项目采用 monorepo（多包仓库）组织方式，根目录通过 pnpm workspace 管理 packages/* 下的包。根 package.json 公开了 SDK、MCP 和 AI SDK 工具包的构建入口，但题述资料没有给出具体子目录清单。

仓库层级与构建入口

根包名称为 @upstash/context7，其版本为 1.0.0，并标记为私有包。工作区声明为 packages/*，说明可发布组件位于 packages 目录下；不过每个工作区包的名称、版本和源文件结构未在资料中提供。

{
  "name": "@upstash/context7",
  "private": true,
  "version": "1.0.0",
  "workspaces": [
    "packages/*"
  ],
  "scripts": {
    "build": "pnpm -r run build",
    "build:sdk": "pnpm --filter @upstash/context7-sdk build",
    "build:mcp": "pnpm --filter @upstash/context7-mcp build",
    "build:ai-sdk": "pnpm --filter @upstash/context7-tools-ai-sdk build"
  }
}

SDK、MCP 与 AI SDK 工具包

根据根脚本，仓库至少公开了三个可单独构建的目标：@upstash/context7-sdk、@upstash/context7-mcp 和 @upstash/context7-tools-ai-sdk。构建时，build:sdk、build:mcp 和 build:ai-sdk 分别使用 pnpm filter 定位目标包。

仓库还提供递归执行的构建、类型检查、测试、清理、Lint、格式化和发布脚本。具体包如何划分职责、SDK 暴露哪些方法，以及 AI SDK 工具包支持哪些调用方式，官方仓库资料未提供该信息，建议以最新 README 和各工作区包的文档为准。

依赖与运行环境

运行已配置的 CLI 至少需要 Node.js 18；这是 README 对 ctx7 CLI 的明确要求。项目根开发依赖包含 TypeScript、ESLint、Prettier、Changesets 以及 Inquirer 相关包，但这些依赖主要描述仓库开发与发布环境，并不等同于最终用户必须手动安装的全部运行依赖。

根依赖还包含 @inquirer/core 和 @inquirer/type，版本分别为 ^11.1.1 和 ^4.0.3。仓库未提供操作系统支持矩阵、最低 npm 版本、生产部署镜像或端口清单。

快速开始

最小闭环是安装并配置 CLI，再用带有 use context7 的提示词验证文档注入。README 将认证、API Key 生成和 Skill 安装集中在 npx ctx7 setup 中，因此资料范围内不需要额外拼接未公开的安装命令。

安装与初始化

# 检查 Node.js 版本，要求为 18 或更高版本
node --version

# 初始化 Context7 CLI，并选择 CLI + Skills 或 MCP 模式
npx ctx7 setup

npx ctx7 setup 会启动 OAuth 认证流程、生成 API Key，并安装对应 Skill。交互式选择应根据实际使用的代理模式完成；如果只想针对特定代理，可以使用 README 明确列出的 --cursor、--claude 或 --opencode 参数。

运行与验证

# 针对 Cursor 的示例初始化
npx ctx7 setup --cursor

# 完成初始化后，在已配置的编码代理中提交以下提示词
Create a Next.js middleware that checks for a valid JWT in cookies
and redirects unauthenticated users to `/login`. use context7

验证标准是代理能够按照已配置的 Context7 接入方式获取相关文档和代码示例，而不是仅检查命令是否退出。README 没有提供自动化健康检查命令、固定输出文本或测试 API，因此不应把某个未记录的返回值作为验证依据。

移除配置

# 删除 setup 生成的配置
npx ctx7 remove

# 如果此前使用全局安装方式，则单独移除全局 CLI
npm uninstall -g ctx7

README 说明，npx ctx7 remove 用于移除生成的设置；如果用户曾执行 npm install -g ctx7，则需要另外执行全局卸载命令。资料没有说明该命令是否删除缓存、历史凭据或代理本身的其他配置，清理范围应以实际版本行为和最新文档为准。

配置说明

配置主要分为 Context7 API、MCP HTTP 服务、网络证书、GitHub 集成和 CLI 行为几组。以下字段均来自仓库的 .env.example；示例文件没有为多数字段提供默认值，因此表格中的“未提供”表示资料明确没有给出可直接使用的值。

API Key 推荐从 Context7 Dashboard 获取。README 只说明 API Key 可提高速率限制，没有公布限制数值、计费规则或密钥生命周期，因此不要依据该配置推断具体配额。

进阶用法

进阶使用的重点不是添加未公开的参数，而是让提示词准确表达目标库、版本和任务。明确的库标识可以减少匹配步骤，明确的版本则可以降低模型引用其他版本 API 的风险。

• 已知库的 Context7 ID 时，在提示词中加入 use library /组织名/仓库名 形式的标识。
• 需要版本行为时，在任务中写出明确版本，例如 README 中的 Next.js 14。
• 使用 CLI 加 Skills 时，让代理遵循已安装 Skill 的调用引导。
• 使用 MCP 时，在客户端配置服务器 URL，并通过 Bearer Authorization 传递 API Key。

README 还展示了 Cloudflare Worker 缓存 JSON API 响应和 Supabase 邮箱密码注册等提示词场景。这些示例说明 Context7 可以被放入不同类型的代码任务中，但不表示项目会替用户完成部署、凭据管理、测试或生产变更。

可观测性与运维

仓库资料能够确认的运维配置主要集中在 MCP 订阅、网络代理、证书和遥测开关。MCP_MAX_SUBSCRIPTIONS 的默认值为 0，注释说明 Context7 的 advertised capabilities 是静态的，因此默认禁用订阅。

运行托管 HTTP 部署时，MCP_CLIENT_IP_ASSERTION_KEY 必须与 context7.com 匹配；这是 .env.example 中的原文约束。资料没有给出日志字段、指标名称、追踪系统、健康检查端点、告警阈值、SLA 或容量基准，生产运维方案应在部署前补充这些验证项。

• 检查 API Key 是否通过安全的环境变量或客户端凭据机制注入。
• 检查 MCP 服务地址是否使用 README 指定的 HTTPS 地址。
• 在代理网络中核对 HTTPS_PROXY 与 NODE_EXTRA_CA_CERTS 是否符合组织网络策略。
• 对 GitHub 集成使用单独的 GITHUB_TOKEN 或 GH_TOKEN，不要把令牌写入代码仓库。
• 针对托管 HTTP 部署核对客户端 IP 断言密钥的来源和匹配要求。

安全与合规边界

Context7 涉及 API Key、OAuth、MCP 请求和可选的 GitHub 集成，安全边界主要在凭据保护与文档内容进入模型上下文。它不是授权管理系统，也不是数据脱敏系统；使用者需要自行确认发送给服务和模型的提示词、代码片段及文档内容符合组织政策。

• API Key 只能放在受控的凭据存储或环境变量中，不能提交到 Git 仓库、日志或提示词。
• 对含有私有源代码、客户数据、访问令牌或内部接口的提示词，先确认组织是否允许发送到相关服务。
• 配置 GitHub Token 时遵循最小权限原则，并限制其使用范围；资料未提供所需权限列表，不应擅自扩大权限。
• 仅在已获授权的代码库、开发环境和代理客户端中使用 MCP 服务，不将其用于访问未授权资源。
• 对生成的代码执行人工审查、依赖检查和测试；文档检索结果不能替代安全评审。

仓库资料未提供数据保留期限、区域存储、合规认证、隐私协议、审计日志保证或企业级隔离承诺。需要满足特定监管、数据驻留或内部审计要求时，应在上线前向官方获取明确条款，并以可核查的服务文档为准。

许可证与商用条款

仓库 LICENSE 文件声明项目采用 MIT License，版权标注为 Copyright © 2021 Upstash, Inc.。MIT 条款允许获得者使用、复制、修改、合并、发布、分发、再许可和销售软件副本，具体权利和条件以仓库 LICENSE 为准。

分发软件或其重要部分时，需要保留版权声明和许可声明，并遵守 MIT License 中列出的条件。许可证同时以“按现状”提供软件，不提供明示或默示担保；作者或版权持有人对许可证文本列出的损害责任不承担责任。

因此，按 LICENSE 的文字，商业使用属于许可范围，但商业部署仍需单独评估 Context7 托管服务、API Key、速率限制、第三方文档和组织合规要求。仓库 LICENSE 不等同于托管服务的商业合同、服务等级协议或数据处理协议。

局限性与已知限制

公开资料充分说明了接入方式和提示词用法，但没有给出完整的服务能力边界。使用者应把“文档已被检索”与“生成代码已经正确”视为两个不同阶段，后者仍需编译、测试和人工复核。

• 资料未提供支持库的完整清单、收录同步频率和文档覆盖率。
• 资料未提供 API 和 MCP 工具的完整接口签名、错误码及重试规则。
• 资料未提供速率限制的具体数值、性能数据、并发上限或 SLA。
• 资料未提供操作系统矩阵、容器镜像、生产端口和部署拓扑。
• 资料未说明文档内容的保留周期、脱敏策略和跨区域处理方式。
• 模型仍可能误解检索到的 API，Context7 不能替代版本锁定、测试和代码审查。

以上限制中，明确来自文件缺失的部分均应理解为“官方仓库未提供该信息，建议以最新 README 为准”，而不是对项目实现能力的否定。

适合谁

以下信号表明 Context7 可能适合纳入开发工作流，判断依据是其 README 明确描述的文档注入、版本提示和 CLI/MCP 接入方式。

• 团队使用 AI 代码代理，并且经常需要查询第三方库的 API 文档。
• 项目依赖多个版本变化较快的 JavaScript 或 TypeScript 库，需要在提示词中指定版本。
• 已有支持 MCP 的代码编辑器或代理，希望通过服务端工具获取文档上下文。
• 团队希望用 CLI 和 Skill 统一提示代理如何调用文档，而不是在每次任务中手动复制资料。
• 组织能够接受将符合政策的代码问题和文档请求发送到 Context7 服务，并能管理 API Key。

不适合谁

以下信号说明需要谨慎采用或先完成合规评估；这不是对项目质量的判断，而是对外部文档服务、模型上下文和公开资料边界的现实约束。

• 组织禁止任何源代码、接口信息或技术问题离开内网，且没有经过批准的部署方式。
• 项目要求可审计的离线文档快照，而当前资料未说明 Context7 提供离线模式或固定快照机制。
• 团队需要明确的吞吐量、延迟、可用性和支持承诺，而资料未提供 Benchmark 或 SLA。
• 系统依赖未被 Context7 收录的内部库，且没有自行提供文档接入或库标识的方案。
• 生产发布流程不允许未经测试的模型生成代码直接合并；这种情况下 Context7 只能作为检索辅助，不能替代审核流程。

常见问题与排查（FAQ / Troubleshooting）

排查优先检查 Node.js 版本、初始化模式、API Key 和服务器地址。由于公开资料没有标准诊断命令，以下步骤只使用仓库明确给出的配置和命令。

执行 setup 前需要什么版本的 Node.js

README 要求 ctx7 CLI 使用 Node.js 18 或更高版本。可以先运行 node --version，如果环境不满足要求，应先按组织批准的方式升级 Node.js；仓库没有提供 Node.js 安装包或升级脚本。

CLI 与 MCP 应该如何选择

希望让代理通过 Skill 遵循 CLI 调用引导时，选择 CLI 加 Skills；希望让 MCP 客户端原生调用文档工具时，选择 MCP。README 同时支持两种模式，但没有提供两者在性能、配额或数据处理方面的对比结论。

已经 setup，但代理没有使用 Context7

先确认初始化时选择了正确的代理，或使用了 README 列出的目标参数。随后在提示词中明确加入 use context7，已知库则追加对应的 Library ID；如果仍无效，官方仓库未提供统一诊断输出，建议核对最新 README、客户端配置和 API Key 状态。

MCP 请求如何传递凭据

README 指定服务器 URL 为 https://mcp.context7.com/mcp，并要求通过 Authorization: Bearer YOUR_API_KEY 请求头传递 API Key。示例中的 YOUR_API_KEY 只是占位符，实际值应从受控凭据来源注入，不应把真实密钥写进公开配置或代码片段。

如何撤销 setup 生成的配置

运行 npx ctx7 remove。如果 CLI 是通过 npm install -g ctx7 安装的，还要运行 npm uninstall -g ctx7；这两步分别对应生成的设置和全局安装包。

开发与发布脚本

如果需要参与仓库开发，根 package.json 提供了统一脚本。递归命令会对工作区执行对应脚本，过滤命令则只针对 SDK、MCP 或 AI SDK 工具包。

pnpm build
pnpm build:sdk
pnpm build:mcp
pnpm build:ai-sdk
pnpm typecheck
pnpm test
pnpm test:sdk
pnpm test:tools-ai-sdk
pnpm lint
pnpm lint:check
pnpm format
pnpm format:check
pnpm clean

发布脚本包括 pnpm release，以及使用 Changesets 的 pnpm release:snapshot。资料没有提供贡献流程、分支保护规则、CI 配置、测试覆盖率或发布权限要求；对这些事项有要求的团队应以仓库当前文件和维护者说明为准。

项目地址与资源

以下链接均来自题述仓库资料或 README 中出现的官方站点，可用于获取源代码、文档、客户端接入说明和 CLI 包信息。

• context7 GitHub 仓库
• Context7 官网与文档
• 其他 MCP 客户端安装说明
• Context7 Dashboard
• @upstash/context7-mcp npm 页面
• Cursor MCP 安装入口