Building AI agents, atomically
Separate MCP tool result conversion from invocation
Eigenwise710bc12bdf8c
diff --git a/atomic-agents/atomic_agents/connectors/mcp/mcp_factory.py b/atomic-agents/atomic_agents/connectors/mcp/mcp_factory.pyindex e43b6a8..62f4005 100644--- a/atomic-agents/atomic_agents/connectors/mcp/mcp_factory.py+++ b/atomic-agents/atomic_agents/connectors/mcp/mcp_factory.py@@ -1,12 +1,12 @@import asyncioimport jsonimport logging-from typing import Any, Dict, List, Type, Optional, Union, Tuple, cast+from typing import Any, Dict, List, Type, Optional, Union, Tuple, cast, Protocol, Callablefrom contextlib import AsyncExitStackimport shleximport types-from pydantic import create_model, Field, BaseModel+from pydantic import create_model, Field, BaseModel, JsonValuefrom mcp import ClientSession, StdioServerParametersfrom mcp.client.sse import sse_client@@ -52,6 +52,152 @@ class MCPPromptOutputSchema(BaseIOSchema):content: str = Field(..., description="The content of the MCP prompt.")+class _ModelDumpPayload(Protocol):+ model_dump: Callable[[], dict[str, JsonValue]]+++class _TextToolContent(Protocol):+ text: JsonValue | bytes | bytearray+++class _DataToolContent(Protocol):+ data: JsonValue+++_ToolContentItem = BaseModel | JsonValue | _TextToolContent | _DataToolContent+_ToolResult = BaseModel | JsonValue | tuple[object, ...] | list[object]+_ToolContent = BaseModel | JsonValue | tuple[_ToolContentItem, ...] | list[_ToolContentItem]+++class _GeneratedMCPTool(Protocol):+ mcp_tool_name: str+ mcp_endpoint: str | None+ transport_type: MCPTransportType+ output_schema: type[BaseIOSchema]+++def _validate_structured_tool_output(+ structured_data: JsonValue | _ModelDumpPayload, output_schema: type[BaseIOSchema], tool_name: str+) -> BaseIOSchema:+ if isinstance(structured_data, dict):+ return output_schema(**structured_data)+ elif hasattr(structured_data, "model_dump"):+ model_dump: Callable[[], dict[str, JsonValue]] = getattr(structured_data, "model_dump")+ return output_schema(**model_dump())+ logger.error(+ f"Unexpected structuredContent type for tool '{tool_name}': "+ f"got {type(structured_data).__name__}, expected dict or BaseModel. "+ f"Content: {structured_data!r}"+ )+ raise TypeError(+ f"MCP tool '{tool_name}' returned structuredContent with unexpected type "+ f"{type(structured_data).__name__}. Expected dict or BaseModel."+ )+++def _log_invalid_tool_json(text: str | bytes | bytearray, tool_name: str, error: json.JSONDecodeError) -> None:+ logger.debug(+ f"Tool '{tool_name}' content is not valid JSON: {error}. " f"Content preview: {text[:200]!r}..."+ if len(text) > 200+ else f"Content: {text!r}"+ )+++def _validate_json_text_tool_output(+ text: JsonValue | bytes | bytearray, output_schema: type[BaseIOSchema], tool_name: str+) -> BaseIOSchema | None:+ try:+ # Invalid adapter text must keep json.loads' native TypeError and the existing data fallback.+ parsed: JsonValue = json.loads(text) # pyright: ignore[reportArgumentType]+ if isinstance(parsed, dict):+ return output_schema(**parsed)+ logger.debug(+ f"Tool '{tool_name}' content parsed as JSON but was "+ f"{type(parsed).__name__}, not dict. Trying other extraction methods."+ )+ except json.JSONDecodeError as error:+ if isinstance(text, (str, bytes, bytearray)):+ _log_invalid_tool_json(text, tool_name, error)+ except TypeError as error:+ logger.warning(f"Tool '{tool_name}' content.text has unexpected type {type(text).__name__}: {error}")+ return None+++def _validate_tool_content_item(+ content_item: _ToolContentItem, output_schema: type[BaseIOSchema], tool_name: str+) -> BaseIOSchema | None:+ if hasattr(content_item, "text"):+ text: JsonValue | bytes | bytearray = getattr(content_item, "text")+ parsed_output = _validate_json_text_tool_output(text, output_schema, tool_name)+ if parsed_output is not None:+ return parsed_output+ if hasattr(content_item, "data"):+ data: JsonValue = getattr(content_item, "data")+ if isinstance(data, dict):+ return output_schema(**data)+ return None+++def _validate_tool_content_output(+ content: _ToolContent, output_schema: type[BaseIOSchema], tool_name: str+) -> BaseIOSchema | None:+ if content and isinstance(content, (list, tuple)) and len(content) > 0:+ return _validate_tool_content_item(content[0], output_schema, tool_name)+ return None+++def _validate_model_tool_output(+ tool_result: BaseModel, output_schema: type[BaseIOSchema], tool_name: str+) -> BaseIOSchema | None:+ if hasattr(tool_result, "structuredContent"):+ structured_data: JsonValue | _ModelDumpPayload = getattr(tool_result, "structuredContent")+ return _validate_structured_tool_output(structured_data, output_schema, tool_name)+ elif hasattr(tool_result, "content"):+ content: _ToolContent = getattr(tool_result, "content")+ return _validate_tool_content_output(content, output_schema, tool_name)+ return None+++def _validate_mapping_tool_output(tool_result: dict[str, JsonValue], output_schema: type[BaseIOSchema]) -> BaseIOSchema:+ if "structuredContent" in tool_result:+ # Malformed mapping payloads must keep the constructor's native keyword-unpacking TypeError.+ return output_schema(**tool_result["structuredContent"]) # pyright: ignore[reportCallIssue]+ elif "content" in tool_result:+ content = tool_result["content"]+ if isinstance(content, dict):+ return output_schema(**content)+ return output_schema(**tool_result)+++def _validate_typed_tool_output(tool_result: _ToolResult, output_schema: type[BaseIOSchema], tool_name: str) -> BaseIOSchema:+ if isinstance(tool_result, BaseModel):+ parsed_output = _validate_model_tool_output(tool_result, output_schema, tool_name)+ if parsed_output is not None:+ return parsed_output+ elif isinstance(tool_result, dict):+ return _validate_mapping_tool_output(tool_result, output_schema)+ logger.error(+ f"Could not parse structured output for tool '{tool_name}'. "+ f"Expected typed output but got: type={type(tool_result).__name__}, "+ f"value={tool_result!r}"+ )+ raise ValueError(+ f"MCP tool '{tool_name}' has outputSchema but returned unparseable result. "+ f"Received type: {type(tool_result).__name__}. Check MCP server implementation."+ )+++def _render_generic_tool_output(tool_result: _ToolResult, output_schema: type[BaseIOSchema]) -> BaseIOSchema:+ content: _ToolContent | _ToolResult+ if isinstance(tool_result, BaseModel) and hasattr(tool_result, "content"):+ content = getattr(tool_result, "content")+ elif isinstance(tool_result, dict) and "content" in tool_result:+ content = tool_result["content"]+ else:+ content = tool_result+ return output_schema(**{"result": content})++class MCPFactory:"""Factory for creating MCP tool classes."""@@ -171,7 +317,7 @@ class MCPFactory:)# Async implementation- async def run_tool_async(self, params: InputSchema) -> OutputSchema: # type: ignore+ async def run_tool_async(self: _GeneratedMCPTool, params: BaseIOSchema) -> BaseIOSchema:bound_tool_name = self.mcp_tool_namebound_mcp_endpoint = self.mcp_endpoint # May be None when using external sessionbound_transport_type = self.transport_type@@ -239,106 +385,14 @@ class MCPFactory:# Legacy behaviour – open a fresh connection per invocation.tool_result = await _connect_and_call()- # Process the result based on whether we have a typed output schema.- # Extraction precedence for typed schemas:- # 1. structuredContent attribute (MCP spec primary path)- # 2. content[0].text parsed as JSON (some servers return JSON as text)- # 3. content[0].data dict (structured data in content item)- # 4. Dict with structuredContent/content keys- # 5. Direct dict usage as fallback- has_typed_schema = getattr(self, "_has_typed_output_schema", False)- BoundOutputSchema = self.output_schema-- if has_typed_schema:- # For typed output schemas, try to extract structured content- # MCP tools with output schemas return structured data- if isinstance(tool_result, BaseModel) and hasattr(tool_result, "structuredContent"):- # Use structured content if available (MCP spec)- structured_data = tool_result.structuredContent- if isinstance(structured_data, dict):- return BoundOutputSchema(**structured_data)- elif hasattr(structured_data, "model_dump"):- return BoundOutputSchema(**structured_data.model_dump())- else:- # Unexpected type for structuredContent- logger.error(- f"Unexpected structuredContent type for tool '{bound_tool_name}': "- f"got {type(structured_data).__name__}, expected dict or BaseModel. "- f"Content: {structured_data!r}"- )- raise TypeError(- f"MCP tool '{bound_tool_name}' returned structuredContent with unexpected type "- f"{type(structured_data).__name__}. Expected dict or BaseModel."- )- elif isinstance(tool_result, BaseModel) and hasattr(tool_result, "content"):- # Try to parse content as structured data- content = tool_result.content- # Ensure content is a list/tuple before indexing- if content and isinstance(content, (list, tuple)) and len(content) > 0:- first_content = content[0]- # Check for text content that might be JSON- if hasattr(first_content, "text"):- try:- parsed = json.loads(first_content.text)- if isinstance(parsed, dict):- return BoundOutputSchema(**parsed)- else:- logger.debug(- f"Tool '{bound_tool_name}' content parsed as JSON but was "- f"{type(parsed).__name__}, not dict. Trying other extraction methods."- )- except json.JSONDecodeError as e:- logger.debug(- f"Tool '{bound_tool_name}' content is not valid JSON: {e}. "- f"Content preview: {first_content.text[:200]!r}..."- if len(first_content.text) > 200- else f"Content: {first_content.text!r}"- )- except TypeError as e:- logger.warning(- f"Tool '{bound_tool_name}' content.text has unexpected type "- f"{type(first_content.text).__name__}: {e}"- )- # Check for structured content in the content item- if hasattr(first_content, "data") and isinstance(first_content.data, dict):- return BoundOutputSchema(**first_content.data)- elif isinstance(tool_result, dict):- if "structuredContent" in tool_result:- return BoundOutputSchema(**tool_result["structuredContent"])- elif "content" in tool_result:- content = tool_result["content"]- if isinstance(content, dict):- return BoundOutputSchema(**content)- # Fallback: try to use tool_result directly if it's a dict- if isinstance(tool_result, dict):- return BoundOutputSchema(**tool_result)- # If we have a typed schema but couldn't extract structured content,- # this is an error - we cannot fall through to generic handling- # because the typed schema doesn't have a 'result' field.- logger.error(- f"Could not parse structured output for tool '{bound_tool_name}'. "- f"Expected typed output but got: type={type(tool_result).__name__}, "- f"value={tool_result!r}"- )- raise ValueError(- f"MCP tool '{bound_tool_name}' has outputSchema but returned unparseable result. "- f"Received type: {type(tool_result).__name__}. "- f"Check MCP server implementation."- )-- # Generic output schema handling (original behavior) - only for tools without typed schemas- if isinstance(tool_result, BaseModel) and hasattr(tool_result, "content"):- actual_result_content = tool_result.content- elif isinstance(tool_result, dict) and "content" in tool_result:- actual_result_content = tool_result["content"]- else:- actual_result_content = tool_result+ output_schema = self.output_schema+ if getattr(self, "_has_typed_output_schema", False):+ return _validate_typed_tool_output(tool_result, output_schema, bound_tool_name)+ return _render_generic_tool_output(tool_result, output_schema)- return BoundOutputSchema(result=actual_result_content)-- except Exception as e:- logger.error(f"Error executing MCP tool '{bound_tool_name}': {e}", exc_info=True)- raise RuntimeError(f"Failed to execute MCP tool '{bound_tool_name}': {e}") from e+ except Exception as error:+ logger.error(f"Error executing MCP tool '{bound_tool_name}': {error}", exc_info=True)+ raise RuntimeError(f"Failed to execute MCP tool '{bound_tool_name}': {error}") from error# Create sync wrapperdef run_tool_sync(self, params: InputSchema) -> OutputSchema: # type: ignorediff --git a/atomic-agents/tests/connectors/mcp/test_mcp_factory.py b/atomic-agents/tests/connectors/mcp/test_mcp_factory.pyindex 639a60c..b06ded0 100644--- a/atomic-agents/tests/connectors/mcp/test_mcp_factory.py+++ b/atomic-agents/tests/connectors/mcp/test_mcp_factory.py@@ -2888,3 +2888,116 @@ async def test_prompt_agenerate_error_handling(monkeypatch):with pytest.raises(RuntimeError) as exc_info:await agenerate_method(params)assert "Failed to get MCP prompt 'ErrorPrompt'" in str(exc_info.value)+++class StructuredModelResult(BaseModel):+ structuredContent: BaseModel | dict[str, str] | str | None+++class NamedToolPayload(BaseModel):+ name: str+++class TextAndDataContent(BaseModel):+ text: str | int | None+ data: dict[str, str]+++def named_output_tool_session(mocked_mcp_connection: tuple[AsyncMock, dict[str, MagicMock]]) -> AsyncMock:+ session, _ = mocked_mcp_connection+ session.list_tools.return_value.tools[0].outputSchema = {+ "type": "object",+ "properties": {"name": {"type": "string"}},+ "required": ["name"],+ }+ return session+++ "tool_result,expected_name",+ [+ (CallToolResult(content=[TextContent(type="text", text='{"name":"text"}')], structuredContent={"name": "sdk"}), "sdk"),+ (StructuredModelResult(structuredContent=NamedToolPayload(name="model")), "model"),+ (+ MockContentResult(content=[MockContentItem(text='{"name":"first"}'), MockContentItem(text='{"name":"second"}')]),+ "first",+ ),+ (MockContentResult(content=(MockContentItemWithData(data={"name": "tuple"}),)), "tuple"),+ (MockContentResult(content=[TextAndDataContent(text="[]", data={"name": "data"})]), "data"),+ (MockContentResult(content=[TextAndDataContent(text="invalid" * 40, data={"name": "long"})]), "long"),+ (MockContentResult(content=[TextAndDataContent(text="invalid", data={"name": "short"})]), "short"),+ (MockContentResult(content=[TextAndDataContent(text=None, data={"name": "none-text"})]), "none-text"),+ ({"structuredContent": {"name": "structured"}, "content": {"name": "content"}}, "structured"),+ ({"content": {"name": "content"}, "name": "raw"}, "content"),+ ({"isError": True, "name": "test_value", "content": "article"}, "test_value"),+ ],+)+async def test_typed_tool_conversion_preserves_precedence(+ named_output_tool_session: AsyncMock, tool_result: BaseModel | dict[str, object], expected_name: str+) -> None:+ named_output_tool_session.call_tool.return_value = tool_result+ tool_class = (await fetch_mcp_tools_async(client_session=named_output_tool_session))[0]+ result = await tool_class().arun(tool_class.input_schema(tool_name="EchoTool", query="hello"))+ assert result.model_dump() == {"name": expected_name}+++ "tool_result,cause_type,message",+ [+ (+ CallToolResult(content=[TextContent(type="text", text='{"name":"text"}')]),+ TypeError,+ "structuredContent with unexpected type NoneType",+ ),+ (StructuredModelResult(structuredContent="invalid"), TypeError, "structuredContent with unexpected type str"),+ (MockContentResult(content=[]), ValueError, "unparseable result"),+ (MockContentResult(content=[MockContentItem(text="invalid")]), ValueError, "unparseable result"),+ (+ MockContentResult(content=[TextAndDataContent(text='{"wrong":"field"}', data={"name": "ignored"})]),+ ValueError,+ "validation error",+ ),+ ({"structuredContent": None, "name": "ignored"}, TypeError, "mapping"),+ ("raw string", ValueError, "unparseable result"),+ ],+)+async def test_typed_tool_conversion_preserves_wrapped_failures(+ named_output_tool_session: AsyncMock,+ tool_result: BaseModel | dict[str, object] | str,+ cause_type: type[Exception],+ message: str,+) -> None:+ named_output_tool_session.call_tool.return_value = tool_result+ tool_class = (await fetch_mcp_tools_async(client_session=named_output_tool_session))[0]+ with pytest.raises(RuntimeError, match="Failed to execute MCP tool 'EchoTool':") as failure:+ await tool_class().arun(tool_class.input_schema(tool_name="EchoTool", query="hello"))+ assert isinstance(failure.value.__cause__, cause_type)+ assert message in str(failure.value)+++ "tool_result,expected_content",+ [+ (+ CallToolResult(content=[TextContent(type="text", text="first"), TextContent(type="text", text="second")]),+ [TextContent(type="text", text="first"), TextContent(type="text", text="second")],+ ),+ ({"isError": True, "name": "test_value", "content": "article"}, "article"),+ ({"name": "raw"}, {"name": "raw"}),+ (123, 123),+ ],+)+async def test_generic_tool_conversion_preserves_content(+ mocked_mcp_connection: tuple[AsyncMock, dict[str, MagicMock]],+ tool_result: BaseModel | dict[str, object] | int,+ expected_content: list[TextContent] | dict[str, str] | str | int,+) -> None:+ session, _ = mocked_mcp_connection+ session.call_tool.return_value = tool_result+ tool_class = (await fetch_mcp_tools_async(client_session=session))[0]+ result = await tool_class().arun(tool_class.input_schema(tool_name="EchoTool", query="hello"))+ assert result.result == expected_content