mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:10:00 +08:00
## Description Supersedes #2658 (`tejas/mcp-2x-port`, a draft with conflicts against `main` since 2026-10-20). This is that PR's net diff rebased onto `main` as one commit (originally `fc1ba891`, now `7e0094d6`; see below), crediting Tejas Chopra and Jerrett Davis as co-authors, with three changes needed on current `main`. Both MCP servers (`headroom/ccr/mcp_server.py`, `headroom/memory/mcp_server.py`) move from SDK 1's decorator API to SDK 2's constructor callbacks, as #2658 did. The `<2.0.0` cap from #2642 is then lifted. Why now: current Claude Code tries the modern `server/discover` handshake first. On SDK 1, `headroom mcp serve` rejects it and logs `Failed to validate request: 31 validation errors for ClientRequest` on stderr in every session. Claude Code then falls back to legacy `initialize`, so the tools still work. On SDK 2 the modern handshake succeeds and nothing is logged. Changes relative to #2658: 1. **The floor is `mcp>=2.2.0,<3.0.0`, not `>=2.0.0`.** The GitHub advisories mark `mcp` `>=2.0.0, <2.2.0` as affected by CVE-2026-59951 (the reason for #4239's `>=1.30.0` floor), CVE-2026-116684, CVE-2026-116685 and CVE-2026-116686. #2658's lock resolved 2.1.1. The contract test keeps `main`'s CVE guard for the 2.x line and rejects 3.x (see #2977). 2. **`tests/test_ccr_mcp_http.py` is ported.** #1773 added it after #2658 branched, and it fails on SDK 2: `streamable_http_client` now takes an `httpx2.AsyncClient`, yields `(read, write)` without the session-id getter, and its types are snake_case (`protocol_version`). `headroom/ccr/mcp_http.py` itself needs no change. 3. **The lock is regenerated** with uv 0.9.30 (`uv lock --upgrade-package mcp`, still `revision = 3`). **Rebased onto main (`7e0094d6`), 2026-11-03.** The branch is now two linear commits, with no merge commits: - `ce4d6442` feat(mcp)!: port MCP servers to SDK 2.x (was `39c574c2`) - `274f0672` fix(mcp): attribute SDK 2 clients by client_info, not clientInfo (was `c7900848`) The previous head was the merge `4c1b774f` (main `5c785e69` into the branch), which carried the resolution against #4525 (GHSA-8g49-pg6g-xgrf, confining `headroom_read` to the workspace). The rebase replays the port directly on top of #4525 instead. What it changed: - `headroom/ccr/mcp_server.py` conflicted with #4525 in two places: the imports (#4525's `errno` next to the port's `contextvars`) and the tool list, where #4525's workspace-scoped `headroom_read` schema met the port's move from the `@list_tools` decorator to `_on_list_tools`. The resolved file keeps both: SDK 2 callbacks and #4525's confinement and `HEADROOM_MCP_READ_ROOTS` description. It is byte-identical to the file in the previous merge head `4c1b774f`. - `uv.lock` conflicted in one hunk with #4614's `mem0ai` bump: kept this PR's `mcp>=2.2.0,<3.0.0` for the `mcp` and `proxy` extras and #4614's `mem0ai>=2.0.18,<3.0`. `uv lock --check` resolves 253 packages. - Every other file this PR touches is unchanged from `4c1b774f`. The only difference in `pyproject.toml` and `uv.lock` against the previous head is #4614's own diff, line for line. The Strands blocker from the July review no longer applies: `strands-agents` 1.63.0 declares `mcp<2.4,>=1.23.0`, and the lock resolves `mcp` 2.3.0 with it. Dependency justification (CONTRIBUTING, new dep or version bump): | Package | Change | Source | |---|---|---| | `mcp` | 1.30.0 → 2.3.0 | modelcontextprotocol/python-sdk | | `mcp-types` | new, 2.3.0 | same SDK; `mcp` 2.3.0 pins it `==2.3.0` | | `httpx2`, `httpcore2` | new, 2.16.0 | pydantic/httpx2 (Tom Christie); SDK 2's HTTP client | | `httpx2-jsfetch` | new, 1.0 | only on `sys_platform == 'emscripten'`; not installed elsewhere | | `strands-agents` | 1.62.0 → 1.63.0 | first release that accepts `mcp` 2.2+ | | `httpx-sse` | removed | SDK 1 only | | `idna` | 3.15 → 3.20 | required by `httpx2` | ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [x] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/ccr/mcp_server.py`, `headroom/memory/mcp_server.py`: register handlers as `on_list_tools` / `on_call_tool` constructor callbacks, return `ListToolsResult` / `CallToolResult`, and read the request context from the callback argument. These are #2658's changes, including Jerrett's memory-backend cleanup hook. - `pyproject.toml`: `mcp>=2.2.0,<3.0.0` in the `proxy` and `mcp` extras. - `uv.lock`: relocked as described above. - `tests/test_mcp_dependency_contract.py`: both extras must admit 2.2.0 and reject 1.30.0, 2.1.1 and 3.0.0. - `tests/test_mcp_sdk2_contract.py`, `tests/_mcp_stub.py`, `tests/test_mcp_stub.py`, `tests/test_memory/test_mcp_server.py`: from #2658. - `tests/test_ccr_mcp_http.py`: ported to the SDK 2 client. It reads the session id from the `mcp-session-id` response header. - `headroom/ccr/mcp_server.py` `_current_client`: read `client_info` (SDK 2) instead of `clientInfo` (SDK 1), so `headroom_compress` savings events name the client again. `tests/test_mcp_sdk2_contract.py` now builds the SDK's own `InitializeRequestParams`; its old stand-in used `clientInfo` and stayed green while every client was recorded as `unknown`. Before and after, with an SDK 2.3 client named `attribution-probe` over stdio: the ledger recorded `unknown` on both `server/discover` and `initialize`, and now records `attribution-probe` on both (found by Devin's review). ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output After the rebase, on `274f0672`: ```text # Python 3.11.17, mcp 2.3.0, strands-agents 1.63.0 $ pytest -q tests/test_mcp_dependency_contract.py tests/test_mcp_sdk2_contract.py tests/test_mcp_stub.py \ tests/test_ccr_mcp_http.py tests/test_memory/test_mcp_server.py \ <every test module that references mcp_server, GHSA or HEADROOM_MCP_READ_ROOTS, incl. tests/test_ccr_mcp_server.py> 840 passed, 2 skipped $ uv lock --check Resolved 253 packages $ ruff check && ruff format --check on every changed .py file (ruff 0.17.2); git diff --check origin/main clean ``` The wider 40-file mcp/strands run below was not repeated after the rebase. Before the rebase: ```text # Python 3.11.17, uv sync --frozen --extra mcp --extra strands --extra proxy --extra otel (mcp 2.3.0, strands-agents 1.63.0) $ pytest -q <every test module that references mcp, strands or the MCP servers: 40 files> 1163 passed, 31 skipped $ pytest -q tests/test_ccr_mcp_http.py tests/test_mcp_dependency_contract.py tests/test_mcp_sdk2_contract.py 9 passed $ pytest -q tests/integrations/test_strands tests/test_strands_tokenizer.py 80 passed, 25 skipped $ uv run --with uv==0.9.30 python -m uv lock --check Resolved 253 packages $ ruff check && ruff format --check on every changed .py file (ruff 0.16.8); git diff --check origin/main clean # [all] export against the union of the extras it includes: no package missing ``` ## Real Behavior Proof - Environment: macOS 27 (arm64), Python 3.11.17; `main` `fc1ba891` (SDK 1.30.0) and this branch (SDK 2.3.0); temporary `HOME`; plus this branch merged into my local runtime branch and installed as the `headroom` uv tool. - Exact command / steps: an SDK 2.3 stdio client starts `headroom mcp serve`, calls `ClientSession.discover()` (`server/discover`, as Claude Code does first), falls back to `initialize()` if that is rejected, then lists tools and calls `headroom_stats`. The server's stderr is captured. - Observed result: on `main`, `server/discover` is rejected with -32602 and the legacy `initialize` is used; stderr has 94 lines, starting `WARNING: Failed to validate request: 31 validation errors for ClientRequest`; 3 tools are listed and the call succeeds. On this branch the modern `server/discover` is accepted and stderr has 0 lines; 3 tools are listed and the call succeeds. The installed build behaves the same. - Not tested: Windows; the memory MCP server against a live client (unit and contract tests only); Strands agents against a live MCP server (`tests/integrations/test_strands` and `tests/test_strands_tokenizer.py`: 80 passed, 25 skipped); a real network client against the Streamable HTTP transport (the ASGI contract test only). ## Runtime Rollout Safety - Rollout-managed feature(s): none - Minimum rollout channel: n/a, dependency and server API change - Stable/default behavior changed: yes; the MCP servers require SDK 2.2+ and speak the modern handshake; the tools and their JSON results are unchanged - Kill switch / disable path: none; pin `headroom-ai` to the previous release to stay on SDK 1 - Unsafe override required: no - Qualification impact: environments that pin `mcp<2` alongside `headroom-ai[mcp]` or `[proxy]` no longer resolve - Rollback path: revert this commit, which restores the `<2.0.0` cap ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) N/A ## Additional Notes Proposed on #2658 (https://github.com/headroomlabs-ai/headroom/pull/2658#issuecomment-6562744017). If maintainers would rather keep #2658, `ce4d6442` and `274f0672` (previously `39c574c2` and `c7900848`) can be cherry-picked onto `tejas/mcp-2x-port` instead, and I'll close this. `mypy headroom/ccr/mcp_server.py headroom/memory/mcp_server.py headroom/ccr/mcp_http.py` with SDK 2.3 installed reports one error, in `headroom/providers/model_metadata.py:79`, which `main` reports too; none in the changed files. Full `mypy headroom` was not run. No docs change: the MCP tool names, arguments and results are unchanged. --------- Co-authored-by: Kenneth Wong <17061293+KennethWKZ@users.noreply.github.com> Co-authored-by: Tejas Chopra <chopratejas@gmail.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
112 lines
3.8 KiB
Python
112 lines
3.8 KiB
Python
from __future__ import annotations
|
|
|
|
import importlib
|
|
import sys
|
|
from types import ModuleType
|
|
|
|
_MCP_MODULE_NAMES = (
|
|
"mcp",
|
|
"mcp.server",
|
|
"mcp.server.stdio",
|
|
"mcp.types",
|
|
)
|
|
|
|
|
|
def _build_mcp_sdk_stub() -> dict[str, ModuleType]:
|
|
mcp_module = type(sys)("mcp")
|
|
mcp_server_module = type(sys)("mcp.server")
|
|
mcp_stdio_module = type(sys)("mcp.server.stdio")
|
|
mcp_types_module = type(sys)("mcp.types")
|
|
|
|
class DummyServer:
|
|
"""Mirrors the MCP 2.x surface: handlers arrive as constructor callbacks.
|
|
|
|
Deliberately does NOT expose ``list_tools()`` / ``call_tool()`` decorators.
|
|
Those were the 1.x API, and a stub that keeps accepting them lets a caller
|
|
still on decorators pass its tests while the real SDK rejects it — which is
|
|
how the 2.0.0 startup crash reached users with a green suite.
|
|
"""
|
|
|
|
def __init__(self, name: str, **handlers) -> None:
|
|
self.name = name
|
|
self.handlers = handlers
|
|
|
|
def create_initialization_options(self):
|
|
return {}
|
|
|
|
class DummyTool:
|
|
def __init__(self, **kwargs) -> None:
|
|
self.kwargs = kwargs
|
|
|
|
class DummyTextContent:
|
|
def __init__(self, **kwargs) -> None:
|
|
self.kwargs = kwargs
|
|
|
|
class DummyListToolsResult:
|
|
def __init__(self, tools=None, **kwargs) -> None:
|
|
self.tools = list(tools or [])
|
|
self.kwargs = kwargs
|
|
|
|
class DummyCallToolResult:
|
|
def __init__(self, content=None, **kwargs) -> None:
|
|
self.content = list(content or [])
|
|
self.kwargs = kwargs
|
|
|
|
async def dummy_stdio_server():
|
|
raise RuntimeError("stdio_server should not run in unit tests")
|
|
|
|
mcp_server_module.Server = DummyServer
|
|
mcp_stdio_module.stdio_server = dummy_stdio_server
|
|
mcp_types_module.TextContent = DummyTextContent
|
|
mcp_types_module.Tool = DummyTool
|
|
mcp_types_module.ListToolsResult = DummyListToolsResult
|
|
mcp_types_module.CallToolResult = DummyCallToolResult
|
|
|
|
return {
|
|
"mcp": mcp_module,
|
|
"mcp.server": mcp_server_module,
|
|
"mcp.server.stdio": mcp_stdio_module,
|
|
"mcp.types": mcp_types_module,
|
|
}
|
|
|
|
|
|
def import_module_with_mcp_stub(module_name: str):
|
|
original_target_module = sys.modules.get(module_name)
|
|
parent_name, _, child_name = module_name.rpartition(".")
|
|
original_parent_module = sys.modules.get(parent_name) if parent_name else None
|
|
original_parent_attr_exists = bool(
|
|
original_parent_module and child_name and hasattr(original_parent_module, child_name)
|
|
)
|
|
original_parent_attr = (
|
|
getattr(original_parent_module, child_name) if original_parent_attr_exists else None
|
|
)
|
|
original_modules = {name: sys.modules.get(name) for name in _MCP_MODULE_NAMES}
|
|
stub_modules = _build_mcp_sdk_stub()
|
|
|
|
sys.modules.pop(module_name, None)
|
|
for name, module in stub_modules.items():
|
|
sys.modules[name] = module
|
|
|
|
try:
|
|
return importlib.import_module(module_name)
|
|
finally:
|
|
if original_target_module is None:
|
|
sys.modules.pop(module_name, None)
|
|
else:
|
|
sys.modules[module_name] = original_target_module
|
|
if child_name:
|
|
current_parent_module = sys.modules.get(parent_name) or original_parent_module
|
|
if current_parent_module is not None:
|
|
if original_parent_attr_exists:
|
|
setattr(current_parent_module, child_name, original_parent_attr)
|
|
else:
|
|
try:
|
|
delattr(current_parent_module, child_name)
|
|
except AttributeError:
|
|
pass
|
|
for name, original_module in original_modules.items():
|
|
if original_module is None:
|
|
sys.modules.pop(name, None)
|
|
else:
|
|
sys.modules[name] = original_module
|