mcp-use 1.3.7__py3-none-any.whl → 1.3.9__py3-none-any.whl

mcp_use/__init__.py

@@ -25,7 +25,6 @@ __all__ = [
     "StdioConnector",
     "WebSocketConnector",
     "HttpConnector",
-    "create_session_from_config",
     "load_config_file",
     "logger",
     "MCP_USE_DEBUG",

mcp_use/adapters/base.py

@@ -91,14 +91,14 @@ class BaseAdapter(ABC):
 
         connector_tools = []
         # Now create tools for each MCP tool
-        for tool in connector.tools:
+        for tool in await connector.list_tools():
             # Convert the tool and add it to the list if conversion was successful
             converted_tool = self._convert_tool(tool, connector)
             if converted_tool:
                 connector_tools.append(converted_tool)
 
         # Convert resources to tools so that agents can access resource content directly
-        resources_list = connector.resources or []
+        resources_list = await connector.list_resources() or []
         if resources_list:
             for resource in resources_list:
                 converted_resource = self._convert_resource(resource, connector)
@@ -106,7 +106,7 @@ class BaseAdapter(ABC):
                     connector_tools.append(converted_resource)
 
         # Convert prompts to tools so that agents can retrieve prompt content
-        prompts_list = connector.prompts or []
+        prompts_list = await connector.list_prompts() or []
         if prompts_list:
             for prompt in prompts_list:
                 converted_prompt = self._convert_prompt(prompt, connector)

mcp_use/adapters/langchain_adapter.py

@@ -21,6 +21,7 @@ from mcp.types import (
 from pydantic import BaseModel, Field, create_model
 
 from ..connectors.base import BaseConnector
+from ..errors.error_formatting import format_error
 from ..logging import logger
 from .base import BaseAdapter
 
@@ -159,11 +160,11 @@ class LangChainAdapter(BaseAdapter):
                     except Exception as e:
                         # Log the exception for debugging
                         logger.error(f"Error parsing tool result: {e}")
-                        return f"Error parsing result: {e!s}; Raw content: {tool_result.content!r}"
+                        return format_error(e, tool=self.name, tool_content=tool_result.content)
 
                 except Exception as e:
                     if self.handle_tool_error:
-                        return f"Error executing MCP tool: {str(e)}"
+                        return format_error(e, tool=self.name)  # Format the error to make LLM understand it
                     raise
 
         return McpToLangChainAdapter()
@@ -204,7 +205,7 @@ class LangChainAdapter(BaseAdapter):
                     return content_decoded
                 except Exception as e:
                     if self.handle_tool_error:
-                        return f"Error reading resource: {str(e)}"
+                        return format_error(e, tool=self.name)  # Format the error to make LLM understand it
                     raise
 
         return ResourceTool()
@@ -261,7 +262,7 @@ class LangChainAdapter(BaseAdapter):
                     return result.messages
                 except Exception as e:
                     if self.handle_tool_error:
-                        return f"Error fetching prompt: {str(e)}"
+                        return format_error(e, tool=self.name)  # Format the error to make LLM understand it
                     raise
 
         return PromptTool()

mcp_use/agents/__init__.py

@@ -5,10 +5,10 @@ This module provides ready-to-use agent implementations
 that are pre-configured for using MCP tools.
 """
 
-from .base import BaseAgent
 from .mcpagent import MCPAgent
+from .remote import RemoteAgent
 
 __all__ = [
-    "BaseAgent",
     "MCPAgent",
+    "RemoteAgent",
 ]

mcp_use/agents/mcpagent.py

@@ -8,6 +8,7 @@ to provide a simple interface for using MCP tools with different LLMs.
 import logging
 import time
 from collections.abc import AsyncGenerator, AsyncIterator
+from typing import TypeVar
 
 from langchain.agents import AgentExecutor, create_tool_calling_agent
 from langchain.agents.output_parsers.tools import ToolAgentAction
@@ -20,6 +21,7 @@ from langchain_core.exceptions import OutputParserException
 from langchain_core.runnables.schema import StreamEvent
 from langchain_core.tools import BaseTool
 from langchain_core.utils.input import get_color_mapping
+from pydantic import BaseModel
 
 from mcp_use.client import MCPClient
 from mcp_use.connectors.base import BaseConnector
@@ -31,9 +33,13 @@ from ..logging import logger
 from ..managers.server_manager import ServerManager
 from .prompts.system_prompt_builder import create_system_message
 from .prompts.templates import DEFAULT_SYSTEM_PROMPT_TEMPLATE, SERVER_MANAGER_SYSTEM_PROMPT_TEMPLATE
+from .remote import RemoteAgent
 
 set_debug(logger.level == logging.DEBUG)
 
+# Type variable for structured output
+T = TypeVar("T", bound=BaseModel)
+
 
 class MCPAgent:
     """Main class for using MCP tools with various LLM providers.
@@ -44,7 +50,7 @@ class MCPAgent:
 
     def __init__(
         self,
-        llm: BaseLanguageModel,
+        llm: BaseLanguageModel | None = None,
         client: MCPClient | None = None,
         connectors: list[BaseConnector] | None = None,
         max_steps: int = 5,
@@ -54,13 +60,17 @@ class MCPAgent:
         system_prompt_template: str | None = None,  # User can still override the template
         additional_instructions: str | None = None,
         disallowed_tools: list[str] | None = None,
+        tools_used_names: list[str] | None = None,
         use_server_manager: bool = False,
         verbose: bool = False,
+        agent_id: str | None = None,
+        api_key: str | None = None,
+        base_url: str = "https://cloud.mcp-use.com",
     ):
         """Initialize a new MCPAgent instance.
 
         Args:
-            llm: The LangChain LLM to use.
+            llm: The LangChain LLM to use. Not required if agent_id is provided for remote execution.
             client: The MCPClient to use. If provided, connector is ignored.
             connectors: A list of MCP connectors to use if client is not provided.
             max_steps: The maximum number of steps to take.
@@ -71,7 +81,23 @@ class MCPAgent:
             additional_instructions: Extra instructions to append to the system prompt.
             disallowed_tools: List of tool names that should not be available to the agent.
             use_server_manager: Whether to use server manager mode instead of exposing all tools.
+            agent_id: Remote agent ID for remote execution. If provided, creates a remote agent.
+            api_key: API key for remote execution. If None, checks MCP_USE_API_KEY env var.
+            base_url: Base URL for remote API calls.
         """
+        # Handle remote execution
+        if agent_id is not None:
+            self._remote_agent = RemoteAgent(agent_id=agent_id, api_key=api_key, base_url=base_url)
+            self._is_remote = True
+            return
+
+        self._is_remote = False
+        self._remote_agent = None
+
+        # Validate requirements for local execution
+        if llm is None:
+            raise ValueError("llm is required for local execution. For remote execution, provide agent_id instead.")
+
         self.llm = llm
         self.client = client
         self.connectors = connectors or []
@@ -81,6 +107,7 @@ class MCPAgent:
         self._initialized = False
         self._conversation_history: list[BaseMessage] = []
         self.disallowed_tools = disallowed_tools or []
+        self.tools_used_names = tools_used_names or []
         self.use_server_manager = use_server_manager
         self.verbose = verbose
         # System prompt configuration
@@ -307,8 +334,8 @@ class MCPAgent:
 
     async def _consume_and_return(
         self,
-        generator: AsyncGenerator[tuple[AgentAction, str], str],
-    ) -> str:
+        generator: AsyncGenerator[tuple[AgentAction, str] | str | T, None],
+    ) -> tuple[str | T, int]:
         """Consume the generator and return the final result.
 
         This method manually iterates through the generator to consume the steps.
@@ -319,20 +346,24 @@ class MCPAgent:
             generator: The async generator that yields steps and a final result.
 
         Returns:
-            The final result from the generator.
+            A tuple of (final_result, steps_taken). final_result can be a string
+            for regular output or a Pydantic model instance for structured output.
         """
         final_result = ""
         steps_taken = 0
-        tools_used_names = []
         async for item in generator:
-            # If it's a string, it's the final result
+            # If it's a string, it's the final result (regular output)
             if isinstance(item, str):
                 final_result = item
                 break
+            # If it's not a tuple, it might be structured output (Pydantic model)
+            elif not isinstance(item, tuple):
+                final_result = item
+                break
             # Otherwise it's a step tuple, just consume it
-            steps_taken += 1
-            tools_used_names.append(item[0].tool)
-        return final_result, steps_taken, tools_used_names
+            else:
+                steps_taken += 1
+        return final_result, steps_taken
 
     async def stream(
         self,
@@ -341,7 +372,8 @@ class MCPAgent:
         manage_connector: bool = True,
         external_history: list[BaseMessage] | None = None,
         track_execution: bool = True,
-    ) -> AsyncGenerator[tuple[AgentAction, str] | str, None]:
+        output_schema: type[T] | None = None,
+    ) -> AsyncGenerator[tuple[AgentAction, str] | str | T, None]:
         """Run the agent and yield intermediate steps as an async generator.
 
         Args:
@@ -350,17 +382,48 @@ class MCPAgent:
             manage_connector: Whether to handle the connector lifecycle internally.
             external_history: Optional external history to use instead of the
                 internal conversation history.
+            track_execution: Whether to track execution for telemetry.
+            output_schema: Optional Pydantic BaseModel class for structured output.
+                If provided, the agent will attempt structured output at finish points
+                and continue execution if required information is missing.
 
         Yields:
-            Intermediate steps as (AgentAction, str) tuples, followed by the final result as a string.
+            Intermediate steps as (AgentAction, str) tuples, followed by the final result.
+            If output_schema is provided, yields structured output as instance of the schema.
         """
