Hermes target: invalid toolset name in `platform_toolsets.cli` + refresh overwrites an existing `mcp_servers.codegraph` block

Start in src/installer/targets/hermes.ts, at upsertCodeGraphToolset (which writes the invalid mcp-codegraph line) and upsertCodeGraphMcpServer with renderCodeGraphMcpChild (which overwrites an existing mcp_servers.codegraph block). Check the existing contract tests in tests/installer-targets.test.ts. Done means a refresh adds only missing keys, leaves user-set values intact, and no longer writes the mcp-codegraph platform_toolsets entry; the platform_toolsets approach still needs a maintainer decision.

Environment

• codegraph 1.5.0 → 1.6.2 on Linux (Debian), installed via the official installer; upgrade via codegraph upgrade.
• Hermes Agent v0.21.6 (git install), config file ~/.hermes/config.yaml (YAML, 43 top-level keys).
• codegraph upgrade printed: Hermes Agent: refreshed <config>.yaml.

Both problems below come from that refresh step. They are independent: one is a wrong key value, one is a destructive write.

1. platform_toolsets.cli gets a toolset name Hermes does not know

upsertCodeGraphToolset() (src/installer/targets/hermes.ts, compiled lib/dist/installer/targets/hermes.js:322/326/334) adds - mcp-codegraph to platform_toolsets.cli. Every Hermes CLI start then prints:

Warning: Unknown toolsets: mcp-codegraph

Hermes-side reason: the startup check accepts a name only if validate_toolset(name) is true, or the name is a key of mcp_servers (bare server name), or it is a plugin toolset key (hermes_cli/cli_init_mixin.py). For an MCP server registered as codegraph, the bare name codegraph passes — it is an mcp_servers key, and tools/mcp_tool_registration.py:366 registers it as a toolset alias to mcp-codegraph (validate_toolset() accepts registry aliases, toolsets.py:476-478). The literal mcp-codegraph matches none of the three checks.

The comment at the top of the target file says the entry is required, otherwise "the MCP server can be configured and connected but its tools may still be filtered out". In current Hermes that is not the case, and the naive fix is not safe either. _merge_mcp_servers() (hermes_cli/tools_config.py:694-706) has allowlist semantics:

• platform list contains no MCP server name → every globally enabled MCP server is enabled for that platform;
• platform list names at least one MCP server → the list becomes an allowlist, and only the named servers survive.

Verified against a config with three enabled servers (agentmail, codegraph, donsetch) in Hermes v0.21.6:

So writing the bare server name would introduce a silent regression: it hides every other configured MCP server from that platform. The minimal correct behaviour is to not write a platform_toolsets entry at all (and to not re-add one the user deleted — see below).

2. The refresh rewrites an existing, valid MCP block

upsertCodeGraphMcpServer() (hermes.js:281-299) reads the existing mcp_servers.codegraph: child block, compares it to the hardcoded template renderCodeGraphMcpChild() (hermes.js:261-272) and, when they differ, splice()s the template over the user's block. Any adaptation is destroyed — including a working absolute command path:

# before the upgrade (working, produced by an earlier install)
mcp_servers:
  codegraph:
    command: /home/<user>/.local/bin/codegraph
    args: [serve, --mcp]
    timeout: 120
    connect_timeout: 60
    enabled: true

# after `codegraph upgrade` — command reverted to the bare name
mcp_servers:
  codegraph:
    command: codegraph
    ...

Reproducer: set mcp_servers.codegraph.command to an absolute path, run any install/refresh, diff the file — exactly one line changed, back to codegraph. The same applies to args, timeout, connect_timeout, enabled.

For an agent config, a bare command is a real risk: MCP stdio servers are spawned by the agent's process environment, and Hermes runs in contexts whose PATH does not always contain the user bin directory. A hand-set absolute path is the deliberate fix for that; the refresh silently undoes it.

Expectation, and consistent with the installer's own contract tests for the other targets (__tests__/installer-targets.test.ts: install idempotency, sibling preservation, byte-equal re-runs returning unchanged): a refresh should add missing keys and leave existing, valid values alone. Deleting a key the user removed is also part of that: platform_toolsets entries are added when missing (hermes.js:331-334), so a user who removes the invalid mcp-codegraph line to silence the warning gets it back on the next refresh — the warning is not fixable from the config side as long as the target keeps writing it.

Versions / evidence

• src/installer/targets/hermes.ts is byte-identical between v1.5.0 and v1.6.2, so none of this changed in the current release:
  • v1.5.0: sha256 410c9b67183c455a9cd19e99aa62c911e6522b38bfde97a024a9269d47c9bec5
  • v1.6.2: sha256 410c9b67183c455a9cd19e99aa62c911e6522b38bfde97a024a9269d47c9bec5
• Hermes-side references: hermes_cli/cli_init_mixin.py (unknown-toolset startup check), toolsets.py:476-478 (validate_toolset accepts registry aliases), tools/mcp_tool_registration.py:366 (registers <server> → mcp-<server> alias), hermes_cli/tools_config.py:694-706 (_merge_mcp_servers allowlist behaviour).

Suggested fix

1. Stop writing platform_toolsets for Hermes (no entry = all enabled MCP servers, which is what the config had before the installer touched it), or make it conditional on the user not having a saved list for that platform.
2. Make the MCP-block upsert additive: fill in keys that are missing, leave present keys untouched (the same "preserve siblings / byte-equal re-run = unchanged" contract the other targets already test).
3. If a platform_toolsets entry is kept for older Hermes versions, at least use the bare server name and never overwrite a value the user set.