Context7 的 ctx7 setup 命令详解：一次配置让 AI 编码 Agent 接上实时文档管道

Context7 的 ctx7 setup 是一条一次性命令，负责把 Context7（面向 LLM 与 AI 代码编辑器的实时库文档服务）接入你的 AI 编码 Agent：MCP server 模式让 Agent 原生调用 Context7 工具，CLI + Skills 模式则安装 find-docs 技能引导 Agent 通过 ctx7 命令取文档。读完本文，你应能完整掌握 ctx7 setup 的全部参数与认证方式、两种模式分别写入了哪些配置文件与规则文件，并能从 CLI 源码层面解释配置合并的幂等性与各 Agent 的适配差异。

两种接入模式：MCP Server 与 CLI + Skills

ctx7 setup 在首次运行时提示你选择接入模式：

• MCP server — 在你的 Agent 配置中注册 Context7 MCP server，Agent 通过 MCP 协议原生调用 resolve-library-id / query-docs 等工具；
• CLI + Skills — 安装一个 find-docs 技能（skill），引导 Agent 使用 ctx7 library 和 ctx7 docs 命令获取文档，无需 MCP。

完整的命令面（继承自 setup 参考文档）：

ctx7 setup                     # 交互式 — 先提示选择模式，再选择 Agent/安装目标
ctx7 setup --mcp               # 跳过提示，使用 MCP server 模式
ctx7 setup --cli               # 跳过提示，使用 CLI + Skills 模式

# MCP 模式 — 指定某个 Agent
ctx7 setup --claude            # 仅 Claude Code
ctx7 setup --cursor            # 仅 Cursor
ctx7 setup --opencode          # 仅 OpenCode

# CLI + Skills 模式 — 指定某个安装位置
ctx7 setup --cli --claude      # Claude Code (~/.claude/skills)
ctx7 setup --cli --cursor      # Cursor (~/.cursor/skills)
ctx7 setup --cli --universal   # Universal (~/.agents/skills)
ctx7 setup --cli --antigravity # Antigravity (~/.config/agent/skills)

ctx7 setup --project           # 配置当前项目而非全局
ctx7 setup --yes               # 跳过确认提示

从源码 registerSetupCommand 可以看到，当前 CLI 注册的完整 flag 集合为：

Flag	作用
--claude / --cursor / --antigravity / --opencode / --codex / --gemini	分别针对 Claude Code、Cursor、Antigravity、OpenCode、Codex、Gemini CLI 配置
--mcp	使用 MCP server 模式
--cli	使用 CLI + Skills 模式（不注册 MCP server）
-p, --project	配置当前项目而非全局
-y, --yes	跳过确认提示
--api-key <key>	使用 API Key 认证
--oauth	使用 OAuth 端点（IDE 自行处理认证流程）
--stdio	将 MCP server 配置为本地 stdio 进程（默认 HTTP）

其中 --stdio 在参考文档中未出现，但它是当前实现的重要能力：HTTP 传输（默认）指向托管端点，stdio 传输则生成 npx -y @upstash/context7-mcp 的本地进程调用。另外从 agents.ts 的 Agent 配置结构看，文档中 --universal 指向的 ~/.agents/skills 目录，正是源码中 OpenCode 与 Codex 两个 Agent 的全局技能目录（~/.agents/skills），属于跨 Agent 的通用技能位置。

模式选择的实现逻辑在 resolveMode：

1. 显式传了 --cli 直接返回 cli 模式；
2. 显式传了 --mcp，或带了 --yes / --oauth / --stdio 之一，直接返回 mcp 模式（后三者都只在 MCP 模式下有意义）；
3. 否则弹出交互式选择，让你二选一。

认证选项：API Key、OAuth 与浏览器登录

参考文档给出的认证选项：

ctx7 setup --api-key YOUR_KEY  # 使用已有 API Key（MCP 与 CLI + Skills 两种模式均支持）
ctx7 setup --oauth             # 使用 OAuth 端点 — 仅 MCP 模式（由 IDE 处理认证流程）

两者都不传时，setup 会打开浏览器进行 OAuth 登录；MCP 模式在登录成功后额外生成一个新的 API key 写入配置。--oauth 仅适用于 MCP 模式。

源码里的认证细节

MCP 模式的认证解析在 resolveAuth / authenticateAndGenerateKey：

• 优先复用本地已登录的有效 token（getValidAccessToken），没有则触发 performLogin() 设备流登录——commands/auth.ts 会渲染一个包含一次性 user code 的终端提示框，按 RFC 8628 展示 verification_uri_complete 与可手动输入的 code；
• 拿到 access token 后，POST 到 /api/dashboard/api-keys 生成一个名为 ctx7-cli-<6位hex> 的新 API key，作为最终写入配置文件的凭据。

也就是说：即使你走的是浏览器登录，MCP 配置文件里落的仍然是一个 API key（以 Authorization: Bearer <key> 头形式），而不是裸的 OAuth 凭据。

