# MCP 集成 (/zh-CN/docs/verdent-manager/configuration/mcp)
> 通过 Model Context Protocol 服务器和插件扩展 Verdent
## 什么是 MCP（Model Context Protocol）？ [#什么是-mcpmodel-context-protocol]
Model Context Protocol（MCP）是一套集成系统，通过连接外部工具、数据源和服务来扩展 Verdent 的能力。
**核心理念：**
MCP 让 Verdent 能够与其内置工具集之外的系统进行交互，实现与以下系统的无缝集成：
* 外部 API 和 Web 服务
* 数据库系统
* 云平台（AWS、Azure、GCP）
* 项目管理工具
* CI/CD 流水线
* 自定义内部工具
**架构：**
MCP 服务器充当 Verdent 与外部系统之间的桥梁。每个 MCP 服务器都暴露出 Verdent 可在编码会话中调用的特定能力，类似于 `file_read` 或 `bash` 等内置工具。
**配置存储：**
MCP 服务器配置存储在 `~/.verdent/mcp.json` 中，并通过设置菜单进行管理。
***
## MCP 集成的优势 [#mcp-集成的优势]
### 扩展能力 [#扩展能力]
**访问外部系统：**
将 Verdent 连接到内置功能无法提供的工具和服务。无需离开编码工作流，即可查询数据库、与云服务交互或集成特定项目的 API。
**自定义工具开发：**
针对项目的独特需求量身打造 MCP 服务器。为内部工具、专有 API 或特定领域系统构建专门的集成。
### 互操作性 [#互操作性]
**借力生态系统：**
接入不断壮大的 MCP 生态系统。社区开发的 MCP 服务器为热门工具和服务提供了预构建的集成。
**标准化协议：**
MCP 为工具集成提供了一致的接口，确保新能力能顺畅地融入 Verdent 现有的工具系统。
### 工作流自动化 [#工作流自动化]
**无缝集成：**
MCP 服务器成为 Verdent 工具集的一部分。智能体会在适当时机自动使用 MCP 工具，你也可以针对特定任务显式调用它们。
**上下文感知操作：**
MCP 集成能理解你的代码库上下文，从而基于当前开发状态与外部系统进行智能交互。
***
## 设置 MCP 服务器 [#设置-mcp-服务器]
### 配置流程 [#配置流程]
**访问 MCP 设置：**
1. 在 Verdent 中打开设置菜单
2. 进入 **MCP Servers** 部分
3. 查看或修改 `~/.verdent/mcp.json` 配置
**配置文件：**
MCP 服务器通过 `~/.verdent/mcp.json` 文件进行配置，该文件定义了服务器连接、认证和集成参数。完整的 schema 见下文 **MCP 配置** 部分。
### 配置管理 [#配置管理]
**添加服务器：**
通过在 `mcp.json` 中添加包含连接详情和认证凭据的条目，来配置新的 MCP 服务器。
**多个服务器：**
Verdent 支持多个并发的 MCP 服务器，可同时集成多个外部系统。
**测试连接：**
在开发工作流中使用 MCP 服务器之前，验证其配置以确保连接成功。
### 服务器状态 [#服务器状态]
在 MCP 设置面板中监控连接状态：
| 状态 | 描述 |
| ----------- | ------------ |
| **Success** | 服务器已连接，工具可用 |
| **Failed** | 连接错误（点击查看详情） |
| **Loading** | 服务器正在初始化 |
**刷新工具：**
在配置更改或出现连接问题后，点击刷新按钮可重新发现服务器上的可用工具。
***
## MCP 配置 [#mcp-配置]
### 基本设置 [#基本设置]
**位置：** 项目根目录中的 `.mcp.json` 或 `~/.verdent/mcp.json`（全局）
```json PostgreSQL Server
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://localhost:5432/myapp_dev"
]
}
}
}
```
```json GitHub Server
{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
```
```json Multiple Servers
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://localhost:5432/myapp_dev"
]
},
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
```
**配置键：**
* `mcpServers` - MCP 配置的必需顶层键
* `command` - 要运行的可执行文件（Node.js 包通常为 `npx`）
* `args` - 传递给命令的参数（包名、连接字符串等）
* `env` - 用于认证/配置的环境变量
**了解更多 MCP 信息：**
* [Model Context Protocol 规范](https://modelcontextprotocol.io/specification)
* [MCP 服务器注册表](https://mcp.so/servers) - 浏览可用的 MCP 服务器
* [官方 MCP 服务器](https://github.com/modelcontextprotocol) - PostgreSQL、GitHub、Filesystem 等
***
## MCP 插件和扩展 [#mcp-插件和扩展]
### 可用插件 [#可用插件]
MCP 插件为常见工具和服务提供预构建的集成。可在社区注册表 [mcp.so/servers](https://mcp.so/servers) 或 [官方 MCP 服务器仓库](https://github.com/modelcontextprotocol) 浏览当前可用的插件。
**常见插件类别：**
* **数据库集成：** PostgreSQL、MySQL、MongoDB 查询工具
* **云服务：** AWS、Azure、GCP API 交互
* **开发者工具：** GitHub、GitLab、Jira、Linear 集成
* **CI/CD 平台：** Jenkins、GitHub Actions、CircleCI
* **监控服务：** Datadog、New Relic、Sentry
* **通信：** Slack、Discord、Microsoft Teams 通知
### 插件安装 [#插件安装]
**安装方式：**
插件通过 MCP 设置界面安装和配置，通常需要：
* 插件标识符或来源
* 配置参数
* 认证凭据（如适用）
**依赖管理：**
MCP 插件可能依赖外部服务或库。安装过程会在可能的情况下自动处理依赖解析。
***
## 自定义 MCP 服务器开发 [#自定义-mcp-服务器开发]
### 创建自定义服务器 [#创建自定义服务器]
高级用户可以创建自定义 MCP 服务器，以集成专有工具或特定领域的系统。
**开发方式：**
自定义 MCP 服务器实现 MCP 协议规范，暴露出 Verdent 可调用的工具能力。有关实现细节和 SDK，请参阅 [Model Context Protocol 规范](https://modelcontextprotocol.io/specification)。
**自定义服务器的使用场景：**
* **内部 API 集成：** 连接到公司特定的 API 和服务
* **遗留系统桥接：** 让 Verdent 能够与遗留基础设施交互
* **专业数据源：** 访问专有数据库或数据仓库
* **工作流自动化：** 触发自定义的构建、部署或测试流水线
### 集成模式 [#集成模式]
**工作区级配置：**
MCP 服务器可在工作区级别配置以实现项目特定的集成，使团队能够通过版本控制共享 MCP 配置。
**工具互操作性：**
MCP 提供的工具能与 Verdent 的内置工具（`file_read`、`bash`、`spawn_subagent`）无缝集成，从而构建结合多种工具类型的复杂工作流。
***
## 桌面端专属 MCP 功能 [#桌面端专属-mcp-功能]
### 按项目配置 [#按项目配置]
| 配置级别 | 位置 | 作用范围 |
| ------------ | --------------------- | ------ |
| **全局** | `~/.verdent/mcp.json` | 所有项目 |
| **项目** | 项目根目录中的 `.mcp.json` | 单个项目 |
| **Worktree** | 继承自项目 | 继承项目配置 |
### 多 Worktree MCP [#多-worktree-mcp]
MCP 服务器可跨 worktree 工作：
* **共享服务器：** 基础工作区的 MCP 配置由所有 worktree 共享
* **隔离操作：** 每个 worktree 维护独立的 MCP 会话状态
* **并行访问：** 多个 worktree 可并发使用同一个 MCP 服务器
### 项目切换 [#项目切换]
切换项目时：
* 当前项目的 MCP 服务器会被加载
* 全局 MCP 服务器始终可用
* 上一个项目的 MCP 连接会在后台保持
***
## MCP 工作流示例 [#mcp-工作流示例]
### 数据库查询集成 [#数据库查询集成]
**场景：** 查询生产数据库以调试数据问题。
**MCP 方式：**
```
User: "Check the orders table for customer ID 12345"
Verdent: [Uses MCP database server to execute safe read-only query]
Results: 3 orders found for customer 12345
[Displays formatted results]
```
MCP 数据库服务器负责处理认证、查询验证和结果格式化。
### 云服务交互 [#云服务交互]
**场景：** 检查 AWS Lambda 函数日志中的错误。
**MCP 方式：**
```
User: "Show me recent errors from the payment-processor Lambda function"
Verdent: [Invokes MCP AWS integration]
[Retrieves CloudWatch logs for specified function]
[Filters for ERROR level entries]
[Presents formatted error summaries]
```
MCP AWS 服务器管理认证、API 调用和日志解析。
### CI/CD 流水线监控 [#cicd-流水线监控]
**场景：** 在部署变更前检查构建状态。
**MCP 方式：**
```
User: "Is the master branch build passing?"
Verdent: [Queries MCP CI/CD integration]
Build #245: ✓ Passed (2 minutes ago)
All tests passed, ready for deployment
```
MCP CI/CD 服务器跟踪流水线状态并提供实时反馈。
***
## 安全注意事项 [#安全注意事项]
### 认证与授权 [#认证与授权]
**凭据管理：**
MCP 服务器负责处理对外部服务的认证。凭据安全地存储在 MCP 配置中，绝不会暴露在聊天记录或代码中。
**权限范围限定：**
为 MCP 服务器配置最小必要权限。尽可能使用只读访问，并限制破坏性操作。
### 安全操作 [#安全操作]
**命令审查：**
涉及 MCP 工具的操作会出现在对话历史中，提供可见性和控制力。
**审计日志：**
MCP 服务器操作会出现在 Verdent 的聊天记录中，为外部系统交互创建审计轨迹。
***
## MCP 集成故障排查 [#mcp-集成故障排查]
### 常见问题 [#常见问题]
**连接失败：**
* 验证到 MCP 服务器的网络连接
* 检查 `mcp.json` 中的认证凭据
* 确保 MCP 服务器正在运行且可访问
* 验证配置文件语法
**权限错误：**
* 确认 API 密钥或凭据具有所需权限
* 检查服务配额或速率限制
* 验证防火墙规则允许 MCP 流量
**工具调用问题：**
* 确保 MCP 服务器正确暴露了预期工具
* 检查工具参数格式是否符合服务器预期
* 查看 MCP 服务器日志以获取错误详情
### 获取帮助 [#获取帮助]
**支持渠道：**
* Verdent 支持：[support@verdent.ai](mailto:support@verdent.ai)
* [MCP 协议文档](https://modelcontextprotocol.io)
* [Verdent Discord 社区](https://discord.com/invite/NGjXEZcbJq)
**诊断信息：**
报告 MCP 问题时，请提供：
* MCP 服务器类型和版本
* 配置详情（已脱敏凭据）
* 聊天记录中的错误消息
* MCP 服务器日志（如可访问）
***
## 常见问题 [#常见问题-1]
MCP 服务器操作会根据处理结果的模型消耗积分。MCP 服务器本身不直接消耗积分。
不是。MCP 服务器是在用户级别配置的，而非按项目配置。所有已配置的服务器可在你所有项目中使用。
mcp.json 中的凭据存储在你的本地机器上，绝不会发送到 Verdent 服务器。请对敏感值使用环境变量（`${VAR_NAME}`）。
MCP 服务器在需要时启动，并在会话期间运行。当 Verdent 关闭时，它们不会消耗资源。
MCP 服务器拥有你为其配置的权限。请尽可能使用只读访问并限制破坏性操作。
请求 Verdent 使用 MCP 服务器中的某个工具。成功的响应表示连接正常。如果出现问题，请查看故障排查部分。