# Snow CLI 使用文档——MCP 配置

欢迎使用 Snow CLI！在终端中进行 Agentic 编程。

## MCP 配置

MCP（Model Context Protocol）是一个开放协议，允许 AI 助手与外部工具和服务集成。Snow CLI 支持配置和管理 MCP 服务。

### 什么是 MCP

MCP（Model Context Protocol）是一种标准化协议，用于连接 AI 助手与各种外部工具、数据源和服务。通过 MCP，Snow CLI 可以访问本地文件系统、连接数据库、调用外部 API 等。

### 查看 MCP 服务状态

在对话界面输入 `/mcp` 指令可以查看所有 MCP 服务的状态：

**显示内容**：

- 服务名称
- 连接状态（绿色 ● 表示已连接，红色 ● 表示连接失败，灰色 ● 表示已禁用）
- 服务类型（System/External/Disabled）
- 可用工具列表

**操作方式**：

- **上下箭头**：在服务列表中导航
- **回车键**：重新连接选中的服务
- **Tab 键**：切换外部服务的启用/禁用状态（内置服务不支持）
- 选择 "Refresh all services" 选项可刷新所有服务

### 配置 MCP 服务

#### 1. 进入配置界面

在主菜单中选择 `MCP Configuration` 进入 MCP 配置编辑器。

进入后会先选择配置范围（Scope）：

- **项目级配置**：写入当前工作目录下的 `.snow/settings.json`（`mcpServers` 字段）
- **全局配置**：写入用户目录下的 `~/.snow/settings.json`（`mcpServers` 字段）

#### 2. 自动打开编辑器

系统会自动检测并使用合适的文本编辑器打开配置草稿文件；保存后会写回对应 scope 的 `settings.json`：

**编辑器优先级**：

1. 环境变量 `VISUAL` 指定的编辑器
2. 环境变量 `EDITOR` 指定的编辑器
3. 系统默认编辑器

**Windows 系统**：检测顺序为 notepad++ > notepad > code > vim > nano

**macOS/Linux 系统**：检测顺序为 nano > vim > vi

**设置默认编辑器**：

macOS/Linux:

```bash
export EDITOR=nano
```

Windows:

```cmd
set EDITOR=notepad
```

#### 3. 配置文件位置与优先级

MCP 配置统一存放在 `settings.json` 的 `mcpServers` 字段中，不再使用独立的 `mcp-config.json`（旧文件会在启动时迁移）。

| 范围   | 路径                            | 作用域     |
| ------ | ------------------------------- | ---------- |
| 项目级 | `<project>/.snow/settings.json` | 仅当前项目 |
| 全局   | `~/.snow/settings.json`         | 所有项目   |

**合并规则**：

- 运行时会合并全局与项目级配置
- **项目级优先**：同名服务以项目级配置为准
- 适合把仅当前仓库需要的 MCP 放在项目级，把通用 MCP 放在全局

你也可以直接手写编辑这两个文件，不必经过 UI。

#### 4. 配置文件格式

**配置文件结构**（项目级 / 全局相同）：

```json
{
	"mcpServers": {
		"服务名称": {
			"command": "命令",
			"args": ["参数1", "参数2"],
			"enabled": true
		}
	}
}
```

> **注意**：`settings.json` 里还可能有其他项目设置（如 `yoloMode`、`disabledSkills`）。新增 MCP 时请先读取现有文件，再**合并**写入 `mcpServers`，不要覆盖整个文件。

**配置项说明**：

- `mcpServers`：MCP 服务配置对象
- `服务名称`：自定义的服务名称（唯一标识）
- `type`：传输类型，可选值为 `'stdio'`、`'local'` 或 `'http'`（可选，默认为根据 `url` 或 `command` 自动推断）
  - `'stdio'`：本地子进程通信（STDIO 模式）
  - `'local'`：`'stdio'` 的别名，功能完全相同
  - `'http'`：HTTP 模式，用于连接远程 MCP 服务
- `command`：启动 MCP 服务的命令（`stdio`/`local` 类型必需）
- `args`：命令参数数组（可选）
- `url`：MCP 服务端点 URL（`http` 类型必需）
- `headers`：HTTP 请求头配置（`http` 类型可选）
- `enabled`：是否启用该服务（可选，默认为 true）
- `timeout`：工具调用超时时间，单位毫秒（可选，默认为 1200000，即 20 分钟）
- `env` / `environment`：环境变量配置（可选），`environment` 是 `env` 的别名

