open-swarm 0.1.1748636259__py3-none-any.whl → 0.1.1748636455__py3-none-any.whl

swarm/extensions/mcp/mcp_client.py

@@ -0,0 +1,233 @@
+"""
+MCP Client Module
+
+Manages connections and interactions with MCP servers using the MCP Python SDK.
+Redirects MCP server stderr to log files unless debug mode is enabled.
+"""
+
+import asyncio
+import logging
+import os
+from typing import Any, Dict, List, Callable
+from contextlib import contextmanager
+import sys
+
+from mcp import ClientSession, StdioServerParameters  # type: ignore
+from mcp.client.stdio import stdio_client  # type: ignore
+from swarm.types import Tool
+from .cache_utils import get_cache
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG)
+
+class MCPClient:
+    """
+    Manages connections and interactions with MCP servers using the MCP Python SDK.
+    """
+
+    def __init__(self, server_config: Dict[str, Any], timeout: int = 15, debug: bool = False):
+        """
+        Initialize the MCPClient with server configuration.
+
+        Args:
+            server_config (dict): Configuration dictionary for the MCP server.
+            timeout (int): Timeout for operations in seconds.
+            debug (bool): If True, MCP server stderr goes to console; otherwise, to log file.
+        """
+        self.command = server_config.get("command", "npx")
+        self.args = server_config.get("args", [])
+        self.env = {**os.environ.copy(), **server_config.get("env", {})}
+        self.timeout = timeout
+        self.debug = debug
+        self._tool_cache: Dict[str, Tool] = {}
+
+        # Initialize cache using the helper
+        self.cache = get_cache()
+
+        logger.info(f"Initialized MCPClient with command={self.command}, args={self.args}, debug={self.debug}")
+
+    @contextmanager
+    def _redirect_stderr(self):
+        import sys, os
+        if not self.debug:
+            old_stderr = sys.stderr
+            sys.stderr = open(os.devnull, "w")
+            try:
+                yield
+            finally:
+                sys.stderr.close()
+                sys.stderr = old_stderr
+        else:
+            yield
+
+    async def list_tools(self) -> List[Tool]:
+        """
+        Discover tools from the MCP server and cache their schemas.
+
+        Returns:
+            List[Tool]: A list of discovered tools with schemas.
+        """
+        logger.debug(f"Entering list_tools for command={self.command}, args={self.args}")
+
+        # Attempt to retrieve tools from cache
+        args_string = "_".join(self.args)
+        cache_key = f"mcp_tools_{self.command}_{args_string}"
+        cached_tools = self.cache.get(cache_key)
+
+        if cached_tools:
+            logger.debug("Retrieved tools from cache")
+            tools = []
+            for tool_data in cached_tools:
+                tool_name = tool_data["name"]
+                tool = Tool(
+                    name=tool_name,
+                    description=tool_data["description"],
+                    input_schema=tool_data.get("input_schema", {}),
+                    func=self._create_tool_callable(tool_name),
+                )
+                tools.append(tool)
+            logger.debug(f"Returning {len(tools)} cached tools")
+            return tools
+
+        server_params = StdioServerParameters(command=self.command, args=self.args, env=self.env)
+        logger.debug("Opening stdio_client connection")
+        async with stdio_client(server_params) as (read, write):
+            logger.debug("Opening ClientSession")
+            async with ClientSession(read, write) as session:
+                try:
+                    logger.info("Initializing session for tool discovery")
+                    await asyncio.wait_for(session.initialize(), timeout=self.timeout)
+                    logger.info("Initializing session for tool discovery")
+                    await asyncio.wait_for(session.initialize(), timeout=self.timeout)
+                    logger.info("Capabilities initialized. Entering tool discovery.")
+                    logger.info("Requesting tool list from MCP server...")
+                    tools_response = await asyncio.wait_for(session.list_tools(), timeout=self.timeout)
+                    logger.debug("Tool list received from MCP server")
+
+                    serialized_tools = [
+                        {
+                            'name': tool.name,
+                            'description': tool.description,
+                            'input_schema': tool.inputSchema,
+                        }
+                        for tool in tools_response.tools
+                    ]
+
+                    self.cache.set(cache_key, serialized_tools, 3600)
+                    logger.debug(f"Cached {len(serialized_tools)} tools.")
+
+                    tools = []
+                    for tool in tools_response.tools:
+                        input_schema = tool.inputSchema or {}
+                        cached_tool = Tool(
+                            name=tool.name,
+                            description=tool.description,
+                            input_schema=input_schema,
+                            func=self._create_tool_callable(tool.name),
+                        )
+                        self._tool_cache[tool.name] = cached_tool
+                        tools.append(cached_tool)
+                        logger.debug(f"Discovered tool: {tool.name} with schema: {input_schema}")
+
+                    logger.debug(f"Returning {len(tools)} tools from MCP server")
+                    return tools
+
+                except asyncio.TimeoutError:
+                    logger.error(f"Timeout after {self.timeout}s waiting for tool list")
+                    raise RuntimeError("Tool list request timed out")
+                except Exception as e:
+                    logger.error(f"Error listing tools: {e}")
+                    raise RuntimeError("Failed to list tools") from e
+
+    async def _do_list_resources(self) -> Any:
+        server_params = StdioServerParameters(command=self.command, args=self.args, env=self.env)
+        logger.debug("Opening stdio_client connection for resources")
+        async with stdio_client(server_params) as (read, write):
+            logger.debug("Opening ClientSession for resources")
+            async with ClientSession(read, write) as session:
+                logger.info("Requesting resource list from MCP server...")
+                with self._redirect_stderr():
+                    # Ensure we initialize the session before listing resources
+                    logger.debug("Initializing session before listing resources")
+                    await asyncio.wait_for(session.initialize(), timeout=self.timeout)
+                    resources_response = await asyncio.wait_for(session.list_resources(), timeout=self.timeout)
+                logger.debug("Resource list received from MCP server")
+                return resources_response
+
+    def _create_tool_callable(self, tool_name: str) -> Callable[..., Any]:
+        """
+        Dynamically create a callable function for the specified tool.
+        """
+        async def dynamic_tool_func(**kwargs) -> Any:
+            logger.debug(f"Creating tool callable for '{tool_name}'")
+            server_params = StdioServerParameters(command=self.command, args=self.args, env=self.env)
+            async with stdio_client(server_params) as (read, write):
+                async with ClientSession(read, write) as session:
+                    try:
+                        logger.debug(f"Initializing session for tool '{tool_name}'")
+                        await asyncio.wait_for(session.initialize(), timeout=self.timeout)
+                        if tool_name in self._tool_cache:
+                            tool = self._tool_cache[tool_name]
+                            self._validate_input_schema(tool.input_schema, kwargs)
+                        logger.info(f"Calling tool '{tool_name}' with arguments: {kwargs}")
+                        result = await asyncio.wait_for(session.call_tool(tool_name, kwargs), timeout=self.timeout)
+                        logger.info(f"Tool '{tool_name}' executed successfully: {result}")
+                        return result
+                    except asyncio.TimeoutError:
+                        logger.error(f"Timeout after {self.timeout}s executing tool '{tool_name}'")
+                        raise RuntimeError(f"Tool '{tool_name}' execution timed out")
+                    except Exception as e:
+                        logger.error(f"Failed to execute tool '{tool_name}': {e}")
+                        raise RuntimeError(f"Tool execution failed: {e}") from e
+
+        return dynamic_tool_func
+
+    def _validate_input_schema(self, schema: Dict[str, Any], kwargs: Dict[str, Any]):
+        """
+        Validate the provided arguments against the input schema.
+        """
+        if not schema:
+            logger.debug("No input schema available for validation. Skipping.")
+            return
+
+        required_params = schema.get("required", [])
+        for param in required_params:
+            if param not in kwargs:
+                raise ValueError(f"Missing required parameter: '{param}'")
+
+        logger.debug(f"Validated input against schema: {schema} with arguments: {kwargs}")
+
+    async def list_resources(self) -> Any:
+        """
+        Discover resources from the MCP server using the internal method with enforced timeout.
+        """
+        return await asyncio.wait_for(self._do_list_resources(), timeout=self.timeout)
+
+    async def get_resource(self, resource_uri: str) -> Any:
+        """
+        Retrieve a specific resource from the MCP server.
+        
+        Args:
+            resource_uri (str): The URI of the resource to retrieve.
+        
+        Returns:
+            Any: The resource retrieval response.
+        """
+        server_params = StdioServerParameters(command=self.command, args=self.args, env=self.env)
+        logger.debug("Opening stdio_client connection for resource retrieval")
+        async with stdio_client(server_params) as (read, write):
+            logger.debug("Opening ClientSession for resource retrieval")
+            async with ClientSession(read, write) as session:
+                try:
+                    logger.debug(f"Initializing session for resource retrieval of {resource_uri}")
+                    await asyncio.wait_for(session.initialize(), timeout=self.timeout)
+                    logger.info(f"Retrieving resource '{resource_uri}' from MCP server")
+                    response = await asyncio.wait_for(session.read_resource(resource_uri), timeout=self.timeout)
+                    logger.info(f"Resource '{resource_uri}' retrieved successfully")
+                    return response
+                except asyncio.TimeoutError:
+                    logger.error(f"Timeout retrieving resource '{resource_uri}' after {self.timeout}s")
+                    raise RuntimeError(f"Resource '{resource_uri}' retrieval timed out")
+                except Exception as e:
+                    logger.error(f"Failed to retrieve resource '{resource_uri}': {e}")
+                    raise RuntimeError(f"Resource retrieval failed: {e}") from e