各模式/传输方式的凭据落法（见 agents.ts 与 setup.test.ts）：

场景	写入形式
HTTP + API Key	URL 为 https://mcp.context7.com/mcp，并附 headers: { Authorization: "Bearer <key>" }
HTTP + OAuth（--oauth）	URL 为 https://mcp.context7.com/mcp/oauth，不附 header，认证由 IDE 流程完成
stdio + API Key	npx -y @upstash/context7-mcp --api-key <key>
stdio + OAuth	组合不合法，setupMcp 会直接报错退出

Authorization 这个头名并非随意：agents.ts 中的注释 解释了 Codex 依据字面名为 Authorization 的 header 或 bearer_token_env_var 来判断服务器认证模式，其他命名会被视为"未配置凭据"而错误地回落到 OAuth 刷新流程；服务端同时兼容旧的 CONTEXT7_API_KEY 头，保证已有配置继续可用。

CLI + Skills 模式的认证更轻（resolveCliAuth）：

1. 传了 --api-key 则把 API key 作为 bearer token 保存到本地；
2. 本地已有有效 token 直接复用；
3. 否则触发浏览器设备流登录。

此外，已安装的 find-docs 技能本身也支持免登录使用，需要更高配额时可通过环境变量 CONTEXT7_API_KEY 或 ctx7 login 提额（见 find-docs 技能 的 Authentication 一节）。

MCP 模式写入什么

参考文档总结 MCP 模式写入三类内容：

• Agent 配置文件中的 MCP server 条目（Claude 写 .mcp.json，Cursor 写 .cursor/mcp.json，OpenCode 写 .opencode.json）；
• 一个 Context7 规则文件，指示 Agent 在查库文档时使用 Context7；
• Agent 技能目录下的 context7-mcp 技能。

从 agents.ts 的 AgentConfig 表 可以看到每个 Agent 的精确落点（全局 vs 项目作用域）：

Agent	MCP 配置文件（项目 / 全局）	配置节	规则文件（项目 / 全局）	技能目录（全局）
Claude Code	.mcp.json / ~/.claude.json	mcpServers	.claude/rules/context7.md / ~/.claude/rules/context7.md	~/.claude/skills
Cursor	.cursor/mcp.json / ~/.cursor/mcp.json	mcpServers	.cursor/rules/context7.mdc / ~/.cursor/rules/context7.mdc	~/.cursor/skills
OpenCode	opencode.json、opencode.jsonc、.opencode.json、.opencode.jsonc 等 / ~/.config/opencode/ 下同名文件	mcp	AGENTS.md（追加）	~/.agents/skills
Codex	.codex/config.toml / ~/.codex/config.toml	mcp_servers	AGENTS.md（追加）	~/.agents/skills
Antigravity	仅全局 ~/.gemini/config/mcp_config.json（无项目级配置）	mcpServers	GEMINI.md（追加）	~/.agent/skills
Gemini CLI	.gemini/settings.json / ~/.gemini/settings.json	mcpServers	GEMINI.md（追加）	~/.gemini/skills

几个值得注意的适配细节：

• 条目形状因 Agent 而异：Claude 用 { type: "http", url }；Cursor 只写 { url }（无 type 字段）；OpenCode 用 { type: "remote"|"local", url, enabled: true }；Gemini CLI 的字段名是 httpUrl 而非 url；Codex 的 TOML 则把 header 展平到 [mcp_servers.context7.http_headers] 子表。这些差异由各 Agent 的 buildEntry(auth, transport) 生成，并有 setup.test.ts 逐 Agent 断言验证。
• Antigravity 没有项目级 MCP 配置：源码注释说明它基于 Gemini 基础设施、共享 ~/.gemini/，MCP server 只从全局 mcp_config.json 读取，因此 projectPaths 为空数组，项目作用域下自动回落到全局路径。
• Claude 支持 CLAUDE_CONFIG_DIR 环境变量：设置后全局 MCP 配置、规则目录、技能目录与 Agent 探测路径全部跟随该变量（见 agents.ts 及对应测试）。

配置合并的幂等性

写入并非盲目追加。JSON 配置走 mergeServerEntry：读取现有配置（readJsonConfig 会先剥离 JSONC 注释，兼容 OpenCode 的 .jsonc 文件）、保留其他 MCP server、若 context7 条目已存在则整体覆盖并标记 alreadyExists——此时终端会显示 reconfigured 而非 configured。

TOML 配置（Codex）走 appendTomlServer：定位已有的 [mcp_servers.context7] 段落（含 .http_headers 子表）整体替换，其余段落原样保留。测试用例 setup.test.ts 覆盖了这些边界：重复执行不产生重复段落（且不会累积空行）、替换旧 URL 时不影响 other server、覆盖位于文件末尾或中间的服务器块等。

