configure-mcp

/configure:mcp

检查并配置此项目的 Model Context Protocol（MCP）服务。

MCP 理念： 服务按项目管理（在 .mcp.json 中），而不是按用户管理（在 ~/.claude/settings.json 中），以保持上下文整洁并明确依赖关系。

有关服务配置、环境变量参考和报告模板，请参阅 REFERENCE.md。

何时使用此技能

在以下情况下使用此技能……	在以下情况下采用其他方式……
为项目设置 MCP 服务	配置用户级设置（直接编辑 ~/.claude/settings.json）
检查 MCP 服务状态并验证配置	只查看 .mcp.json 内容（使用 Read 工具）
添加特定服务（context7、playwright、sequential-thinking 等）	为非 MCP 用途安装 npm/bun 软件包（使用软件包管理器）
确保 MCP 配置可供团队共享	仅供个人使用的 MCP 配置（使用 ~/.claude/settings.json）
安装核心效率服务	调试特定服务的运行时问题（检查服务日志，重启 Claude Code）

上下文

• 配置是否存在： !find . -maxdepth 1 -name \'.mcp.json\'
• 已安装的服务： !jq -r '.mcpServers' .mcp.json
• Git 跟踪情况： !grep '.mcp.json' .gitignore
• 标准文件： !find . -maxdepth 1 -name \'.project-standards.yaml\'
• 是否有 playwright 配置： !find . -maxdepth 1 -name 'playwright.config.*' -print -quit
• 是否有 TS/JS 文件： !find . -maxdepth 2 \( -name '*.ts' -o -name '*.py' -o -name '*.go' -o -name '*.rs' \) -print -quit
• 点文件注册表： !find . -maxdepth 1 -name \'~/.local/share/chezmoi/.chezmoidata.toml\'

参数

从 $ARGUMENTS 中解析以下参数：

• --check-only：报告当前状态，不提供安装选项
• --fix：无需确认提示，直接安装服务
• --core：安装所有核心服务（context7、sequential-thinking）
• --server <name>：按名称安装指定服务（可重复指定）

如果未提供任何标志，则运行交互模式（检测 → 报告 → 提供安装选项）。

核心服务

以下服务应安装在所有项目中：

服务	用途	环境变量
context7	来自 Upstash 的文档上下文	无
sequential-thinking	增强推理和规划	无

执行

执行此 MCP 配置工作流：

步骤 1：检测当前状态

检查上述上下文值。确定：

1. .mcp.json 是否存在？如果存在，解析并列出所有已配置的服务。
2. 检查每个服务的命令类型（npx、bunx、uvx、go run）及所需环境变量。
3. 标记缺少必需环境变量的服务。

如果使用 --check-only，则跳至步骤 4（仅报告）。

步骤 2：确定要安装的服务

根据标志选择：

• --core：选择 context7 和 sequential-thinking。
• --server <name>：选择指定的服务。根据 REFERENCE.md 中的可用服务进行验证。
• 无标志（交互模式）：向用户显示已安装和可用的服务。使用 AskUserQuestion 询问要添加哪些服务。根据项目上下文推荐服务（例如，如果存在 playwright.config.*，则推荐 playwright；如果代码库中有大量 TS/Python/Rust 文件，则推荐 cclsp）。

如果所有指定的服务都已安装，则报告“所有服务均已配置”并停止。

第 3 步：安装选定的服务

对于每个选定的服务：

1. 从 REFERENCE.md 获取服务配置。
2. 如果 .mcp.json 不存在，则创建该文件，内容为 {"mcpServers": {}}。
3. 将服务配置合并到现有的 mcpServers 对象中。保留现有服务。
4. 使用规范的 JSON 格式写入更新后的 .mcp.json。

如果选中了 cclsp，还需设置 cclsp.json（语言检测和设置详情请参阅 REFERENCE.md）。

处理 Git 跟踪：

• 检查 .mcp.json 是否已列入 .gitignore。
• 如果文件既未被跟踪也未被忽略，则建议个人项目将其加入 .gitignore，团队项目则进行跟踪。

第 4 步：报告结果

使用 REFERENCE.md 中的报告格式打印摘要：

• 列出所有已配置的服务及其状态
• 标出缺失的环境变量，并说明其设置位置
• 显示 Git 跟踪状态
• 如果添加了服务，显示后续步骤（重启 Claude Code、设置环境变量）

第 5 步：更新标准跟踪

如果 .project-standards.yaml 存在，则更新其中的 MCP 部分，写入当前服务列表和时间戳。

运行时服务管理

配置 .mcp.json 后，可在 Claude Code 中使用以下 /mcp 命令管理服务，无需编辑文件：

命令	说明
/mcp	列出所有已配置的服务及连接状态
/mcp enable <server>	为当前会话启用服务
/mcp disable <server>	为当前会话禁用服务（仅限当前会话）

注意：启用和禁用仅对当前会话有效。永久更改需要编辑 .mcp.json。

Agent 式优化

场景	命令
快速检查状态	jq -c '.mcpServers | keys' .mcp.json 2>/dev/null
验证 JSON 语法	jq empty .mcp.json 2>&1
列出所需的环境变量	jq -r '.mcpServers[] | .env // {} | keys[]' .mcp.json 2>/dev/null | sort -u
检查服务是否已安装	jq -e '.mcpServers.context7' .mcp.json >/dev/null 2>&1 && echo "installed" || echo "missing"
安装核心服务（自动）	/configure:mcp --core --fix
安装指定服务（自动）	/configure:mcp --server context7 --fix
仅检查模式（CI/报告）	/configure:mcp --check-only

标志

标志	说明
--check-only	报告状态，但不提供安装服务的选项
--fix	无需提示，安装指定或建议的服务
--core	安装所有核心服务（context7、sequential-thinking）
--server <name>	安装指定服务（可重复使用）

错误处理

• 无效的 .mcp.json：提供备份选项，并替换为有效模板
• 服务已安装：跳过并显示提示信息
• 缺少环境变量：发出警告，但继续执行（服务可能使用默认值运行）
• 未知服务：报告错误并列出可用的服务名称