feat(mcp): add streamable HTTP MCP transport

[rodboev]

Description

headroom mcp serve only exposes stdio today, which blocks MCP clients that need a Streamable HTTP endpoint. This adds an explicit HTTP transport mode around the existing Headroom MCP server while leaving stdio as the default and keeping tool registration single-sourced. Closes #1346.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Performance improvement
• Code refactoring (no functional changes)

Changes Made

• Add explicit headroom mcp serve --transport http support with host, port, and path options.
• Serve the existing headroom_compress, headroom_retrieve, and headroom_stats tools through the same MCP server instance used by stdio.
• Keep headroom mcp serve defaulting to stdio for current Claude Code and local MCP host configs.
• Update MCP docs to show stdio and HTTP setup without implying the proxy automatically owns /mcp.
• Acknowledge stale prior work in streamable http mcp #153 by keeping the scope clean, rebased, and covered by focused tests.

Testing

• Unit tests pass (uv run pytest tests/test_ccr_mcp_http.py tests/test_cli/test_mcp.py -q)
• Linting passes (uv run ruff check headroom/cli/mcp.py headroom/ccr/mcp_server.py headroom/ccr/mcp_http.py tests/test_ccr_mcp_http.py tests/test_cli/test_mcp.py)
• Type checking passes (uv run mypy headroom --ignore-missing-imports)
• New tests added for new functionality when applicable
• Manual testing performed

Test Output

uv run pytest tests/test_ccr_mcp_http.py tests/test_cli/test_mcp.py -q
20 passed in 0.53s

uv run ruff check headroom/cli/mcp.py headroom/ccr/mcp_server.py headroom/ccr/mcp_http.py tests/test_ccr_mcp_http.py tests/test_cli/test_mcp.py
All checks passed!

uv run ruff format headroom/cli/mcp.py headroom/ccr/mcp_server.py headroom/ccr/mcp_http.py tests/test_ccr_mcp_http.py tests/test_cli/test_mcp.py --check
5 files already formatted

uv run mypy headroom --ignore-missing-imports
Success: no issues found in 407 source files

Real Behavior Proof

• Environment: local Python environment with Headroom dev dependencies and MCP extra installed.
• Exact command / steps: start headroom mcp serve --transport http --host 127.0.0.1 --port <test-port> --path /mcp, then perform an MCP SDK Streamable HTTP initialize/list-tools exchange.
• Observed result: the HTTP transport initializes and lists the existing Headroom MCP tools; headroom mcp serve without --transport still selects stdio, and mixed-case --transport HTTP routes to the HTTP transport.
• Not tested: live third-party hosted MCP clients, TLS termination, auth gateways, and reverse-proxy deployment.

Review Readiness

• I have performed a self-review
• This PR is ready for human review

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have updated the CHANGELOG.md if applicable

Additional Notes

CHANGELOG.md is not edited because this repository generates changelog entries from conventional commits. The HTTP proof is scoped to the MCP Python SDK transport contract and does not claim live validation against every external MCP host.
Focused MCP and CLI tests passed locally; full-suite validation is left to CI.

[github-actions]

PR governance

This PR follows the template and is marked ready for human review.

[JerrettDavis]

Reviewed the HTTP transport wiring, CLI surface, docs, and tests. Stdio remains the default, the HTTP mode reuses the existing MCP server/tool registration, path handling is explicit, and the SDK initialize/list-tools test gives useful coverage of the transport contract. Current PR checks are green; this looks ready.