From e854b504ecc6977207c0a91314a788c30c8f6ff9 Mon Sep 17 00:00:00 2001 From: Tobias Herber <22559657+herber@users.noreply.github.com> Date: Mon, 9 Nov 2026 20:13:32 +0100 Subject: [PATCH] Add support for mcp v2 --- .github/workflows/ci.yml | 27 ++- CHANGELOG.md | 19 ++ pyproject.toml | 4 +- src/metorial/_tool_results.py | 26 +++ src/metorial/_version.py | 2 +- src/metorial/integrations/_common.py | 13 -- src/metorial/integrations/autogen.py | 2 +- src/metorial/integrations/crewai.py | 2 +- src/metorial/integrations/google_adk.py | 2 +- src/metorial/integrations/langchain.py | 6 +- src/metorial/integrations/llamaindex.py | 2 +- src/metorial/integrations/openai_agents.py | 10 +- src/metorial/integrations/pydantic_ai.py | 14 +- src/metorial/mcp/_compat.py | 93 ++++++++ src/metorial/mcp/magnetar_mcp_session.py | 43 +--- src/metorial/mcp/mcp_client.py | 21 +- src/metorial/mcp/mcp_tool.py | 15 +- src/metorial/mcp/transport.py | 81 +++++-- src/metorial/providers/anthropic.py | 6 +- src/metorial/providers/google.py | 5 +- src/metorial/providers/mistral.py | 6 +- src/metorial/providers/openai.py | 6 +- src/metorial/providers/openai_compatible.py | 6 +- tests/test_mcp_compat.py | 184 +++++++++++++++ tests/test_mcp_interop.py | 239 +++++++++++++++++++ tests/test_mcp_transport.py | 246 ++++++++++++++++++++ 26 files changed, 950 insertions(+), 130 deletions(-) create mode 100644 src/metorial/_tool_results.py create mode 100644 src/metorial/mcp/_compat.py create mode 100644 tests/test_mcp_compat.py create mode 100644 tests/test_mcp_interop.py create mode 100644 tests/test_mcp_transport.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e5e36fbb..2a36a8e8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -37,18 +37,33 @@ jobs: - run: uv run mypy src/metorial/ test: + name: test (py${{ matrix.python-version }}, ${{ matrix.mcp }}) runs-on: ubuntu-latest strategy: + fail-fast: false matrix: python-version: ["3.10", "3.11", "3.12"] + mcp: ["mcp>=2,<3", "mcp>=1.21,<2"] + include: + # Oldest supported mcp. Its bundled FastMCP test server needs a + # pydantic from the same era. + - python-version: "3.10" + mcp: "mcp==1.21.0" + extra: "pydantic<2.13" steps: - uses: actions/checkout@v4 - uses: astral-sh/setup-uv@v3 - run: uv python install ${{ matrix.python-version }} + - run: uv sync --dev --python ${{ matrix.python-version }} + - run: uv pip install "${{ matrix.mcp }}" ${{ matrix.extra && format('"{0}"', matrix.extra) || '' }} + - run: uv run --no-sync python -c "import importlib.metadata as m; print('mcp', m.version('mcp'))" + - run: uv run --no-sync pytest -q + + type-check-mcp-v1: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: astral-sh/setup-uv@v3 - run: uv sync --dev - - run: | - if [ -d tests ]; then - uv run pytest -q - else - echo "No tests directory present; skipping pytest." - fi + - run: uv pip install "mcp>=1.21,<2" + - run: uv run --no-sync mypy src/metorial/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 270bc6f1..bb3664ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,25 @@ All notable changes to the Metorial Python SDK will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.7.0] - 2026-11-09 + +### Added + +- Added support for v2 of the MCP Python SDK (`mcp` 2.x). The SDK now works with both `mcp>=1.21,<2` and `mcp>=2,<3`; all version-specific handling lives in `metorial.mcp._compat`. + +### Fixed + +- `MetorialMcpClient.from_url` no longer fails with `TypeError: unsupported operand type(s) for +: 'float' and 'datetime.timedelta'` on mcp 2.x. The read timeout is passed in the form the installed `mcp` expects. +- Tool input schemas and resource URI templates are read correctly from mcp 2.x models (which use snake_case attributes). Previously they would have been silently dropped. +- Tool results passed to LLM providers and framework integrations are serialized with MCP wire names (`isError`, `structuredContent`, `_meta`) regardless of the installed `mcp` version, and `null` fields are omitted. +- A failed HTTP request to the MCP server (for example a read timeout on a long-running tool or a 5xx response) now fails only that request, with a JSON-RPC error. Previously it shut down the client's transport, and every later call on that client failed. +- Per-request MCP headers set by the `mcp` client session are now forwarded by the Streamable HTTP transport. + +### Changed + +- `httpx-sse` is now a direct dependency. mcp 2.x no longer installs it. +- The minimum supported `mcp` version is now 1.21.0, the oldest release that provides every API the SDK already used. + ## [2.6.0] - 2026-10-16 ### Added diff --git a/pyproject.toml b/pyproject.toml index fd40b2d1..834ac421 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -28,9 +28,11 @@ dependencies = [ "aiohttp-sse-client>=0.2.1", "typing-extensions>=4.0.0", "httpx>=0.25.0", + "httpx-sse>=0.4.0", "requests>=2.25.0", "truststore>=0.8.0", - "mcp>=1.0.0,<2", + # Both MCP Python SDK majors are supported; metorial.mcp._compat bridges them. + "mcp>=1.21.0,<3", ] # Provider SDKs are optional: the Metorial SDK itself never imports them, they diff --git a/src/metorial/_tool_results.py b/src/metorial/_tool_results.py new file mode 100644 index 00000000..7f3c5409 --- /dev/null +++ b/src/metorial/_tool_results.py @@ -0,0 +1,26 @@ +"""Turning tool results into the plain JSON handed to LLM providers.""" + +from __future__ import annotations + +import json +from typing import Any + +from pydantic import BaseModel + + +def normalize_tool_result(result: Any) -> Any: + """Convert an MCP result model into plain JSON-compatible data. + + Pydantic models are dumped by alias so the keys match the MCP wire format + (``structuredContent``, ``isError``, ``_meta``) regardless of whether the + installed MCP SDK names its attributes in camelCase (1.x) or snake_case (2.x). + """ + if isinstance(result, BaseModel): + return result.model_dump(by_alias=True, mode="json", exclude_none=True) + if hasattr(result, "model_dump"): + return result.model_dump() + return result + + +def serialize_tool_result(result: Any) -> str: + return json.dumps(normalize_tool_result(result), ensure_ascii=False, default=str) diff --git a/src/metorial/_version.py b/src/metorial/_version.py index 92f6328d..4947d4d9 100644 --- a/src/metorial/_version.py +++ b/src/metorial/_version.py @@ -1,3 +1,3 @@ """Metorial SDK version.""" -__version__ = "2.6.0" +__version__ = "2.7.0" diff --git a/src/metorial/integrations/_common.py b/src/metorial/integrations/_common.py index 4c2eb7c6..12d59c0e 100644 --- a/src/metorial/integrations/_common.py +++ b/src/metorial/integrations/_common.py @@ -4,7 +4,6 @@ import asyncio import inspect -import json from collections.abc import Callable from typing import Any @@ -22,18 +21,6 @@ def json_type_to_python(json_type: str) -> type[Any]: return type_map.get(json_type, str) -def normalize_tool_result(result: Any) -> Any: - """Normalize SDK objects into plain Python data.""" - if hasattr(result, "model_dump"): - return result.model_dump() - return result - - -def serialize_tool_result(result: Any) -> str: - """Serialize a tool result as JSON text.""" - return json.dumps(normalize_tool_result(result), ensure_ascii=False, default=str) - - def apply_tool_signature( fn: Callable[..., Any], *, diff --git a/src/metorial/integrations/autogen.py b/src/metorial/integrations/autogen.py index b0acd0fe..190af2ff 100644 --- a/src/metorial/integrations/autogen.py +++ b/src/metorial/integrations/autogen.py @@ -51,7 +51,7 @@ async def _invoke(**kwargs: Any) -> str: try: result = await tool_manager.execute_tool(tool_name, args) if hasattr(result, "model_dump"): - result = result.model_dump() + result = result.model_dump(by_alias=True, mode="json", exclude_none=True) return json.dumps(result, ensure_ascii=False, default=str) except Exception as e: return json.dumps({"error": str(e)}, ensure_ascii=False) diff --git a/src/metorial/integrations/crewai.py b/src/metorial/integrations/crewai.py index 95640719..5c8bd54c 100644 --- a/src/metorial/integrations/crewai.py +++ b/src/metorial/integrations/crewai.py @@ -6,11 +6,11 @@ import json from typing import TYPE_CHECKING, Any +from metorial._tool_results import serialize_tool_result from metorial.integrations import _sanitize_tool_name from metorial.integrations._common import ( apply_tool_signature, run_coro_on_loop, - serialize_tool_result, ) if TYPE_CHECKING: diff --git a/src/metorial/integrations/google_adk.py b/src/metorial/integrations/google_adk.py index 10977bd0..8d9eabb1 100644 --- a/src/metorial/integrations/google_adk.py +++ b/src/metorial/integrations/google_adk.py @@ -5,10 +5,10 @@ import json from typing import TYPE_CHECKING, Any +from metorial._tool_results import normalize_tool_result from metorial.integrations import _sanitize_tool_name from metorial.integrations._common import ( apply_tool_signature, - normalize_tool_result, ) if TYPE_CHECKING: diff --git a/src/metorial/integrations/langchain.py b/src/metorial/integrations/langchain.py index f4a44878..d082e80c 100644 --- a/src/metorial/integrations/langchain.py +++ b/src/metorial/integrations/langchain.py @@ -21,6 +21,8 @@ import json from typing import TYPE_CHECKING, Any +from metorial._tool_results import serialize_tool_result + if TYPE_CHECKING: from metorial._client import ProviderSession @@ -64,9 +66,7 @@ async def tool_fn(**kwargs: Any) -> str: filtered_kwargs = {k: v for k, v in kwargs.items() if v is not None} try: result = await tool_manager.execute_tool(tool_name, filtered_kwargs) - if hasattr(result, "model_dump"): - result = result.model_dump() - return json.dumps(result, ensure_ascii=False, default=str) + return serialize_tool_result(result) except Exception as e: return json.dumps({"error": str(e)}, ensure_ascii=False) diff --git a/src/metorial/integrations/llamaindex.py b/src/metorial/integrations/llamaindex.py index 91a30a91..a65a2d8f 100644 --- a/src/metorial/integrations/llamaindex.py +++ b/src/metorial/integrations/llamaindex.py @@ -6,11 +6,11 @@ import json from typing import TYPE_CHECKING, Any +from metorial._tool_results import serialize_tool_result from metorial.integrations import _sanitize_tool_name from metorial.integrations._common import ( apply_tool_signature, run_coro_on_loop, - serialize_tool_result, ) if TYPE_CHECKING: diff --git a/src/metorial/integrations/openai_agents.py b/src/metorial/integrations/openai_agents.py index ec40b802..44669a88 100644 --- a/src/metorial/integrations/openai_agents.py +++ b/src/metorial/integrations/openai_agents.py @@ -24,6 +24,8 @@ import json from typing import TYPE_CHECKING, Any +from metorial._tool_results import serialize_tool_result + if TYPE_CHECKING: from metorial._client import ProviderSession @@ -94,9 +96,7 @@ async def tool_fn(**kwargs: Any) -> str: # Filter out None values filtered_kwargs = {k: v for k, v in kwargs.items() if v is not None} result = await tool_manager.execute_tool(original_name, filtered_kwargs) - if hasattr(result, "model_dump"): - result = result.model_dump() - return json.dumps(result, ensure_ascii=False, default=str) + return serialize_tool_result(result) tool_fn.__name__ = tool_name tool_fn.__doc__ = tool_description @@ -126,9 +126,7 @@ async def invoke_handler(ctx: Any, input_json: str) -> str: if k in required_params or (v is not None and v != ""): filtered_kwargs[k] = v result = await tool_manager.execute_tool(tool_name, filtered_kwargs) - if hasattr(result, "model_dump"): - result = result.model_dump() - return json.dumps(result, ensure_ascii=False, default=str) + return serialize_tool_result(result) return invoke_handler diff --git a/src/metorial/integrations/pydantic_ai.py b/src/metorial/integrations/pydantic_ai.py index 059fadc2..d4168c94 100644 --- a/src/metorial/integrations/pydantic_ai.py +++ b/src/metorial/integrations/pydantic_ai.py @@ -21,6 +21,8 @@ import json from typing import TYPE_CHECKING, Any +from metorial._tool_results import serialize_tool_result + if TYPE_CHECKING: from metorial._client import ProviderSession @@ -70,9 +72,7 @@ async def metorial_tool(**kwargs: Any) -> str: result = await tool_manager.execute_tool(tool_name, filtered_kwargs) except Exception as e: return json.dumps({"error": str(e)}, ensure_ascii=False) - if hasattr(result, "model_dump"): - result = result.model_dump() - return json.dumps(result, ensure_ascii=False, default=str) + return serialize_tool_result(result) # Override the function metadata metorial_tool.__name__ = tool_name @@ -154,9 +154,7 @@ async def tool_fn(**kwargs: Any) -> str: result = await mgr.execute_tool(name, filtered_kwargs) except Exception as e: return json.dumps({"error": str(e)}, ensure_ascii=False) - if hasattr(result, "model_dump"): - result = result.model_dump() - return json.dumps(result, ensure_ascii=False, default=str) + return serialize_tool_result(result) # Set annotations for PydanticAI to discover parameters tool_fn.__annotations__ = { @@ -184,9 +182,7 @@ async def tool_fn() -> str: result = await mgr.execute_tool(name, {}) except Exception as e: return json.dumps({"error": str(e)}, ensure_ascii=False) - if hasattr(result, "model_dump"): - result = result.model_dump() - return json.dumps(result, ensure_ascii=False, default=str) + return serialize_tool_result(result) tool_fn.__signature__ = inspect.Signature(return_annotation=str) diff --git a/src/metorial/mcp/_compat.py b/src/metorial/mcp/_compat.py new file mode 100644 index 00000000..9617489d --- /dev/null +++ b/src/metorial/mcp/_compat.py @@ -0,0 +1,93 @@ +"""Bridges the differences between the 1.x and 2.x MCP Python SDKs. + +Every place in Metorial that depends on an API that changed between the two +majors goes through this module, so the rest of the SDK can stay +version-agnostic. The differences handled here: + +- ``ClientSession(read_timeout_seconds=...)`` takes a ``timedelta`` in 1.x and + a ``float`` of seconds in 2.x. +- ``mcp.types.JSONRPCMessage`` is a pydantic ``RootModel`` in 1.x (the concrete + message lives on ``.root``) and a plain ``Union`` of message models in 2.x. +- MCP models expose camelCase attributes in 1.x (``tool.inputSchema``) and + snake_case attributes in 2.x (``tool.input_schema``). The wire format is + camelCase in both. +- ``ClientSession.get_server_capabilities()`` became the + ``ClientSession.server_capabilities`` property in 2.x. +- ``ClientSession.read_resource`` takes a pydantic ``AnyUrl`` in 1.x and a + ``str`` in 2.x. +""" + +from __future__ import annotations + +import re +from datetime import timedelta +from typing import TYPE_CHECKING, Any + +from mcp.types import JSONRPCMessage, ServerCapabilities, Tool +from pydantic import AnyUrl, TypeAdapter + +if TYPE_CHECKING: + from mcp import ClientSession + +MCP_V2: bool = "input_schema" in Tool.model_fields + +_JSONRPC_MESSAGE_ADAPTER: TypeAdapter[JSONRPCMessage] = TypeAdapter(JSONRPCMessage) + +_CAMEL_BOUNDARY = re.compile(r"(? Any: + if seconds is None: + return None + return float(seconds) if MCP_V2 else timedelta(seconds=seconds) + + +def parse_jsonrpc_message(data: Any) -> JSONRPCMessage: + return _JSONRPC_MESSAGE_ADAPTER.validate_python(data) + + +def parse_jsonrpc_json(data: str | bytes) -> JSONRPCMessage: + return _JSONRPC_MESSAGE_ADAPTER.validate_json(data) + + +def unwrap_jsonrpc_message(message: JSONRPCMessage) -> Any: + """Return the concrete request/notification/response/error model.""" + return message if MCP_V2 else message.root # type: ignore[union-attr,attr-defined,unused-ignore] + + +def to_snake_case(name: str) -> str: + return _CAMEL_BOUNDARY.sub("_", name).lower() + + +def get_field(obj: Any, name: str, default: Any = None) -> Any: + """Read an MCP field by its camelCase wire name from a dict or a model. + + Accepts raw JSON dicts, 1.x models (camelCase attributes) and 2.x models + (snake_case attributes) alike. + """ + if obj is None: + return default + + snake = to_snake_case(name) + + if isinstance(obj, dict): + if name in obj: + return obj[name] + return obj.get(snake, default) + + value = getattr(obj, name, _MISSING) + if value is _MISSING: + value = getattr(obj, snake, default) + return value + + +def get_server_capabilities(session: ClientSession) -> ServerCapabilities | None: + if MCP_V2: + return session.server_capabilities # type: ignore[attr-defined,no-any-return,unused-ignore] + return session.get_server_capabilities() # type: ignore[attr-defined,no-any-return,unused-ignore] + + +def resource_uri(uri: str) -> Any: + return uri if MCP_V2 else AnyUrl(uri) diff --git a/src/metorial/mcp/magnetar_mcp_session.py b/src/metorial/mcp/magnetar_mcp_session.py index 6b7db3cc..36682525 100644 --- a/src/metorial/mcp/magnetar_mcp_session.py +++ b/src/metorial/mcp/magnetar_mcp_session.py @@ -12,6 +12,7 @@ import logging from typing import TYPE_CHECKING, Any, Protocol, TypedDict +from ._compat import get_field from .mcp_client import MetorialMcpClient from .mcp_tool import Capability, ResourceTemplate, Tool @@ -250,14 +251,9 @@ async def _get_tools_via_direct_mcp(self) -> list[Capability]: _log_info("Starting Magnetar direct MCP tool discovery...") def _normalize_tool(raw_tool: object) -> Tool | None: - if isinstance(raw_tool, dict): - name_value = raw_tool.get("name") - description_value = raw_tool.get("description") - input_schema_value = raw_tool.get("inputSchema") - else: - name_value = getattr(raw_tool, "name", None) - description_value = getattr(raw_tool, "description", None) - input_schema_value = getattr(raw_tool, "inputSchema", None) + name_value = get_field(raw_tool, "name") + description_value = get_field(raw_tool, "description") + input_schema_value = get_field(raw_tool, "inputSchema") if not isinstance(name_value, str) or not name_value: return None @@ -270,14 +266,9 @@ def _normalize_tool(raw_tool: object) -> Tool | None: return normalized_tool def _normalize_resource_template(raw_template: object) -> ResourceTemplate | None: - if isinstance(raw_template, dict): - name_value = raw_template.get("name") - description_value = raw_template.get("description") - uri_template_value = raw_template.get("uriTemplate") - else: - name_value = getattr(raw_template, "name", None) - description_value = getattr(raw_template, "description", None) - uri_template_value = getattr(raw_template, "uriTemplate", None) + name_value = get_field(raw_template, "name") + description_value = get_field(raw_template, "description") + uri_template_value = get_field(raw_template, "uriTemplate") if not isinstance(name_value, str) or not name_value: return None @@ -316,13 +307,7 @@ def _normalize_resource_template(raw_template: object) -> ResourceTemplate | Non # Get tools try: tools_response = await client.list_tools() - raw_tools: object - if hasattr(tools_response, "tools"): - raw_tools = tools_response.tools - elif isinstance(tools_response, dict): - raw_tools = tools_response.get("tools", []) - else: - raw_tools = [] + raw_tools: object = get_field(tools_response, "tools") or [] if isinstance(raw_tools, list): for raw_tool in raw_tools: @@ -337,17 +322,7 @@ def _normalize_resource_template(raw_template: object) -> ResourceTemplate | Non # Get resource templates try: templates_response = await client.list_resource_templates() - raw_templates: object - if hasattr(templates_response, "resourceTemplates"): - raw_templates = templates_response.resourceTemplates or [] - elif hasattr(templates_response, "resource_templates"): - raw_templates = templates_response.resource_templates or [] - elif isinstance(templates_response, dict): - raw_templates = templates_response.get( - "resourceTemplates" - ) or templates_response.get("resource_templates", []) - else: - raw_templates = [] + raw_templates: object = get_field(templates_response, "resourceTemplates") or [] if isinstance(raw_templates, list): for raw_template in raw_templates: diff --git a/src/metorial/mcp/mcp_client.py b/src/metorial/mcp/mcp_client.py index 06562cec..6d379ea9 100644 --- a/src/metorial/mcp/mcp_client.py +++ b/src/metorial/mcp/mcp_client.py @@ -5,7 +5,6 @@ import logging from collections.abc import Awaitable, Callable from dataclasses import dataclass -from datetime import timedelta from typing import Any, TypedDict, TypeVar import mcp.types as mcp_types @@ -16,8 +15,8 @@ PaginatedRequestParams, ServerCapabilities, ) -from pydantic import AnyUrl +from ._compat import get_server_capabilities, resource_uri, session_read_timeout from .transport import MetorialMcpTransport @@ -50,7 +49,11 @@ class ListRequestParams(TypedDict, total=False): class MetorialClientSession(ClientSession): - """ClientSession variant that preserves raw MCP tool results.""" + """ClientSession variant that preserves raw MCP tool results. + + The output-schema validation hook is ``_validate_tool_result`` in mcp 1.x and + ``validate_tool_result`` in mcp 2.x; both are overridden. + """ async def _validate_tool_result( self, name: str, result: mcp_types.CallToolResult @@ -58,6 +61,12 @@ async def _validate_tool_result( logger.debug("Skipping MCP outputSchema validation for tool result: %s", name) return None + async def validate_tool_result( + self, name: str, result: mcp_types.CallToolResult + ) -> None: + logger.debug("Skipping MCP outputSchema validation for tool result: %s", name) + return None + def _log_info(message: str, **kwargs: Any) -> None: """Conditionally log info messages only if debug logging is enabled.""" @@ -137,7 +146,7 @@ async def from_url( read, write, client_info=client_info, - read_timeout_seconds=timedelta(seconds=read_timeout), + read_timeout_seconds=session_read_timeout(read_timeout), ) await session_cm.__aenter__() try: @@ -171,7 +180,7 @@ def _ensure_open(self) -> None: raise RuntimeError("MetorialMcpClient is closed") def get_server_capabilities(self) -> ServerCapabilities: - caps: ServerCapabilities | None = self._session.get_server_capabilities() + caps = get_server_capabilities(self._session) logger.debug("get_server_capabilities -> %s", caps) if caps is None: raise RuntimeError("Server capabilities not available") @@ -253,7 +262,7 @@ async def read_resource( ) -> Any: self._ensure_open() logger.debug("read_resource params=%s options=%s", params, options) - uri = AnyUrl(params["uri"]) + uri = resource_uri(params["uri"]) return await self._with_timeout(self._session.read_resource(uri), options) async def call_tool( diff --git a/src/metorial/mcp/mcp_tool.py b/src/metorial/mcp/mcp_tool.py index 24bcccc6..26a74ea2 100644 --- a/src/metorial/mcp/mcp_tool.py +++ b/src/metorial/mcp/mcp_tool.py @@ -12,6 +12,8 @@ TypedDict, ) +from ._compat import get_field + if TYPE_CHECKING: from metorial._protocols import McpSessionProtocol @@ -245,15 +247,12 @@ async def _action(params: Any) -> Any: raise last_error raise RuntimeError(f"Tool execution failed after {MAX_RETRIES} attempts") - # Handle both dict and object responses for tool data if isinstance(tool, dict): tool_name = tool["name"] - tool_description = tool.get("description") - tool_input_schema = tool.get("inputSchema") else: tool_name = getattr(tool, "name", "tool") - tool_description = getattr(tool, "description", None) - tool_input_schema = getattr(tool, "inputSchema", None) + tool_description = get_field(tool, "description") + tool_input_schema = get_field(tool, "inputSchema") # Handle None input schema with sensible defaults based on tool name if tool_input_schema is None: @@ -310,11 +309,7 @@ def from_resource_template( "is missing serverDeployment.id" ) - # Handle both dict and object responses for rt - if isinstance(rt, dict): - uri_template = rt.get("uriTemplate") - else: - uri_template = getattr(rt, "uriTemplate", None) + uri_template = get_field(rt, "uriTemplate") # Handle None uriTemplate with sensible defaults based on resource name if uri_template is None: diff --git a/src/metorial/mcp/transport.py b/src/metorial/mcp/transport.py index 5cc5b693..df9e202b 100644 --- a/src/metorial/mcp/transport.py +++ b/src/metorial/mcp/transport.py @@ -11,13 +11,14 @@ from httpx_sse import EventSource from mcp.shared.message import SessionMessage from mcp.types import ( - InitializeResult, JSONRPCError, JSONRPCMessage, JSONRPCRequest, JSONRPCResponse, ) +from ._compat import parse_jsonrpc_json, parse_jsonrpc_message, unwrap_jsonrpc_message + logger = logging.getLogger("metorial.mcp.transport") MCP_SESSION_ID = "mcp-session-id" @@ -27,6 +28,9 @@ JSON = "application/json" SSE = "text/event-stream" +# JSON-RPC "server error" range, used for requests whose HTTP exchange failed. +POST_FAILED_ERROR_CODE = -32000 + class MetorialMcpTransportError(RuntimeError): pass @@ -74,22 +78,25 @@ async def open( ) return self.read_stream, self.write_stream - def _prepare_headers(self) -> dict[str, str]: + def _prepare_headers( + self, message_headers: dict[str, str] | None = None + ) -> dict[str, str]: headers = { ACCEPT: f"{JSON}, {SSE}", CONTENT_TYPE: JSON, **self._headers, } - if self._session_id: - headers[MCP_SESSION_ID] = self._session_id if self._protocol_version: headers[MCP_PROTOCOL_VERSION] = self._protocol_version + if message_headers: + headers.update(message_headers) + if self._session_id: + headers[MCP_SESSION_ID] = self._session_id return headers def _is_initialize_request(self, message: JSONRPCMessage) -> bool: - return ( - isinstance(message.root, JSONRPCRequest) and message.root.method == "initialize" - ) + inner = unwrap_jsonrpc_message(message) + return isinstance(inner, JSONRPCRequest) and inner.method == "initialize" def _update_session_id(self, response: httpx.Response) -> None: session_id = response.headers.get(MCP_SESSION_ID) @@ -97,12 +104,14 @@ def _update_session_id(self, response: httpx.Response) -> None: self._session_id = session_id def _update_protocol_version(self, message: JSONRPCMessage) -> None: - if isinstance(message.root, JSONRPCResponse) and message.root.result: - try: - init_result = InitializeResult.model_validate(message.root.result) - self._protocol_version = str(init_result.protocolVersion) - except Exception: - logger.debug("Failed to extract negotiated protocol version", exc_info=True) + inner = unwrap_jsonrpc_message(message) + if not isinstance(inner, JSONRPCResponse) or not isinstance(inner.result, dict): + return + protocol_version = inner.result.get("protocolVersion") + if isinstance(protocol_version, str) and protocol_version: + self._protocol_version = protocol_version + else: + logger.debug("Initialize response carried no protocol version") async def _send_message( self, @@ -127,7 +136,7 @@ async def _handle_json_response( payload = json.loads(content) messages = payload if isinstance(payload, list) else [payload] for item in messages: - message = JSONRPCMessage.model_validate(item) + message = parse_jsonrpc_message(item) await self._send_message(message, is_initialize=is_initialize) async def _handle_sse_response( @@ -142,9 +151,9 @@ async def _handle_sse_response( continue if not sse.data: continue - message = JSONRPCMessage.model_validate_json(sse.data) + message = parse_jsonrpc_json(sse.data) await self._send_message(message, is_initialize=is_initialize) - if isinstance(message.root, (JSONRPCResponse, JSONRPCError)): + if isinstance(unwrap_jsonrpc_message(message), (JSONRPCResponse, JSONRPCError)): await response.aclose() return await response.aclose() @@ -154,11 +163,13 @@ async def _handle_post(self, session_message: SessionMessage) -> None: is_initialize = self._is_initialize_request(message) payload = message.model_dump(by_alias=True, mode="json", exclude_none=True) + message_headers = getattr(session_message.metadata, "headers", None) + async with self._client.stream( "POST", self._url, json=payload, - headers=self._prepare_headers(), + headers=self._prepare_headers(message_headers), ) as response: if response.status_code == 202: return @@ -166,7 +177,7 @@ async def _handle_post(self, session_message: SessionMessage) -> None: response.raise_for_status() self._update_session_id(response) - if not isinstance(message.root, JSONRPCRequest): + if not isinstance(unwrap_jsonrpc_message(message), JSONRPCRequest): await response.aclose() return @@ -180,17 +191,41 @@ async def _handle_post(self, session_message: SessionMessage) -> None: f"Unexpected content type from MCP endpoint: {content_type}" ) + async def _report_post_failure( + self, session_message: SessionMessage, exc: Exception + ) -> None: + inner = unwrap_jsonrpc_message(session_message.message) + if not isinstance(inner, JSONRPCRequest): + await self._read_stream_writer.send(exc) + return + + error = parse_jsonrpc_message( + { + "jsonrpc": "2.0", + "id": inner.id, + "error": { + "code": POST_FAILED_ERROR_CODE, + "message": f"MCP request failed: {type(exc).__name__}: {exc}", + }, + } + ) + await self._read_stream_writer.send(SessionMessage(error)) + async def _post_writer(self) -> None: try: async with self._write_stream_reader: async for session_message in self._write_stream_reader: - await self._handle_post(session_message) + try: + await self._handle_post(session_message) + except asyncio.CancelledError: + raise + except Exception as exc: + logger.debug("MCP request failed", exc_info=True) + await self._report_post_failure(session_message, exc) except asyncio.CancelledError: raise - except Exception as exc: - logger.debug("Transport writer failed", exc_info=True) - with contextlib.suppress(Exception): - await self._read_stream_writer.send(exc) + except Exception: + logger.debug("Transport writer stopped", exc_info=True) finally: with contextlib.suppress(Exception): await self._read_stream_writer.aclose() diff --git a/src/metorial/providers/anthropic.py b/src/metorial/providers/anthropic.py index 9d1b5672..f69d34a6 100644 --- a/src/metorial/providers/anthropic.py +++ b/src/metorial/providers/anthropic.py @@ -4,6 +4,8 @@ from collections.abc import Generator, Iterable from typing import TYPE_CHECKING, Any, cast +from metorial._tool_results import serialize_tool_result + if TYPE_CHECKING: from metorial._protocols import ( SessionWithToolManagerProtocol, @@ -199,9 +201,7 @@ async def call_anthropic_tools( try: result = await tool_mgr.execute_tool(str(tool_name), args) - if hasattr(result, "model_dump"): - result = result.model_dump() - content = json.dumps(result, ensure_ascii=False, default=str) + content = serialize_tool_result(result) except Exception as e: content = f"[ERROR] Tool call failed: {e!r}" diff --git a/src/metorial/providers/google.py b/src/metorial/providers/google.py index b4175687..3d604d03 100644 --- a/src/metorial/providers/google.py +++ b/src/metorial/providers/google.py @@ -4,6 +4,8 @@ from collections.abc import Generator, Iterable from typing import TYPE_CHECKING, Any, cast +from metorial._tool_results import normalize_tool_result + if TYPE_CHECKING: from metorial._protocols import ( SessionWithToolManagerProtocol, @@ -86,8 +88,7 @@ async def call_google_tools( try: result = await tool_mgr.execute_tool(str(call_name), cast(dict[str, Any], args)) - if hasattr(result, "model_dump"): - result = result.model_dump() + result = normalize_tool_result(result) except Exception as e: result = {"error": f"[ERROR] Tool call failed: {e!r}"} diff --git a/src/metorial/providers/mistral.py b/src/metorial/providers/mistral.py index 7c88b616..4eb2fd5d 100644 --- a/src/metorial/providers/mistral.py +++ b/src/metorial/providers/mistral.py @@ -4,6 +4,8 @@ from collections.abc import Generator, Iterable from typing import TYPE_CHECKING, Any, cast +from metorial._tool_results import serialize_tool_result + if TYPE_CHECKING: from metorial._protocols import ( SessionWithToolManagerProtocol, @@ -85,9 +87,7 @@ async def call_mistral_tools( try: result = await tool_mgr.execute_tool(str(function_name), args) - if hasattr(result, "model_dump"): - result = result.model_dump() - content = json.dumps(result, ensure_ascii=False, default=str) + content = serialize_tool_result(result) except Exception as e: content = f"[ERROR] Tool call failed: {e!r}" diff --git a/src/metorial/providers/openai.py b/src/metorial/providers/openai.py index 31957e56..3cb21686 100644 --- a/src/metorial/providers/openai.py +++ b/src/metorial/providers/openai.py @@ -4,6 +4,8 @@ from collections.abc import Generator, Iterable from typing import TYPE_CHECKING, Any, cast +from metorial._tool_results import serialize_tool_result + if TYPE_CHECKING: from metorial._protocols import ( SessionWithToolManagerProtocol, @@ -77,9 +79,7 @@ async def call_openai_tools( try: result = await tool_mgr.execute_tool(str(fn_name), args) - if hasattr(result, "model_dump"): - result = result.model_dump() - content = json.dumps(result, ensure_ascii=False, default=str) + content = serialize_tool_result(result) except Exception as e: content = f"[ERROR] Tool call failed: {e!r}" diff --git a/src/metorial/providers/openai_compatible.py b/src/metorial/providers/openai_compatible.py index 21934ebd..9c7ff869 100644 --- a/src/metorial/providers/openai_compatible.py +++ b/src/metorial/providers/openai_compatible.py @@ -4,6 +4,8 @@ from collections.abc import Generator, Iterable from typing import TYPE_CHECKING, Any, cast +from metorial._tool_results import serialize_tool_result + if TYPE_CHECKING: from metorial._protocols import ( SessionWithToolManagerProtocol, @@ -90,9 +92,7 @@ async def call_openai_compatible_tools( try: result = await tool_mgr.execute_tool(str(function_name), args) - if hasattr(result, "model_dump"): - result = result.model_dump() - content = json.dumps(result, ensure_ascii=False, default=str) + content = serialize_tool_result(result) except Exception as e: content = f"[ERROR] Tool call failed: {e!r}" diff --git a/tests/test_mcp_compat.py b/tests/test_mcp_compat.py new file mode 100644 index 00000000..86661053 --- /dev/null +++ b/tests/test_mcp_compat.py @@ -0,0 +1,184 @@ +from __future__ import annotations + +from datetime import timedelta +from importlib.metadata import version +from typing import Any + +import mcp.types as mcp_types +import pytest +from pydantic import AnyUrl + +from metorial._tool_results import normalize_tool_result, serialize_tool_result +from metorial.mcp._compat import ( + MCP_V2, + get_field, + parse_jsonrpc_json, + parse_jsonrpc_message, + resource_uri, + session_read_timeout, + to_snake_case, + unwrap_jsonrpc_message, +) +from metorial.mcp.mcp_client import MetorialClientSession +from metorial.mcp.mcp_tool import MetorialMcpTool + +TOOL_WIRE = { + "name": "search", + "description": "Search things", + "inputSchema": { + "type": "object", + "properties": {"q": {"type": "string"}}, + "required": ["q"], + }, +} + +CALL_RESULT_WIRE = { + "content": [{"type": "text", "text": "hi"}], + "structuredContent": {"answer": 42}, + "isError": False, +} + + +def test_detected_major_matches_installed_mcp() -> None: + installed_major = int(version("mcp").split(".")[0]) + assert MCP_V2 is (installed_major >= 2) + + +def test_session_read_timeout_matches_client_session_contract() -> None: + assert session_read_timeout(None) is None + converted = session_read_timeout(2.5) + if MCP_V2: + assert converted == 2.5 + assert isinstance(converted, float) + else: + assert converted == timedelta(seconds=2.5) + + +@pytest.mark.parametrize( + ("camel", "snake"), + [ + ("inputSchema", "input_schema"), + ("uriTemplate", "uri_template"), + ("resourceTemplates", "resource_templates"), + ("isError", "is_error"), + ("name", "name"), + ], +) +def test_to_snake_case(camel: str, snake: str) -> None: + assert to_snake_case(camel) == snake + + +def test_get_field_reads_models_of_installed_major() -> None: + tool = mcp_types.Tool.model_validate(TOOL_WIRE) + assert get_field(tool, "inputSchema") == TOOL_WIRE["inputSchema"] + assert get_field(tool, "description") == "Search things" + assert get_field(tool, "outputSchema") is None + assert get_field(tool, "doesNotExist", "fallback") == "fallback" + + +@pytest.mark.parametrize( + "obj", + [ + {"inputSchema": {"type": "object"}}, + {"input_schema": {"type": "object"}}, + type("V1Like", (), {"inputSchema": {"type": "object"}})(), + type("V2Like", (), {"input_schema": {"type": "object"}})(), + ], + ids=["camel-dict", "snake-dict", "camel-attr", "snake-attr"], +) +def test_get_field_accepts_either_naming(obj: Any) -> None: + assert get_field(obj, "inputSchema") == {"type": "object"} + + +def test_get_field_handles_none() -> None: + assert get_field(None, "inputSchema", "x") == "x" + + +def test_jsonrpc_parse_and_unwrap_round_trip() -> None: + request = {"jsonrpc": "2.0", "id": 1, "method": "tools/list"} + for message in ( + parse_jsonrpc_message(request), + parse_jsonrpc_json('{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'), + ): + inner = unwrap_jsonrpc_message(message) + assert isinstance(inner, mcp_types.JSONRPCRequest) + assert inner.method == "tools/list" + assert ( + message.model_dump(by_alias=True, mode="json", exclude_none=True) == request # type: ignore[union-attr] + ) + + error = unwrap_jsonrpc_message( + parse_jsonrpc_message( + {"jsonrpc": "2.0", "id": 2, "error": {"code": -1, "message": "no"}} + ) + ) + assert isinstance(error, mcp_types.JSONRPCError) + + +def test_resource_uri_matches_read_resource_contract() -> None: + uri = resource_uri("note://alpha") + if MCP_V2: + assert uri == "note://alpha" + else: + assert isinstance(uri, AnyUrl) + assert str(uri) == "note://alpha" + + +def test_client_session_overrides_both_validation_hooks() -> None: + assert "_validate_tool_result" in MetorialClientSession.__dict__ + assert "validate_tool_result" in MetorialClientSession.__dict__ + + +def test_normalize_tool_result_uses_wire_names() -> None: + result = mcp_types.CallToolResult.model_validate(CALL_RESULT_WIRE) + normalized = normalize_tool_result(result) + + assert normalized["content"] == CALL_RESULT_WIRE["content"] + assert normalized["structuredContent"] == {"answer": 42} + assert normalized["isError"] is False + assert not any("_" in key.lstrip("_") for key in normalized) + + +def test_normalize_tool_result_passes_plain_data_through() -> None: + assert normalize_tool_result({"a": 1}) == {"a": 1} + assert normalize_tool_result("text") == "text" + assert serialize_tool_result({"a": "é"}) == '{"a": "é"}' + + +def test_normalize_tool_result_supports_duck_typed_models() -> None: + class Legacy: + def model_dump(self) -> dict[str, Any]: + return {"legacy": True} + + assert normalize_tool_result(Legacy()) == {"legacy": True} + + +class _NoSession: + async def get_client(self, opts: dict[str, str]) -> Any: + raise AssertionError("not called") + + +def test_metorial_tool_reads_schema_from_installed_major_model() -> None: + capability = { + "type": "tool", + "tool": mcp_types.Tool.model_validate(TOOL_WIRE), + "serverDeployment": {"id": "dep"}, + } + tool = MetorialMcpTool.from_capability(_NoSession(), capability) # type: ignore[arg-type] + + assert tool.name == "search" + assert tool.description == "Search things" + assert tool.parameters == TOOL_WIRE["inputSchema"] + + +def test_metorial_tool_reads_uri_template_from_installed_major_model() -> None: + capability = { + "type": "resource-template", + "resourceTemplate": mcp_types.ResourceTemplate.model_validate( + {"name": "note", "uriTemplate": "note://{name}"} + ), + "serverDeployment": {"id": "dep"}, + } + tool = MetorialMcpTool.from_capability(_NoSession(), capability) # type: ignore[arg-type] + + assert tool.parameters["required"] == ["name"] diff --git a/tests/test_mcp_interop.py b/tests/test_mcp_interop.py new file mode 100644 index 00000000..3354ab5d --- /dev/null +++ b/tests/test_mcp_interop.py @@ -0,0 +1,239 @@ +"""End-to-end tests of the Metorial MCP client against a real MCP server. + +The server is the official Streamable HTTP server shipped by whichever MCP +Python SDK is installed (``FastMCP`` in 1.x, ``MCPServer`` in 2.x), so running +this suite under both majors checks that the client interoperates with each. +""" + +from __future__ import annotations + +import asyncio +import json +import socket +import threading +import time +from collections.abc import Iterator +from typing import Any + +import pytest +import uvicorn + +from metorial._tool_results import normalize_tool_result, serialize_tool_result +from metorial.mcp import MetorialMagnetarMcpSession, MetorialMcpClient +from metorial.mcp._compat import MCP_V2, get_field +from metorial.mcp.mcp_client import RequestOptions + +ADD_SCHEMA_PROPERTIES = {"a", "b"} + + +def _build_app(json_response: bool) -> Any: + if MCP_V2: + from mcp.server.mcpserver import MCPServer + + server: Any = MCPServer("metorial-test") + else: + from mcp.server.fastmcp import FastMCP + + server = FastMCP("metorial-test", json_response=json_response) + + @server.tool(description="Add two integers") + def add(a: int, b: int) -> int: + return a + b + + @server.tool(description="Always fails") + def explode() -> str: + raise ValueError("kaboom") + + @server.tool(description="Sleeps before answering") + async def slow(seconds: float) -> str: + await asyncio.sleep(seconds) + return "done" + + @server.resource("config://app", description="Static config") + def config() -> str: + return "config-body" + + @server.resource("note://{name}", description="A note by name") + def note(name: str) -> str: + return f"note:{name}" + + @server.prompt(description="Greets someone") + def greet(name: str) -> str: + return f"Hello {name}" + + if MCP_V2: + return server.streamable_http_app(json_response=json_response) + return server.streamable_http_app() + + +def _free_port() -> int: + with socket.socket() as sock: + sock.bind(("127.0.0.1", 0)) + return int(sock.getsockname()[1]) + + +@pytest.fixture(scope="module", params=["sse", "json"]) +def server_url(request: pytest.FixtureRequest) -> Iterator[str]: + port = _free_port() + config = uvicorn.Config( + _build_app(json_response=request.param == "json"), + host="127.0.0.1", + port=port, + log_level="error", + ) + server = uvicorn.Server(config) + thread = threading.Thread(target=server.run, daemon=True) + thread.start() + + deadline = time.monotonic() + 10 + while not server.started: + if time.monotonic() > deadline: + raise RuntimeError("MCP test server did not start") + time.sleep(0.02) + + yield f"http://127.0.0.1:{port}/mcp" + + server.should_exit = True + thread.join(timeout=10) + + +async def _connect(url: str, **kwargs: Any) -> MetorialMcpClient: + return await MetorialMcpClient.from_url(url, use_http_stream=True, **kwargs) + + +async def test_handshake_and_capabilities(server_url: str) -> None: + async with await _connect(server_url) as client: + caps = client.get_server_capabilities() + assert get_field(caps, "tools") is not None + assert get_field(caps, "resources") is not None + assert get_field(caps, "prompts") is not None + + +async def test_list_tools_exposes_input_schema(server_url: str) -> None: + async with await _connect(server_url) as client: + result = await client.list_tools() + + tools = {tool.name: tool for tool in get_field(result, "tools")} + assert set(tools) == {"add", "explode", "slow"} + + schema = get_field(tools["add"], "inputSchema") + assert schema["type"] == "object" + assert set(schema["properties"]) == ADD_SCHEMA_PROPERTIES + + +async def test_call_tool_result_serializes_to_wire_format(server_url: str) -> None: + async with await _connect(server_url) as client: + result = await client.call_tool({"name": "add", "arguments": {"a": 2, "b": 3}}) + + payload = normalize_tool_result(result) + assert payload["isError"] is False + assert payload["content"][0] == {"type": "text", "text": "5"} + assert "is_error" not in payload + assert "structured_content" not in payload + assert json.loads(serialize_tool_result(result)) == payload + + +async def test_failing_tool_reports_error_result(server_url: str) -> None: + async with await _connect(server_url) as client: + result = await client.call_tool({"name": "explode", "arguments": {}}) + + payload = normalize_tool_result(result) + text = payload["content"][0]["text"] + assert payload["isError"] is True + assert "explode" in text or "kaboom" in text + + +async def test_read_timeout_is_enforced(server_url: str) -> None: + async with await _connect(server_url, read_timeout=0.5) as client: + started = time.monotonic() + with pytest.raises(Exception, match="(?i)tim"): + await client.call_tool({"name": "slow", "arguments": {"seconds": 5}}) + assert time.monotonic() - started < 4 + + result = await client.call_tool({"name": "add", "arguments": {"a": 1, "b": 1}}) + assert normalize_tool_result(result)["content"][0]["text"] == "2" + + +async def test_per_request_timeout_option(server_url: str) -> None: + async with await _connect(server_url) as client: + with pytest.raises(asyncio.TimeoutError): + await client.list_tools(options=RequestOptions(timeout=0.000001)) + + +async def test_resources(server_url: str) -> None: + async with await _connect(server_url) as client: + resources = await client.list_resources() + templates = await client.list_resource_templates() + static = await client.read_resource({"uri": "config://app"}) + templated = await client.read_resource({"uri": "note://alpha"}) + + assert [str(get_field(r, "uri")) for r in get_field(resources, "resources")] == [ + "config://app" + ] + assert [ + get_field(t, "uriTemplate") for t in get_field(templates, "resourceTemplates") + ] == ["note://{name}"] + assert normalize_tool_result(static)["contents"][0]["text"] == "config-body" + assert normalize_tool_result(templated)["contents"][0]["text"] == "note:alpha" + + +async def test_prompts(server_url: str) -> None: + async with await _connect(server_url) as client: + prompts = await client.list_prompts() + prompt = await client.get_prompt({"name": "greet", "arguments": {"name": "Ada"}}) + + assert [p.name for p in get_field(prompts, "prompts")] == ["greet"] + message = normalize_tool_result(prompt)["messages"][0] + assert message["content"]["text"] == "Hello Ada" + + +async def test_close_is_idempotent_and_blocks_further_use(server_url: str) -> None: + client = await _connect(server_url) + await client.close() + await client.close() + + with pytest.raises(RuntimeError, match="closed"): + await client.list_tools() + + +class _FakeMagnetarSessions: + def __init__(self, connection_url: str) -> None: + self._connection_url = connection_url + + def create(self, **kwargs: Any) -> dict[str, Any]: + return { + "id": "ses_test", + "connection_url": self._connection_url, + "provider_deployments": [{"id": "dep_test"}], + } + + +class _FakeMagnetarSDK: + def __init__(self, connection_url: str) -> None: + self._config = {"apiKey": "test-key", "apiHost": "http://127.0.0.1"} + self.magnetar_sessions = _FakeMagnetarSessions(connection_url) + + +async def test_magnetar_session_tool_discovery_and_execution(server_url: str) -> None: + session = MetorialMagnetarMcpSession( + _FakeMagnetarSDK(server_url), # type: ignore[arg-type] + {"providers": ["dep_test"]}, + ) + try: + manager = await session.get_tool_manager() + + add = manager.get_tool("add") + assert add is not None + assert set(add.parameters["properties"]) == ADD_SCHEMA_PROPERTIES + + note = manager.get_tool("note") + assert note is not None + assert note.parameters["required"] == ["name"] + + result = await manager.call_tool("add", {"a": 20, "b": 22}) + assert normalize_tool_result(result)["content"][0]["text"] == "42" + + resource = await manager.call_tool("note", {"name": "beta"}) + assert normalize_tool_result(resource)["contents"][0]["text"] == "note:beta" + finally: + await session.close() diff --git a/tests/test_mcp_transport.py b/tests/test_mcp_transport.py new file mode 100644 index 00000000..49ea3e3b --- /dev/null +++ b/tests/test_mcp_transport.py @@ -0,0 +1,246 @@ +from __future__ import annotations + +import json +from collections.abc import AsyncIterator, Callable +from types import SimpleNamespace +from typing import Any + +import httpx +import pytest +from mcp.shared.message import SessionMessage +from mcp.types import JSONRPCError, JSONRPCResponse + +from metorial.mcp._compat import parse_jsonrpc_message, unwrap_jsonrpc_message +from metorial.mcp.transport import POST_FAILED_ERROR_CODE, MetorialMcpTransport + +URL = "http://mcp.test/mcp" + +Handler = Callable[[httpx.Request], httpx.Response] + + +def _request(id_: int, method: str, params: dict[str, Any] | None = None) -> Any: + payload: dict[str, Any] = {"jsonrpc": "2.0", "id": id_, "method": method} + if params is not None: + payload["params"] = params + return parse_jsonrpc_message(payload) + + +def _notification(method: str) -> Any: + return parse_jsonrpc_message({"jsonrpc": "2.0", "method": method}) + + +def _json(body: Any, **headers: str) -> httpx.Response: + return httpx.Response( + 200, + content=json.dumps(body).encode(), + headers={"content-type": "application/json", **headers}, + ) + + +class _Recorder: + def __init__(self, handler: Handler) -> None: + self.requests: list[httpx.Request] = [] + self._handler = handler + + def __call__(self, request: httpx.Request) -> httpx.Response: + self.requests.append(request) + return self._handler(request) + + +@pytest.fixture +async def make_transport() -> AsyncIterator[ + Callable[[Handler], tuple[MetorialMcpTransport, _Recorder]] +]: + transports: list[MetorialMcpTransport] = [] + + def factory(handler: Handler) -> tuple[MetorialMcpTransport, _Recorder]: + recorder = _Recorder(handler) + client = httpx.AsyncClient(transport=httpx.MockTransport(recorder)) + transport = MetorialMcpTransport(URL, client=client, headers={"x-api": "k"}) + transports.append(transport) + return transport, recorder + + yield factory + + for transport in transports: + await transport.close() + + +async def _roundtrip(transport: MetorialMcpTransport, message: Any) -> Any: + read, write = await transport.open() + await write.send(SessionMessage(message)) + received = await read.receive() + assert isinstance(received, SessionMessage) + return unwrap_jsonrpc_message(received.message) + + +async def test_session_and_protocol_headers_follow_initialize(make_transport) -> None: + def handler(request: httpx.Request) -> httpx.Response: + body = json.loads(request.content) + if body["method"] == "initialize": + return _json( + { + "jsonrpc": "2.0", + "id": body["id"], + "result": { + "protocolVersion": "2025-06-18", + "capabilities": {}, + "serverInfo": {"name": "s", "version": "1"}, + }, + }, + **{"mcp-session-id": "sess-123"}, + ) + return _json({"jsonrpc": "2.0", "id": body["id"], "result": {"tools": []}}) + + transport, recorder = make_transport(handler) + + init = await _roundtrip(transport, _request(1, "initialize", {})) + assert isinstance(init, JSONRPCResponse) + listed = await _roundtrip(transport, _request(2, "tools/list")) + assert isinstance(listed, JSONRPCResponse) + + first, second = recorder.requests + assert first.headers["x-api"] == "k" + assert "mcp-session-id" not in first.headers + assert second.headers["mcp-session-id"] == "sess-123" + assert second.headers["mcp-protocol-version"] == "2025-06-18" + assert json.loads(second.content) == { + "jsonrpc": "2.0", + "id": 2, + "method": "tools/list", + } + + +async def test_per_message_headers_are_forwarded(make_transport) -> None: + transport, recorder = make_transport( + lambda request: _json( + {"jsonrpc": "2.0", "id": json.loads(request.content)["id"], "result": {}} + ) + ) + read, write = await transport.open() + + metadata = SimpleNamespace(headers={"mcp-method": "tools/list"}) + await write.send(SessionMessage(_request(1, "tools/list"), metadata=metadata)) # type: ignore[arg-type] + await read.receive() + + assert recorder.requests[0].headers["mcp-method"] == "tools/list" + + +async def test_sse_response_is_parsed(make_transport) -> None: + def handler(request: httpx.Request) -> httpx.Response: + request_id = json.loads(request.content)["id"] + progress = {"jsonrpc": "2.0", "method": "notifications/message", "params": {}} + result = {"jsonrpc": "2.0", "id": request_id, "result": {"ok": True}} + body = ( + f"event: message\ndata: {json.dumps(progress)}\n\n" + f"event: message\ndata: {json.dumps(result)}\n\n" + ) + return httpx.Response( + 200, content=body.encode(), headers={"content-type": "text/event-stream"} + ) + + transport, _ = make_transport(handler) + read, write = await transport.open() + await write.send(SessionMessage(_request(7, "tools/call", {"name": "x"}))) + + first = unwrap_jsonrpc_message((await read.receive()).message) # type: ignore[union-attr] + second = unwrap_jsonrpc_message((await read.receive()).message) # type: ignore[union-attr] + assert first.method == "notifications/message" + assert isinstance(second, JSONRPCResponse) + assert second.result == {"ok": True} + + +async def test_batched_json_response(make_transport) -> None: + transport, _ = make_transport( + lambda request: _json( + [ + {"jsonrpc": "2.0", "method": "notifications/message", "params": {}}, + {"jsonrpc": "2.0", "id": 3, "result": {}}, + ] + ) + ) + read, write = await transport.open() + await write.send(SessionMessage(_request(3, "ping"))) + + first = unwrap_jsonrpc_message((await read.receive()).message) # type: ignore[union-attr] + second = unwrap_jsonrpc_message((await read.receive()).message) # type: ignore[union-attr] + assert first.method == "notifications/message" + assert isinstance(second, JSONRPCResponse) + + +async def test_failed_request_becomes_error_and_transport_survives( + make_transport, +) -> None: + def handler(request: httpx.Request) -> httpx.Response: + body = json.loads(request.content) + if body["method"] == "tools/call": + return httpx.Response(500, content=b"boom") + return _json({"jsonrpc": "2.0", "id": body["id"], "result": {}}) + + transport, _ = make_transport(handler) + + failed = await _roundtrip(transport, _request(1, "tools/call", {"name": "x"})) + assert isinstance(failed, JSONRPCError) + assert failed.id == 1 + assert failed.error.code == POST_FAILED_ERROR_CODE + assert "500" in failed.error.message + + recovered = await _roundtrip(transport, _request(2, "ping")) + assert isinstance(recovered, JSONRPCResponse) + + +async def test_failed_notification_surfaces_exception(make_transport) -> None: + def handler(request: httpx.Request) -> httpx.Response: + body = json.loads(request.content) + if "id" not in body: + raise httpx.ConnectError("down") + return _json({"jsonrpc": "2.0", "id": body["id"], "result": {}}) + + transport, _ = make_transport(handler) + read, write = await transport.open() + + await write.send(SessionMessage(_notification("notifications/initialized"))) + assert isinstance(await read.receive(), httpx.ConnectError) + + await write.send(SessionMessage(_request(2, "ping"))) + received = await read.receive() + assert isinstance(received, SessionMessage) + assert isinstance(unwrap_jsonrpc_message(received.message), JSONRPCResponse) + + +async def test_accepted_notification_produces_no_message(make_transport) -> None: + def handler(request: httpx.Request) -> httpx.Response: + body = json.loads(request.content) + if "id" not in body: + return httpx.Response(202) + return _json({"jsonrpc": "2.0", "id": body["id"], "result": {}}) + + transport, recorder = make_transport(handler) + read, write = await transport.open() + + await write.send(SessionMessage(_notification("notifications/initialized"))) + await write.send(SessionMessage(_request(4, "ping"))) + received = await read.receive() + + assert isinstance(received, SessionMessage) + assert unwrap_jsonrpc_message(received.message).id == 4 + assert len(recorder.requests) == 2 + + +async def test_close_terminates_session(make_transport) -> None: + def handler(request: httpx.Request) -> httpx.Response: + if request.method == "DELETE": + return httpx.Response(204) + body = json.loads(request.content) + return _json( + {"jsonrpc": "2.0", "id": body["id"], "result": {}}, + **{"mcp-session-id": "sess-9"}, + ) + + transport, recorder = make_transport(handler) + await _roundtrip(transport, _request(1, "ping")) + await transport.close() + + delete = recorder.requests[-1] + assert delete.method == "DELETE" + assert delete.headers["mcp-session-id"] == "sess-9"