P19 19_能力篇_MCP本地服务

课时概要

能力篇 · MCP 本地服务。Hermes 自身可以作为 MCP server 被外部调用（仓库根有 mcp_serve.py），也能连本地 MCP 服务。

本分P 没有逐P 的官方简介（视频简介只有资源链接）。以下「本节要点 / 关键概念 / 代码实操」均改写自 Hermes 官方文档（MCP 页 + Use MCP with Hermes 指南）与官方仓库原文并标注来源；「我的收获」里标 本机实测 的是在本机实跑得到的真实状态。

视频：19_能力篇_MCP本地服务｜时长 7:13 ｜ P19

本节要点

MCP 给 Hermes 带来什么（官方 What MCP gives you）：不必先写一个原生 Hermes 工具，就能接入外部工具生态；本地 stdio 与远程 HTTP 可以在同一份配置里；启动时自动发现并注册工具；服务器支持的话自动加 resources / prompts 的 utility 包装；还能按服务器过滤，只把你真想让它看到的工具暴露出去。
两类 MCP 服务器（官方原文）：Stdio servers 是本地子进程，用 stdin/stdout 通信；HTTP servers 是 Hermes 直连的远程端点。本课时的「本地服务」讲的就是 stdio。
最小 stdio 配置（官方原文）：mcp_servers: → filesystem: → command: "npx" / args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]。MCP 支持随标准安装一起提供，不需要额外步骤。
stdio 常用配置键（官方 Common keys）：command 可执行文件｜ args 参数｜ env 环境变量｜ cwd 子进程工作目录（默认：会话被钉住时用会话工作目录，否则用 Hermes 进程目录）｜ timeout 工具调用超时｜ connect_timeout 首次连接超时（同时约束 MCP initialize 握手）｜ lazy 惰性启动｜ idle_timeout_seconds 闲置多久回收｜ max_lifetime_seconds 最大存活时长｜ enabled ｜ supports_parallel_tool_calls ｜ tools 过滤策略。
内置 preset（免去查 command/args）：hermes mcp add codex --preset codex 一行把 Codex CLI 接成 MCP 服务器（等价于 command: "codex" / args: ["mcp-server"]）。preset 只提供默认值，你另传的 env/headers/过滤仍然优先。
工具命名规则：Hermes 给 MCP 工具加前缀 mcp_<服务器名>_<工具名>（例：filesystem 的 read_file → mcp_filesystem_read_file；my-api 的 query.data → mcp_my_api_query_data）。实际使用时通常不用手写全名，Hermes 推理时会自己选。
工具结果会被净化（官方 Tool-result sanitization）：① 不可见的 U+E0000–U+E007F TAG 字符会被剥掉 —— 它们在终端/聊天界面里不可见、对模型却完全可见，是经典的提示注入走私通道（合法 emoji tag 序列如 🏴󠁧󠁢󠁳󠁣󠁴󠁿 会保留）② 厂商 _meta 会透传给模型，但协议保留前缀（modelcontextprotocol… / mcp…）的键会被丢掉。
utility 工具（服务器支持时才有）：list_resources / read_resource / list_prompts / get_prompt，同样带前缀（如 mcp_github_list_resources）。它们是能力感知的：只有 MCP 会话真的支持 resource / prompt 操作才会注册 —— 只暴露 callable tools 的服务器不会得到这些包装。
stdio 的安全模型：Hermes 不会把你完整的 shell 环境盲传给子进程 —— 只传显式配置的 env 加一份安全基线，降低密钥意外泄漏的风险。
回收吃内存的 stdio 服务器：浏览器类 MCP（如 @playwright/mcp）首次调用后会常驻一整个 Chromium（数百 MB 不释放）→ 配 idle_timeout_seconds: 900 + max_lifetime_seconds: 86400，到点就拆、下次调用透明重启（工具全程保持已注册）。
Hermes 自己也能当 MCP 服务器：hermes mcp serve 起一个 stdio MCP server，把 Hermes 的会话暴露给别的 agent（读操作不需要 gateway，发消息需要）。
「启动时发现」是默认行为：Hermes 在启动时发现 MCP 服务器并把工具注册进常规工具注册表；改配置后用 /reload-mcp。

关键概念

MCP（Model Context Protocol）：让 agent 通过统一协议接入外部工具/资源的标准；对 Hermes 来说 = 低成本扩工具面，不用先写原生工具。
stdio server：作为本地子进程运行、走 stdin/stdout 的 MCP 服务器。适合「服务器装在本地」「要低延迟访问本地资源」「跟着 MCP 文档给出的 command/args/env 走」这三种情况。
工具名前缀 mcp_<server>_<tool>：Hermes 的防冲突命名，服务器名里的 - 会规范成 _。
utility 工具：把 MCP 的 resources / prompts 包装成可调用工具（list/read、list/get），且只在服务器真支持时注册。
env 白名单：stdio 子进程只拿到显式配置的环境变量 + 安全基线，不是你的整个 shell 环境。
hermes mcp serve：反向用法 —— 把 Hermes 变成别人的 MCP 服务器。

代码 / 实操

yaml

# ~/.hermes/config.yaml —— 最小 stdio 配置（官方原文）
mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

bash

# 内置 preset：一行接入 Codex CLI
hermes mcp add codex --preset codex
 
# 查看 / 测试 / 过滤
hermes mcp list                 # 列出已配置服务器
hermes mcp test github          # 测试连接
hermes mcp configure github     # 交互式选工具
 
# 反向：把 Hermes 当 MCP server 暴露给别的 agent
hermes mcp serve

本机实测（2026-09-25）：hermes mcp list 列出 7 个服务器、全部 ✓ enabled；其中 5 个是 stdio：

github           /Users/fkycoya/.npm-global/bin/mcp-server-github
agentkey         /Users/fkycoya/.npm-global/bin/agentkey-mcp
hermes-studio    hermes-studio-mcp
codegraph        codegraph serve --mcp
open-knowledge   /bin/sh -l -c   （走 OpenKnowledge.app 自带 ok.sh）

hermes doctor 的 MCP Server Security: ✓ No suspicious MCP stdio commands 也是 ✓。

我的收获

用户此前已完成本模块的学习与配置；以下是本机实测状态（2026-09-25）：

本机 7 个 MCP 里 5 个是 stdio（github / agentkey / hermes-studio / codegraph / open-knowledge）—— 正好是官方说的「服务器装在本地、要低延迟访问本地资源」那一类；github 与 agentkey 直接指向 ~/.npm-global/bin/ 下的本地可执行文件。
open-knowledge 的配置是 command: /bin/sh + args: [-l, -c, …] 再调 OpenKnowledge.app 里的 ok.sh —— 说明 stdio 服务器不限于 npx，任何能起进程并说 MCP 的壳都行。
codegraph 带 timeout: 120 / connect_timeout: 60 —— 印证官方那两个超时键在真实配置里的用法（本地索引型服务器首次连可能慢）。
本机 7 个服务器都没有配 tools.include/exclude（全是 all）→ 官方说的「config 级过滤就是安全控制」这条我还没用上，属于可收紧项。
hermes doctor 的 MCP 安全项为 ✓：没有可疑的 MCP stdio 命令。

（个人感想部分待补写。）

待深入

（待填：没听懂、想回头查的。）

课时概要

本节要点

关键概念

代码 / 实操

我的收获

待深入

Related Posts