企业官网建设流程全解析

• 开发工具
• CLI
• AI 应用

ZCF 内置了一批经过预配置的 MCP（Model Context Protocol）服务，覆盖文档检索、Web 搜索、浏览器自动化等场景，可通过交互菜单或npx zcf i -s --mcp-services一键写入 Claude Code / Codex 的本地配置。本文基于仓库中 docs/ja-JP/features/mcp.md 的完整内容，结合 src/config/mcp-services.ts、src/utils/claude-config.ts 等源码，讲清每个服务的真实启动命令、参数解析规则、配置落盘流程与故障排查方法。

一、MCP 是什么

MCP（Model Context Protocol）是 AI 助手访问外部工具和服务的协议，可为 Claude Code / Codex 扩展文档搜索、Web 搜索、浏览器操作、代码检索等能力。ZCF 的价值在于：它把常用 MCP 服务的命令行、参数与环境变量全部预先封装好，用户只需勾选或传 ID，ZCF 负责把正确的mcpServers（JSON）或[mcp_servers.*]（TOML）配置块合并进目标工具的配置文件中。

二、内置服务清单与真实启动配置

ZCF 内置 7 个 MCP 服务，定义在 src/config/mcp-services.ts 的MCP_SERVICE_CONFIGS常量中。官方文档给出的概览如下：

从源码看，每个服务落盘时的完整启动配置为：

两个值得注意的实现细节：

• 类型差异：除mcp-deepwiki是http类型（只写url字段、无本地命令）外，其余均为stdio类型。其中serena的启动命令不是npx而是uvx，意味着使用它需要本机具备 uv/uvx 环境。
• API Key 元数据：只有exa声明了requiresApiKey: true与apiKeyEnvVar: 'EXA_API_KEY'，交互式流程会因此弹出 Key 输入框；服务名称与描述则通过getMcpServices()从 i18n 语言包（如 src/i18n/locales/zh-CN/mcp.json）注入，与纯业务配置分离。

相关配置可参考测试用例 tests/config/mcp-services.test.ts 对服务列表与字段的断言。

三、安装方式

3.1 交互式安装

运行npx zcf进入主菜单，选择4 (Configure MCP)，即文档中的configureMcpFeature流程（实现于 src/utils/features.ts）：

1. 若当前是 Windows 环境，先询问是否修正已有 MCP 配置的路径格式（fixWindowsMcp），确认后立即用fixWindowsMcpConfig重写配置；
2. 弹出复选框列表勾选服务（多选，由 src/utils/mcp-selector.ts 的selectMcpServices()基于 inquirercheckbox实现，选项展示「名称 - 灰色描述」）；
3. 若勾选了需要 API Key 的服务（目前仅exa），逐项提示输入 Key，输入为空则跳过该服务；
4. 先调用backupMcpConfig()备份现有配置，再把选中服务合并写入，并打印备份路径。

3.2 CLI 参数安装

npx zcf i -s --mcp-services all npx zcf i -s --mcp-services context7,open-websearch,spec-workflow npx zcf i -s --mcp-services skip # 不安装

-s（skip-prompt 模式）下，参数解析规则在 src/commands/init.ts 的validateSkipPromptOptions中实现：

• skip→ 解析为false，完全跳过 MCP 配置；
• all→ 展开为所有不需要 API Key 的服务 ID（MCP_SERVICE_CONFIGS.filter(s => !s.requiresApiKey)，即实际不包含exa，避免无 Key 时写入占位符配置）；
• 逗号分隔的列表 → 逐个trim后与内置服务 ID 逐一校验，出现未知 ID 会抛出invalidMcpService错误并列出全部合法值；
• 默认值：未传--mcp-services时按all处理，也就是默认安装全部免 Key 服务。

参数行为可对照测试 tests/unit/commands/init-param-validation.test.ts 与 tests/commands/init.single-config.test.ts。

四、配置写入的底层流程

4.1 Claude Code 侧

从源码结构看，ZCF 对 Claude Code 的 MCP 读写集中在 src/utils/claude-config.ts：