+        # Delegate to remote agent if in remote mode
+        if self._is_remote and self._remote_agent:
+            async for item in self._remote_agent.stream(
+                query, max_steps, manage_connector, external_history, track_execution, output_schema
+            ):
+                yield item
+            return
+
         result = ""
         initialized_here = False
         start_time = time.time()
-        tools_used_names = []
         steps_taken = 0
         success = False
 
+        # Schema-aware setup for structured output
+        structured_llm = None
+        schema_description = ""
+        if output_schema:
+            query = self._enhance_query_with_schema(query, output_schema)
+            structured_llm = self.llm.with_structured_output(output_schema)
+            # Get schema description for feedback
+            schema_fields = []
+            try:
+                for field_name, field_info in output_schema.model_fields.items():
+                    description = getattr(field_info, "description", "") or field_name
+                    required = not hasattr(field_info, "default") or field_info.default is None
+                    schema_fields.append(f"- {field_name}: {description} {'(required)' if required else '(optional)'}")
+
+                schema_description = "\n".join(schema_fields)
+            except Exception as e:
+                logger.warning(f"Could not extract schema details: {e}")
+                schema_description = f"Schema: {output_schema.__name__}"
+
         try:
             # Initialize if needed
             if manage_connector and not self._initialized:
@@ -449,7 +512,49 @@ class MCPAgent:
                     if isinstance(next_step_output, AgentFinish):
                         logger.info(f"✅ Agent finished at step {step_num + 1}")
                         result = next_step_output.return_values.get("output", "No output generated")
