Claude.ai  ──MCP──▶  cms-mcp-hub  ──HTTP──▶  Drupal MCP server
                                  ──HTTP──▶  WordPress MCP server
                                  ──SSE───▶  Any CMS MCP server

# 1. Install dependencies
npm install

# 2. (Recommended) Set encryption key
export ENCRYPTION_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")

# 3. Start dev server (auto-reloads on src/ changes)
npm run dev

# 4. Open browser
open http://localhost:3456

node src/index.js
  └── new WorkspaceRegistry()         reads data/workspaces/ from disk
  └── new McpHubServer(registry)
        └── _setupRoutes()            registers all Express routes + app.param workspace validation
        └── app.listen(PORT)

Browser → POST /api/workspaces  { name }
  └── WorkspaceRegistry.create()
        ├── generates  workspace_id = "ws_" + 12 random bytes (hex)
        ├── generates  admin_key    = "ak_" + 24 random bytes (hex)
        ├── stores     admin_key_hash = SHA-256(admin_key)
        └── writes     data/workspaces/{workspace_id}/config.json

Response → { workspace_id, admin_key, name }
           ⚠ admin_key shown ONCE — save it immediately

{
  "workspace_id": "ws_abc123...",
  "name": "My Org",
  "admin_key_hash": "sha256hex...",
  "idp": null,
  "created_at": "2025-01-01T00:00:00.000Z"
}

Browser → POST /ws/:id/auth/admin  { admin_key }
  └── WorkspaceRegistry.verifyAdminKey()
        └── SHA-256(admin_key) == stored admin_key_hash  (timing-safe compare)
  └── TokenStore.signSession({ workspace_id, exp: now + 24h })
        └── base64url(payload) + "." + HMAC-SHA256(payload, ENCRYPTION_KEY)
        └── Set-Cookie: ws_session=<token>; HttpOnly; SameSite=Lax;
                        Path=/ws/{workspace_id}/; Max-Age=86400

Response → { ok: true }
Browser  → redirects to /ws/:id/ui

Browser JS  load()
  ├── GET /ws/:id/health           (no auth — workspace health + tool count)
  ├── GET /ws/:id/api/connectors   (session required)
  ├── GET /ws/:id/auth/sso/status  (session required)
  └── GET /ws/:id/api/idp          (session required)

If any session-required endpoint returns 401:
  └── showAuthWall()  ← overlay with "Session expired" + link to login

If all succeed:
  └── renders workspace name, stats bar, SSO panel, connector cards

Admin → POST /ws/:id/api/connectors  { name, url, token?, transport?, sseUrl? }
  └── ConnectorRegistry.connectOne()
        └── transport auto-detection (if not specified):
              1. Direct HTTP  — JSON-RPC POST to url
              2. Streamable HTTP — MCP SDK StreamableHTTPClientTransport
              3. SSE — MCP SDK SSEClientTransport

        └── calls tools/list on remote server
        └── registers each tool as  {safePrefix(name)}__{toolName}
              e.g. drupal-prod__get_node
        └── stores in memory (ConnectorRegistry.connectors Map)
        └── saves to data/workspaces/{id}/connectors.json

On server restart:
  └── ConnectorRegistry.initialize() reconnects all saved connectors in parallel
      Non-blocking: registry returned immediately, connections run in background

Claude.ai → POST /ws/:id/mcp
  └── checks Mcp-Session-Id header
        ├── existing session → route to cached StreamableHTTPServerTransport
        └── new session      → create MCP Server + StreamableHTTPServerTransport
                                store in httpSessions Map (keyed by session ID)

  └── MCP Server handles:
        ├── tools/list  → ConnectorRegistry.getAllTools()
        │                 all tools from all connected connectors (prefixed)
        └── tools/call  { name: "drupal-prod__get_node", arguments: {...} }
              └── ConnectorRegistry.callTool()
                    ├── strips prefix → finds connector by name
                    ├── calls remote MCP server with original tool name
                    └── returns result to Claude.ai

Claude.ai GET /ws/:id/mcp   ← SSE stream for streaming responses
Claude.ai DELETE /ws/:id/mcp ← close session

Step 1 — Configure IdP
  Admin → PATCH /ws/:id/api/idp
            { authorize_url, token_url, client_id, client_secret, scope }
  └── saved to config.json idp field

