Building AI agents, atomically
feat: add async MCP tools fetcher without event loop dependency (#133)
jon fox963a14786f6c
diff --git a/atomic-agents/atomic_agents/lib/factories/mcp_tool_factory.py b/atomic-agents/atomic_agents/lib/factories/mcp_tool_factory.pyindex 7dcf2ee..87f23a9 100644--- a/atomic-agents/atomic_agents/lib/factories/mcp_tool_factory.py+++ b/atomic-agents/atomic_agents/lib/factories/mcp_tool_factory.py@@ -303,6 +303,34 @@ def fetch_mcp_tools(return factory.create_tools()+async def fetch_mcp_tools_async(+ mcp_endpoint: Optional[str] = None,+ transport_type: MCPTransportType = MCPTransportType.STDIO,+ *,+ client_session: Optional[ClientSession] = None,+ working_directory: Optional[str] = None,+) -> List[Type[BaseTool]]:+ """+ Asynchronously connects to an MCP server and dynamically generates BaseTool subclasses for each tool.+ Must be called within an existing asyncio event loop context.++ Args:+ mcp_endpoint: URL of the MCP server (for HTTP/SSE) or command for STDIO.+ transport_type: Type of transport to use (SSE, HTTP_STREAM, or STDIO).+ client_session: Optional pre-initialized ClientSession for reuse.+ working_directory: Optional working directory for STDIO transport.+ """+ if client_session is not None:+ tool_defs = await ToolDefinitionService.fetch_definitions_from_session(client_session)+ factory = MCPToolFactory(mcp_endpoint, transport_type, client_session, asyncio.get_running_loop(), working_directory)+ else:+ service = ToolDefinitionService(mcp_endpoint, transport_type, working_directory)+ tool_defs = await service.fetch_definitions()+ factory = MCPToolFactory(mcp_endpoint, transport_type, None, None, working_directory)++ return factory._create_tool_classes(tool_defs)++def create_mcp_orchestrator_schema(tools: List[Type[BaseTool]]) -> Optional[Type[BaseIOSchema]]:"""Creates a schema for the MCP Orchestrator's output using the Union of all tool input schemas.diff --git a/atomic-agents/tests/lib/factories/test_mcp_tool_factory.py b/atomic-agents/tests/lib/factories/test_mcp_tool_factory.pyindex 47359d0..a3320be 100644--- a/atomic-agents/tests/lib/factories/test_mcp_tool_factory.py+++ b/atomic-agents/tests/lib/factories/test_mcp_tool_factory.py@@ -5,6 +5,7 @@ from atomic_agents.lib.factories.mcp_tool_factory import (fetch_mcp_tools,create_mcp_orchestrator_schema,fetch_mcp_tools_with_schema,+ fetch_mcp_tools_async,MCPToolFactory,)from atomic_agents.lib.factories.tool_definition_service import MCPToolDefinition, ToolDefinitionService, MCPTransportType@@ -437,3 +438,245 @@ def test_http_stream_endpoint_formatting():# Verify the factory was created with correct transport typeassert factory.transport_type == MCPTransportType.HTTP_STREAM+++# Tests for fetch_mcp_tools_async function+++async def test_fetch_mcp_tools_async_with_client_session(monkeypatch):+ """Test fetch_mcp_tools_async with pre-initialized client session."""+ import atomic_agents.lib.factories.mcp_tool_factory as mtf++ # Setup persistent client+ class DummySessionPersistent:+ async def call_tool(self, name, arguments):+ return {"content": "async-session-ok"}++ client = DummySessionPersistent()+ definitions = [+ MCPToolDefinition(+ name="AsyncTool", description="Test async tool", input_schema={"type": "object", "properties": {}, "required": []}+ )+ ]++ async def fake_fetch_defs(session):+ return definitions++ monkeypatch.setattr(mtf.ToolDefinitionService, "fetch_definitions_from_session", staticmethod(fake_fetch_defs))++ # Call fetch_mcp_tools_async with client session+ tools = await fetch_mcp_tools_async(None, MCPTransportType.HTTP_STREAM, client_session=client)++ assert len(tools) == 1+ tool_cls = tools[0]+ # Verify the tool was created correctly+ assert hasattr(tool_cls, "mcp_tool_name")+++async def test_fetch_mcp_tools_async_without_client_session(monkeypatch):+ """Test fetch_mcp_tools_async without pre-initialized client session."""++ definitions = [+ MCPToolDefinition(+ name="AsyncTool2",+ description="Test async tool 2",+ input_schema={"type": "object", "properties": {}, "required": []},+ )+ ]++ async def fake_fetch_defs(self):+ return definitions++ monkeypatch.setattr(ToolDefinitionService, "fetch_definitions", fake_fetch_defs)++ # Call fetch_mcp_tools_async without client session+ tools = await fetch_mcp_tools_async("http://test-endpoint", MCPTransportType.HTTP_STREAM)++ assert len(tools) == 1+ tool_cls = tools[0]+ # Verify the tool was created correctly+ assert hasattr(tool_cls, "mcp_tool_name")+++async def test_fetch_mcp_tools_async_stdio_transport(monkeypatch):+ """Test fetch_mcp_tools_async with STDIO transport."""+ definitions = [+ MCPToolDefinition(+ name="StdioAsyncTool",+ description="Test stdio async tool",+ input_schema={"type": "object", "properties": {}, "required": []},+ )+ ]++ async def fake_fetch_defs(self):+ return definitions++ monkeypatch.setattr(ToolDefinitionService, "fetch_definitions", fake_fetch_defs)++ # Call fetch_mcp_tools_async with STDIO transport+ tools = await fetch_mcp_tools_async("test-command", MCPTransportType.STDIO, working_directory="/tmp")++ assert len(tools) == 1+ tool_cls = tools[0]+ # Verify the tool was created correctly+ assert hasattr(tool_cls, "mcp_tool_name")+++async def test_fetch_mcp_tools_async_empty_definitions(monkeypatch):+ """Test fetch_mcp_tools_async returns empty list when no definitions found."""++ async def fake_fetch_defs(self):+ return []++ monkeypatch.setattr(ToolDefinitionService, "fetch_definitions", fake_fetch_defs)++ # Call fetch_mcp_tools_async+ tools = await fetch_mcp_tools_async("http://test-endpoint", MCPTransportType.HTTP_STREAM)++ assert tools == []+++async def test_fetch_mcp_tools_async_connection_error(monkeypatch):+ """Test fetch_mcp_tools_async propagates connection errors."""++ async def fake_fetch_defs_error(self):+ raise ConnectionError("Failed to connect to MCP server")++ monkeypatch.setattr(ToolDefinitionService, "fetch_definitions", fake_fetch_defs_error)++ # Call fetch_mcp_tools_async and expect ConnectionError+ with pytest.raises(ConnectionError, match="Failed to connect to MCP server"):+ await fetch_mcp_tools_async("http://test-endpoint", MCPTransportType.HTTP_STREAM)+++async def test_fetch_mcp_tools_async_runtime_error(monkeypatch):+ """Test fetch_mcp_tools_async propagates runtime errors."""++ async def fake_fetch_defs_error(self):+ raise RuntimeError("Unexpected error during fetching")++ monkeypatch.setattr(ToolDefinitionService, "fetch_definitions", fake_fetch_defs_error)++ # Call fetch_mcp_tools_async and expect RuntimeError+ with pytest.raises(RuntimeError, match="Unexpected error during fetching"):+ await fetch_mcp_tools_async("http://test-endpoint", MCPTransportType.HTTP_STREAM)+++async def test_fetch_mcp_tools_async_with_working_directory(monkeypatch):+ """Test fetch_mcp_tools_async with working directory parameter."""+ definitions = [+ MCPToolDefinition(+ name="WorkingDirTool",+ description="Test tool with working dir",+ input_schema={"type": "object", "properties": {}, "required": []},+ )+ ]++ async def fake_fetch_defs(self):+ return definitions++ monkeypatch.setattr(ToolDefinitionService, "fetch_definitions", fake_fetch_defs)++ # Call fetch_mcp_tools_async with working directory+ tools = await fetch_mcp_tools_async("test-command", MCPTransportType.STDIO, working_directory="/custom/working/dir")++ assert len(tools) == 1+ tool_cls = tools[0]+ # Verify the tool was created correctly+ assert hasattr(tool_cls, "mcp_tool_name")+++async def test_fetch_mcp_tools_async_session_error_propagation(monkeypatch):+ """Test fetch_mcp_tools_async with client session error propagation."""+ import atomic_agents.lib.factories.mcp_tool_factory as mtf++ class DummySessionPersistent:+ async def call_tool(self, name, arguments):+ return {"content": "session-ok"}++ client = DummySessionPersistent()++ async def fake_fetch_defs_error(session):+ raise ValueError("Session fetch error")++ monkeypatch.setattr(mtf.ToolDefinitionService, "fetch_definitions_from_session", staticmethod(fake_fetch_defs_error))++ # Call fetch_mcp_tools_async with client session and expect error+ with pytest.raises(ValueError, match="Session fetch error"):+ await fetch_mcp_tools_async(None, MCPTransportType.HTTP_STREAM, client_session=client)++[email protected]("transport_type", [MCPTransportType.HTTP_STREAM, MCPTransportType.STDIO, MCPTransportType.SSE])+async def test_fetch_mcp_tools_async_all_transport_types(monkeypatch, transport_type):+ """Test fetch_mcp_tools_async with all supported transport types."""+ definitions = [+ MCPToolDefinition(+ name=f"Tool_{transport_type.value}",+ description=f"Test tool for {transport_type.value}",+ input_schema={"type": "object", "properties": {}, "required": []},+ )+ ]++ async def fake_fetch_defs(self):+ return definitions++ monkeypatch.setattr(ToolDefinitionService, "fetch_definitions", fake_fetch_defs)++ # Determine endpoint based on transport type+ endpoint = "test-command" if transport_type == MCPTransportType.STDIO else "http://test-endpoint"+ working_dir = "/tmp" if transport_type == MCPTransportType.STDIO else None++ # Call fetch_mcp_tools_async with different transport types+ tools = await fetch_mcp_tools_async(endpoint, transport_type, working_directory=working_dir)++ assert len(tools) == 1+ tool_cls = tools[0]+ # Verify the tool was created correctly+ assert hasattr(tool_cls, "mcp_tool_name")+++async def test_fetch_mcp_tools_async_multiple_tools(monkeypatch):+ """Test fetch_mcp_tools_async with multiple tool definitions."""+ definitions = [+ MCPToolDefinition(+ name="Tool1", description="First tool", input_schema={"type": "object", "properties": {}, "required": []}+ ),+ MCPToolDefinition(+ name="Tool2",+ description="Second tool",+ input_schema={"type": "object", "properties": {"param": {"type": "string"}}, "required": ["param"]},+ ),+ MCPToolDefinition(+ name="Tool3",+ description="Third tool",+ input_schema={+ "type": "object",+ "properties": {"x": {"type": "number"}, "y": {"type": "number"}},+ "required": ["x", "y"],+ },+ ),+ ]++ async def fake_fetch_defs(self):+ return definitions++ monkeypatch.setattr(ToolDefinitionService, "fetch_definitions", fake_fetch_defs)++ # Call fetch_mcp_tools_async+ tools = await fetch_mcp_tools_async("http://test-endpoint", MCPTransportType.HTTP_STREAM)++ assert len(tools) == 3+ tool_names = [getattr(tool_cls, "mcp_tool_name", None) for tool_cls in tools]+ assert "Tool1" in tool_names+ assert "Tool2" in tool_names+ assert "Tool3" in tool_namesdiff --git a/atomic-examples/mcp-agent/example-client/example_client/main_stdio_async.py b/atomic-examples/mcp-agent/example-client/example_client/main_stdio_async.pynew file mode 100644index 0000000..ab18c24--- /dev/null+++ b/atomic-examples/mcp-agent/example-client/example_client/main_stdio_async.py@@ -0,0 +1,222 @@+# pyright: reportInvalidTypeForm=false+from atomic_agents.lib.factories.mcp_tool_factory import fetch_mcp_tools_async, MCPToolOutputSchema+from atomic_agents.lib.factories.tool_definition_service import MCPTransportType+from rich.console import Console+from rich.table import Table+import openai+import os+import instructor+import asyncio+import shlex+from contextlib import AsyncExitStack+from pydantic import Field+from atomic_agents.agents.base_agent import BaseIOSchema, BaseAgent, BaseAgentConfig+from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator+from atomic_agents.lib.components.chat_history import ChatHistory+from typing import Union, Type, Dict+from dataclasses import dataclass+from mcp import ClientSession, StdioServerParameters+from mcp.client.stdio import stdio_client+++# 1. Configuration and environment setup+@dataclass+class MCPConfig:+ """Configuration for the MCP Agent system using STDIO transport."""++ # NOTE: In contrast to other examples, we use gpt-4o and not gpt-4o-mini here.+ # In my tests, gpt-4o-mini was not smart enough to deal with multiple tools like that+ # and at the moment MCP does not yet allow for adding sufficient metadata to+ # clarify tools even more and introduce more constraints.+ openai_model: str = "gpt-4o"+ openai_api_key: str = os.getenv("OPENAI_API_KEY")++ # Command to run the STDIO server.+ # In practice, this could be something like "pipx some-other-persons-server or npx some-other-persons-server+ # if working with a server you did not write yourself.+ mcp_stdio_server_command: str = "poetry run example-mcp-server --mode stdio"++ def __post_init__(self):+ if not self.openai_api_key:+ raise ValueError("OPENAI_API_KEY environment variable is not set")+++config = MCPConfig()+console = Console()+client = instructor.from_openai(openai.OpenAI(api_key=config.openai_api_key))+++class FinalResponseSchema(BaseIOSchema):+ """Schema for providing a final text response to the user."""++ response_text: str = Field(..., description="The final text response to the user's query")+++async def main():+ async with AsyncExitStack() as stack:+ # Start MCP server+ cmd, *args = shlex.split(config.mcp_stdio_server_command)+ read_stream, write_stream = await stack.enter_async_context(+ stdio_client(StdioServerParameters(command=cmd, args=args))+ )+ session = await stack.enter_async_context(ClientSession(read_stream, write_stream))+ await session.initialize()++ # Fetch tools - factory sees running loop+ tools = await fetch_mcp_tools_async(+ transport_type=MCPTransportType.STDIO,+ client_session=session, # factory sees running loop+ )++ if not tools:+ raise RuntimeError("No MCP tools found. Please ensure the MCP server is running and accessible.")++ # Build mapping from input_schema to ToolClass+ tool_schema_to_class_map: Dict[Type[BaseIOSchema], Type[BaseAgent]] = {+ ToolClass.input_schema: ToolClass for ToolClass in tools if hasattr(ToolClass, "input_schema")+ }+ # Collect all tool input schemas+ tool_input_schemas = tuple(tool_schema_to_class_map.keys())++ # Available schemas include all tool input schemas and the final response schema+ available_schemas = tool_input_schemas + (FinalResponseSchema,)++ # Define the Union of all action schemas+ ActionUnion = Union[available_schemas]++ # 2. Schema and class definitions+ class MCPOrchestratorInputSchema(BaseIOSchema):+ """Input schema for the MCP Orchestrator Agent."""++ query: str = Field(..., description="The user's query to analyze.")++ class OrchestratorOutputSchema(BaseIOSchema):+ """Output schema for the orchestrator. Contains reasoning and the chosen action."""++ reasoning: str = Field(+ ..., description="Detailed explanation of why this action was chosen and how it will address the user's query."+ )+ action: ActionUnion = Field( # type: ignore+ ...,+ description="The chosen action: either a tool's input schema instance or a final response schema instance.",+ )++ model_config = {"arbitrary_types_allowed": True}++ # 3. Main logic+ console.print("[bold green]Initializing MCP Agent System (STDIO mode - Async)...[/bold green]")++ # Display available tools+ table = Table(title="Available MCP Tools", box=None)+ table.add_column("Tool Name", style="cyan")+ table.add_column("Input Schema", style="yellow")+ table.add_column("Description", style="magenta")+ for ToolClass in tools:+ schema_name = ToolClass.input_schema.__name__ if hasattr(ToolClass, "input_schema") else "N/A"+ table.add_row(ToolClass.mcp_tool_name, schema_name, ToolClass.__doc__ or "")+ console.print(table)++ # Create and initialize orchestrator agent+ console.print("[dim]• Creating orchestrator agent...[/dim]")+ history = ChatHistory()+ orchestrator_agent = BaseAgent[MCPOrchestratorInputSchema, OrchestratorOutputSchema](+ BaseAgentConfig(+ client=client,+ model=config.openai_model,+ history=history,+ system_prompt_generator=SystemPromptGenerator(+ background=[+ "You are an MCP Orchestrator Agent, designed to chat with users and",+ "determine the best way to handle their queries using the available tools.",+ ],+ steps=[+ "1. Use the reasoning field to determine if one or more successive tool calls could be used to handle the user's query.",+ "2. If so, choose the appropriate tool(s) one at a time and extract all necessary parameters from the query.",+ "3. If a single tool can not be used to handle the user's query, think about how to break down the query into "+ "smaller tasks and route them to the appropriate tool(s).",+ "4. If no sequence of tools could be used, or if you are finished processing the user's query, provide a final "+ "response to the user.",+ ],+ output_instructions=[+ "1. Always provide a detailed explanation of your decision-making process in the 'reasoning' field.",+ "2. Choose exactly one action schema (either a tool input or FinalResponseSchema).",+ "3. Ensure all required parameters for the chosen tool are properly extracted and validated.",+ "4. Maintain a professional and helpful tone in all responses.",+ "5. Break down complex queries into sequential tool calls before giving the final answer via `FinalResponseSchema`.",+ ],+ ),+ )+ )+ console.print("[green]Successfully created orchestrator agent.[/green]")++ # Interactive chat loop+ console.print(+ "[bold green]MCP Agent Interactive Chat (STDIO mode - Async). Type 'exit' or 'quit' to leave.[/bold green]"+ )+ while True:+ query = console.input("[bold yellow]You:[/bold yellow] ").strip()+ if query.lower() in {"/exit", "/quit"}:+ console.print("[bold red]Exiting chat. Goodbye![/bold red]")+ break+ if not query:+ continue # Ignore empty input++ try:+ # Initial run with user query+ orchestrator_output = orchestrator_agent.run(MCPOrchestratorInputSchema(query=query))+ action_instance = orchestrator_output.action+ reasoning = orchestrator_output.reasoning+ console.print(f"[cyan]Orchestrator reasoning:[/cyan] {reasoning}")++ # Keep executing until we get a final response+ while not isinstance(action_instance, FinalResponseSchema):+ schema_type = type(action_instance)+ ToolClass = tool_schema_to_class_map.get(schema_type)+ if not ToolClass:+ raise ValueError(f"Unknown schema type '" f"{schema_type.__name__}" f"' returned by orchestrator")++ tool_name = ToolClass.mcp_tool_name+ console.print(f"[blue]Executing tool:[/blue] {tool_name}")+ console.print(f"[dim]Parameters:[/dim] " f"{action_instance.model_dump()}")++ # Execute the MCP tool using the session directly to avoid event loop conflicts+ arguments = action_instance.model_dump(exclude={"tool_name"}, exclude_none=True)+ tool_result = await session.call_tool(name=tool_name, arguments=arguments)++ # Process the result similar to how the factory does it+ if 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++ # Create output schema instance+ OutputSchema = type(+ f"{tool_name}OutputSchema", (MCPToolOutputSchema,), {"__doc__": f"Output schema for {tool_name}"}+ )+ tool_output = OutputSchema(result=actual_result_content)+ console.print(f"[bold green]Result:[/bold green] {tool_output.result}")++ # Add tool result to agent history+ result_message = MCPOrchestratorInputSchema(+ query=(f"Tool {tool_name} executed with result: " f"{tool_output.result}")+ )+ orchestrator_agent.history.add_message("system", result_message)++ # Run the agent again without parameters to continue the flow+ orchestrator_output = orchestrator_agent.run()+ action_instance = orchestrator_output.action+ reasoning = orchestrator_output.reasoning+ console.print(f"[cyan]Orchestrator reasoning:[/cyan] {reasoning}")++ # Final response from the agent+ console.print(f"[bold blue]Agent:[/bold blue] {action_instance.response_text}")++ except Exception as e:+ console.print(f"[red]Error processing query:[/red] {str(e)}")+ console.print_exception()+++if __name__ == "__main__":+ asyncio.run(main())