feat: HTTP Stream transport with per-request credential injection

[fjprobos]

Closes #29

Why this matters

The classic stdio transport requires one server process per user with credentials baked in at startup. This makes it incompatible with modern MCP clients like Claude Code CLI, which connect to HTTP endpoints and pass credentials per-request. This PR adds HTTP Stream transport support so a single deployed instance can serve many users — each with their own Metabase credentials.

	stdio (classic)	HTTP Stream (this PR)
Deployment	One process per user	One shared process
Credentials	Env vars at startup	Per-request headers
Claude Code CLI	❌ Not supported	✅ Supported
Cursor, Windsurf	✅ Supported	✅ Supported

Changes

Core feature

• src/auth.ts (new): createAuthenticateHandler() + createClientResolver() — the per-request credential injection logic extracted into a testable module
• src/server.ts: detects MCP_TRANSPORT=http, wires FastMCP authenticate() hook to extract x-metabase-url, x-metabase-api-key (or x-metabase-username/x-metabase-password) from request headers; falls back to stdio mode with shared client when env var is absent
• All tool files: signature changed from a MetabaseClient instance to a getClient(ctx) resolver so each execute() call picks up the session's client
• sse-server.js: legacy SSE wrapper for clients that only support the older SSE transport

Tests (31 passing, 0 pre-existing)

• tests/auth.test.ts — createClientResolver and createAuthenticateHandler unit tests
• tests/metabase-client.test.ts — constructor with api-key, username/password, invalid-credentials
• tests/tool-filters.test.ts — flag parsing and default behaviour
• tests/config.test.ts — loadConfig / validateConfig env var permutations

Docs

• README.md: new "HTTP Stream Transport" section with Claude Code CLI setup instructions, header reference table, and npm test command

Usage — Claude Code CLI

# Add to current project
claude mcp add --transport http metabase "https://your-server.example.com/mcp" \
  --header "x-metabase-url: https://your-metabase.com" \
  --header "x-metabase-api-key: your_api_key"

# Or globally (available in all projects)
claude mcp add --transport http --scope user metabase "https://your-server.example.com/mcp" \
  --header "x-metabase-url: https://your-metabase.com" \
  --header "x-metabase-api-key: your_api_key"

Test plan

• MCP_TRANSPORT=http node dist/server.js starts HTTP server on port 8011
• Connect via Claude Code CLI with x-metabase-url + x-metabase-api-key headers — tools work
• Connect without headers — server returns 401 with descriptive message
• Without MCP_TRANSPORT=http, server starts in stdio mode (no regression)
• npm test — 31 tests pass

🤖 Generated with Claude Code