-                        break
+
+                        # If structured output is requested, attempt to create it
+                        if output_schema and structured_llm:
+                            try:
+                                logger.info("🔧 Attempting structured output...")
+                                structured_result = await self._attempt_structured_output(
+                                    result, structured_llm, output_schema, schema_description
+                                )
+
+                                # Add the final response to conversation history if memory is enabled
+                                if self.memory_enabled:
+                                    self.add_to_history(AIMessage(content=f"Structured result: {structured_result}"))
+
+                                logger.info("✅ Structured output successful")
+                                success = True
+                                yield structured_result
+                                return
+
+                            except Exception as e:
+                                logger.warning(f"⚠️ Structured output failed: {e}")
+                                # Continue execution to gather missing information
+                                missing_info_prompt = f"""
+                                The current result cannot be formatted into the required structure.
+                                Error: {str(e)}
+
+                                Current information: {result}
+
+                                Please continue working to gather the missing information needed for:
+                                {schema_description}
+
+                                Focus on finding the specific missing details.
+                                """
+
+                                # Add this as feedback and continue the loop
+                                inputs["input"] = missing_info_prompt
+                                if self.memory_enabled:
+                                    self.add_to_history(HumanMessage(content=missing_info_prompt))
+
+                                logger.info("🔄 Continuing execution to gather missing information...")
+                                continue
+                        else:
+                            # Regular execution without structured output
+                            break
 
                     # If it's actions/steps, add to intermediate steps and yield them
                     intermediate_steps.extend(next_step_output)
