Hermes-agent
This commit is contained in:
Zakaria
+490
@@ -0,0 +1,490 @@
|
||||
---
|
||||
sidebar_position: 6
|
||||
title: "在 Hermes 中使用 MCP"
|
||||
description: "将 MCP 服务器连接到 Hermes Agent、过滤其工具并在实际工作流中安全使用的实践指南"
|
||||
---
|
||||
|
||||
# 在 Hermes 中使用 MCP
|
||||
|
||||
本指南介绍如何在日常工作流中实际使用 Hermes Agent 的 MCP 功能。
|
||||
|
||||
如果功能页面解释的是 MCP 是什么，本指南则关注如何快速、安全地从中获取价值。
|
||||
|
||||
## 何时应该使用 MCP？
|
||||
|
||||
在以下情况下使用 MCP：
|
||||
- 工具已以 MCP 形式存在，且你不想构建原生 Hermes 工具
|
||||
- 你希望 Hermes 通过干净的 RPC 层操作本地或远程系统
|
||||
- 你需要细粒度的按服务器暴露控制
|
||||
- 你希望将 Hermes 连接到内部 API、数据库或公司系统，而无需修改 Hermes 核心
|
||||
|
||||
在以下情况下不要使用 MCP：
|
||||
- 内置 Hermes 工具已能很好地完成该工作
|
||||
- 服务器暴露了大量危险工具，而你没有准备好对其进行过滤
|
||||
- 你只需要一个非常窄的集成，原生工具会更简单、更安全
|
||||
|
||||
## 心智模型
|
||||
|
||||
将 MCP 视为一个适配器层：
|
||||
|
||||
- Hermes 仍然是 agent
|
||||
- MCP 服务器提供工具
|
||||
- Hermes 在启动或重新加载时发现这些工具
|
||||
- 模型可以像使用普通工具一样使用它们
|
||||
- 你控制每个服务器有多少内容可见
|
||||
|
||||
最后一点很重要。良好的 MCP 使用不是"连接一切"，而是"以最小的有效范围连接正确的东西"。
|
||||
|
||||
## 第一步：安装 MCP 支持
|
||||
|
||||
如果你使用标准安装脚本安装了 Hermes，MCP 支持已包含在内（安装程序会运行 `uv pip install -e ".[all]"`）。
|
||||
|
||||
如果你在没有附加组件的情况下安装，需要单独添加 MCP：
|
||||
|
||||
```bash
|
||||
cd ~/.hermes/hermes-agent
|
||||
uv pip install -e ".[mcp]"
|
||||
```
|
||||
|
||||
对于基于 npm 的服务器，请确保 Node.js 和 `npx` 可用。
|
||||
|
||||
对于许多 Python MCP 服务器，`uvx` 是一个不错的默认选择。
|
||||
|
||||
## 第二步：先添加一个服务器
|
||||
|
||||
从单个、安全的服务器开始。
|
||||
|
||||
示例：仅访问一个项目目录的文件系统。
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
project_fs:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]
|
||||
```
|
||||
|
||||
然后启动 Hermes：
|
||||
|
||||
```bash
|
||||
hermes chat
|
||||
```
|
||||
|
||||
现在提出一个具体问题：
|
||||
|
||||
```text
|
||||
Inspect this project and summarize the repo layout.
|
||||
```
|
||||
|
||||
## 第三步：验证 MCP 已加载
|
||||
|
||||
你可以通过以下几种方式验证 MCP：
|
||||
|
||||
- 配置后 Hermes 横幅/状态应显示 MCP 集成
|
||||
- 询问 Hermes 当前有哪些可用工具
|
||||
- 配置更改后使用 `/reload-mcp`
|
||||
- 如果服务器连接失败，检查日志
|
||||
|
||||
一个实用的测试 prompt（提示词）：
|
||||
|
||||
```text
|
||||
Tell me which MCP-backed tools are available right now.
|
||||
```
|
||||
|
||||
## 第四步：立即开始过滤
|
||||
|
||||
如果服务器暴露了大量工具，不要等到以后再过滤。
|
||||
|
||||
### 示例：仅白名单你需要的内容
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
|
||||
tools:
|
||||
include: [list_issues, create_issue, search_code]
|
||||
```
|
||||
|
||||
对于敏感系统，这通常是最佳默认设置。
|
||||
|
||||
## WSL2：将 WSL 中的 Hermes 桥接到 Windows Chrome
|
||||
|
||||
以下是适用场景的实际配置：
|
||||
|
||||
- Hermes 在 WSL2 内运行
|
||||
- 你想控制的浏览器是 Windows 上已登录的普通 Chrome
|
||||
- 从 WSL 使用 `/browser connect` 不稳定或不可靠
|
||||
|
||||
在此配置中，Hermes **不**直接连接到 Chrome，而是：
|
||||
|
||||
- Hermes 在 WSL 中运行
|
||||
- Hermes 启动一个本地 stdio MCP 服务器
|
||||
- 该 MCP 服务器通过 Windows 互操作（`cmd.exe` 或 `powershell.exe`）启动
|
||||
- MCP 服务器附加到你的实时 Windows Chrome 会话
|
||||
|
||||
心智模型：
|
||||
|
||||
```text
|
||||
Hermes (WSL) -> MCP stdio bridge -> Windows Chrome
|
||||
```
|
||||
|
||||
### 为什么此模式有用
|
||||
|
||||
- 你保留真实的 Windows 浏览器配置文件、Cookie 和登录状态
|
||||
- Hermes 保持在其支持的 Unix 环境（WSL2）中
|
||||
- 浏览器控制以 MCP 工具的形式暴露，而不依赖 Hermes 核心浏览器传输
|
||||
|
||||
### 推荐服务器
|
||||
|
||||
使用 `chrome-devtools-mcp`。
|
||||
|
||||
如果你的 Windows Chrome 已通过 `chrome://inspect/#remote-debugging` 启用了实时远程调试，在 WSL 中按如下方式添加：
|
||||
|
||||
```bash
|
||||
hermes mcp add chrome-devtools-win --command cmd.exe --args /c npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics
|
||||
```
|
||||
|
||||
保存服务器后：
|
||||
|
||||
```bash
|
||||
hermes mcp test chrome-devtools-win
|
||||
```
|
||||
|
||||
然后启动一个新的 Hermes 会话或运行：
|
||||
|
||||
```text
|
||||
/reload-mcp
|
||||
```
|
||||
|
||||
### 典型 prompt
|
||||
|
||||
加载后，Hermes 可以直接使用带 MCP 前缀的浏览器工具。例如：
|
||||
|
||||
```text
|
||||
调用 MCP 工具 mcp_chrome_devtools_win_list_pages，列出当前浏览器标签页。
|
||||
```
|
||||
|
||||
### 何时 `/browser connect` 不适用
|
||||
|
||||
如果 Hermes 在 WSL 中运行而 Chrome 在 Windows 上运行，即使 Chrome 已打开且可调试，`/browser connect` 也可能失败。
|
||||
|
||||
常见原因：
|
||||
|
||||
- WSL 无法访问 Chrome 向 Windows 工具暴露的同一主机本地端点
|
||||
- 较新的 Chrome 实时调试流程与经典的 `ws://localhost:9222` 不同
|
||||
- 从 Windows 端辅助工具（如 `chrome-devtools-mcp`）附加浏览器更容易
|
||||
|
||||
在这些情况下，将 `/browser connect` 用于同环境配置，使用 MCP 进行 WSL 到 Windows 的浏览器桥接。
|
||||
|
||||
### 已知问题
|
||||
|
||||
- 通过 MCP 使用 Windows stdio 可执行文件时，从 `/mnt/c/Users/<you>` 或 `/mnt/c/workspace/...` 等 Windows 挂载路径启动 Hermes。
|
||||
- 如果从 `/root` 或 `/home/...` 启动 Hermes，Windows 可能在 MCP 服务器启动前发出 `UNC` 当前目录警告。
|
||||
- 如果 `chrome-devtools-mcp --autoConnect` 在枚举页面时超时，请减少 Chrome 中的后台/冻结标签页并重试。
|
||||
|
||||
### 示例：黑名单危险操作
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
stripe:
|
||||
url: "https://mcp.stripe.com"
|
||||
headers:
|
||||
Authorization: "Bearer ***"
|
||||
tools:
|
||||
exclude: [delete_customer, refund_payment]
|
||||
```
|
||||
|
||||
### 示例：同时禁用实用工具包装器
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
docs:
|
||||
url: "https://mcp.docs.example.com"
|
||||
tools:
|
||||
prompts: false
|
||||
resources: false
|
||||
```
|
||||
|
||||
## 过滤实际影响什么？
|
||||
|
||||
Hermes 中 MCP 暴露的功能分为两类：
|
||||
|
||||
1. 服务器原生 MCP 工具
|
||||
- 通过以下方式过滤：
|
||||
- `tools.include`
|
||||
- `tools.exclude`
|
||||
|
||||
2. Hermes 添加的实用工具包装器
|
||||
- 通过以下方式过滤：
|
||||
- `tools.resources`
|
||||
- `tools.prompts`
|
||||
|
||||
### 你可能看到的实用工具包装器
|
||||
|
||||
Resources（资源）：
|
||||
- `list_resources`
|
||||
- `read_resource`
|
||||
|
||||
Prompts（提示词）：
|
||||
- `list_prompts`
|
||||
- `get_prompt`
|
||||
|
||||
这些包装器仅在以下情况下出现：
|
||||
- 你的配置允许它们，且
|
||||
- MCP 服务器会话实际支持这些能力
|
||||
|
||||
因此，如果服务器不支持 resources/prompts，Hermes 不会假装它支持。
|
||||
|
||||
## 常见模式
|
||||
|
||||
### 模式 1：本地项目助手
|
||||
|
||||
当你希望 Hermes 在有界工作区内推理时，使用 MCP 连接仓库本地的文件系统或 git 服务器。
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
fs:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]
|
||||
|
||||
git:
|
||||
command: "uvx"
|
||||
args: ["mcp-server-git", "--repository", "/home/user/project"]
|
||||
```
|
||||
|
||||
好的 prompt：
|
||||
|
||||
```text
|
||||
Review the project structure and identify where configuration lives.
|
||||
```
|
||||
|
||||
```text
|
||||
Check the local git state and summarize what changed recently.
|
||||
```
|
||||
|
||||
### 模式 2：GitHub 分类助手
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
|
||||
tools:
|
||||
include: [list_issues, create_issue, update_issue, search_code]
|
||||
prompts: false
|
||||
resources: false
|
||||
```
|
||||
|
||||
好的 prompt：
|
||||
|
||||
```text
|
||||
List open issues about MCP, cluster them by theme, and draft a high-quality issue for the most common bug.
|
||||
```
|
||||
|
||||
```text
|
||||
Search the repo for uses of _discover_and_register_server and explain how MCP tools are registered.
|
||||
```
|
||||
|
||||
### 模式 3：内部 API 助手
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
internal_api:
|
||||
url: "https://mcp.internal.example.com"
|
||||
headers:
|
||||
Authorization: "Bearer ***"
|
||||
tools:
|
||||
include: [list_customers, get_customer, list_invoices]
|
||||
resources: false
|
||||
prompts: false
|
||||
```
|
||||
|
||||
好的 prompt：
|
||||
|
||||
```text
|
||||
Look up customer ACME Corp and summarize recent invoice activity.
|
||||
```
|
||||
|
||||
在这类场景中，严格的白名单远优于排除列表。
|
||||
|
||||
### 模式 4：文档/知识服务器
|
||||
|
||||
某些 MCP 服务器暴露的 prompts 或 resources 更像是共享知识资产，而非直接操作。
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
docs:
|
||||
url: "https://mcp.docs.example.com"
|
||||
tools:
|
||||
prompts: true
|
||||
resources: true
|
||||
```
|
||||
|
||||
好的 prompt：
|
||||
|
||||
```text
|
||||
List available MCP resources from the docs server, then read the onboarding guide and summarize it.
|
||||
```
|
||||
|
||||
```text
|
||||
List prompts exposed by the docs server and tell me which ones would help with incident response.
|
||||
```
|
||||
|
||||
## 教程：带过滤的端到端配置
|
||||
|
||||
以下是一个实际的渐进式流程。
|
||||
|
||||
### 阶段 1：使用严格白名单添加 GitHub MCP
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
|
||||
tools:
|
||||
include: [list_issues, create_issue, search_code]
|
||||
prompts: false
|
||||
resources: false
|
||||
```
|
||||
|
||||
启动 Hermes 并询问：
|
||||
|
||||
```text
|
||||
Search the codebase for references to MCP and summarize the main integration points.
|
||||
```
|
||||
|
||||
### 阶段 2：仅在需要时扩展
|
||||
|
||||
如果之后还需要更新 issue：
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
include: [list_issues, create_issue, update_issue, search_code]
|
||||
```
|
||||
|
||||
然后重新加载：
|
||||
|
||||
```text
|
||||
/reload-mcp
|
||||
```
|
||||
|
||||
### 阶段 3：添加具有不同策略的第二个服务器
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
|
||||
tools:
|
||||
include: [list_issues, create_issue, update_issue, search_code]
|
||||
prompts: false
|
||||
resources: false
|
||||
|
||||
filesystem:
|
||||
command: "npx"
|
||||
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]
|
||||
```
|
||||
|
||||
现在 Hermes 可以组合使用它们：
|
||||
|
||||
```text
|
||||
Inspect the local project files, then create a GitHub issue summarizing the bug you find.
|
||||
```
|
||||
|
||||
这就是 MCP 的强大之处：无需修改 Hermes 核心即可实现多系统工作流。
|
||||
|
||||
## 安全使用建议
|
||||
|
||||
### 对危险系统优先使用白名单
|
||||
|
||||
对于任何涉及财务、面向客户或具有破坏性的系统：
|
||||
- 使用 `tools.include`
|
||||
- 从尽可能小的集合开始
|
||||
|
||||
### 禁用未使用的实用工具
|
||||
|
||||
如果你不希望模型浏览服务器提供的 resources/prompts，请将其关闭：
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
resources: false
|
||||
prompts: false
|
||||
```
|
||||
|
||||
### 保持服务器范围狭窄
|
||||
|
||||
示例：
|
||||
- 文件系统服务器根目录指向一个项目目录，而非整个主目录
|
||||
- git 服务器指向一个仓库
|
||||
- 内部 API 服务器默认以读取为主的工具暴露
|
||||
|
||||
### 配置更改后重新加载
|
||||
|
||||
```text
|
||||
/reload-mcp
|
||||
```
|
||||
|
||||
在更改以下内容后执行此操作：
|
||||
- include/exclude 列表
|
||||
- enabled 标志
|
||||
- resources/prompts 开关
|
||||
- 认证 header / env
|
||||
|
||||
## 按症状排查问题
|
||||
|
||||
### "服务器已连接，但我期望的工具不见了"
|
||||
|
||||
可能原因：
|
||||
- 被 `tools.include` 过滤
|
||||
- 被 `tools.exclude` 排除
|
||||
- 实用工具包装器通过 `resources: false` 或 `prompts: false` 禁用
|
||||
- 服务器实际上不支持 resources/prompts
|
||||
|
||||
### "服务器已配置，但什么都没加载"
|
||||
|
||||
检查：
|
||||
- 配置中是否遗留了 `enabled: false`
|
||||
- 命令/运行时是否存在（`npx`、`uvx` 等）
|
||||
- HTTP 端点是否可达
|
||||
- 认证 env 或 header 是否正确
|
||||
|
||||
### "为什么我看到的工具比 MCP 服务器公告的少？"
|
||||
|
||||
因为 Hermes 现在遵守你的按服务器策略和能力感知注册。这是预期行为，通常也是期望的结果。
|
||||
|
||||
### "如何在不删除配置的情况下移除 MCP 服务器？"
|
||||
|
||||
使用：
|
||||
|
||||
```yaml
|
||||
enabled: false
|
||||
```
|
||||
|
||||
这会保留配置，但阻止连接和注册。
|
||||
|
||||
## 推荐的首批 MCP 配置
|
||||
|
||||
适合大多数用户的首选服务器：
|
||||
- filesystem
|
||||
- git
|
||||
- GitHub
|
||||
- fetch / 文档 MCP 服务器
|
||||
- 一个范围窄的内部 API
|
||||
|
||||
不适合作为首选的服务器：
|
||||
- 具有大量破坏性操作且未经过滤的大型业务系统
|
||||
- 任何你不够了解、无法加以约束的系统
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [MCP（模型上下文协议）](/user-guide/features/mcp)
|
||||
- [FAQ](/reference/faq)
|
||||
- [斜杠命令](/reference/slash-commands)
|
||||
Reference in New Issue
Block a user