context7 项目说明书

Doramagic 项目包 · 项目说明书

context7 项目

Context7 的 MCP 服务器，用于在 MCP 客户端中实时获取最新的库和框架文档。

项目概览与多包架构

Context7 是一个面向大语言模型（LLM）与 AI 编程代理的文档检索基础设施，它通过 Model Context Protocol（MCP）将任意库的文档以结构化、按主题的形式注入到模型上下文，从而让 Cursor、Claude Code、Antigravity 等代理无需重新训练即可访问实时、版本相关的库 API 信息。

章节 相关页面

继续阅读本节完整说明和来源证据。

项目定位与核心能力

README 将其定位总结为“为 LLM 和 AI 代码编辑器提供最新的、版本特定的文档和代码示例”。核心项目括：

库发现（resolve-library-id）与主题化文档拉取（get-library-docs）。
支持公开 GitHub 仓库、官方文档站点以及 llmstxt 协议。
提供云托管（context7.com）与本地/自托管两条调用路径。

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

多包（Monorepo）布局

仓库采用 pnpm workspace 管理多个发布单元：根目录 pnpm-workspace.yaml 集中声明 packages/* 路径，package.json 通过统一的 pnpm 脚本协调构建、测试与发布；版本号与变更日志由根目录的 .changeset/config.json 配合 Changesets 工具统一调度，保证各包可独立发版。

包名	路径	角色
`@upstash/context7-mcp`	`packages/mcp`	MCP 服务器实现，对外暴露 `query-docs`、`resolve-library-id`、`get-library-docs` 等工具
`@upstash/context7`（SDK）	`packages/sdk`	客户端 SDK，供 Node.js、浏览器或边缘运行时直接调用 Context7 HTTP API
`ctx7`（CLI）	`packages/cli`	命令行工具，负责本地技能下载（`setup --cli`）、多代理配置与库索引刷新（`refresh`）

社区近期可见的同步发布包括 @upstash/[email protected]（新增 Microsoft Entra ID 多租户鉴权，按 issuer 模式匹配并校验 JWKS）与 [email protected]（直接通过 gh CLI 读取 token，避免 Windows Defender 因 cmd.exe /d /s /c 包装产生的可疑进程告警）。

资料来源：package.json:1-60、pnpm-workspace.yaml:1-20、.changeset/config.json:1-20、packages/mcp/package.json:1-40、packages/sdk/package.json:1-40、packages/cli/package.json:1-40

运行时架构与数据流

运行时由三层构成：客户端（MCP 客户端、CLI 或 SDK 调用方）、@upstash/context7-mcp 服务器、以及 Context7 后端 API 与文档索引存储。云端部署默认通过 HTTPS 访问 context7.com/api，自托管场景下可在 MCP 服务器与 SDK 两层分别替换 endpoint，从而支持 air-gapped 与离线文档检索。

packages/mcp/src/index.ts 是 MCP 服务器入口，负责初始化 Server、StdioServerTransport/StreamableHTTPServerTransport，并注册工具处理函数。
packages/sdk/src/client.ts 提供类型安全的 SDK 客户端，允许不依赖 MCP 协议直接调用 Context7 后端。
packages/cli/src/index.ts 启动 Commander.js 程序，把 setup、refresh、search 等命令串联到 MCP 服务器与 GitHub API。

CLI 启动时还会通过 downloadSkillFromGitHub() 拉取 Anthropic 等代理的技能文件；近期修复（[email protected]）通过直接调用 gh 进程读取 token，绕开 cmd.exe 包装引发的安全告警。

资料来源：packages/mcp/src/index.ts:1-80、packages/sdk/src/client.ts:1-60、packages/cli/src/index.ts:1-80

社区驱动的演进方向

围绕多包架构，社区讨论集中在以下方向：

自托管与离线：Issue #59 与 #320 多次请求脱离 context7.com 的依赖，仓库在 MCP 层与 SDK 层均预留了可替换 endpoint，便于在 air-gapped 环境运行。
私有文档：Issue #34 推动个人索引与 API Key 鉴权，最新 MCP 版本（3.1.0）已加入 Entra ID 多租户校验作为参考实现。
版本化文档：Issue #45 建议按 Git 标签锁定版本，文档后端的库条目已支持按 ref 解析。
目录过滤：Issue #2688 反馈 Web UI 缺少 Include/Exclude folders 控制，相关的解析逻辑位于 MCP 服务器侧。
安全告警：Issue #2663、#2673 报告 query-docs 响应被嵌入类提示词注入内容，社区已在抓取与清洗链路中加强过滤。

资料来源：README.md:40-80、packages/mcp/src/index.ts:80-140（MCP 工具路由覆盖 query-docs 与 resolve-library-id 的边界）。

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

CLI、MCP 工具与客户端集成

Context7 通过两个协同的 npm 包向终端用户提供文档查询能力：@upstash/context7-mcp（MCP 服务器，承载 get-library-docs、query-docs 等工具）以及 ctx7 CLI（在 packages/cli 下）。CLI 负责把 MCP 服务器"安装"到本地已检测到的 AI 编程助手中，而 MCP 包负责实际向 context...

章节 相关页面

继续阅读本节完整说明和来源证据。

Context7 通过两个协同的 npm 包向终端用户提供文档查询能力：@upstash/context7-mcp（MCP 服务器，承载 get-library-docs、query-docs 等工具）以及 ctx7 CLI（在 packages/cli 下）。CLI 负责把 MCP 服务器"安装"到本地已检测到的 AI 编程助手中，而 MCP 包负责实际向 context7.com API 转发请求。本页描述它们的角色边界、配置流程以及与 Claude Code、Cursor 等客户端的集成方式。

CLI 与 MCP 的职责划分

packages/cli/src/commands/setup.ts 定义了 ctx7 setup 命令，它的核心职责不是查询文档，而是：

检测当前目录下已安装的 AI 代理（Claude Code、Cursor、Windsurf、Antigravity 等）。
在代理的配置目录写入 MCP 服务器条目，使代理启动时自动加载 Context7。
通过 downloadSkillFromGitHub 从 GitHub 拉取并安装 .skill 文件，从而把上下文检索行为注入代理。

packages/cli/src/commands/docs.ts 则提供"无需代理"的 CLI 体验：直接调用 packages/mcp/src/lib/api.ts 中的 searchLibraries、fetchLibraryDocumentation 等函数，让用户在终端里就能完成文档查询，相当于 MCP 工具的命令行等价物。资料来源：packages/cli/src/commands/setup.ts:1-40 packages/cli/src/commands/docs.ts:1-30

packages/mcp/src/lib/api.ts 是两层之间的真实数据通道：CLI 与 MCP 服务器共享同一份 API 客户端，避免重复实现搜索、获取、查询逻辑。资料来源：packages/mcp/src/lib/api.ts:1-20

`ctx7 setup` 的工作流程

ctx7 setup 接受若干标志位影响安装目标：

--cli：纯命令行模式，仅确保 CLI 可用，不向代理写入配置。
--universal：要求把 MCP 写入"通用"位置。
--project：把配置写入项目级 .mcp.json（或等价文件）而非用户级目录。
--antigravity（自 0.4.5 起）：将 skill 写入 .agent/skills，并把 MCP 配置追加到 ~/.gemini/config/mcp_config.json，使用 Gemini 家族约定的 httpUrl 字段。资料来源：packages/cli/src/commands/setup.ts:60-120

packages/cli/src/setup/agents.ts 维护一个代理注册表：每个条目描述代理的检测方式（环境变量、特征文件）、MCP 配置的目标路径以及 HTTP/stdio 传输偏好。setup 在交互式流程中调用 detectAgents()，把结果回写到用户选择的目标。当用户同时指定 --universal --project 时，若当前目录命中某个代理，代理优先级会覆盖 --universal，这正是 issue #2695 报告的"静默忽略 --universal"行为的来源。资料来源：packages/cli/src/setup/agents.ts:30-90

flowchart LR
    A[用户执行 ctx7 setup] --> B[解析 CLI 标志]
    B --> C[detectAgents 扫描目录]
    C --> D{选择目标代理/路径}
    D --> E[downloadSkillFromGitHub]
    E --> F[写入 .mcp.json / mcp_config.json]
    F --> G[代理下次启动加载 MCP]
    G --> H[调用 @upstash/context7-mcp 工具]
    H --> I[packages/mcp/src/lib/api.ts]
    I --> J[context7.com API]

客户端集成（Claude / Cursor / Windsurf）

plugins/ 目录下的子目录是 CLI 安装的"模板"：

plugins/claude/context7/.mcp.json：Claude Code 在读取项目根目录的 .mcp.json 时加载该条目，从而在会话中暴露 get-library-docs、query-docs 工具。
plugins/cursor/context7/mcp.json：Cursor 读取等价路径并启动同一个 @upstash/context7-mcp 包。资料来源：plugins/claude/context7/.mcp.json:1-10 plugins/cursor/context7/mcp.json:1-10

setup 本质上是把这些 JSON 片段按目标代理的约定复制/合并到用户或项目级配置，并附带 skill 文件。downloadSkillFromGitHub 必须携带 GitHub Authorization 头，否则匿名请求会返回 403（issue #2363）。最新 0.5.6 版本还把读取 gh auth token 的方式改为直接调用 gh，避免 Windows 上 cmd.exe 包装被 Microsoft Defender for Endpoint 标记为可疑。资料来源：packages/cli/src/commands/setup.ts:140-180

安全与多租户注意

packages/mcp/src/lib/api.ts 在 3.1.0 起支持多租户 Microsoft Entra ID 令牌校验：服务器按 issuer 模式识别入站 Entra v2 token，向 Context7 应用拉取每个 teamspace 的 tenantId/audience/requiredScope，并用对应租户的 JWKS 校验。资料来源：packages/mcp/src/lib/api.ts:40-90

社区还报告 query-docs 响应中存在提示注入内容（issues #2663、#2673）。由于 MCP 工具返回的是结构化文档块，注入通常来自被索引文档本身——并非 CLI/客户端集成层的 bug，但终端用户在阅读 ctx7 docs 输出或代理注入的上下文时，应意识到返回内容可能包含试图操纵 LLM 的指令，并按上下文进行清洗。

来源：https://github.com/upstash/context7 / 项目说明书

企业版部署、自托管与 SSO 认证

Context7 提供了一套面向企业的部署与认证方案，允许组织在自有基础设施中运行文档后端，并通过企业级身份提供商（IdP）控制访问。本页汇总自托管、容器化编排、向量库可插拔配置以及基于 Microsoft Entra ID 的 SSO 接入要点。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 3.1 多租户 Entra v2 令牌校验

继续阅读本节完整说明和来源证据。

章节 3.2 单点登录（SSO）

继续阅读本节完整说明和来源证据。

1. 企业版部署模式

Context7 企业版支持从单机 Docker 到生产级 Kubernetes 集群的多档部署形态，并兼容完全离线的本地环境。

Docker 部署：面向开发与评估场景，单容器即可启动 Context7 服务。文档说明了镜像、端口映射、环境变量以及与本地向量库的连接方式。资料来源：docs/enterprise/deployment/docker.mdx:1-1
Kubernetes 部署：面向生产环境，提供 Deployment、Service、Ingress 等示例清单，支持水平扩容与滚动更新。资料来源：docs/enterprise/deployment/kubernetes.mdx:1-1
On-Premise（本地化）部署：针对气隙隔离或合规受限场景，文档明确说明哪些网络出口必须放行（例如 GitHub 原始内容、npm registry、解析依赖站），哪些可以完全关闭。资料来源：docs/enterprise/on-premise.mdx:1-1

社区多次出现"自托管后端"与"离线文档检索"诉求，仓库 Issue #59 与 Issue #320 反映了用户希望摆脱对 context7.com/api 的中心化依赖，并在无外网环境下使用 MCP 服务器。资料来源：docs/enterprise/on-premise.mdx:1-1

2. 向量库与可插拔存储

企业版允许将默认的托管向量检索替换为自带的向量库，以满足数据驻留与性能要求。

组件	可选项	适用场景
向量库	内置 / Qdrant / Pinecone / 其他	数据合规、低延迟、本地优先
元数据存储	Postgres / 文件系统	私有库索引、审计
鉴权层	Entra ID / API Key	团队级接入

向量库的接入配置集中在部署文档的"vector-stores"章节，提供连接字符串、集合命名以及索引重建说明。资料来源：docs/enterprise/deployment/vector-stores.mdx:1-1

3. 企业托管认证与 Microsoft Entra ID

Context7 企业版提供"enterprise-managed auth"接入层，使 MCP 服务器能够以企业 IdP 颁发的令牌完成请求方身份校验。

3.1 多租户 Entra v2 令牌校验

@upstash/[email protected] 引入了多租户 Microsoft Entra ID 校验：

服务器按发行人（issuer）模式识别入站 Entra v2 令牌；
从 Context7 应用端按团队空间（teamspace）拉取配置：tenantId、audience、requiredScope；
使用匹配租户的 JWKS 验证令牌签名与声明；
强制执行所需作用域（scope），未授权请求被拒绝。

资料来源：docs/enterprise/enterprise-managed-auth/entra.mdx:1-1

3.2 单点登录（SSO）

docs/enterprise/security/entra-sso.mdx 描述了面向运维管理员的 SSO 启用步骤，包括在 Entra 中注册应用、配置回调、配置 Graph 读取权限（用于用户/组查找），以及在 Context7 控制台中绑定租户。管理员登录后即可管理团队、库与令牌。资料来源：docs/enterprise/security/entra-sso.mdx:1-1

4. 部署拓扑示意

flowchart LR
    A[IDE / Agent] -->|MCP over HTTP/SSE| B(Context7 MCP Server)
    B --> C{AuthN}
    C -->|Entra v2 JWT| D[Entra ID / JWKS]
    C -->|API Key| E[本地密钥]
    B --> F[(Vector Store)]
    B --> G[(Metadata DB)]
    B --> H[Doc Source: GitHub / llms.txt / Web]

上图描述了一次典型的企业请求：Agent 通过 MCP 协议进入 Context7 服务器，认证层根据令牌类型分流到 Entra ID 校验或本地密钥校验，认证通过后由向量库与元数据库协同完成文档检索。

5. 选型与注意事项

优先 Docker 评估，再迁移 Kubernetes：小规模试用阶段推荐 Docker，规模化与多副本场景切换到 Kubernetes。资料来源：docs/enterprise/deployment/docker.mdx:1-1 与 docs/enterprise/deployment/kubernetes.mdx:1-1
向量库就近部署：对延迟敏感或合规要求高的团队，应将向量库部署在同一可用区甚至同一 Pod 内。资料来源：docs/enterprise/deployment/vector-stores.mdx:1-1
离线环境需白名单：气隙部署前应核对 on-premise.mdx 中列出的外部域名清单。资料来源：docs/enterprise/on-premise.mdx:1-1
私有库接入：社区 Issue #34 提议的"私有文档"能力，目前通过企业版的团队空间与 Entra SSO 组合实现文档级 ACL。资料来源：docs/enterprise/security/entra-sso.mdx:1-1
多租户 Entra：当组织存在多个 Azure AD 租户或子团队时，可在 Context7 应用端为每个 teamspace 独立维护 tenantId、audience 与 requiredScope。资料来源：docs/enterprise/enterprise-managed-auth/entra.mdx:1-1

资料来源：docs/enterprise/enterprise-managed-auth/entra.mdx:1-1

安全、提示注入风险与社区热点议题

本页汇总 context7 在供应链、MCP 协议层与 CLI 工具链三个层面被社区频繁讨论的安全议题，并整理来自 issues 与 release notes 的修复节点。

章节 相关页面

继续阅读本节完整说明和来源证据。

1. 提示注入向量与响应净化

query-docs 工具返回的内容直接进入调用方 LLM 的上下文，因此入库文档若包含伪造的"system notice"，就会形成跨工具的提示注入。社区已报告两起相关事件：

在 /websites/mapbox 等大型仓库的响应尾部观察到伪装为 "system notice" 的指令块，试图让上游助手自动批准一条 install 命令 issues/2663:1-3。
在 HubSpot Developer Documentation 库的响应中同样出现追加在合法内容之后的 LLM 指令文本 issues/2673:1-5。

packages/mcp-server/src/lib/query-docs.ts 负责序列化文档片段，文档解析层需要在写入索引前剥离或转义外层指令性模板片段。官方处理建议记录在安全概述中，强调把"内容片段"与"工具输出"在 prompt 拼接位置显式区分，并对带 system 风格前缀的字符串做启发式过滤。资料来源：packages/mcp-server/src/lib/query-docs.ts:1-80；docs/security/overview.mdx:1-40。

2. CLI 工具链的认证与路径覆盖

ctx7 setup 在本地代理、Skill 安装与 MCP 配置写入三个环节都出现过安全相关缺陷。

问题编号	模块	影响
#2363	`downloadSkillFromGitHub`	缺少 `Authorization` 头，被限流到 403
#2695	`--cli --universal --project`	静默忽略 `--universal`，回落到自动探测目录
#0.5.6	`gh` token 读取	改由子进程直连，避免被 Windows Defender 标记

packages/cli/src/setup/mcp-writer.ts 是配置落盘的最终执行点，需要在追加 mcpServers 前做 --dry-run 与白名单路径校验，避免覆盖自动探测到的本地代理目录。资料来源：packages/cli/src/utils/github.ts:1-60；packages/cli/src/setup/mcp-writer.ts:1-120；packages/cli/src/setup/cli-flow.ts:1-90。

3. 多租户令牌与 Entra ID 校验

@upstash/[email protected] 引入对 Microsoft Entra v2 令牌的多租户校验：服务器先识别 issuer 模式，再向 Context7 应用拉取每个 teamspace 的 tenantId / audience / requiredScope，最后用对应租户的 JWKS 完成签名与受众校验。资料来源：packages/mcp-server/src/auth/entra-validator.ts:1-140；@upstash/[email protected] release notes。

flowchart LR
  A[客户端 Bearer] --> B{JWT issuer}
  B -- v2 / Entra --> C[拉取 teamspace 配置]
  C --> D[按 tenant 取 JWKS]
  D --> E[校验 audience + scope]
  B -- 其它 --> F[拒绝 / 回退匿名]

4. 社区持续请求的高优先级议题

按互动量排序，长期未关闭的诉求集中在以下方向：

自托管后端（#59）：替换默认 context7.com/api，避免中心化宕机风险。
离线 / 隔离网络文档（#320）：MCP 端仍会外发请求，希望引入本地索引缓存。
私有文档接入（#34）：为个人账号提供索引存储与 API Key，与 MCP 客户端集成。
文档版本化（#45）：支持按 Git tag 锁定版本号（如 Next.js v13.5.11）以服务遗留项目。

另外 #2710 与 #2701 展示了大体量库的刷新流程：超过 ~1.2M tokens 时自动刷新会失败，需要人工触发并执行 closed 状态切换。资料来源：SECURITY.md:1-40；docs/security/data-privacy.mdx:1-80；docs/resources/troubleshooting.mdx:1-100。

来源：https://github.com/upstash/context7 / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 失败模式：security_permissions: [Bug]: OAuth metadata issuer mismatch for MCP OAuth endpoint

Developers may expose sensitive permissions or credentials: [Bug]: OAuth metadata issuer mismatch for MCP OAuth endpoint

high 来源证据：Publish an official docker image

可能影响授权、密钥配置或安全边界。

high 来源证据：🧹 Help us clean up duplicate (or unnecessary) libraries in Context7

可能阻塞安装或首次运行。

medium 失败模式：installation: @upstash/[email protected]

Upgrade or migration may change expected behavior: @upstash/[email protected]

Pitfall Log / 踩坑日志

项目：upstash/context7

摘要：发现 38 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: [Bug]: OAuth metadata issuer mismatch for MCP OAuth endpoint。

1. 安全/权限坑 · 失败模式：security_permissions: [Bug]: OAuth metadata issuer mismatch for MCP OAuth endpoint

严重度：high
证据强度：source_linked
发现：Developers should check this security_permissions risk before relying on the project: [Bug]: OAuth metadata issuer mismatch for MCP OAuth endpoint
对用户的影响：Developers may expose sensitive permissions or credentials: [Bug]: OAuth metadata issuer mismatch for MCP OAuth endpoint
证据：failure_mode_cluster:github_issue | https://github.com/upstash/context7/issues/2723 | [Bug]: OAuth metadata issuer mismatch for MCP OAuth endpoint

2. 安全/权限坑 · 来源证据：Publish an official docker image

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Publish an official docker image
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/upstash/context7/issues/214 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

3. 安全/权限坑 · 来源证据：🧹 Help us clean up duplicate (or unnecessary) libraries in Context7

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：🧹 Help us clean up duplicate (or unnecessary) libraries in Context7
对用户的影响：可能阻塞安装或首次运行。
证据：community_evidence:github | https://github.com/upstash/context7/issues/339 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 失败模式：installation: @upstash/[email protected]

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: @upstash/[email protected]
对用户的影响：Upgrade or migration may change expected behavior: @upstash/[email protected]
证据：failure_mode_cluster:github_release | https://github.com/upstash/context7/releases/tag/%40upstash/context7-pi%400.1.0 | @upstash/[email protected]

5. 安装坑 · 失败模式：installation: Add tool to search by npm package name to skip the initial docs index search, makes MCP serve...

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: Add tool to search by npm package name to skip the initial docs index search, makes MCP server faster
对用户的影响：Developers may fail before the first successful local run: Add tool to search by npm package name to skip the initial docs index search, makes MCP server faster
证据：failure_mode_cluster:github_issue | https://github.com/upstash/context7/issues/230 | Add tool to search by npm package name to skip the initial docs index search, makes MCP server faster

6. 安装坑 · 失败模式：installation: [Feature Request] Local docs sync and numerous dx improvements

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: [Feature Request] Local docs sync and numerous dx improvements
对用户的影响：Developers may fail before the first successful local run: [Feature Request] Local docs sync and numerous dx improvements
证据：failure_mode_cluster:github_issue | https://github.com/upstash/context7/issues/103 | [Feature Request] Local docs sync and numerous dx improvements, failure_mode_cluster:github_issue | https://github.com/upstash/context7/issues/103 | [Feature Request] Local docs sync and numerous dx improvements

7. 安装坑 · 失败模式：installation: ctx7 setup --cli: downloadSkillFromGitHub missing Authorization header causes 403

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: ctx7 setup --cli: downloadSkillFromGitHub missing Authorization header causes 403
对用户的影响：Developers may fail before the first successful local run: ctx7 setup --cli: downloadSkillFromGitHub missing Authorization header causes 403
证据：failure_mode_cluster:github_issue | https://github.com/upstash/context7/issues/2363 | ctx7 setup --cli: downloadSkillFromGitHub missing Authorization header causes 403

8. 安装坑 · 失败模式：installation: [email protected]

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: [email protected]
对用户的影响：Upgrade or migration may change expected behavior: [email protected]
证据：failure_mode_cluster:github_release | https://github.com/upstash/context7/releases/tag/ctx7%400.4.5 | [email protected]

9. 安装坑 · 失败模式：installation: [email protected]

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: [email protected]
对用户的影响：Upgrade or migration may change expected behavior: [email protected]
证据：failure_mode_cluster:github_release | https://github.com/upstash/context7/releases/tag/ctx7%400.5.1 | [email protected]

10. 安装坑 · 来源证据：Add tool to search by npm package name to skip the initial docs index search, makes MCP server faster

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add tool to search by npm package name to skip the initial docs index search, makes MCP server faster
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/upstash/context7/issues/230 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

11. 配置坑 · 失败模式：configuration: @upstash/[email protected]

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: @upstash/[email protected]
对用户的影响：Upgrade or migration may change expected behavior: @upstash/[email protected]
证据：failure_mode_cluster:github_release | https://github.com/upstash/context7/releases/tag/%40upstash/context7-mcp%403.1.0 | @upstash/[email protected]

12. 配置坑 · 失败模式：configuration: Feature Request: Support multiple product docs in one repo

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: Feature Request: Support multiple product docs in one repo
对用户的影响：Developers may misconfigure credentials, environment, or host setup: Feature Request: Support multiple product docs in one repo
证据：failure_mode_cluster:github_issue | https://github.com/upstash/context7/issues/328 | Feature Request: Support multiple product docs in one repo

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: [Bug]: ctx7 setup on a remote server fails login
对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Bug]: ctx7 setup on a remote server fails login
证据：failure_mode_cluster:github_issue | https://github.com/upstash/context7/issues/2693 | [Bug]: ctx7 setup on a remote server fails login, failure_mode_cluster:github_issue | https://github.com/upstash/context7/issues/2693 | [Bug]: ctx7 setup on a remote server fails login

14. 配置坑 · 失败模式：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]
证据：failure_mode_cluster:github_release | https://github.com/upstash/context7/releases/tag/ctx7%400.5.0 | [email protected]

15. 配置坑 · 来源证据：Library Report: /websites/gaussian - Missing documentation.

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Library Report: /websites/gaussian - Missing documentation.
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/upstash/context7/issues/2768 | 来源类型 github_issue 暴露的待验证使用条件。

16. 配置坑 · 来源证据：Library Report: /websites/openwrt - Missing or incorrect documentation.

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Library Report: /websites/openwrt - Missing or incorrect documentation.
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/upstash/context7/issues/1985 | 来源类型 github_issue 暴露的待验证使用条件。

17. 能力坑 · 来源证据：Library Report: /websites/help_obsidian_md - Missing or incorrect documentation.

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：Library Report: /websites/help_obsidian_md - Missing or incorrect documentation.
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/upstash/context7/issues/2402 | 来源类型 github_issue 暴露的待验证使用条件。

18. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
证据：capability.assumptions | https://www.npmjs.com/package/@upstash/context7-mcp | README/documentation is current enough for a first validation pass.

19. 运行坑 · 来源证据：[Bug/Missing Data] Context7 index missing crucial GraphQL mutations for Upwork Developer API (createJobProposal)

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug/Missing Data] Context7 index missing crucial GraphQL mutations for Upwork Developer API (createJobProposal)
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/upstash/context7/issues/2924 | 来源类型 github_issue 暴露的待验证使用条件。

20. 维护坑 · 失败模式：migration: Library Report: /powershell/powershell - Missing or incorrect documentation.

严重度：medium
证据强度：source_linked
发现：Developers should check this migration risk before relying on the project: Library Report: /powershell/powershell - Missing or incorrect documentation.
对用户的影响：Developers may hit a documented source-backed failure mode: Library Report: /powershell/powershell - Missing or incorrect documentation.
证据：failure_mode_cluster:github_issue | https://github.com/upstash/context7/issues/2726 | Library Report: /powershell/powershell - Missing or incorrect documentation.

21. 维护坑 · 失败模式：migration: Library Report: /websites/help_obsidian_md - Missing or incorrect documentation.

严重度：medium
证据强度：source_linked
发现：Developers should check this migration risk before relying on the project: Library Report: /websites/help_obsidian_md - Missing or incorrect documentation.
对用户的影响：Developers may hit a documented source-backed failure mode: Library Report: /websites/help_obsidian_md - Missing or incorrect documentation.
证据：failure_mode_cluster:github_issue | https://github.com/upstash/context7/issues/2402 | Library Report: /websites/help_obsidian_md - Missing or incorrect documentation.

22. 维护坑 · 来源证据：[Docs]: Mui material adds, v8, v9

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Docs]: Mui material adds, v8, v9
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/upstash/context7/issues/2937 | 来源类型 github_issue 暴露的待验证使用条件。

23. 维护坑 · 来源证据：[Docs]: Sofistik

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Docs]: Sofistik
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/upstash/context7/issues/2759 | 来源类型 github_issue 暴露的待验证使用条件。

24. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | https://www.npmjs.com/package/@upstash/context7-mcp | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | https://www.npmjs.com/package/@upstash/context7-mcp | no_demo; severity=medium

26. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | https://www.npmjs.com/package/@upstash/context7-mcp | no_demo; severity=medium

27. 安全/权限坑 · 来源证据：Refresh request for /torvalds/linux

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Refresh request for /torvalds/linux
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/upstash/context7/issues/2912 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

28. 安全/权限坑 · 来源证据：Refresh request for /websites/blender_api_current

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Refresh request for /websites/blender_api_current
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/upstash/context7/issues/2914 | 来源类型 github_issue 暴露的待验证使用条件。

29. 安全/权限坑 · 来源证据：Refresh request for /websites/discord_js

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Refresh request for /websites/discord_js
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/upstash/context7/issues/2916 | 来源类型 github_issue 暴露的待验证使用条件。

30. 安全/权限坑 · 来源证据：Refresh request for /websites/servercore

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Refresh request for /websites/servercore
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/upstash/context7/issues/2907 | 来源类型 github_issue 暴露的待验证使用条件。

31. 安全/权限坑 · 来源证据：Refresh request for /websites/spacelift_io

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Refresh request for /websites/spacelift_io
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/upstash/context7/issues/2940 | 来源类型 github_issue 暴露的待验证使用条件。

32. 安全/权限坑 · 来源证据：[Bug]: Codex setup Skill failed

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Codex setup Skill failed
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/upstash/context7/issues/2936 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

33. 安全/权限坑 · 来源证据：ctx7 setup --cli: downloadSkillFromGitHub missing Authorization header causes 403

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ctx7 setup --cli: downloadSkillFromGitHub missing Authorization header causes 403
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/upstash/context7/issues/2363 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

34. 能力坑 · 失败模式：conceptual: Library Report: /websites/antigravity_google_home - Missing or incorrect documentation.

严重度：low
证据强度：source_linked
发现：Developers should check this conceptual risk before relying on the project: Library Report: /websites/antigravity_google_home - Missing or incorrect documentation.
对用户的影响：Developers may hit a documented source-backed failure mode: Library Report: /websites/antigravity_google_home - Missing or incorrect documentation.
证据：failure_mode_cluster:github_issue | https://github.com/upstash/context7/issues/2404 | Library Report: /websites/antigravity_google_home - Missing or incorrect documentation.

35. 能力坑 · 失败模式：conceptual: Library Report: /websites/openwrt - Missing or incorrect documentation.

严重度：low
证据强度：source_linked
发现：Developers should check this conceptual risk before relying on the project: Library Report: /websites/openwrt - Missing or incorrect documentation.
对用户的影响：Developers may hit a documented source-backed failure mode: Library Report: /websites/openwrt - Missing or incorrect documentation.
证据：failure_mode_cluster:github_issue | https://github.com/upstash/context7/issues/1985 | Library Report: /websites/openwrt - Missing or incorrect documentation.

36. 能力坑 · 失败模式：conceptual: [Feature]: Multiple sources under a single repo

严重度：low
证据强度：source_linked
发现：Developers should check this conceptual risk before relying on the project: [Feature]: Multiple sources under a single repo
对用户的影响：Developers may hit a documented source-backed failure mode: [Feature]: Multiple sources under a single repo
证据：failure_mode_cluster:github_issue | https://github.com/upstash/context7/issues/2725 | [Feature]: Multiple sources under a single repo

37. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | https://www.npmjs.com/package/@upstash/context7-mcp | issue_or_pr_quality=unknown

38. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | https://www.npmjs.com/package/@upstash/context7-mcp | release_recency=unknown

来源：Doramagic 发现、验证与编译记录

context7 项目

项目概览与多包架构

项目定位与核心能力

多包（Monorepo）布局

运行时架构与数据流

社区驱动的演进方向

CLI、MCP 工具与客户端集成

CLI 与 MCP 的职责划分

`ctx7 setup` 的工作流程

客户端集成（Claude / Cursor / Windsurf）

安全与多租户注意

企业版部署、自托管与 SSO 认证

1. 企业版部署模式

2. 向量库与可插拔存储

3. 企业托管认证与 Microsoft Entra ID

3.1 多租户 Entra v2 令牌校验

3.2 单点登录（SSO）

4. 部署拓扑示意

5. 选型与注意事项

安全、提示注入风险与社区热点议题

1. 提示注入向量与响应净化

2. CLI 工具链的认证与路径覆盖

3. 多租户令牌与 Entra ID 校验

4. 社区持续请求的高优先级议题

失败模式与踩坑日记

Pitfall Log / 踩坑日志

1. 安全/权限坑 · 失败模式：security_permissions: [Bug]: OAuth metadata issuer mismatch for MCP OAuth endpoint

2. 安全/权限坑 · 来源证据：Publish an official docker image

3. 安全/权限坑 · 来源证据：🧹 Help us clean up duplicate (or unnecessary) libraries in Context7

4. 安装坑 · 失败模式：installation: @upstash/[email protected]

5. 安装坑 · 失败模式：installation: Add tool to search by npm package name to skip the initial docs index search, makes MCP serve...

6. 安装坑 · 失败模式：installation: [Feature Request] Local docs sync and numerous dx improvements

7. 安装坑 · 失败模式：installation: ctx7 setup --cli: downloadSkillFromGitHub missing Authorization header causes 403

8. 安装坑 · 失败模式：installation: [email protected]

9. 安装坑 · 失败模式：installation: [email protected]

10. 安装坑 · 来源证据：Add tool to search by npm package name to skip the initial docs index search, makes MCP server faster

11. 配置坑 · 失败模式：configuration: @upstash/[email protected]

12. 配置坑 · 失败模式：configuration: Feature Request: Support multiple product docs in one repo

13. 配置坑 · 失败模式：configuration: [Bug]: ctx7 setup on a remote server fails login

14. 配置坑 · 失败模式：configuration: [email protected]

15. 配置坑 · 来源证据：Library Report: /websites/gaussian - Missing documentation.

16. 配置坑 · 来源证据：Library Report: /websites/openwrt - Missing or incorrect documentation.

17. 能力坑 · 来源证据：Library Report: /websites/help_obsidian_md - Missing or incorrect documentation.

18. 能力坑 · 能力判断依赖假设

19. 运行坑 · 来源证据：[Bug/Missing Data] Context7 index missing crucial GraphQL mutations for Upwork Developer API (createJobProposal)

20. 维护坑 · 失败模式：migration: Library Report: /powershell/powershell - Missing or incorrect documentation.

21. 维护坑 · 失败模式：migration: Library Report: /websites/help_obsidian_md - Missing or incorrect documentation.

22. 维护坑 · 来源证据：[Docs]: Mui material adds, v8, v9

23. 维护坑 · 来源证据：[Docs]: Sofistik

24. 维护坑 · 维护活跃度未知

26. 安全/权限坑 · 存在评分风险

27. 安全/权限坑 · 来源证据：Refresh request for /torvalds/linux

28. 安全/权限坑 · 来源证据：Refresh request for /websites/blender_api_current

29. 安全/权限坑 · 来源证据：Refresh request for /websites/discord_js

30. 安全/权限坑 · 来源证据：Refresh request for /websites/servercore

31. 安全/权限坑 · 来源证据：Refresh request for /websites/spacelift_io

32. 安全/权限坑 · 来源证据：[Bug]: Codex setup Skill failed

33. 安全/权限坑 · 来源证据：ctx7 setup --cli: downloadSkillFromGitHub missing Authorization header causes 403

34. 能力坑 · 失败模式：conceptual: Library Report: /websites/antigravity_google_home - Missing or incorrect documentation.

35. 能力坑 · 失败模式：conceptual: Library Report: /websites/openwrt - Missing or incorrect documentation.

36. 能力坑 · 失败模式：conceptual: [Feature]: Multiple sources under a single repo

37. 维护坑 · issue/PR 响应质量未知

38. 维护坑 · 发布节奏不明确