• 配置路径：readMcpConfig()/writeMcpConfig()均作用于常量ClAUDE_CONFIG_FILE（src/constants.ts 中定义为~/.claude.json），读写其中的mcpServers字段。注意官方文档表述为~/.claude/settings.json的mcpServers，而当前源码实际落盘目标是~/.claude.json，以仓库当前实现为准；
• 备份：backupMcpConfig()将原文件复制到~/.claude/backup/目录，因此每次写入前都有回滚点；
• 合并策略：mergeMcpServers()用Object.assign(config.mcpServers, newServers)把新服务并入既有mcpServers，不覆盖其他字段（如 API 配置、hasCompletedOnboarding等），这正对应文档中「即使手动添加过新服务，npx zcf i也能选择合并策略」的说明；
• Windows 路径修正：fixWindowsMcpConfig()遍历所有带command的服务，经 src/utils/platform.ts 的getMcpCommand()判断后，把需要包装的命令改写为cmd+/c前缀参数，解决 Windows 下 stdio 服务器路径解析问题；http 类服务（无command字段）会被跳过不处理；
• API Key 注入：buildMcpServerConfig()先深克隆配置避免污染源配置；若指定了envVarName（如EXA_API_KEY），直接把用户输入的 Key 写进config.env；否则回退到在args/url中替换占位符YOUR_EXA_API_KEY的旧式做法。

4.2 Codex 侧

Codex 的 MCP 配置写入~/.codex/config.toml（常量CODEX_CONFIG_FILE，见 src/constants.ts）。写入逻辑在 src/utils/code-tools/codex-toml-updater.ts：

• 更新函数只修改[mcp_servers.{serviceId}]这一个表，注释中明确「Does NOT touch: mcp_servers 其他表、顶层字段、其他 providers」；
• 删除函数用正则仅剥离[mcp_servers.{id}]区块，避免误伤文件其余部分；
• 读取与序列化在 src/utils/code-tools/codex.ts：从 TOML 解析出mcp_servers各表，保留command、args、env、startup_timeout_sec等字段，重写时按[mcp_servers.<id>]分段输出。文档中简写的mcp_server.*在代码中对应的实际表名前缀是mcp_servers.，去重逻辑另有测试 tests/unit/utils/code-tools/codex-mcp-deduplication.test.ts 覆盖。

五、API Key 与环境变量

需要 API Key 的服务通过环境变量配置：

export EXA_API_KEY="your-api-key"

在 ZCF 的交互流程中，勾选exa后会通过apiKeyPrompt（来自 i18n）弹出输入框，校验非空后经buildMcpServerConfig()将真实 Key 写入该服务的env.EXA_API_KEY；CLI 的all模式则直接跳过exa。Key 的交互式审批与配置审批流程另有 tests/utils/api-key-approval.test.ts 验证。

六、连接确认

1. 在 IDE 的 MCP 面板确认状态为Connected；
2. 用测试提示词验证，例如：
   • Context7：「查一下 React hooks 的最新文档」
   • Open Web Search：「搜索 TypeScript 5.0 的新特性」
   • DeepWiki：「获取 vuejs/core 仓库的 Composition API 文档」

七、故障排查

相关行为在 tests/unit/utils/mcp.test.ts、tests/unit/utils/claude-config.test.ts 与 tests/unit/commands/init.test.ts 中均有覆盖。

八、最佳实践

1. 只装所需服务：MCP 服务会占用进程与资源，按需勾选而非all全开；
2. 定期更新配置：用npx zcf update保持配置与工具链同步；
3. 规范化管理 Key：环境通过.env等方式管理EXA_API_KEY，安装后执行第六节的连接测试确认生效;
4. 放心合并：即使手动添加过第三方 MCP 服务，npx zcf i的合并策略（Object.assign增量合并 + 写前备份到~/.claude/backup/）不会破坏既有条目。

适用前提：stdio 类服务依赖本机npx（Node.js）环境，serena额外依赖uvx；CLI 免交互安装需搭配-s参数并显式给出--mcp-services取值，否则默认安装全部免 Key 服务。

• 开发工具
• CLI
• AI 应用