Skip to content

Building AI agents, atomically

feat(mcp): capture and use outputSchema from MCP tools

KennyVaneetveldee10a9ff4dc7d
diff --git a/atomic-agents/atomic_agents/connectors/mcp/mcp_definition_service.py b/atomic-agents/atomic_agents/connectors/mcp/mcp_definition_service.py
index a995f4c..c1011a9 100644
--- a/atomic-agents/atomic_agents/connectors/mcp/mcp_definition_service.py
+++ b/atomic-agents/atomic_agents/connectors/mcp/mcp_definition_service.py
@@ -40,6 +40,7 @@ class MCPToolDefinition(NamedTuple):
name: str
description: Optional[str]
input_schema: Dict[str, Any]
+ output_schema: Optional[Dict[str, Any]] = None
class MCPResourceDefinition(NamedTuple):
@@ -163,11 +164,14 @@ class MCPDefinitionService:
await session.initialize()
response = await session.list_tools()
for mcp_tool in response.tools:
+ # Capture outputSchema if the MCP server provides one
+ output_schema = getattr(mcp_tool, "outputSchema", None)
definitions.append(
MCPToolDefinition(
name=mcp_tool.name,
description=mcp_tool.description,
input_schema=mcp_tool.inputSchema or {"type": "object", "properties": {}},
+ output_schema=output_schema,
)
)
diff --git a/atomic-agents/atomic_agents/connectors/mcp/mcp_factory.py b/atomic-agents/atomic_agents/connectors/mcp/mcp_factory.py
index bdc3c35..b401352 100644
--- a/atomic-agents/atomic_agents/connectors/mcp/mcp_factory.py
+++ b/atomic-agents/atomic_agents/connectors/mcp/mcp_factory.py
@@ -1,4 +1,5 @@
import asyncio
+import json
import logging
from typing import Any, List, Type, Optional, Union, Tuple, cast
from contextlib import AsyncExitStack
@@ -143,10 +144,25 @@ class MCPFactory:
attribute_type=MCPAttributeType.TOOL,
)
- # Create output schema
- OutputSchema = type(
- f"{tool_name}OutputSchema", (MCPToolOutputSchema,), {"__doc__": f"Output schema for {tool_name}"}
- )
+ # Create output schema - use MCP-provided schema if available, otherwise fallback to generic
+ output_schema_dict = definition.output_schema
+ has_typed_output_schema = False
+ if output_schema_dict:
+ # Use the schema transformer to create a proper typed output schema
+ OutputSchema = self.schema_transformer.create_model_from_schema(
+ output_schema_dict,
+ f"{tool_name}OutputSchema",
+ tool_name,
+ f"Output schema for {tool_name}",
+ attribute_type=MCPAttributeType.TOOL,
+ is_output_schema=True,
+ )
+ has_typed_output_schema = True
+ else:
+ # Fallback to generic output schema
+ OutputSchema = type(
+ f"{tool_name}OutputSchema", (MCPToolOutputSchema,), {"__doc__": f"Output schema for {tool_name}"}
+ )
# Async implementation
async def run_tool_async(self, params: InputSchema) -> OutputSchema: # type: ignore
@@ -217,7 +233,53 @@ class MCPFactory:
# Legacy behaviour – open a fresh connection per invocation.
tool_result = await _connect_and_call()
- # Process the result
+ # Process the result based on whether we have a typed output schema
+ 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)
+ return BoundOutputSchema(
+ **structured_data.model_dump() if hasattr(structured_data, "model_dump") else {}
+ )
+ elif isinstance(tool_result, BaseModel) and hasattr(tool_result, "content"):
+ # Try to parse content as structured data
+ content = tool_result.content
+ if content 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)
+ except (json.JSONDecodeError, TypeError):
+ pass
+ # 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)
+ # Last resort: return with whatever we can extract
+ logger.warning(
+ f"Could not parse structured output for tool '{bound_tool_name}', falling back to generic handling"
+ )
+
+ # Generic output schema handling (original behavior)
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:
@@ -225,7 +287,7 @@ class MCPFactory:
else:
actual_result_content = tool_result
- return OutputSchema(result=actual_result_content)
+ return BoundOutputSchema(result=actual_result_content)
except Exception as e:
logger.error(f"Error executing MCP tool '{bound_tool_name}': {e}", exc_info=True)
@@ -257,6 +319,7 @@ class MCPFactory:
"_client_session": self.client_session,
"_event_loop": self.event_loop,
"working_directory": self.working_directory,
+ "_has_typed_output_schema": has_typed_output_schema,
}
# Create the class using new_class() for proper generic type support
diff --git a/atomic-agents/atomic_agents/connectors/mcp/schema_transformer.py b/atomic-agents/atomic_agents/connectors/mcp/schema_transformer.py
index 8bfdac7..ee8e1e5 100644
--- a/atomic-agents/atomic_agents/connectors/mcp/schema_transformer.py
+++ b/atomic-agents/atomic_agents/connectors/mcp/schema_transformer.py
@@ -151,6 +151,7 @@ class SchemaTransformer:
tool_name_literal: str,
docstring: Optional[str] = None,
attribute_type: str = MCPAttributeType.TOOL,
+ is_output_schema: bool = False,
) -> Type[BaseIOSchema]:
"""
Dynamically create a Pydantic model from a JSON schema.
@@ -160,6 +161,8 @@ class SchemaTransformer:
model_name: Name for the model
tool_name_literal: Tool name to use for the Literal type
docstring: Optional docstring for the model
+ attribute_type: Type of MCP attribute (tool, resource, prompt)
+ is_output_schema: If True, skip adding the tool_name literal field (output schemas don't need it)
Returns:
Pydantic model class
@@ -180,12 +183,13 @@ class SchemaTransformer:
f"Schema for {model_name} is not a typical object with properties. Fields might be empty beyond tool_name."
)
- # Create a proper Literal type for the attribute identifier field.
- tool_name_type = cast(Type[str], Literal[tool_name_literal])
- fields[f"{attribute_type}_name"] = (
- tool_name_type,
- Field(..., description=f"Required identifier for the {tool_name_literal} {attribute_type}."),
- )
+ # Only add the attribute identifier field for input schemas
+ if not is_output_schema:
+ tool_name_type = cast(Type[str], Literal[tool_name_literal])
+ fields[f"{attribute_type}_name"] = (
+ tool_name_type,
+ Field(..., description=f"Required identifier for the {tool_name_literal} {attribute_type}."),
+ )
# Create the model
model = create_model(
diff --git a/atomic-agents/tests/connectors/mcp/test_mcp_definition_service.py b/atomic-agents/tests/connectors/mcp/test_mcp_definition_service.py
index 658c3c6..350b30e 100644
--- a/atomic-agents/tests/connectors/mcp/test_mcp_definition_service.py
+++ b/atomic-agents/tests/connectors/mcp/test_mcp_definition_service.py
@@ -562,3 +562,67 @@ async def test_fetch_prompts_from_session(caplog):
assert pd.name == "welcome"
# validate input_schema was constructed from arguments
assert pd.input_schema["properties"]["name"]["description"] == "The user's name"
+
+
+async def test_fetch_tool_definitions_with_output_schema():
+ """Test that outputSchema is captured from MCP tools when available"""
+ sess = AsyncMock()
+ sess.initialize = AsyncMock()
+
+ # Create a mock tool with outputSchema
+ mock_tool = MagicMock()
+ mock_tool.name = "StructuredTool"
+ mock_tool.description = "A tool with structured output"
+ mock_tool.inputSchema = {
+ "type": "object",
+ "properties": {"query": {"type": "string", "description": "Search query"}},
+ "required": ["query"],
+ }
+ mock_tool.outputSchema = {
+ "type": "object",
+ "properties": {
+ "results": {"type": "array", "items": {"type": "string"}, "description": "Search results"},
+ "count": {"type": "integer", "description": "Number of results"},
+ },
+ "required": ["results", "count"],
+ }
+
+ mock_response = MagicMock()
+ mock_response.tools = [mock_tool]
+ sess.list_tools = AsyncMock(return_value=mock_response)
+
+ result = await MCPDefinitionService.fetch_tool_definitions_from_session(sess)
+
+ assert len(result) == 1
+ td = result[0]
+ assert td.name == "StructuredTool"
+ assert td.output_schema is not None
+ assert td.output_schema["properties"]["results"]["type"] == "array"
+ assert td.output_schema["properties"]["count"]["type"] == "integer"
+
+
+async def test_fetch_tool_definitions_without_output_schema():
+ """Test that output_schema is None when MCP tool doesn't provide outputSchema"""
+ sess = AsyncMock()
+ sess.initialize = AsyncMock()
+
+ # Create a mock tool without outputSchema
+ mock_tool = MagicMock()
+ mock_tool.name = "SimpleTool"
+ mock_tool.description = "A simple tool without structured output"
+ mock_tool.inputSchema = {"type": "object", "properties": {}}
+ # Simulate tool without outputSchema attribute
+ del mock_tool.outputSchema
+
+ mock_response = MagicMock()
+ mock_response.tools = [mock_tool]
+ sess.list_tools = AsyncMock(return_value=mock_response)
+
+ result = await MCPDefinitionService.fetch_tool_definitions_from_session(sess)
+
+ assert len(result) == 1
+ td = result[0]
+ assert td.name == "SimpleTool"
+ assert td.output_schema is None
diff --git a/atomic-agents/tests/connectors/mcp/test_mcp_factory.py b/atomic-agents/tests/connectors/mcp/test_mcp_factory.py
index 51c0de1..526fa8d 100644
--- a/atomic-agents/tests/connectors/mcp/test_mcp_factory.py
+++ b/atomic-agents/tests/connectors/mcp/test_mcp_factory.py
@@ -86,9 +86,83 @@ def test_fetch_mcp_tools_with_definitions_http(monkeypatch):
# input_schema has only tool_name field
Model = tool_cls.input_schema
assert "tool_name" in Model.model_fields
- # output_schema has result field
+ # output_schema has result field (generic schema)
OutModel = tool_cls.output_schema
assert "result" in OutModel.model_fields
+ # verify _has_typed_output_schema is False for generic schema
+ assert tool_cls._has_typed_output_schema is False
+
+
+def test_fetch_mcp_tools_with_typed_output_schema(monkeypatch):
+ """Test that tools with outputSchema get typed output models"""
+ input_schema = {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}
+ output_schema = {
+ "type": "object",
+ "properties": {
+ "results": {"type": "array", "items": {"type": "string"}, "description": "Search results"},
+ "count": {"type": "integer", "description": "Number of results"},
+ },
+ "required": ["results", "count"],
+ }
+ definitions = [
+ MCPToolDefinition(
+ name="SearchTool", description="A tool with typed output", input_schema=input_schema, output_schema=output_schema
+ )
+ ]
+ monkeypatch.setattr(MCPFactory, "_fetch_tool_definitions", lambda self: definitions)
+ tools = fetch_mcp_tools("http://example.com", MCPTransportType.HTTP_STREAM)
+
+ assert len(tools) == 1
+ tool_cls = tools[0]
+
+ # verify class attributes
+ assert tool_cls.mcp_endpoint == "http://example.com"
+ assert tool_cls._has_typed_output_schema is True
+
+ # input_schema has tool_name and query fields
+ Model = tool_cls.input_schema
+ assert "tool_name" in Model.model_fields
+ assert "query" in Model.model_fields
+
+ # output_schema has typed fields instead of generic 'result'
+ OutModel = tool_cls.output_schema
+ assert "results" in OutModel.model_fields
+ assert "count" in OutModel.model_fields
+ # Should NOT have the generic 'result' field
+ assert "result" not in OutModel.model_fields
+ # Should NOT have the tool_name field (output schemas don't need it)
+ assert "tool_name" not in OutModel.model_fields
+
+
+def test_fetch_mcp_tools_mixed_output_schemas(monkeypatch):
+ """Test that tools with and without outputSchema are handled correctly together"""
+ input_schema = {"type": "object", "properties": {}, "required": []}
+ output_schema = {
+ "type": "object",
+ "properties": {"data": {"type": "string"}},
+ "required": ["data"],
+ }
+ definitions = [
+ MCPToolDefinition(name="GenericTool", description="No output schema", input_schema=input_schema),
+ MCPToolDefinition(
+ name="TypedTool", description="With output schema", input_schema=input_schema, output_schema=output_schema
+ ),
+ ]
+ monkeypatch.setattr(MCPFactory, "_fetch_tool_definitions", lambda self: definitions)
+ tools = fetch_mcp_tools("http://example.com", MCPTransportType.HTTP_STREAM)
+
+ assert len(tools) == 2
+
+ # First tool should have generic output
+ generic_tool = tools[0]
+ assert generic_tool._has_typed_output_schema is False
+ assert "result" in generic_tool.output_schema.model_fields
+
+ # Second tool should have typed output
+ typed_tool = tools[1]
+ assert typed_tool._has_typed_output_schema is True
+ assert "data" in typed_tool.output_schema.model_fields
+ assert "result" not in typed_tool.output_schema.model_fields
def test_fetch_mcp_resources_with_definitions_stdio(monkeypatch):