hermes - 💡(How to fix) Fix MCP stdio client raises NameError: name 'StdioServerParameters' is not defined (v0.14.0)

Symptom

$ hermes mcp test ax-status
  Testing 'ax-status'...
  Transport: stdio → python3
  Auth: none
  ✗ Connection failed (7061ms): name 'StdioServerParameters' is not defined

The server is recorded by hermes mcp add and persisted, but hermes mcp list shows it as ✗ disabled, and every call into the registered stdio server fails with the same NameError. Only the stdio transport is affected — HTTP MCP servers work normally.

Reproduction (minimal)

cat > /tmp/echo_mcp.py <<'PY'
#!/usr/bin/env python3
import json, sys
def main():
    for line in sys.stdin:
        req = json.loads(line)
        if req.get("method") == "initialize":
            print(json.dumps({"jsonrpc":"2.0","id":req["id"],"result":{"protocolVersion":"2025-06-18","capabilities":{}}}), flush=True)
        elif req.get("method") == "tools/list":
            print(json.dumps({"jsonrpc":"2.0","id":req["id"],"result":{"tools":[]}}), flush=True)
main()
PY
chmod +x /tmp/echo_mcp.py

hermes mcp add echo-test --command python3 --args /tmp/echo_mcp.py
hermes mcp test echo-test
# → ✗ Connection failed: name 'StdioServerParameters' is not defined

The MCP server itself responds correctly to manual JSON-RPC:

$ echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | python3 /tmp/echo_mcp.py
{"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2025-06-18", "capabilities": {}}}

So the failure is exclusively on the Hermes client side.

Likely root cause

StdioServerParameters is exported by the official mcp Python SDK (mcp.client.stdio.StdioServerParameters or mcp.StdioServerParameters depending on version). The Hermes stdio client appears to reference this name without importing it — possibly an import guarded by try/except ImportError that silently leaves the name unbound at call site.

Expected at the top of the stdio client module:

from mcp import StdioServerParameters
# or
from mcp.client.stdio import StdioServerParameters

Workarounds

1. Re-host the same tools as an HTTP MCP server (hermes mcp add --transport http --url ...) — bypasses the buggy code path.
2. Embed the tool as a normal shell command in a Skill (python3 /path/to/server.py + manual JSON-RPC parsing).
3. Local patch — locate the missing import:

   grep -rn 'StdioServerParameters' "$(python3 -c 'import hermes; print(hermes.__path__[0])')" | head

Acceptance criteria

1. hermes mcp test echo-test returns ✓
2. hermes mcp list shows the server as enabled
3. hermes -z with --tool echo-test actually invokes the stdio server

Environment

• OS: Linux 6.6.87.2-microsoft-standard-WSL2 (Ubuntu on WSL2)
• Python: 3.13 (per pyproject.toml)
• Hermes installation: uv venv under ~/.hermes/, installed via the canonical one-liner
• Provider: openai-codex (ChatGPT subscription OAuth)
• Hermes version: 0.14.0 (2026.5.16)