@@ -459,7 +564,7 @@ class MCPAgent:
                         yield agent_step
                         action, observation = agent_step
                         tool_name = action.tool
-                        tools_used_names.append(tool_name)
+                        self.tools_used_names.append(tool_name)
                         tool_input_str = str(action.tool_input)
                         # Truncate long inputs for readability
                         if len(tool_input_str) > 100:
@@ -498,15 +603,37 @@ class MCPAgent:
                 logger.warning(f"⚠️ Agent stopped after reaching max iterations ({steps})")
                 result = f"Agent stopped after reaching the maximum number of steps ({steps})."
 
-            # Add the final response to conversation history if memory is enabled
-            if self.memory_enabled:
+            # If structured output was requested but not achieved, attempt one final time
+            if output_schema and structured_llm and not success:
+                try:
+                    logger.info("🔧 Final attempt at structured output...")
+                    structured_result = await self._attempt_structured_output(
+                        result, structured_llm, output_schema, schema_description
+                    )
+
+                    # Add the final response to conversation history if memory is enabled
+                    if self.memory_enabled:
+                        self.add_to_history(AIMessage(content=f"Structured result: {structured_result}"))
+
+                    logger.info("✅ Final structured output successful")
+                    success = True
+                    yield structured_result
+                    return
+
+                except Exception as e:
+                    logger.error(f"❌ Final structured output attempt failed: {e}")
+                    raise RuntimeError(f"Failed to generate structured output after {steps} steps: {str(e)}") from e
+
+            if self.memory_enabled and not output_schema:
                 self.add_to_history(AIMessage(content=result))
 
             logger.info(f"🎉 Agent execution complete in {time.time() - start_time} seconds")
-            success = True
+            if not success:
+                success = True
 
-            # Yield the final result as a string
-            yield result
+            # Yield the final result (only for non-structured output)
+            if not output_schema:
+                yield result
 
         except Exception as e:
             logger.error(f"❌ Error running query: {e}")
@@ -548,8 +675,8 @@ class MCPAgent:
                     manage_connector=manage_connector,
                     external_history_used=external_history is not None,
                     steps_taken=steps_taken,
-                    tools_used_count=len(tools_used_names),
-                    tools_used_names=tools_used_names,
+                    tools_used_count=len(self.tools_used_names),
+                    tools_used_names=self.tools_used_names,
                     response=result,
                     execution_time_ms=execution_time_ms,
                     error_type=None if success else "execution_error",
@@ -567,11 +694,13 @@ class MCPAgent:
         max_steps: int | None = None,
         manage_connector: bool = True,
         external_history: list[BaseMessage] | None = None,