swarm/extensions/mcp/mcp_tool_provider.py

@@ -0,0 +1,135 @@
+"""
+MCPToolProvider Module for Open-Swarm
+
+This module is responsible for discovering tools from MCP (Model Context Protocol) servers
+and integrating them into the Open-Swarm framework as `Tool` instances. It handles
+communication with MCP servers, constructs callable functions for dynamic tools, and
+ensures that these tools are properly validated and integrated into the agent's function list.
+"""
+
+import logging
+from typing import List, Dict, Any
+
+from swarm.settings import DEBUG
+from swarm.types import Tool, Agent
+from swarm.extensions.mcp.mcp_client import MCPClient
+
+from .cache_utils import get_cache
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG if DEBUG else logging.INFO)
+stream_handler = logging.StreamHandler()
+formatter = logging.Formatter("[%(levelname)s] %(asctime)s - %(name)s - %(message)s")
+stream_handler.setFormatter(formatter)
+if not logger.handlers:
+    logger.addHandler(stream_handler)
+
+
+class MCPToolProvider:
+    """
+    Singleton MCPToolProvider to discover tools from an MCP server and convert them into `Tool` instances.
+    """
+    _instances: Dict[str, "MCPToolProvider"] = {}
+
+    @classmethod
+    def get_instance(cls, server_name: str, server_config: Dict[str, Any], timeout: int = 15, debug: bool = False) -> "MCPToolProvider":
+        """Get or create a singleton instance for the given server name."""
+        if server_name not in cls._instances:
+            cls._instances[server_name] = cls(server_name, server_config, timeout, debug)
+        return cls._instances[server_name]
+
+    def __init__(self, server_name: str, server_config: Dict[str, Any], timeout: int = 15, debug: bool = False):
+        """
+        Initialize an MCPToolProvider instance with a configurable timeout.
+
+        Args:
+            server_name (str): The name of the MCP server.
+            server_config (dict): Configuration dictionary for the specific server.
+            timeout (int): Timeout in seconds for MCP operations (default 15, overridden by caller if provided).
+            debug (bool): If True, MCP server stderr goes to stderr; otherwise, to log file.
+        """
+        if server_name in self._instances:
+            raise ValueError(f"MCPToolProvider for '{server_name}' already initialized. Use get_instance().")
+        self.server_name = server_name
+        self.client = MCPClient(server_config=server_config, timeout=timeout, debug=debug)
+        self.cache = get_cache()
+        logger.debug(f"Initialized MCPToolProvider for server '{self.server_name}' with timeout {timeout}s.")
+
+    async def discover_tools(self, agent: Agent) -> List[Tool]:
+        """
+        Discover tools from the MCP server and return them as a list of `Tool` instances.
+        Utilizes Django cache to persist tool metadata if available.
+
+        Args:
+            agent (Agent): The agent for which tools are being discovered.
+
+        Returns:
+            List[Tool]: A list of discovered `Tool` instances.
+
+        Raises:
+            RuntimeError: If tool discovery from the MCP server fails.
+        """
+        cache_key = f"mcp_tools_{self.server_name}"
+        cached_tools = self.cache.get(cache_key)
+
+        if cached_tools:
+            logger.debug(f"Retrieved tools for server '{self.server_name}' from cache.")
+            tools = []
+            for tool_data in cached_tools:
+                tool_name = tool_data["name"]
+                tool = Tool(
+                    name=tool_name,
+                    description=tool_data["description"],
+                    input_schema=tool_data.get("input_schema", {}),
+                    func=self._create_tool_callable(tool_name),
+                )
+                tools.append(tool)
+            return tools
+
+        logger.debug(f"Starting tool discovery from MCP server '{self.server_name}' for agent '{agent.name}'.")
+        try:
+            tools = await self.client.list_tools()
+            logger.debug(f"Discovered tools from MCP server '{self.server_name}': {[tool.name for tool in tools]}")
+
+            # Serialize tools for caching
+            serialized_tools = [
+                {
+                    'name': tool.name,
+                    'description': tool.description,
+                    'input_schema': tool.input_schema,
+                }
+                for tool in tools
+            ]
+
+            # Cache the tools for 1 hour (3600 seconds)
+            self.cache.set(cache_key, serialized_tools, 3600)
+            logger.debug(f"Cached tools for MCP server '{self.server_name}'.")
+
+            return tools
+
+        except Exception as e:
+            logger.error(f"Failed to discover tools from MCP server '{self.server_name}': {e}", exc_info=True)
+            raise RuntimeError(f"Tool discovery failed for MCP server '{self.server_name}': {e}") from e
+
+    def _create_tool_callable(self, tool_name: str):
+        """
+        Create a callable function for a dynamically discovered tool.
+
+        Args:
+            tool_name (str): The name of the tool.
+
+        Returns:
+            Callable: An async callable function for the tool.
+        """
+        async def dynamic_tool_func(**kwargs) -> Any:
+            try:
+                logger.info(f"Executing tool '{tool_name}' with arguments: {kwargs}")
+                tool_callable = self.client._create_tool_callable(tool_name)
+                result = await tool_callable(**kwargs)
+                logger.info(f"Tool '{tool_name}' executed successfully: {result}")
+                return result
+            except Exception as e:
+                logger.error(f"Error executing tool '{tool_name}': {e}")
+                raise RuntimeError(f"Tool execution failed: {e}") from e
+
+        return dynamic_tool_func

