feat: add MCP server mode — hermes mcp serve

[teknium1]

Summary

Adds hermes mcp serve — a stdio MCP server that matches OpenClaw's 9-tool channel bridge surface. Any MCP-capable agent (Claude Code, Cursor, Codex, etc.) can interact with Hermes conversations across all connected messaging platforms.

Inspired by OpenClaw's MCP channel bridge (shipped March 28, 2026).

What it does

hermes mcp serve starts a FastMCP stdio server exposing 10 tools:

Tool	OpenClaw equivalent	Description
conversations_list	✅	List active sessions across all platforms
conversation_get	✅	Get detailed info about one conversation
messages_read	✅	Read message history for a conversation
attachments_fetch	✅	Extract non-text attachments from a message
events_poll	✅	Poll for new events since a cursor
events_wait	✅	Long-poll / block until next event (near-real-time)
messages_send	✅	Send messages through platform adapters
permissions_list_open	✅	List pending approval requests
permissions_respond	✅	Allow/deny approval requests
channels_list	➕ extra	List available messaging targets (Hermes-specific)

Architecture

MCP Client (Claude Code, Cursor, Codex)
    ↕ stdio
hermes mcp serve  (FastMCP server)
    ↕ direct Python imports
├── EventBridge      (background DB poller → in-memory event queue)
├── sessions.json    (conversation index)
├── SessionDB        (message transcripts + event source)
├── channel_directory.json  (target listing)
└── send_message_tool       (platform adapters for sending)

EventBridge

The key component for real-time events. A background thread polls SessionDB every ~2s for new messages and maintains an in-memory event queue with cursor-based access:

• events_poll(after_cursor=N) — returns events since cursor, non-blocking
• events_wait(after_cursor=N, timeout_ms=30000) — blocks until event arrives
• Queue capped at 1000 events, threading-safe with waiter wakeup
• Also tracks pending approvals in-memory

This is the Hermes equivalent of OpenClaw's WebSocket gateway bridge — instead of WebSocket push events, we poll the SQLite database.

Design decisions

• Read operations work without the gateway (reads session store directly)
• Send operations require the gateway (uses send_message_tool's platform adapters)
• Zero new dependencies — uses existing mcp>=1.2.0 optional dep
• ~600 lines of implementation code

MCP client config

{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["mcp", "serve"]
    }
  }
}

Files changed

File	Change
mcp_serve.py	New — MCP server + EventBridge implementation
hermes_cli/main.py	Added serve sub-parser to existing hermes mcp command
hermes_cli/mcp_config.py	Route serve action to run_mcp_server()
tests/test_mcp_serve.py	53 tests — EventBridge, tools, attachments, permissions, CLI
website/docs/user-guide/features/mcp.md	Added "Running Hermes as an MCP server" section
website/docs/reference/cli-commands.md	Added serve to MCP subcommands table

Backwards compatibility

• No breaking changes
• serve is a new sub-action alongside existing add/remove/list/test/configure
• MCP SDK remains optional — graceful error if not installed

Test plan

• 53 new tests all passing
• Full hermes_cli suite (742 tests) passing
• Full tools suite (1878 tests) passing
• Gateway suite passing (7 pre-existing failures in test_hooks.py unrelated)

vs OpenClaw — what's different

Feature	OpenClaw	Hermes
Event source	WebSocket to gateway	DB polling (~2s)
Transport	stdio only	stdio only
claude/channel push	Yes	Not yet
HTTP MCP transport	Not yet	Not yet
Approval integration	Full (via gateway WebSocket)	In-memory tracking
Extra tools	—	channels_list

The claude/channel push notification protocol and HTTP transport are follow-up items that both codebases share as limitations.

[github-actions]

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py

---

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

[github-actions]

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py

---

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

[github-actions]

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py

---

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

[github-actions]

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py

---

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.

[github-actions]

⚠️ Supply Chain Risk Detected

This PR contains patterns commonly associated with supply chain attacks. This does not mean the PR is malicious — but these patterns require careful human review before merging.

⚠️ WARNING: Install hook files modified

These files can execute code during package installation or interpreter startup.

Files:

hermes_cli/setup.py

---

Automated scan triggered by supply-chain-audit. If this is a false positive, a maintainer can approve after manual review.