feat: Add MCP authentication command with OAuth and API key support

[HautlyS]

Summary

This PR adds a unified authentication flow for MCP (Model Context Protocol) servers that require OAuth 2.1 PKCE or API key authentication. The command works identically across all Hermes channels: CLI, Telegram, Discord, WhatsApp, Slack, and more.

Features

CLI Command

hermes mcp auth              # Authenticate all servers needing auth
hermes mcp                   # List servers with auth status (includes hint)

Gateway Commands

/mcp              # List MCP servers and their authentication status
/mcp auth         # Authenticate all servers needing OAuth or API keys

How It Works

OAuth Authentication

1. Detects servers with auth: oauth lacking stored tokens
2. Initiates OAuth 2.1 PKCE flow using MCP SDK's OAuthClientProvider
3. Opens browser for user authorization
4. Exchanges authorization code for tokens
5. Stores tokens securely in ~/.hermes/mcp-tokens/

API Key Authentication

1. Detects headers with env var interpolation: Authorization: Bearer ${MCP_SERVER_API_KEY}
2. Checks if environment variable is set
3. Prompts for API key (hidden input)
4. Stores in ~/.hermes/.env

Configuration Examples

OAuth Server

mcp_servers:
  supabase:
    url: https://mcp.supabase.com/mcp
    auth: oauth

API Key Server

mcp_servers:
  my-api:
    url: https://api.example.com/mcp
    headers:
      Authorization: Bearer ${MCP_MY_API_API_KEY}

Implementation

Files Changed

File	Changes	Description
hermes_cli/mcp_config.py	+129 lines	Auth command implementation
gateway/run.py	+66 lines	Gateway command handler
hermes_cli/main.py	+2 lines	CLI argument parser
tests/hermes_cli/test_mcp_auth.py	+350 lines	Comprehensive test suite
docs/mcp-authentication.md	+200 lines	Full documentation
CHANGELOG.md	+50 lines	Changelog entry

Code Architecture

cmd_mcp_auth()
├── Detects servers needing auth
│   ├── OAuth servers (no token file)
│   └── Header servers (unset env vars)
├── _do_oauth_auth()
│   └── build_oauth_auth() → browser flow
└── _do_header_auth()
    └── _prompt() → save_env_value()

Testing

Comprehensive test suite with 28 tests covering:

• Unit tests: Auth detection, OAuth flow, header auth
• Integration tests: Dispatcher registration, help output
• Gateway tests: Command dispatch, subcommand handling
• Edge cases: Mixed server types, invalid configs, user cancellation

# Run tests
pytest tests/hermes_cli/test_mcp_auth.py -v

Security

• Token Storage: OAuth tokens stored with 0600 permissions
• API Key Masking: Sensitive values masked in output (e.g., sk-***1234)
• Environment Variables: API keys stored in .env (git-ignored)
• OAuth Callback: Uses localhost (127.0.0.1) for redirect

Documentation

• User Guide: docs/mcp-authentication.md
• Inline Help: Updated hermes mcp help text
• Changelog: CHANGELOG.md
• Code Comments: Comprehensive docstrings

Testing Done

✅ Syntax validation (py_compile)
✅ CLI command execution (hermes mcp auth)
✅ Gateway command logic verified
✅ All modified files compile without errors
✅ Test file syntax validated

Screenshots

CLI Output

$ hermes mcp auth

  Servers needing authentication:

  supabase             OAuth 2.1 PKCE

  Authenticating 'supabase'...
  Opening browser for OAuth authorization...
  ✓ OAuth flow initiated for 'supabase'
  Check your browser to complete authorization

✓ Authentication complete. Start a new session to use these servers.

Gateway Output

User: /mcp

Bot: MCP Servers:

  Name             Transport                      Tools        Status
  ──────────────── ────────────────────────────── ──────────── ──────────
  supabase         https://mcp.supabase.com/mcp   all          ✓ enabled
  chrome-devtools  npx -y chrome-devtools-mc...   all          ✓ enabled

  💡 Use /mcp auth to authenticate servers

Breaking Changes

None. This is a new feature that doesn't affect existing functionality.

Related Issues

• Addresses authentication workflow for MCP servers
• Related to MCP server management and OAuth 2.1 support

Checklist

• Code follows project style guidelines
• Comprehensive tests added
• Documentation created
• Changelog updated
• No breaking changes
• All files compile without errors
• CLI command tested and working
• Gateway command logic verified

---

🤖 Generated with Claude Code assistance