better-dsh 0.2.4 → 0.2.5-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/use-mcp-with-hermes.md

@@ -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 {#wsl2-bridge-hermes-in-wsl-to-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)