首页 / Stage 06 · MCP协议与工具链集成
🔌 Stage 06

MCP协议与
工具链集成

掌握 Model Context Protocol (MCP) 标准协议，学会开发自定义 MCP 服务器，集成 Hermes Agent 与 Dify MCP 适配器，构建多工具协同的智能化工作流。这是从单点AI应用迈向系统化智能的关键一步。

下一阶段：企业级应用 → ← 上一阶段 返回总览
Core Concept
🔌 Model Context Protocol (MCP)

Anthropic 主导的标准化工具调用协议，让 AI 能够以统一方式访问外部数据和服务。

📡
MCP 是什么
MCP 是一个开放协议，标准化了 AI 应用如何连接和操作数据源、工具和外部服务。它解决了以下问题：

核心价值：
  • 统一的接口标准，避免每个AI应用都写自己的集成代码
  • 支持双向通信，AI可以读取数据也可以执行操作
  • 插件化架构，易于扩展新的数据源和工具
  • 安全性设计，权限控制和沙箱隔离
开放标准 双向通信 插件化
🏗️
MCP 架构组成
MCP Client
AI应用端，如 Claude Desktop、Hermes Agent，发起请求并接收响应
MCP Server
服务端，提供数据和工具能力，如文件系统、数据库、API等
Transport Layer
传输层，支持 stdio（本地）和 SSE（远程）两种模式
Tools & Resources
暴露给AI的工具和资源列表，定义可执行的操作和可访问的数据
🔄
MCP 工作流程
典型交互流程：
  1. 初始化：Client 连接到 Server，交换能力列表
  2. 发现：Client 查询可用的 Tools 和 Resources
  3. 调用：AI 决定调用某个 Tool，发送请求参数
  4. 执行：Server 执行实际操作（读文件、查数据库等）
  5. 返回：Server 将结果返回给 Client
  6. 决策：AI 根据结果决定下一步行动
💡 为什么需要 MCP？
没有 MCP 时，每个 AI 应用都要为每个数据源写专用代码。有了 MCP，只需实现一次 Server，所有兼容的 Client 都能使用。这就像 USB 标准统一了外设接口一样。
Practical Skills
🤖 Hermes Agent 部署与配置

Hermes 是 Nous Research 开发的开源 Agent 框架，支持 MCP 协议，是学习和实践的理想平台。

1️⃣ 环境准备与 Docker 安装
前置条件：
  • Docker Desktop 已安装并运行
  • Windows 版本 ≥ 22H2
  • 建议内存 ≥ 8GB
创建部署目录： 
mkdir -p d:\System\Docker\hermes
cd d:\System\Docker\hermes
端口说明：
8088 Hermes Dashboard Web 界面
11435 Hermes API 接口
2️⃣ 创建 docker-compose.yml
docker-compose.yml 核心配置： 
services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-agent
    volumes:
      - ./.hermes:/opt/data
    environment:
      - ANTHROPIC_API_KEY=your-api-key-here
      - ANTHROPIC_BASE_URL=http://coding.zhengyuantech.cn
      - HERMES_DASHBOARD=true
      - GATEWAY_ALLOW_ALL_USERS=true
    ports:
      - "8088:9119"
      - "11435:11434"
    restart: unless-stopped
    command: ["gateway"]
⚠️ 重要配置说明：
  • command: ["gateway"] 必须添加，否则无法启用 Web 界面
  • HERMES_DASHBOARD=true 启用 Dashboard
  • GATEWAY_ALLOW_ALL_USERS=true 允许访问（生产环境需调整）
  • 容器内 Dashboard 运行在端口 9119，映射到主机 8088
3️⃣ 配置模型供应商
修改环境变量 (.env)： 
ANTHROPIC_API_KEY=sk-your-api-key
ANTHROPIC_BASE_URL=http://coding.zhengyuantech.cn
配置默认模型 (config.yaml)： 
model:
  default: "qwen3.6-plus"
  provider: "anthropic"
  base_url: "http://coding.zhengyuantech.cn"
可用模型列表：
qwen3.6-plus 通义千问3.6（推荐用于代码任务）
glm-5 智谱GLM-5
MiniMax-M2.5 MiniMax快速模型
claude-opus-4.6 Claude Opus
4️⃣ 启动与验证
启动命令： 
cd d:\System\Docker\hermes
docker-compose up -d
验证服务状态： 
# 查看容器状态
docker ps | findstr hermes