Step 2 — Start SSO
  Admin → GET /ws/:id/auth/sso/start
  └── OAuthManager.buildStartUrl()
        ├── generates random state (20 bytes hex), stores with 10-min expiry
        └── builds IdP redirect URL:
              {authorize_url}?response_type=code
                             &client_id=...
                             &redirect_uri={origin}/ws/{id}/auth/callback
                             &scope=...
                             &state=...
  └── 302 redirect → IdP login page

Step 3 — IdP Callback
  IdP → GET /ws/:id/auth/callback?code=...&state=...
  └── OAuthManager.handleCallback()
        ├── validates state (exists + not expired)
        ├── POST to token_url to exchange code → tokens
        ├── decodes JWT id_token to extract sub claim
        └── WorkspaceRegistry.saveToken(workspace_id, '_service', {
                access_token, refresh_token, expires_at, token_type, sub
              })
              └── AES-256-GCM encrypted → data/workspaces/{id}/tokens/_service.enc
  └── 302 redirect → /ws/:id/ui?sso=ok

Step 4 — Token Auto-Refresh
  On every tool call: WorkspaceRegistry.getToken()
    └── if expires_at - 60s < now && has refresh_token
          POST to idp.token_url with grant_type=refresh_token
          saves updated token
    └── returns current access_token
    └── ConnectorRegistry injects Authorization: Bearer {access_token}

_requireAdmin(req, res)
  └── reads Cookie: ws_session=<token>
  └── TokenStore.verifySession(token)
        ├── splits "data.sig"
        ├── recomputes HMAC-SHA256(data, key)
        ├── crypto.timingSafeEqual(sig, expected)
        ├── decodes base64url payload
        └── checks payload.exp > Date.now()
  └── verifies payload.workspace_id === req.params.workspace_id
  └── on failure: sends { error: "..." } with status 401

cms-mcp-hub/
├── src/
│   ├── index.js                    entry point — creates WorkspaceRegistry + McpHubServer
│   ├── proxy/
│   │   └── McpHubServer.js         Express app, all route handlers, MCP session factory
│   ├── connectors/
│   │   └── ConnectorRegistry.js    connector lifecycle, transport detection, tool routing
│   ├── workspaces/
│   │   ├── WorkspaceRegistry.js    workspace CRUD, per-workspace ConnectorRegistry factory
│   │   ├── OAuthManager.js         OAuth 2.0 authorization code flow
│   │   └── TokenStore.js           AES-256-GCM encrypt/decrypt, HMAC session sign/verify
│   └── web/
│       └── ui.js                   landing page + dashboard HTML (served as template strings)
└── data/
    └── workspaces/
        └── {workspace_id}/
            ├── config.json         workspace name, admin_key_hash, idp config
            ├── connectors.json     saved connector configs
            └── tokens/
                └── _service.enc    encrypted SSO service token

Body:     { "name": "My Org" }
Response: { "workspace_id": "ws_...", "admin_key": "ak_...", "name": "My Org" }

{
  "status": "ok",
  "workspace": "My Org",
  "sso": { "connected": false },
  "connectors": [{ "name": "drupal-prod", "status": "connected", "toolCount": 8 }],
  "totalTools": 8
}

Body:       { "admin_key": "ak_..." }
Response:   { "ok": true }
Set-Cookie: ws_session=...; HttpOnly; SameSite=Lax; Path=/ws/{id}/; Max-Age=86400

{ "connected": true,  "expired": false, "expires_at": 1749123456789, "has_refresh": true }
{ "connected": false }

{
  "name":        "drupal-prod",
  "url":         "https://cms.example.com/mcp",
  "token":       "Basic abc123",
  "transport":   "streamable-http",
  "sseUrl":      "https://cms.example.com/mcp/sse",
  "description": "Production Drupal"
}

{
  "name":      "drupal-prod",
  "url":       "https://...",
  "status":    "connected",
  "transport": "direct-http",
  "toolCount": 8,
  "tools": [
    {
      "name":        "get_node",
      "title":       "Get Node",
      "description": "...",
      "inputSchema": { "type": "object", "properties": {} }
    }
  ],
  "error": null
}

{
  "authorize_url": "https://idp.example.com/oauth/authorize",
  "token_url":     "https://idp.example.com/oauth/token",
  "client_id":     "your-client-id",
  "client_secret": "your-secret",
  "scope":         "openid profile email"
}

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

export ENCRYPTION_KEY=your64hexchars
npm run dev