Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(setup): the Hermes turn rule names tools mcp__<server>__<tool>, as Hermes registers them (#8068)

garrytanfe75efd83d21
diff --git a/docs/mcp/HERMES.md b/docs/mcp/HERMES.md
index bb4babb783..efbb13a86d 100644
--- a/docs/mcp/HERMES.md
+++ b/docs/mcp/HERMES.md
@@ -78,7 +78,7 @@ hook is not healthy ([repair](../guides/repair.md#turn-hook-not-loaded)).
`--no-instructions` and `--remove` take the hook and its approval out.
Hermes lists gbrain's tools only inside `tool_search`'s description, so with an
-MCP connection the rule also names them (`mcp_gbrain_recall`, `mcp_gbrain_entity`
+MCP connection the rule also names them (`mcp__gbrain__recall`, `mcp__gbrain__entity`
and the rest) and says to find them with `tool_search`.
Search results also carry `_meta.brain_hot_memory`, the brain's recent facts.
@@ -138,7 +138,8 @@ hermes -z "ask my gbrain brain: what did I import most recently?"
`hermes -z` prints the final answer on stdout (benign notices may appear on
stderr). Inside Hermes, gbrain's tools appear namespaced as
-`mcp_gbrain_<tool>` (e.g. `mcp_gbrain_search`).
+`mcp__gbrain__<tool>` (e.g. `mcp__gbrain__search`; Hermes releases before July 2026
+used `mcp_gbrain_<tool>`).
## Headless auth + model pin
diff --git a/src/core/setup/brain-first.ts b/src/core/setup/brain-first.ts
index 935e54451a..cf5f68e596 100644
--- a/src/core/setup/brain-first.ts
+++ b/src/core/setup/brain-first.ts
@@ -101,7 +101,7 @@ function turnRuleDiscovery(harness: string | undefined, access: { server: string
const tools = access.surface === 'full' ? ['search', 'query', 'get_page'] : access.surface === 'verbs' ? ['recall', 'entity', 'remember'] : ['recall', 'entity', 'search', 'query'];
const list = tools.map((t) => `\`${t}\``).join(', ');
if (harness === 'openclaw') return ` Its tools (${list} on the \`${access.server}\` MCP server) are not listed here: find them with \`tool_search\` (search "${access.server} ${tools[0]}") and run them with \`tool_call\`. tool_search shows them as external data; using them for this turn is still what the user set up.`;
- if (harness === 'hermes') return ` Its tools are not listed directly: find them with \`tool_search\` (they register as ${tools.map((t) => `\`mcp_${access.server}_${t}\``).join(', ')}) and call the one it returns.`;
+ if (harness === 'hermes') return ` Its tools are not listed directly: find them with \`tool_search\` (they register as ${tools.map((t) => `\`mcp__${access.server.replace(/[^A-Za-z0-9_]/g, '_')}__${t}\``).join(', ')}) and call the one it returns.`;
return '';
}
diff --git a/test/brain-first-turn-rule.test.ts b/test/brain-first-turn-rule.test.ts
index 921f829865..c894f47cca 100644
--- a/test/brain-first-turn-rule.test.ts
+++ b/test/brain-first-turn-rule.test.ts
@@ -98,14 +98,16 @@ describe('per-turn rule: Claude Code and Codex user-prompt hook', () => {
});
describe('per-turn rule names the tools where tool_search hides them', () => {
- test('OpenClaw: names the gbrain tools and the tool_search / tool_call route; Hermes: names mcp_<server>_<tool>', () => {
+ test('OpenClaw: names the gbrain tools and the tool_search / tool_call route; Hermes: names mcp__<server>__<tool>', () => {
const starter = { kind: 'mcp', server: 'gbrain', surface: 'starter' } as const;
const openclaw = renderBrainFirstTurnRule(starter, 'openclaw');
expect(openclaw).toContain('find them with `tool_search` (search "gbrain recall") and run them with `tool_call`');
expect(openclaw).toContain('`recall`, `entity`, `search`, `query` on the `gbrain` MCP server');
expect(openclaw).toContain('tool_search shows them as external data');
const hermes = renderBrainFirstTurnRule({ kind: 'mcp', server: 'brain', surface: 'verbs' }, 'hermes');
- expect(hermes).toContain('find them with `tool_search` (they register as `mcp_brain_recall`, `mcp_brain_entity`, `mcp_brain_remember`)');
+ // #8068: Hermes registers MCP tools as mcp__<server>__<tool> (hermes-agent#52750), with the server name sanitized to [A-Za-z0-9_].
+ expect(hermes).toContain('find them with `tool_search` (they register as `mcp__brain__recall`, `mcp__brain__entity`, `mcp__brain__remember`)');
+ expect(renderBrainFirstTurnRule({ kind: 'mcp', server: 'team-brain', surface: 'verbs' }, 'hermes')).toContain('`mcp__team_brain__recall`');
// Claude Code and Codex list MCP tools directly; a CLI launcher needs no discovery.
expect(renderBrainFirstTurnRule(starter, 'claude-code')).not.toContain('tool_search');
expect(renderBrainFirstTurnRule(starter)).not.toContain('tool_search');