还有一个易被忽略的兼容逻辑：resolveEntryToWrite 与 patchStdioApiKey 表明，若检测到已有的 @upstash/context7-mcp stdio 调用（包括用户钉住的版本如 @upstash/context7-mcp@latest），setup 会保留原有包引用，只替换 --api-key 值；HTTP 传输则始终写标准形状。

规则文件与技能的来源

• 规则内容：templates.ts 优先从上游仓库拉取 rules/context7-mcp.md（MCP 模式）或 rules/context7-cli.md（CLI 模式），拉取失败时回落到内置的 fallback 文本。规则核心是"只要用户问到任何库/框架/SDK/CLI 工具/云服务——包括 React、Next.js、Prisma 这类你可能以为熟悉的——就先取最新文档再回答"，并给出 resolve-library-id → 选最佳匹配 → query-docs → 用文档作答 的四步流程。
• 安装方式因 Agent 而异（installRule）：Claude/Cursor 写独立规则文件；OpenCode/Codex/Antigravity/Gemini 把规则包在 <!-- context7 --> 标记内追加到 AGENTS.md/GEMINI.md，重跑时会替换标记内的旧内容而不影响周边文本（测试见 AGENTS.md append 部分，断言幂等与"替换段落不影响前后内容"）。
• Cursor 特例：规则文件会加 alwaysApply: true 的 frontmatter（templates.ts），保证规则始终生效；Codex 特例：CLI 模式规则与技能会被注入一段"沙箱外运行"的指引，因为 Codex 默认沙箱内网络受限（templates.ts、customizeSkillFilesForAgent）。
• 技能下载：context7-mcp 技能通过 downloadSkill 从 Context7 注册表（/upstash/context7 项目）下载文件后安装，其内容即 skills/context7-mcp/SKILL.md：教 Agent 何时激活、如何用 resolve-library-id 与 query-docs、如何按版本选择库 ID 等。

CLI + Skills 模式写入什么

CLI 模式只写入两样东西（setupCli / setupCliAgent）：

1. find-docs 技能：从注册表下载 find-docs 技能（本项目内即 skills/find-docs/SKILL.md），装入所选 Agent 的技能目录。技能教 Agent 走两步式命令流：

   # Step 1: 解析库 ID
   npx ctx7@latest library <name> "<query>"
   # Step 2: 用 ID 查文档
   npx ctx7@latest docs <libraryId> "<query>"
   

   技能中同时给出了查询质量指引（单概念一查询、具体优于单词、敏感信息勿入 query）、版本 ID 用法（/org/project/version）、每问不超过 3 次命令、配额用尽时建议 ctx7 login 而非静默回退训练数据等约束。

2. CLI 版规则文件：内容取自 rules/context7-cli.md（同样有内置 fallback），与 MCP 规则结构一致，只是把工具调用替换为 npx ctx7@latest library/docs 命令。

CLI 模式不写任何 MCP 配置——这正是它与 MCP 模式的分界，也解释了为什么 --stdio、--oauth 只在 MCP 分支处理。

作用域、Agent 探测与执行输出

• 作用域：--project 把规则/技能/MCP 配置写到当前目录（如 .cursor/rules/context7.mdc、项目级 AGENTS.md、项目级 opencode.json）；不加则写全局。对只有全局路径的 Agent（如 Antigravity），项目作用域自动回落到全局（源码中 projectPaths 为空时直接使用 globalPaths）。
• Agent 解析（resolveAgents）：显式传了 Agent flag 就用它；否则交互式勾选（可选 Claude Code / Cursor / OpenCode / Codex / Antigravity / Gemini CLI）；配合 --yes 时会先用 detectAgents 探测——按各 Agent 的特征路径（如项目里的 .cursor/、opencode.json，全局的 ~/.gemini/）判断哪些 Agent 已安装并自动选中。
• 执行输出：每个 Agent 会汇报三段状态——MCP server configured/reconfigured（含目标路径）、Rule installed/updated、Skill installed/failed（含路径）。技能安装失败若是权限问题（EACCES），终端会额外提示用 chown 修复目录权限。

小结：从一条命令到三条落盘路径

ctx7 setup 的价值在于把"认证 + 配置 + 规则 + 技能"四件事收敛成一条幂等命令：MCP 模式落 mcpServers/mcp 条目（HTTP 或 stdio 传输）+ 规则文件 + context7-mcp 技能；CLI 模式只落 find-docs 技能 + CLI 规则；两种模式都支持 --api-key 免交互、--project 项目级配置，且重跑只会替换 context7 自己的段落，不碰其他 MCP server 或文件内容。实现与行为验证分别集中在 packages/cli/src/commands/setup.ts、packages/cli/src/setup/agents.ts、packages/cli/src/setup/mcp-writer.ts 与 packages/cli/src/tests/setup.test.ts，可作为进一步阅读源码的入口。