better-dsh 0.2.5 → 0.3.0-c

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

@@ -1,490 +0,0 @@
----
-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)