[BUG] Hermes MCP adapter drops cwd, extra passthrough keys and the SSE transport when writing config.yaml

Open Beginner friendly
#3,749 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@Parth-Vasave is already working on this.

Since Nov 16, 2026.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
76/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
backend, tooling

Research direction

Read src/apm_cli/adapters/client/hermes.py, especially _to_hermes_format, and inspect the Hermes adapter tests. Start by running the focused tests for server formatting, then add coverage for stdio cwd and extra keys and for remote SSE transport. Done when the generated Hermes config preserves those values while still filtering reserved keys.

Written by the indexing model from the issue text.

Description

Describe the bug

HermesClientAdapter (src/apm_cli/adapters/client/hermes.py) formats each MCP server with the Copilot formatter, then rebuilds it in _to_hermes_format from a fixed allowlist: command, args, env for stdio and url, headers for remote. Any other key is dropped before ~/.hermes/config.yaml is written, including keys that Hermes supports per server (Hermes MCP docs):

  1. cwd on a self-defined stdio server is dropped. The Copilot formatter emits it, but Hermes starts the server in its own working directory.
  2. Passthrough keys from apm.yml are dropped. McpDependency.extra reaches the formatter through _merge_extra (for example, timeout, connect_timeout, lazy, auth: oauth), but none of these reach config.yaml. An OAuth server configured with auth: oauth is therefore written without it and cannot authenticate.
  3. SSE remotes lose their transport. The Copilot formatter writes type: "http" for every remote, and the Hermes conversion writes only url. Hermes needs transport: sse for the legacy SSE transport, so a registry server with transport_type: sse is written as a Streamable HTTP server and fails to connect.

The other JSON adapters (Claude, Cursor, Kiro, Gemini) write cwd and the extra keys through, so Hermes is the only target that loses them.

To Reproduce
# HERMES_HOME points at an empty temp directory
from apm_cli.adapters.client.hermes import HermesClientAdapter

a = HermesClientAdapter()
local = a._format_server_config({
    "name": "local",
    "_raw_stdio": {"command": "node", "args": ["s.js"], "cwd": "/srv/app"},
    "_extra": {"timeout": 120, "connect_timeout": 30},
})
legacy = a._format_server_config({
    "name": "legacy",
    "remotes": [{"url": "https://x.example/sse", "transport_type": "sse"}],
    "_extra": {"auth": "oauth"},
})
print(local)   # {..., 'command': 'node', 'cwd': '/srv/app', 'args': ['s.js'], 'timeout': 120, 'connect_timeout': 30}
print(legacy)  # {'type': 'http', 'url': 'https://x.example/sse', ..., 'auth': 'oauth'}
a.update_config({"local": local, "legacy": legacy})

Resulting $HERMES_HOME/config.yaml:

mcp_servers:
  local:
    command: node
    args:
    - s.js
    enabled: true
  legacy:
    url: https://x.example/sse
    enabled: true

cwd, timeout, connect_timeout and auth are missing, and nothing marks legacy as an SSE server.

Expected behavior
mcp_servers:
  local:
    command: node
    args:
    - s.js
    cwd: /srv/app
    timeout: 120
    connect_timeout: 30
    enabled: true
  legacy:
    url: https://x.example/sse
    transport: sse
    auth: oauth
    enabled: true
  • cwd is kept for stdio servers.
  • Non-reserved extra keys pass through, as on the other adapters (the _EXTRA_DENYLIST guard still applies).
  • A remote with transport_type: sse is written with transport: sse.
Environment
  • APM version: 0.35.1 (f574a62c2, current main)
  • OS: macOS 27.2.1
  • Python: 3.12.12
  • Client: Hermes agent
Additional context

I could not find an existing issue or PR covering this. I'm happy to work on a fix if a maintainer can approve the scope:

  • Scope: _to_hermes_format keeps cwd and non-Copilot-only keys (it still drops type: local, default tools: ["*"] and empty id). The Hermes formatting path also records an SSE transport so the written entry carries transport: sse.
  • Done when: unit tests covering the three cases above fail on current main and pass with the fix.
  • Out of scope: translating APM's tools overlay into Hermes' tools.include/tools.exclude shape, and other targets.
Dominant language
Python
Stars
4.3k
Forks
415
Avg merge
3d 4h
Merged PRs (30d)
176

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/apm

All issues in microsoft/apm

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.