mirror of
https://github.com/colbymchenry/codegraph.git
synced 2026-10-24 06:53:52 +08:00
Colby MchenryandClaude Opus 5.5
7dfef8451f
Root cause, two parts:
1. Install and refresh appended `mcp-codegraph` to
`platform_toolsets.cli` in `~/.hermes/config.yaml`. It was never
needed. Hermes loads every enabled MCP server on a platform whose list
names none (hermes_cli/tools_config.py `_merge_mcp_servers`, a rule
present back in May 2026 when the target was written). The name
itself is harmful:
- Hermes up to 0.22.2 rejects it at startup ("Unknown toolsets").
- Hermes 0.22.4 maps `mcp-<server>` onto the server, so the list
becomes an MCP allowlist and every other server disappears from CLI
sessions.
A user who deleted the line got it back on the next upgrade.
2. When the `mcp_servers.codegraph` block differed from the template, it
was replaced wholesale. That reverted an absolute command path, the
timeouts, `enabled: false` and `env`. The line-based YAML code also
missed some shapes:
- a codegraph key written on one line or quoted, which got a second
codegraph key;
- a 4-space-indented `mcp_servers`, which came out unparseable;
- a one-line `mcp_servers: {…}`, which got a second top-level key, and
Hermes's PyYAML reader then dropped the user's servers.
CRLF files came back LF.
Fix:
- CodeGraph never writes `platform_toolsets`.
- A `- mcp-codegraph` line an earlier install left in
`platform_toolsets.cli` is removed, or becomes `- codegraph` when the
list is an allowlist naming other MCP servers (the spelling every Hermes
version reads as the server). An allowlist that leaves CodeGraph out
gets a note, not an edit.
- An existing `mcp_servers.codegraph` entry is the user's: nothing in it
changes. A block entry missing `command` or `args` gets just those, at
its own indent.
- A new entry goes in at the indent its siblings use, and a codegraph key
is found however it is written. `mcp_servers: {}` becomes a block.
- A one-line mapping that holds other servers makes install refuse with a
clear error and change nothing. One that holds codegraph is left as
written, with a note, and uninstall says it can't remove it.
- The file keeps its line breaks, and is written only when something was
edited.
- Uninstall also removes a `- codegraph` the refresh may have written.
Hermes references (NousResearch/hermes-agent v0.22.4, 64dbae64):
- hermes_cli/tools_config.py `_get_platform_tools` / `_merge_mcp_servers`
("mcp-<server> names the same server as its bare alias: either spelling
selects only that server").
- hermes_cli/toolset_validation.py `saved_toolset_resolver`.
- website/docs/reference/mcp-config-reference.md (command, args, env,
enabled, timeout, connect_timeout).
- hermes_cli/tools_config.py at 1b9c539c (2026-05-17) for the May 2026
rule.
Validation:
- installer-targets.test.ts: 13 new Hermes tests. 3 existing tests that
asserted the `mcp-codegraph` write are updated; the #456 same-indent
list case now proves the old line is removed cleanly. With main's
hermes.ts put back, those 16 fail, all on behavior. The 7 other Hermes
tests pass on both.
- The real CLI on this Windows machine against a private HERMES_HOME:
`install --yes`, a second `install --yes`, `install --refresh` and
`uninstall --yes --keep-cli`, for 14 config.yaml shapes. Each result
was loaded with PyYAML (the reader Hermes uses), checked for duplicate
keys, and run through a re-implementation of the cited selection rule.
Of 42 results:
- main: 2 unparseable, 10 with duplicate keys, 26 carrying
`mcp-codegraph`, 10 where Hermes 0.22.4 would load only codegraph in
CLI sessions, 3 converted CRLF to LF, and the customized entry
reverted.
- The fix: 0, 0, 0, 0, 0, the customized entry kept byte-for-byte, and
1 install refused by design (a one-line `mcp_servers` holding other
servers).
Fixes #2485
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>