"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
fix(mcp): harden result serialization errors
Haozhe Wu22bfd087a744
diff --git a/agent/src/tools/mcp.py b/agent/src/tools/mcp.pyindex 3506b3ead..78ea20acc 100644--- a/agent/src/tools/mcp.py+++ b/agent/src/tools/mcp.py@@ -9,9 +9,9 @@ import loggingimport osimport reimport threading+from collections.abc import Mappingfrom copy import deepcopy-from dataclasses import dataclass, fields, is_dataclass-from datetime import date, datetime+from dataclasses import dataclass, is_dataclassfrom typing import Any, Awaitable, Callable, Coroutine, Iterable, Protocol, TypeVarfrom fastmcp.client import Client@@ -30,6 +30,7 @@ except ModuleNotFoundError:from fastmcp.exceptions import McpError, ToolErrorfrom key_value.aio.stores.filetree import FileTreeStore, FileTreeV1KeySanitizationStrategyfrom mcp import types as mcp_types+from pydantic_core import PydanticSerializationError, to_jsonable_pythonfrom src.agent.tools import BaseToolfrom 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.pyindex c745d23e8..a9c9493cd 100644--- a/agent/tests/test_mcp_client_adapter.py+++ b/agent/tests/test_mcp_client_adapter.py@@ -6,12 +6,18 @@ import jsonimport loggingfrom dataclasses import dataclassfrom datetime import date, datetime, timezone+from decimal import Decimal+from enum import Enum+from pathlib import Pathfrom typing import Any+from uuid import UUIDimport pytest+from fastmcp import Client, FastMCPfrom fastmcp.client.client import CallToolResultfrom fastmcp.exceptions import McpError, ToolErrorfrom mcp import types as mcp_types+from pydantic import BaseModel, field_serializerfrom src.config.schema import MCPServerConfigfrom 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 = {