Skip to content

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.py
index 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 asyncio
import json
import logging
-from typing import Any, Dict, List, Type, Optional, Union, Tuple, cast
+from typing import Any, Dict, List, Type, Optional, Union, Tuple, cast, Protocol, Callable
from contextlib import AsyncExitStack
import shlex
import types
-from pydantic import create_model, Field, BaseModel
+from pydantic import create_model, Field, BaseModel, JsonValue
from mcp import ClientSession, StdioServerParameters
from 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_name
bound_mcp_endpoint = self.mcp_endpoint # May be None when using external session
bound_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 wrapper
def run_tool_sync(self, params: InputSchema) -> OutputSchema: # type: ignore
diff --git a/atomic-agents/tests/connectors/mcp/test_mcp_factory.py b/atomic-agents/tests/connectors/mcp/test_mcp_factory.py
index 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