--- title: MCP 集成 description: "通过 Model Context Protocol 服务器和插件扩展 Verdent" --- ## 什么是 MCP（Model 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 集成的优势 ### 扩展能力 **访问外部系统：** 将 Verdent 连接到内置功能无法提供的工具和服务。无需离开编码工作流，即可查询数据库、与云服务交互或集成特定项目的 API。 **自定义工具开发：** 针对项目的独特需求量身打造 MCP 服务器。为内部工具、专有 API 或特定领域系统构建专门的集成。 ### 互操作性 **借力生态系统：** 接入不断壮大的 MCP 生态系统。社区开发的 MCP 服务器为热门工具和服务提供了预构建的集成。 **标准化协议：** MCP 为工具集成提供了一致的接口，确保新能力能顺畅地融入 Verdent 现有的工具系统。 ### 工作流自动化 **无缝集成：** MCP 服务器成为 Verdent 工具集的一部分。智能体会在适当时机自动使用 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.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.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 协议规范，暴露出 Verdent 可调用的工具能力。有关实现细节和 SDK，请参阅 [Model Context Protocol 规范](https://modelcontextprotocol.io/specification)。 **自定义服务器的使用场景：** - **内部 API 集成：** 连接到公司特定的 API 和服务 - **遗留系统桥接：** 让 Verdent 能够与遗留基础设施交互 - **专业数据源：** 访问专有数据库或数据仓库 - **工作流自动化：** 触发自定义的构建、部署或测试流水线 ### 集成模式 **工作区级配置：** MCP 服务器可在工作区级别配置以实现项目特定的集成，使团队能够通过版本控制共享 MCP 配置。 **工具互操作性：** MCP 提供的工具能与 Verdent 的内置工具（`file_read`、`bash`、`spawn_subagent`）无缝集成，从而构建结合多种工具类型的复杂工作流。 --- ## 桌面端专属 MCP 功能 ### 按项目配置 | 配置级别 | 位置 | 作用范围 | |---------------------|----------|-------| | **全局** | `~/.verdent/mcp.json` | 所有项目 | | **项目** | 项目根目录中的 `.mcp.json` | 单个项目 | | **Worktree** | 继承自项目 | 继承项目配置 | ### 多 Worktree MCP MCP 服务器可跨 worktree 工作： - **共享服务器：** 基础工作区的 MCP 配置由所有 worktree 共享 - **隔离操作：** 每个 worktree 维护独立的 MCP 会话状态 - **并行访问：** 多个 worktree 可并发使用同一个 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 流水线监控 **场景：** 在部署变更前检查构建状态。 **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.json` 中的认证凭据 - 确保 MCP 服务器正在运行且可访问 - 验证配置文件语法 **权限错误：** - 确认 API 密钥或凭据具有所需权限 - 检查服务配额或速率限制 - 验证防火墙规则允许 MCP 流量 **工具调用问题：** - 确保 MCP 服务器正确暴露了预期工具 - 检查工具参数格式是否符合服务器预期 - 查看 MCP 服务器日志以获取错误详情 ### 获取帮助 **支持渠道：** - Verdent 支持：support@verdent.ai - [MCP 协议文档](https://modelcontextprotocol.io) - [Verdent Discord 社区](https://discord.com/invite/NGjXEZcbJq) **诊断信息：** 报告 MCP 问题时，请提供： - MCP 服务器类型和版本 - 配置详情（已脱敏凭据） - 聊天记录中的错误消息 - MCP 服务器日志（如可访问） --- ## 常见问题 MCP 服务器操作会根据处理结果的模型消耗积分。MCP 服务器本身不直接消耗积分。 不是。MCP 服务器是在用户级别配置的，而非按项目配置。所有已配置的服务器可在你所有项目中使用。 mcp.json 中的凭据存储在你的本地机器上，绝不会发送到 Verdent 服务器。请对敏感值使用环境变量（`${VAR_NAME}`）。 MCP 服务器在需要时启动，并在会话期间运行。当 Verdent 关闭时，它们不会消耗资源。 MCP 服务器拥有你为其配置的权限。请尽可能使用只读访问并限制破坏性操作。 请求 Verdent 使用 MCP 服务器中的某个工具。成功的响应表示连接正常。如果出现问题，请查看故障排查部分。