Skip to content

"Vibe-Trading: Your Personal Trading Agent"

fix(mcp): harden result serialization errors

Haozhe Wu22bfd087a744
diff --git a/agent/src/tools/mcp.py b/agent/src/tools/mcp.py
index 3506b3ead..78ea20acc 100644
--- a/agent/src/tools/mcp.py
+++ b/agent/src/tools/mcp.py
@@ -9,9 +9,9 @@ import logging
import os
import re
import threading
+from collections.abc import Mapping
from copy import deepcopy
-from dataclasses import dataclass, fields, is_dataclass
-from datetime import date, datetime
+from dataclasses import dataclass, is_dataclass
from typing import Any, Awaitable, Callable, Coroutine, Iterable, Protocol, TypeVar
from fastmcp.client import Client
@@ -30,6 +30,7 @@ except ModuleNotFoundError:
from fastmcp.exceptions import McpError, ToolError
from key_value.aio.stores.filetree import FileTreeStore, FileTreeV1KeySanitizationStrategy
from mcp import types as mcp_types
+from pydantic_core import PydanticSerializationError, to_jsonable_python
from src.agent.tools import BaseTool
from src.config.schema import (
@@ -970,10 +971,21 @@ def _normalize_call_tool_result(result: CallToolResult) -> dict[str, Any]:
}
payload: dict[str, Any] = {"status": "ok"}
- if result.data is not None:
- payload["data"] = _make_jsonable(result.data)
if result.structured_content is not None:
- payload["structured_content"] = _make_jsonable(result.structured_content)
+ # ``structured_content`` is the canonical JSON value received over
+ # MCP. FastMCP's ``data`` is a convenience view hydrated from that
+ # value into dataclasses, datetime objects, UUIDs, and other Python
+ # types. Prefer the wire value whenever hydration made ``data`` cease
+ # to be natively JSON-serializable; serializing the hydrated copy is
+ # both redundant and the source of #922's false circular-reference
+ # failure.
+ structured = result.structured_content
+ payload["data"] = _select_result_data(result, structured)
+ payload["structured_content"] = structured
+ elif result.data is not None:
+ # Compatibility fallback for injected/legacy clients that provide a
+ # parsed value without standard MCP structured content.
+ payload["data"] = _make_jsonable(result.data)
if result.content:
payload["content"] = [_make_jsonable(block) for block in result.content]
text = _extract_text_content(result.content)
@@ -982,6 +994,54 @@ def _normalize_call_tool_result(result: CallToolResult) -> dict[str, Any]:
return payload
+def _select_result_data(result: CallToolResult, structured: dict[str, Any]) -> Any:
+ """Choose a JSON-safe local ``data`` view for a structured MCP result.
+
+ FastMCP unwraps primitive return values from ``{"result": value}`` and
+ exposes the unwrapped value through ``CallToolResult.data``. Mirror only
+ that wire-format convention; otherwise use the canonical structured JSON
+ instead of re-serializing FastMCP's hydrated Python copy.
+
+ Args:
+ result: Parsed FastMCP result.
+ structured: Canonical structured JSON received over MCP.
+
+ Returns:
+ JSON-compatible value for the local ``data`` field.
+ """
+ if _is_wrapped_fastmcp_result(result, structured):
+ return structured["result"]
+
+ return structured
+
+
+def _is_wrapped_fastmcp_result(
+ result: CallToolResult,
+ structured: dict[str, Any],
+) -> bool:
+ """Detect FastMCP's wrapper for non-object tool return values.
+
+ Modern FastMCP marks the wrapper in result metadata. FastMCP 2.14, the
+ project's minimum supported version, only exposed the marker through the
+ output schema. The narrow fallback below handles its hydrated non-object
+ values without mistaking an ordinary object-schema dataclass for a wrapper.
+ """
+ if set(structured) != {"result"}:
+ return False
+
+ fastmcp_meta = (result.meta or {}).get("fastmcp")
+ if isinstance(fastmcp_meta, dict) and fastmcp_meta.get("wrap_result") is True:
+ return True
+
+ data = result.data
+ return (
+ data is not None
+ and not isinstance(data, Mapping)
+ and not (is_dataclass(data) and not isinstance(data, type))
+ and not callable(getattr(data, "model_dump", None))
+ )
+
+
def _extract_result_error(result: CallToolResult) -> str:
"""Extract a readable error message from a failed MCP result.
@@ -1073,35 +1133,35 @@ def _format_exception_message(exc: Exception) -> str:
def _make_jsonable(value: Any) -> Any:
- """Convert FastMCP response payloads into JSON-serializable objects.
-
- ``fastmcp``'s client auto-types ``CallToolResult.data`` from a tool's
- output schema via ``json_schema_to_type``, which produces a plain
- ``dataclasses`` instance (not a Pydantic ``BaseModel``) for any object
- schema that doesn't set ``additionalProperties: true`` -- the common
- case. Without a dedicated branch here, such an instance falls through
- to the final ``return value`` unconverted; ``json.dumps``'s ``default``
- then receives the same unconvertible object back and raises
- ``ValueError: Circular reference detected``, since its cycle detector
- can't distinguish "default() gave up" from an actual cycle.
+ """Convert a fallback MCP value with Pydantic's JSON serializer.
+
+ FastMCP uses the same public ``pydantic_core`` primitive when producing
+ structured tool results. Normal structured responses bypass this helper;
+ it exists for content blocks and legacy/data-only client results.
Args:
value: Arbitrary response value.
Returns:
JSON-serializable equivalent.
+
+ Raises:
+ TypeError: If the value is cyclic or unsupported. The error reports
+ only type names, never the value or the underlying exception text.
"""
- if hasattr(value, "model_dump"):
- return value.model_dump(mode="json", by_alias=True, exclude_none=True)
- if is_dataclass(value) and not isinstance(value, type):
- return {field.name: _make_jsonable(getattr(value, field.name)) for field in fields(value)}
- if isinstance(value, (datetime, date)):
- return value.isoformat()
- if isinstance(value, list):
- return [_make_jsonable(item) for item in value]
- if isinstance(value, dict):
- return {str(key): _make_jsonable(item) for key, item in value.items()}
- return value
+ try:
+ return to_jsonable_python(value, by_alias=True, exclude_none=True)
+ except (PydanticSerializationError, TypeError, ValueError, UnicodeDecodeError) as exc:
+ raise TypeError(
+ f"Unable to serialize MCP result type {_qualified_type_name(value)}: "
+ f"{type(exc).__name__}"
+ ) from None
+
+
+def _qualified_type_name(value: Any) -> str:
+ """Return a stable type name without calling the value's representation."""
+ value_type = type(value)
+ return f"{value_type.__module__}.{value_type.__qualname__}"
def _json_default(value: Any) -> Any:
@@ -1112,6 +1172,9 @@ def _json_default(value: Any) -> Any:
Returns:
JSON-serializable representation.
+
+ Raises:
+ TypeError: If the value has no safe serialization contract.
"""
return _make_jsonable(value)
diff --git a/agent/tests/test_mcp_client_adapter.py b/agent/tests/test_mcp_client_adapter.py
index c745d23e8..a9c9493cd 100644
--- a/agent/tests/test_mcp_client_adapter.py
+++ b/agent/tests/test_mcp_client_adapter.py
@@ -6,12 +6,18 @@ import json
import logging
from dataclasses import dataclass
from datetime import date, datetime, timezone
+from decimal import Decimal
+from enum import Enum
+from pathlib import Path
from typing import Any
+from uuid import UUID
import pytest
+from fastmcp import Client, FastMCP
from fastmcp.client.client import CallToolResult
from fastmcp.exceptions import McpError, ToolError
from mcp import types as mcp_types
+from pydantic import BaseModel, field_serializer
from src.config.schema import MCPServerConfig
from src.tools.mcp import (
@@ -299,51 +305,62 @@ class _RobinhoodPortfolio:
market_dates: dict[str, date]
-def test_robinhood_dataclass_dates_are_json_safe_end_to_end() -> None:
- """Generated dataclasses must not raise the false circular-reference error (#922)."""
- portfolio = _RobinhoodPortfolio(
- account_number="RH-123",
- buying_power=2500.75,
- positions=[
- _RobinhoodPosition(
- symbol="AAPL",
- quantity=3.5,
- opened_on=date(2026, 7, 31),
- updated_at=datetime(2026, 8, 1, 7, 30, tzinfo=timezone.utc),
- )
- ],
- market_dates={"next_open": date(2026, 8, 3)},
- )
+def _execute_data_result(
+ data: Any,
+ *,
+ structured_content: dict[str, Any] | None = None,
+ meta: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+ """Execute one fake MCP tool with a parsed FastMCP result."""
state = {
"list_calls": 0,
"call_calls": 0,
"call_records": [],
"list_outcomes": [[
mcp_types.Tool(
- name="get_portfolio",
- description="Read the Robinhood portfolio",
+ name="get_data",
+ description="Return test data",
inputSchema={"type": "object", "properties": {}},
)
]],
"call_outcomes": [
CallToolResult(
content=[],
- structured_content=None,
- meta=None,
- data=portfolio,
+ structured_content=structured_content,
+ meta=meta,
+ data=data,
)
],
}
-
tool = build_mcp_tool_wrappers(
- "robinhood",
- _make_config(enabled_tools=["get_portfolio"]),
+ "demo",
+ _make_config(enabled_tools=["get_data"]),
client_factory=_make_factory(state),
)[0]
- payload = json.loads(tool.execute())
+ return json.loads(tool.execute())
- assert payload["status"] == "ok"
- assert payload["data"] == {
+
+def test_robinhood_dataclass_dates_are_json_safe_end_to_end() -> None:
+ """A real FastMCP dataclass round trip must stay JSON-safe (#922)."""
+ server = FastMCP("robinhood-regression")
+
+ @server.tool
+ def get_portfolio() -> _RobinhoodPortfolio:
+ return _RobinhoodPortfolio(
+ account_number="RH-123",
+ buying_power=2500.75,
+ positions=[
+ _RobinhoodPosition(
+ symbol="AAPL",
+ quantity=3.5,
+ opened_on=date(2026, 7, 31),
+ updated_at=datetime(2026, 8, 1, 7, 30, tzinfo=timezone.utc),
+ )
+ ],
+ market_dates={"next_open": date(2026, 8, 3)},
+ )
+
+ structured_portfolio = {
"account_number": "RH-123",
"buying_power": 2500.75,
"positions": [
@@ -351,12 +368,165 @@ def test_robinhood_dataclass_dates_are_json_safe_end_to_end() -> None:
"symbol": "AAPL",
"quantity": 3.5,
"opened_on": "2026-07-31",
- "updated_at": "2026-08-01T07:30:00+00:00",
+ "updated_at": "2026-08-01T07:30:00Z",
}
],
"market_dates": {"next_open": "2026-08-03"},
}
+ tool = build_mcp_tool_wrappers(
+ "robinhood",
+ _make_config(enabled_tools=["get_portfolio"]),
+ client_factory=lambda: Client(server),
+ )[0]
+ payload = json.loads(tool.execute())
+
+ assert payload["status"] == "ok"
+ assert payload["data"] == structured_portfolio
+ assert payload["structured_content"] == structured_portfolio
+
+
+ ("data", "structured", "meta", "expected"),
+ [
+ (8, {"result": 8}, None, 8),
+ (
+ date(2026, 8, 3),
+ {"result": "2026-08-03"},
+ {"fastmcp": {"wrap_result": True}},
+ "2026-08-03",
+ ),
+ (
+ [date(2026, 8, 3)],
+ {"result": ["2026-08-03"]},
+ None,
+ ["2026-08-03"],
+ ),
+ ],
+)
+def test_fastmcp_wrapped_results_keep_unwrapped_data_shape(
+ data: Any,
+ structured: dict[str, Any],
+ meta: dict[str, Any] | None,
+ expected: Any,
+) -> None:
+ """Keep FastMCP's primitive unwrapping across supported versions."""
+ payload = _execute_data_result(
+ data,
+ structured_content=structured,
+ meta=meta,
+ )
+
+ assert payload["data"] == expected
+ assert payload["structured_content"] == structured
+
+
+@dataclass
+class _SingleResultObject:
+ result: date
+
+
+def test_single_result_object_schema_is_not_mistaken_for_fastmcp_wrapper() -> None:
+ structured = {"result": "2026-08-03"}
+
+ payload = _execute_data_result(
+ _SingleResultObject(result=date(2026, 8, 3)),
+ structured_content=structured,
+ )
+
+ assert payload["data"] == structured
+
+
+def test_structured_content_remains_available_when_fastmcp_hydration_fails() -> None:
+ structured = {"account_number": "RH-123", "buying_power": 2500.75}
+
+ payload = _execute_data_result(None, structured_content=structured)
+
+ assert payload["status"] == "ok"
+ assert payload["data"] == structured
+ assert payload["structured_content"] == structured
+
+
+class _OrderState(Enum):
+ OPEN = "open"
+
+
+@dataclass
+class _StandardJsonAdapters:
+ amount: Decimal
+ order_id: UUID
+ output_path: Path
+ state: _OrderState
+ labels: set[str]
+ range_pair: tuple[int, int]
+
+
+def test_data_only_fallback_uses_pydantic_json_serialization() -> None:
+ payload = _execute_data_result(
+ _StandardJsonAdapters(
+ amount=Decimal("1234.5600"),
+ order_id=UUID("12345678-1234-5678-1234-567812345678"),
+ output_path=Path("reports/daily.json"),
+ state=_OrderState.OPEN,
+ labels={"beta", "alpha"},
+ range_pair=(1, 5),
+ )
+ )
+
+ assert payload["status"] == "ok"
+ assert set(payload["data"].pop("labels")) == {"alpha", "beta"}
+ assert payload["data"] == {
+ "amount": "1234.5600",
+ "order_id": "12345678-1234-5678-1234-567812345678",
+ "output_path": "reports/daily.json",
+ "state": "open",
+ "range_pair": [1, 5],
+ }
+
+
+def test_unsupported_mcp_value_returns_explicit_error_not_false_cycle() -> None:
+ class OpaqueAccountValue:
+ pass
+
+ payload = _execute_data_result(OpaqueAccountValue())
+
+ assert payload["status"] == "error"
+ assert payload["error_type"] == "TypeError"
+ assert "Unable to serialize MCP result type" in payload["error"]
+ assert "OpaqueAccountValue" in payload["error"]
+ assert "Circular reference detected" not in payload["error"]
+
+
+def test_actual_mcp_result_cycle_returns_sanitized_error() -> None:
+ cyclic: list[Any] = []
+ cyclic.append(cyclic)
+
+ payload = _execute_data_result(cyclic)
+
+ assert payload["status"] == "error"
+ assert payload["error_type"] == "TypeError"
+ assert "Unable to serialize MCP result type builtins.list" in payload["error"]
+ assert "ValueError" in payload["error"]
+ assert "Circular reference detected" not in payload["error"]
+
+
+def test_data_only_serialization_failure_does_not_leak_exception_text() -> None:
+ class BrokenAccountValue(BaseModel):
+ account_number: str
+
+ @field_serializer("account_number")
+ def serialize_account_number(self, value: str) -> str:
+ del value
+ raise RuntimeError("api_key=should-never-appear")
+
+ payload = _execute_data_result(BrokenAccountValue(account_number="RH-123"))
+
+ assert payload["status"] == "error"
+ assert payload["error_type"] == "TypeError"
+ assert "Unable to serialize MCP result type" in payload["error"]
+ assert "PydanticSerializationError" in payload["error"]
+ assert "should-never-appear" not in payload["error"]
+
def test_build_mcp_tool_wrappers_disambiguates_colliding_local_names() -> None:
state = {