# 查看日志
docker-compose logs -f
访问地址： CLI 测试： 
# 交互式聊天
docker exec -it hermes-agent hermes chat

# 单次对话
docker exec hermes-agent hermes chat --prompt "Hello, Hermes!"
Integration
🔧 Dify MCP Adapter 集成

自定义 Dify MCP Adapter 作为官方插件的备选方案，实现对 Dify 应用的程序化访问。

🛠️
Adapter 功能
可用工具：
  • list_dify_apps - 列出所有 Dify 应用
  • call_dify_chat_app - 调用 Dify 聊天应用
  • get_app_info - 获取应用详细信息
核心特性：
  • stdio 传输模式（性能好）
  • 支持会话持续对话
  • 环境变量配置
  • Docker 支持
🚀
快速集成步骤
方式一：直接集成到 Hermes（推荐）
  1. 安装 Python 依赖：pip install -r requirements.txt
  2. 挂载代码到 Hermes 容器
  3. 重启 Hermes：docker-compose down && docker-compose up -d
  4. 添加 MCP 服务器：hermes mcp add dify-mcp-adapter
方式二：独立 Docker 部署
  1. 配置 .env 文件（填入 API Key）
  2. 启动容器：docker-compose up -d
💡 最佳实践：优先使用 Dify 官方 MCP 插件，仅在需要深度定制时使用自定义 Adapter。官方插件更稳定、维护更及时。
Case Study
💼 实战案例：构建智能工作流

结合 Hermes Agent、Dify MCP Adapter 和多个工具，构建自动化的智能工作流。

场景描述
假设你需要一个智能助手，能够：
  • 自动查询 Dify 中的应用列表
  • 根据用户需求调用特定的 Dify 应用
  • 读取本地文件系统中的文档
  • 将处理结果保存到指定位置
解决方案架构
Hermes Agent（主控）
├── MCP Server 1: Dify Adapter（访问 Dify 应用）
├── MCP Server 2: Filesystem（读写本地文件）
├── MCP Server 3: Database（查询业务数据）
└── MCP Server 4: Custom API（调用内部服务）

工作流程：
  1. 用户提问："帮我分析上月的销售数据"
  2. Hermes 调用 Database MCP 查询销售数据
  3. 调用 Dify MCP 触发数据分析应用
  4. 将分析结果通过 Filesystem MCP 保存为报告
  5. 返回给用户完整报告路径和摘要
✅ 优势
  • 模块化设计，易于扩展新工具
  • 标准化接口，降低集成复杂度
  • Agent 自主决策，减少人工干预
  • 可追溯的执行日志，便于调试
⚠️ 注意事项
  • 合理设置超时时间，避免无限等待
  • 权限控制，防止未授权访问
  • 错误处理，优雅降级而非崩溃
  • 性能监控，及时发现瓶颈
Troubleshooting
❓ 常见问题与解决
问题1：无法访问 Dashboard
检查项：
  • 确认容器是否运行：docker-compose ps
  • 检查日志中的错误：docker-compose logs -f
  • 验证端口映射：Dashboard 在容器内运行在端口 9119
  • 确保设置了 HERMES_DASHBOARD=true
问题2：配置文件解析错误
解决方法：
  • 确保 config.yaml 有有效的 YAML 语法
  • 从注释中移除非 ASCII 字符（如中文）
  • 验证所有部分的缩进正确
  • 使用 UTF-8 编码保存文件
问题3：MCP 工具调用失败
排查步骤：
  • 验证 API Key 是否正确
  • 确认目标服务是否正常运行
  • 检查网络连接（host.docker.internal 配置）
  • 查看 Hermes 日志中的详细错误信息
问题4：端口已被占用
解决方案：
  • 如果 8088 被占用，更改主机端口映射
  • 示例：使用 - "8089:9119" 替代 - "8088:9119"
  • 查看端口占用：netstat -ano | findstr ":8088"
  • 终止占用进程或更换端口
Resources
📚 学习资源
官方文档
实战教程
社区资源
  • MCP Servers 仓库
  • Hermes Discord 社区
  • Dify 开发者论坛
My Notes
📝 我的学习笔记

暂无笔记内容
你可以在这里添加自己在实践中总结的经验、遇到的问题和解决方案