-    ) -> str:
+        output_schema: type[T] | None = None,
+    ) -> str | T:
         """Run a query using the MCP tools and return the final result.
 
         This method uses the streaming implementation internally and returns
-        the final result after consuming all intermediate steps.
+        the final result after consuming all intermediate steps. If output_schema
+        is provided, the agent will be schema-aware and return structured output.
 
         Args:
             query: The query to run.
@@ -582,19 +711,47 @@ class MCPAgent:
                 for managing the connector lifecycle.
             external_history: Optional external history to use instead of the
                 internal conversation history.
+            output_schema: Optional Pydantic BaseModel class for structured output.
+                If provided, the agent will attempt to return an instance of this model.
 
         Returns:
-            The result of running the query.
+            The result of running the query as a string, or if output_schema is provided,
+            an instance of the specified Pydantic model.
+
+        Example:
+            ```python
+            # Regular usage
+            result = await agent.run("What's the weather like?")
+
+            # Structured output usage
+            from pydantic import BaseModel, Field
+
+            class WeatherInfo(BaseModel):
+                temperature: float = Field(description="Temperature in Celsius")
+                condition: str = Field(description="Weather condition")
+
+            weather: WeatherInfo = await agent.run(
+                "What's the weather like?",
+                output_schema=WeatherInfo
+            )
+            ```
         """
+        # Delegate to remote agent if in remote mode
+        if self._is_remote and self._remote_agent:
+            return await self._remote_agent.run(query, max_steps, manage_connector, external_history, output_schema)
+
         success = True
         start_time = time.time()
-        generator = self.stream(query, max_steps, manage_connector, external_history, track_execution=False)
+
+        generator = self.stream(
+            query, max_steps, manage_connector, external_history, track_execution=False, output_schema=output_schema
+        )
         error = None
         steps_taken = 0
-        tools_used_names = []
         result = None
         try:
-            result, steps_taken, tools_used_names = await self._consume_and_return(generator)
+            result, steps_taken = await self._consume_and_return(generator)
+
         except Exception as e:
             success = False
             error = str(e)
@@ -618,15 +775,79 @@ class MCPAgent:
                 manage_connector=manage_connector,
                 external_history_used=external_history is not None,
                 steps_taken=steps_taken,
-                tools_used_count=len(tools_used_names),
-                tools_used_names=tools_used_names,
-                response=result,
+                tools_used_count=len(self.tools_used_names),
+                tools_used_names=self.tools_used_names,
+                response=str(result),
                 execution_time_ms=int((time.time() - start_time) * 1000),
                 error_type=error,
                 conversation_history_length=len(self._conversation_history),
             )
         return result
 
