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.pyindex 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: strdescription: Optional[str]input_schema: Dict[str, Any]+ output_schema: Optional[Dict[str, Any]] = Noneclass 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.pyindex 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 jsonimport loggingfrom typing import Any, List, Type, Optional, Union, Tuple, castfrom 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 implementationasync 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.contentelif 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 supportdiff --git a/atomic-agents/atomic_agents/connectors/mcp/schema_transformer.py b/atomic-agents/atomic_agents/connectors/mcp/schema_transformer.pyindex 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 modeltool_name_literal: Tool name to use for the Literal typedocstring: 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 modelmodel = 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.pyindex 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 argumentsassert 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 Nonediff --git a/atomic-agents/tests/connectors/mcp/test_mcp_factory.py b/atomic-agents/tests/connectors/mcp/test_mcp_factory.pyindex 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 fieldModel = tool_cls.input_schemaassert "tool_name" in Model.model_fields- # output_schema has result field+ # output_schema has result field (generic schema)OutModel = tool_cls.output_schemaassert "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_fieldsdef test_fetch_mcp_resources_with_definitions_stdio(monkeypatch):