MCP 集成

MCP（Model Context Protocol）是 Anthropic 推出的开放协议，用于标准化 AI 模型与外部工具、数据源之间的交互。Hermes 既可以作为 MCP 客户端消费外部服务器提供的工具，也可以作为 MCP 服务器向其他客户端暴露自身能力。

Hermes 作为 MCP 客户端

基本配置

在 ~/.hermes/config.yaml 的 mcp_servers 节点下配置外部 MCP 服务器：

mcp_servers:
  # 本地进程型 MCP 服务器（stdio 传输）
  filesystem:
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "/home/user/documents"

  # 远程 HTTP 型 MCP 服务器（SSE 传输）
  my_remote_service:
    url: "https://api.example.com/mcp"
    headers:
      Authorization: "Bearer ${MY_API_KEY}"
      X-Custom-Header: "value"

  # 带完整选项的本地服务器
  database_tools:
    command: python
    args:
      - "/opt/mcp-servers/db-server.py"
      - "--db-url"
      - "${DATABASE_URL}"

工具命名规则

MCP 服务器提供的工具以 mcp_<server_name>_<tool_name> 格式自动注册：

MCP 服务器名	原始工具名	Hermes 中的工具名
filesystem	read_file	mcp_filesystem_read_file
filesystem	write_file	mcp_filesystem_write_file
database_tools	query	mcp_database_tools_query
my_remote_service	search	mcp_my_remote_service_search

智能体可以直接使用这些工具，无需额外配置。

---

工具过滤

白名单（include）

只允许使用指定工具，其余工具不可见：

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    include:
      - list_repositories
      - get_file_contents
      - create_issue
      # create_pull_request 等其他工具被过滤掉

黑名单（exclude）

禁用特定工具，其余工具均可用：

mcp_servers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/"]
    exclude:
      - delete_file      # 禁止删除文件
      - move_file        # 禁止移动文件
      - write_file       # 只读访问

禁用资源和提示词

MCP 服务器除工具外还可以提供资源（Resources）和提示词（Prompts），可以按需禁用：

mcp_servers:
  my_server:
    command: ./my-mcp-server
    disable_resources: true   # 不加载资源列表
    disable_prompts: true     # 不加载提示词模板

---

运行时重载

无需重启 Hermes 即可重新加载 MCP 服务器配置：

/reload-mcp

执行后 Hermes 将：

1. 断开所有现有 MCP 连接
2. 重新读取 config.yaml 中的 mcp_servers 配置
3. 重新建立连接并注册工具

这对于开发 MCP 服务器时的调试迭代非常有用。

---

Hermes 作为 MCP 服务器

Hermes 自身也可以作为 MCP 服务器运行，将其工具和能力暴露给其他 MCP 客户端：

# 启动 MCP 服务器模式
hermes mcp serve

# 指定端口
hermes mcp serve --port 3000

# 指定传输协议
hermes mcp serve --transport stdio   # stdio 模式（适合本地客户端）
hermes mcp serve --transport sse     # SSE 模式（适合远程客户端）

暴露的能力

作为 MCP 服务器时，Hermes 将其工具集作为 MCP 工具暴露：

{
  "tools": [
    {"name": "web_search", "description": "..."},
    {"name": "terminal", "description": "..."},
    {"name": "memory", "description": "..."}
  ]
}

---

MCP Sampling（采样请求）

MCP 1.0 引入了 Sampling 功能，允许 MCP 服务器向 Hermes 请求 LLM 推理，而不需要自己持有 API 密钥。

基本配置

mcp_servers:
  smart_tool:
    command: ./smart-mcp-server
    sampling:
      enabled: true                    # 允许此服务器发起采样请求
      model: claude-3-5-haiku-20241022 # 覆盖模型（可选）
      max_tokens: 1000                 # 单次请求 Token 上限
      rate_limit:
        requests_per_minute: 10        # 每分钟请求次数限制
        tokens_per_hour: 50000         # 每小时 Token 用量限制
      audit_log: true                  # 记录所有采样请求到日志

审计日志

启用 audit_log 后，所有采样请求记录在 ~/.hermes/logs/mcp-sampling.log：

{
  "timestamp": "2025-04-07T10:23:45Z",
  "server": "smart_tool",
  "model": "claude-3-5-haiku-20241022",
  "tokens_used": 342,
  "prompt_preview": "Analyze the following data...",
  "status": "success"
}

---

ACP 编辑器集成

ACP（Agent Communication Protocol）是 Hermes 提供的编辑器集成功能，让您可以在 IDE 中直接与 Hermes 交互，无需切换到终端。

# 启动 ACP 服务
hermes acp

VS Code 集成

1. 安装 Hermes VS Code 扩展
2. 在设置中配置 ACP 端点：

{
  "hermes.acp.endpoint": "http://localhost:7373",
  "hermes.acp.autoStart": true
}

3. 使用快捷键 Ctrl+Shift+H 打开 Hermes 面板

Zed 集成

在 Zed 的 settings.json 中添加：

{
  "assistant": {
    "provider": {
      "type": "hermes-acp",
      "endpoint": "http://localhost:7373"
    }
  }
}

JetBrains 集成

安装 Hermes 插件后，在 Settings → Tools → Hermes 中配置：

ACP Endpoint: http://localhost:7373
Auto-connect: ✓

---

实用示例

集成 Postgres 数据库工具

mcp_servers:
  postgres:
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-postgres"
      - "${DATABASE_URL}"
    include:
      - query           # 只允许查询
    disable_resources: false  # 允许浏览表结构

集成 Slack 通知

mcp_servers:
  slack:
    url: "https://mcp.slack.com/v1"
    headers:
      Authorization: "Bearer ${SLACK_BOT_TOKEN}"
    include:
      - send_message
      - list_channels

集成本地知识库

mcp_servers:
  knowledge_base:
    command: python
    args: ["-m", "my_kb_server", "--data-dir", "/data/knowledge"]
    sampling:
      enabled: true
      max_tokens: 2000

---

常用 MCP 服务器

服务器	安装命令	提供工具
文件系统	npx @modelcontextprotocol/server-filesystem	读写本地文件
GitHub	npx @modelcontextprotocol/server-github	仓库、Issue、PR 操作
PostgreSQL	npx @modelcontextprotocol/server-postgres	数据库查询
Brave Search	npx @modelcontextprotocol/server-brave-search	网页搜索
Puppeteer	npx @modelcontextprotocol/server-puppeteer	浏览器自动化
Memory	npx @modelcontextprotocol/server-memory	知识图谱记忆
Slack	npx @modelcontextprotocol/server-slack	Slack 消息
Notion	npx @modelcontextprotocol/server-notion	Notion 文档