+    async def _attempt_structured_output(
+        self, raw_result: str, structured_llm, output_schema: type[T], schema_description: str
+    ) -> T:
+        """Attempt to create structured output from raw result with validation."""
+        format_prompt = f"""
+        Please format the following information according to the specified schema.
+        Extract and structure the relevant information from the content below.
+
+        Required schema fields:
+        {schema_description}
+
+        Content to format:
+        {raw_result}
+
+        Please provide the information in the requested structured format.
+        If any required information is missing, you must indicate this clearly.
+        """
+
+        structured_result = await structured_llm.ainvoke(format_prompt)
+
+        try:
+            for field_name, field_info in output_schema.model_fields.items():
+                required = not hasattr(field_info, "default") or field_info.default is None
+                if required:
+                    value = getattr(structured_result, field_name, None)
+                    if value is None or (isinstance(value, str) and not value.strip()):
+                        raise ValueError(f"Required field '{field_name}' is missing or empty")
+                    if isinstance(value, list) and len(value) == 0:
+                        raise ValueError(f"Required field '{field_name}' is an empty list")
+        except Exception as e:
+            logger.debug(f"Validation details: {e}")
+            raise  # Re-raise to trigger retry logic
+
+        return structured_result
+
+    def _enhance_query_with_schema(self, query: str, output_schema: type[T]) -> str:
+        """Enhance the query with schema information to make the agent aware of required fields."""
+        schema_fields = []
+
+        try:
+            for field_name, field_info in output_schema.model_fields.items():
+                description = getattr(field_info, "description", "") or field_name
+                required = not hasattr(field_info, "default") or field_info.default is None
+                schema_fields.append(f"- {field_name}: {description} {'(required)' if required else '(optional)'}")
+
+            schema_description = "\n".join(schema_fields)
+        except Exception as e:
+            logger.warning(f"Could not extract schema details: {e}")
+            schema_description = f"Schema: {output_schema.__name__}"
+
+        # Enhance the query with schema awareness
+        enhanced_query = f"""
+        {query}
+
+        IMPORTANT: Your response must include sufficient information to populate the following structured output:
+
+        {schema_description}
+
+        Make sure you gather ALL the required information during your task execution.
+        If any required information is missing, continue working to find it.
+        """
+
+        return enhanced_query
+
     async def _generate_response_chunks_async(
         self,
         query: str,
@@ -749,6 +970,11 @@ class MCPAgent:
 
     async def close(self) -> None:
         """Close the MCP connection with improved error handling."""
+        # Delegate to remote agent if in remote mode
+        if self._is_remote and self._remote_agent:
+            await self._remote_agent.close()
+            return
+
         logger.info("🔌 Closing agent and cleaning up resources...")
         try:
             # Clean up the agent first

mcp_use/agents/prompts/templates.py

@@ -17,27 +17,25 @@ Thought: I now know the final answer
 Final Answer: the final answer to the original input question"""
 
 
-SERVER_MANAGER_SYSTEM_PROMPT_TEMPLATE = """You are a helpful assistant designed to interact with MCP
- (Model Context Protocol) servers. You can manage connections to different servers and use the tools
- provided by the currently active server.
-
-Important: The available tools change depending on which server is active.
-If a request requires tools not listed below (e.g., file operations, web browsing,
- image manipulation), you MUST first connect to the appropriate server using
- 'connect_to_mcp_server'.
-Use 'list_mcp_servers' to find the relevant server if you are unsure.
-Only after successfully connecting and seeing the new tools listed in
-the response should you attempt to use those server-specific tools.
-Before attempting a task that requires specific tools, you should
-ensure you are connected to the correct server and aware of its
-available tools. If unsure, use 'list_mcp_servers' to see options
-or 'get_active_mcp_server' to check the current connection.
-
-When you connect to a server using 'connect_to_mcp_server',
- you will be informed about the new tools that become available.
-You can then use these server-specific tools in subsequent steps.
-
-Here are the tools *currently* available to you (this list includes server management tools and will
- change when you connect to a server):
+SERVER_MANAGER_SYSTEM_PROMPT_TEMPLATE = """You are a helpful assistant designed
+to interact with MCP (Model Context Protocol) servers. You can manage connections
+ to different servers and use the tools provided by the currently active server.
+
+Important: The available tools change dynamically based on which server is active.
+
+- When you connect to a server using 'connect_to_mcp_server', that server's tools are automatically added to
+your available tools with their full schemas
+- When you disconnect using 'disconnect_from_mcp_server', the server's tools are removed from your available tools
+- The tool list below will automatically update when you connect/disconnect from servers
+
+If a request requires tools not currently listed below (e.g., file operations, web browsing, image manipulation),
+you MUST first connect to the appropriate server using 'connect_to_mcp_server'. Use 'list_mcp_servers' to find
+available servers if you are unsure which one to connect to.
+
+After connecting to a server, you can immediately use its tools - they will be directly available to you with their
+proper schemas and validation. No additional steps are needed.
+
+Here are the tools currently available to you (this list dynamically updates when
+connecting/disconnecting from servers):
 {tool_descriptions}
 """