swarm/extensions/mcp/mcp_utils.py

@@ -0,0 +1,260 @@
+"""
+Utilities for MCP server interactions in the Swarm framework.
+Handles discovery and merging of tools and resources from MCP servers.
+"""
+
+import logging
+from typing import List, Dict, Any, Optional, cast
+import asyncio # Needed for async operations
+
+# Import necessary types from the core swarm types
+from swarm.types import Agent, AgentFunction
+# Import the MCPToolProvider which handles communication with MCP servers
+from .mcp_tool_provider import MCPToolProvider
+
+# Configure module-level logging
+logger = logging.getLogger(__name__)
+# Ensure logger level is set appropriately (e.g., DEBUG for development)
+# logger.setLevel(logging.DEBUG) # Uncomment for verbose logging
+# Add handler if not already configured by root logger setup
+if not logger.handlers:
+    stream_handler = logging.StreamHandler()
+    formatter = logging.Formatter("[%(levelname)s] %(asctime)s - %(name)s:%(lineno)d - %(message)s")
+    stream_handler.setFormatter(formatter)
+    logger.addHandler(stream_handler)
+
+# Dictionary to manage locks for concurrent discovery per agent (optional)
+# _discovery_locks: Dict[str, asyncio.Lock] = {}
+
+async def discover_and_merge_agent_tools(agent: Agent, config: Dict[str, Any], debug: bool = False) -> List[AgentFunction]:
+    """
+    Discover tools from MCP servers listed in the agent's config and merge
+    them with the agent's statically defined functions.
+
+    Handles deduplication of discovered tools based on name.
+
+    Args:
+        agent: The agent instance for which to discover tools.
+        config: The main Swarm configuration dictionary containing MCP server details.
+        debug: If True, enable detailed debugging logs.
+
+    Returns:
+        List[AgentFunction]: A combined list containing the agent's static functions
+                             and unique tools discovered from its associated MCP servers.
+                             Returns the agent's static functions if no MCP servers are defined.
+                             Returns an empty list if the agent is None.
+    """
+    if not agent:
+        logger.error("Cannot discover tools: Agent object is None.")
+        return []
+    # Use agent's name for logging clarity
+    agent_name = getattr(agent, "name", "UnnamedAgent")
+
+    logger.debug(f"Starting tool discovery for agent '{agent_name}'.")
+    # Get the list of MCP servers associated with the agent
+    mcp_server_names = getattr(agent, "mcp_servers", [])
+
+    # Retrieve the agent's statically defined functions
+    static_functions = getattr(agent, "functions", []) or []
+    if not isinstance(static_functions, list):
+         logger.warning(f"Agent '{agent_name}' functions attribute is not a list ({type(static_functions)}). Treating as empty.")
+         static_functions = []
+
+    # If no MCP servers are listed for the agent, return only static functions
+    if not mcp_server_names:
+        func_names = [getattr(f, 'name', getattr(f, '__name__', '<unknown>')) for f in static_functions]
+        logger.debug(f"Agent '{agent_name}' has no MCP servers listed. Returning {len(static_functions)} static functions: {func_names}")
+        return static_functions
+
+    # List to hold tools discovered from all MCP servers
+    all_discovered_tools: List[AgentFunction] = []
+    # Set to keep track of discovered tool names for deduplication
+    discovered_tool_names = set()
+
+    # Iterate through each MCP server listed for the agent
+    for server_name in mcp_server_names:
+        if not isinstance(server_name, str):
+            logger.warning(f"Invalid MCP server name type for agent '{agent_name}': {type(server_name)}. Skipping.")
+            continue
+
+        logger.debug(f"Discovering tools from MCP server '{server_name}' for agent '{agent_name}'.")
+        # Get the configuration for the specific MCP server from the main config
+        server_config = config.get("mcpServers", {}).get(server_name)
+        if not server_config:
+            logger.warning(f"MCP server '{server_name}' configuration not found in main config for agent '{agent_name}'. Skipping.")
+            continue
+
+        try:
+            # Get an instance of the MCPToolProvider for this server
+            # Timeout can be adjusted based on expected MCP response time
+            provider = MCPToolProvider.get_instance(server_name, server_config, timeout=15, debug=debug)
+            # Call the provider to discover tools (this interacts with the MCP server)
+            discovered_tools_from_server = await provider.discover_tools(agent)
+
+            # Validate the response from the provider
+            if not isinstance(discovered_tools_from_server, list):
+                logger.warning(f"Invalid tools format received from MCP server '{server_name}' for agent '{agent_name}': Expected list, got {type(discovered_tools_from_server)}. Skipping.")
+                continue
+
+            server_tool_count = 0
+            for tool in discovered_tools_from_server:
+                 # Attempt to get tool name for deduplication and logging
+                 tool_name = getattr(tool, 'name', None) # Assuming tool objects have a 'name' attribute
+                 if not tool_name:
+                      logger.warning(f"Discovered tool from '{server_name}' is missing a 'name'. Skipping.")
+                      continue
+
+                 # Deduplication: Add tool only if its name hasn't been seen before
+                 if tool_name not in discovered_tool_names:
+                     # Ensure 'requires_approval' attribute exists (defaulting to True if missing)
+                     if not hasattr(tool, "requires_approval"):
+                         logger.debug(f"Tool '{tool_name}' from '{server_name}' missing 'requires_approval', defaulting to True.")
+                         try:
+                              setattr(tool, "requires_approval", True)
+                         except AttributeError:
+                              logger.warning(f"Could not set 'requires_approval' on tool '{tool_name}'.")
+
+                     all_discovered_tools.append(tool)
+                     discovered_tool_names.add(tool_name)
+                     server_tool_count += 1
+                 else:
+                      logger.debug(f"Tool '{tool_name}' from '{server_name}' is a duplicate. Skipping.")
+
+            tool_names_log = [getattr(t, 'name', '<noname>') for t in discovered_tools_from_server]
+            logger.debug(f"Discovered {server_tool_count} unique tools from '{server_name}': {tool_names_log}")
+
+        except Exception as e:
+            # Log errors during discovery for a specific server but continue with others
+            logger.error(f"Failed to discover tools from MCP server '{server_name}' for agent '{agent_name}': {e}", exc_info=debug) # Show traceback if debug
+
+    # Combine static functions with the unique discovered tools
+    # Static functions take precedence if names conflict (though deduplication above is based on discovered names)
+    final_functions = static_functions + all_discovered_tools
+
+    # Log final combined list details if debugging
+    if debug:
+        static_names = [getattr(f, 'name', getattr(f, '__name__', '<unknown>')) for f in static_functions]
+        discovered_names = list(discovered_tool_names) # Names of unique discovered tools
+        combined_names = [getattr(f, 'name', getattr(f, '__name__', '<unknown>')) for f in final_functions]
+        logger.debug(f"[DEBUG] Agent '{agent_name}' - Static functions: {static_names}")
+        logger.debug(f"[DEBUG] Agent '{agent_name}' - Unique discovered tools: {discovered_names}")
+        logger.debug(f"[DEBUG] Agent '{agent_name}' - Final combined functions: {combined_names}")
+
+    logger.debug(f"Agent '{agent_name}' total functions/tools after merge: {len(final_functions)} (Static: {len(static_functions)}, Discovered: {len(all_discovered_tools)})")
+    return final_functions
+
+
+async def discover_and_merge_agent_resources(agent: Agent, config: Dict[str, Any], debug: bool = False) -> List[Dict[str, Any]]:
+    """
+    Discover resources from MCP servers listed in the agent's config and merge
+    them with the agent's statically defined resources.
+
+    Handles deduplication of discovered resources based on their 'uri'.
+
+    Args:
+        agent: The agent instance for which to discover resources.
+        config: The main Swarm configuration dictionary containing MCP server details.
+        debug: If True, enable detailed debugging logs.
+
+    Returns:
+        List[Dict[str, Any]]: A combined list containing the agent's static resources
+                              and unique resources discovered from its associated MCP servers.
+                              Returns the agent's static resources if no MCP servers are defined.
+                              Returns an empty list if the agent is None.
+    """
+    if not agent:
+        logger.error("Cannot discover resources: Agent object is None.")
+        return []
+    agent_name = getattr(agent, "name", "UnnamedAgent")
+
+    logger.debug(f"Starting resource discovery for agent '{agent_name}'.")
+    mcp_server_names = getattr(agent, "mcp_servers", [])
+
+    # Get static resources, ensure it's a list
+    static_resources = getattr(agent, "resources", []) or []
+    if not isinstance(static_resources, list):
+         logger.warning(f"Agent '{agent_name}' resources attribute is not a list ({type(static_resources)}). Treating as empty.")
+         static_resources = []
+    # Ensure static resources are dicts (basic check)
+    static_resources = [r for r in static_resources if isinstance(r, dict)]
+
+    if not mcp_server_names:
+        res_names = [r.get('name', '<unnamed>') for r in static_resources]
+        logger.debug(f"Agent '{agent_name}' has no MCP servers listed. Returning {len(static_resources)} static resources: {res_names}")
+        return static_resources
+
+    # List to hold resources discovered from all MCP servers
+    all_discovered_resources: List[Dict[str, Any]] = []
+
+    # Iterate through each MCP server listed for the agent
+    for server_name in mcp_server_names:
+        if not isinstance(server_name, str):
+            logger.warning(f"Invalid MCP server name type for agent '{agent_name}': {type(server_name)}. Skipping.")
+            continue
+
+        logger.debug(f"Discovering resources from MCP server '{server_name}' for agent '{agent_name}'.")
+        server_config = config.get("mcpServers", {}).get(server_name)
+        if not server_config:
+            logger.warning(f"MCP server '{server_name}' configuration not found for agent '{agent_name}'. Skipping.")
+            continue
+
+        try:
+            provider = MCPToolProvider.get_instance(server_name, server_config, timeout=15, debug=debug)
+            # Fetch resources using the provider's client
+            # Assuming provider.client has a method like list_resources() that returns {'resources': [...]}
+            resources_response = await provider.client.list_resources()
+
+            # Validate the structure of the response
+            if not isinstance(resources_response, dict) or "resources" not in resources_response:
+                logger.warning(f"Invalid resources response format from MCP server '{server_name}' for agent '{agent_name}'. Expected dict with 'resources' key, got: {type(resources_response)}")
+                continue
+
+            resources_from_server = resources_response["resources"]
+            if not isinstance(resources_from_server, list):
+                logger.warning(f"Invalid 'resources' format in response from '{server_name}': Expected list, got {type(resources_from_server)}.")
+                continue
+
+            # Filter for valid resource dictionaries (must be dict and have 'uri')
+            valid_resources = [res for res in resources_from_server if isinstance(res, dict) and 'uri' in res]
+            invalid_count = len(resources_from_server) - len(valid_resources)
+            if invalid_count > 0:
+                 logger.warning(f"Filtered out {invalid_count} invalid resource entries from '{server_name}'.")
+
+            all_discovered_resources.extend(valid_resources)
+            res_names_log = [r.get('name', '<unnamed>') for r in valid_resources]
+            logger.debug(f"Discovered {len(valid_resources)} valid resources from '{server_name}': {res_names_log}")
+
+        except AttributeError:
+             logger.error(f"MCPToolProvider client for '{server_name}' does not have a 'list_resources' method.", exc_info=debug)
+        except Exception as e:
+            logger.error(f"Failed to discover resources from MCP server '{server_name}' for agent '{agent_name}': {e}", exc_info=debug)
+
+    # Deduplicate discovered resources based on 'uri'
+    # Use a dictionary to keep only the first occurrence of each URI
+    unique_discovered_resources_map: Dict[str, Dict[str, Any]] = {}
+    for resource in all_discovered_resources:
+        uri = resource.get('uri') # URI is expected from validation above
+        if uri not in unique_discovered_resources_map:
+            unique_discovered_resources_map[uri] = resource
+
+    unique_discovered_resources_list = list(unique_discovered_resources_map.values())
+
+    # Combine static resources with unique discovered resources
+    # Create a map of static resource URIs to prevent duplicates if they also exist in discovered
+    static_resource_uris = {res.get('uri') for res in static_resources if res.get('uri')}
+    final_resources = static_resources + [
+        res for res in unique_discovered_resources_list if res.get('uri') not in static_resource_uris
+    ]
+
+    if debug:
+        static_names = [r.get('name', '<unnamed>') for r in static_resources]
+        discovered_names = [r.get('name', '<unnamed>') for r in all_discovered_resources] # Before dedupe
+        unique_discovered_names = [r.get('name', '<unnamed>') for r in unique_discovered_resources_list] # After dedupe
+        combined_names = [r.get('name', '<unnamed>') for r in final_resources]
+        logger.debug(f"[DEBUG] Agent '{agent_name}' - Static resources: {static_names}")
+        logger.debug(f"[DEBUG] Agent '{agent_name}' - Discovered resources (before URI dedupe): {discovered_names}")
+        logger.debug(f"[DEBUG] Agent '{agent_name}' - Unique discovered resources (after URI dedupe): {unique_discovered_names}")
+        logger.debug(f"[DEBUG] Agent '{agent_name}' - Final combined resources: {combined_names}")
+
+    logger.debug(f"Agent '{agent_name}' total resources after merge: {len(final_resources)} (Static: {len(static_resources)}, Unique Discovered: {len(unique_discovered_resources_list)})")
+    return final_resources