Hermes Agent MCP 配置上下文变量：${userHome}、${workspaceFolder} 等 5 个 Cursor 风格变量详解

配置 MCP 服务器本该是五分钟的事，但对大多数人来说不是——因为配置里全是绝对路径。/Users/you/.cache/mcp、C:\Users\you\projects\webapp：每换一台机器、每来一个同事、每挪一次文件夹，就得改一遍配置，共享的 mcp.json 很快就变得没法移植。这周 Hermes 引入了 Cursor 风格的上下文变量，让这些路径变得可移植——配置写一次，到处都能用。

还在 MCP 配置里写死路径？

配置 MCP 服务器时，最烦人的就是路径：/Users/neo/.cache/mcp、C:\Users\neo\projects\webapp……换个机器、换个用户、换个项目目录就要改一遍。更麻烦的是，如果团队把 MCP 配置提交进仓库共享，每个人的绝对路径都不一样，mcp.json 几乎无法通用。

2026-08-08 合入 Hermes Agent main 的新特性解决了这个问题：MCP 服务器配置现在支持 Cursor 风格的上下文变量插值——${userHome}、${workspaceFolder}、${workspaceFolderBasename}、${pathSeparator} 和 ${/}。这意味着两件事：

  1. 你在 Cursor 里写好的 mcp.json 配置，搬进 Hermes 不用改任何路径；
  2. 配置里的路径终于可以写成相对语义的形式，跨机器、跨用户通用。

5 个上下文变量一览

变量（大小写敏感） 解析结果
${userHome} 当前用户主目录（os.path.expanduser("~")）
${workspaceFolder} 会话工作区根目录（见下方解析链）
${workspaceFolderBasename} ${workspaceFolder} 的 basename（最后一级目录名）
${pathSeparator} 操作系统的路径分隔符（os.sep，Windows 为 \，其他为 /）
${/} ${pathSeparator} 的简写

⚠️ 大小写敏感：只有上面这五个精确拼写会被识别。${USERHOME} 不会被当成上下文变量——它和任何其他 ${...} 一样，走原有的环境变量查找逻辑。

实际配置示例

变量可以出现在服务器条目的任何字符串位置：args、env、url、headers 都可以。

示例 1：filesystem server 指向当前工作区

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]

无论你在哪个项目目录启动 Hermes，filesystem server 都会自动指向当前会话的工作区——不需要记住 session id，也不需要先 cd。

示例 2：缓存目录用主目录 + 分隔符拼接

mcp_servers:
  my-server:
    command: "node"
    args: ["server.js"]
    env:
      CACHE_DIR: "${userHome}${/}.cache${/}mcp"

${/} 让这条配置在 Windows（\）和 macOS/Linux（/）上同时成立，一条配置全平台通用。

示例 3：从 Cursor 直接迁移

Cursor 的 mcp.json 里最常见的写法是 "${env:VAR}" 形式的密钥引用。Hermes 同样支持：

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${env:GITHUB_TOKEN}"

${env:GITHUB_TOKEN} 与 ${GITHUB_TOKEN} 解析到同一个变量，值从当前 profile 的 secret 作用域读取（回退到进程环境变量），所以密钥放进 ~/.hermes/.env 即可。未设置的变量保留字面占位符，不会报错。

${workspaceFolder} 的解析链（按优先级）

${workspaceFolder} 并不是简单地取进程启动目录，而是走一个三级解析：

  1. 会话记录的终端 cwd：每次终端命令完成时都会写入的会话级记录（terminal_tool.get_session_cwd），按原始 session id 键控——一个会话的 cd 永远不会泄漏到另一个会话；
  2. 注册的任务/会话 cwd 覆盖：TUI / Desktop / ACP 会话在跑任何工具前注册的 cwd；
  3. 无哨兵的绝对 $TERMINAL_CWD：hermes -w <worktree> 会话设置的工作树路径。

以上都没有可靠锚点时，才回退到进程的 os.getcwd()。

这意味着：你在桌面应用里打开某个项目、或在 TUI 里 cd 到子目录后，${workspaceFolder} 会跟着当前会话的实际工作区走，而不是启动时的目录。

解析顺序：上下文变量 → 环境变量 → 字面量

整个插值过程对每个 ${...} 引用依次尝试：

  1. 精确匹配 5 个上下文变量（优先）；
  2. 环境变量查找（profile secret 作用域 → os.environ）；
  3. 都不命中则保留字面占位符（例如 "${NOT_EXIST}" 原样保留）。

所以上下文变量不会改变任何已有环境变量语义——${HOME} 之类的旧写法完全不受影响，只是新增了 5 个“先手”名字。

什么时候值得用

  • 团队共享配置：把 mcp_servers 提交进仓库，任何成员 clone 后直接可用，不再互相踩绝对路径；
  • 多机同步：台式机 + 笔记本 + CI 环境共用一份配置，${userHome} / ${/} 抹平平台差异；
  • 工作区相关工具：需要基于当前项目运行的 server（filesystem、linter、代码检索），${workspaceFolder} 自动跟随会话。

想复习 MCP 服务器的完整配置键（tools.include/exclude、trust 信任层级、auth: oauth 等），可以看站内的 hermes mcp 命令参考；想了解 MCP 在 v0.20.0 里随发布带来的其他能力，参考 v0.20.0 Herald 发版解析。如果你刚接触 Hermes Agent，建议先走一遍安装指南再回来试验。

一句话总结：写 MCP 配置时，把绝对路径换成 ${userHome}、${workspaceFolder}、${/}，你的配置就同时获得了可移植性和“跟随当前工作区”的智能——和 Cursor 生态的配置互相通用，无需任何修改。