**配置示例**：

**项目级配置示例**（`<project>/.snow/settings.json`）：

```json
{
	"yoloMode": false,
	"mcpServers": {
		"project-docs": {
			"type": "stdio",
			"command": "npx",
			"args": ["-y", "@modelcontextprotocol/server-filesystem", "./docs"],
			"enabled": true
		}
	}
}
```

**STDIO/Local 模式示例**：

```json
{
	"mcpServers": {
		"filesystem": {
			"type": "stdio",
			"command": "npx",
			"args": [
				"-y",
				"@modelcontextprotocol/server-filesystem",
				"/path/to/files"
			],
			"timeout": 600000
		},
		"github": {
			"type": "local",
			"command": "npx",
			"args": ["-y", "@modelcontextprotocol/server-github"],
			"enabled": true,
			"environment": {
				"GITHUB_TOKEN": "your_token_here"
			}
		}
	}
}
```

**HTTP 模式示例**：

```json
{
	"mcpServers": {
		"remote-service": {
			"type": "http",
			"url": "https://api.example.com/mcp",
			"headers": {
				"Authorization": "Bearer ${API_KEY}",
				"X-Custom-Header": "custom-value"
			},
			"env": {
				"API_KEY": "your_api_key_here"
			},
			"timeout": 1200000
		}
	}
}
```

> **注意**：HTTP 模式支持从环境变量读取配置值，使用 `${VAR_NAME}` 语法。

### 配置验证

保存配置文件后，系统会自动进行验证：

**成功提示**（会带上当前编辑范围名称）：

```text
项目级配置 MCP 配置保存成功！请用 `snow` 重启！
```

**错误提示**：

```text
JSON 格式无效，修改已回退至上一个有效配置。
```

### 使用 MCP 服务

配置后需要重启 Snow CLI 使配置生效：

```bash
snow
```

启动后可以使用 `/mcp` 指令查看服务连接状态。

### 管理 MCP 服务

#### 启用/禁用服务

**方法 1：编辑配置文件**

设置 `enabled` 字段为 `false` 禁用服务

**方法 2：使用 /mcp 指令**

1. 输入 `/mcp` 打开服务面板
2. 使用上下箭头选择服务
3. 按 Tab 键切换启用/禁用状态

**注意**：

- `/mcp` 面板里的 **Tab 切换**主要面向外部 MCP 服务
- 部分内置工具服务可通过设置项 `disabledBuiltInServices` 禁用（例如 `snow-docs`）
- 例如在 `<project>/.snow/settings.json` 中写入：

```json
{
	"disabledBuiltInServices": ["snow-docs"]
}
```

内置官方文档工具（`snow-docs-list` / `snow-docs-search` / `snow-docs-get`）说明见：[官方文档工具（snow-docs）](./28.官方文档工具snow-docs.md)。

#### 重新连接服务

在 `/mcp` 面板中选择服务并按回车键可重新连接

### 故障排除

#### 1. 编辑器无法打开

**错误信息**：

```text
No text editor found! Please set the EDITOR or VISUAL environment variable.
```

**解决方案**：

设置环境变量或安装文本编辑器：

macOS/Linux:

```bash
export EDITOR=nano
```

Windows:

```cmd
set EDITOR=notepad
```

#### 2. 服务连接失败

**检查项**：

1. 命令路径是否正确
2. 是否已安装依赖包（如使用 npx 需要 Node.js）
3. 参数格式是否正确
4. 使用 `/mcp` 查看具体错误信息

#### 3. 配置不生效

**解决方案**：

1. 确认已保存配置文件
2. 重启 Snow CLI
3. 使用 `/mcp` 查看服务状态

### 相关资源

- MCP 官方文档：<https://modelcontextprotocol.io>
- MCP 服务仓库：<https://github.com/modelcontextprotocol>
- 指令说明：[指令面板说明](./09.0.指令面板说明.md)
- 内置官方文档工具：[官方文档工具（snow-docs）](./28.官方文档工具snow-docs.md)