fast-agent-mcp 0.2.35__py3-none-any.whl → 0.2.37__py3-none-any.whl

mcp_agent/mcp/elicitation_factory.py

@@ -0,0 +1,84 @@
+"""
+Factory for resolving elicitation handlers with proper precedence.
+"""
+
+from typing import Any, Optional
+
+from mcp.client.session import ElicitationFnT
+
+from mcp_agent.core.agent_types import AgentConfig
+from mcp_agent.logging.logger import get_logger
+from mcp_agent.mcp.elicitation_handlers import (
+    auto_cancel_elicitation_handler,
+    forms_elicitation_handler,
+)
+
+logger = get_logger(__name__)
+
+
+def resolve_elicitation_handler(
+    agent_config: AgentConfig, app_config: Any, server_config: Any = None
+) -> Optional[ElicitationFnT]:
+    """Resolve elicitation handler with proper precedence.
+
+    Precedence order:
+    1. Agent decorator supplied (highest precedence)
+    2. Server-specific config file setting
+    3. Global config file setting
+    4. Default forms handler (lowest precedence)
+
+    Args:
+        agent_config: Agent configuration from decorator
+        app_config: Application configuration from YAML
+        server_config: Server-specific configuration (optional)
+
+    Returns:
+        ElicitationFnT handler or None (no elicitation capability)
+    """
+
+    # 1. Decorator takes highest precedence
+    if agent_config.elicitation_handler:
+        logger.debug(f"Using decorator-provided elicitation handler for agent {agent_config.name}")
+        return agent_config.elicitation_handler
+
+    # 2. Check server-specific config first
+    if server_config:
+        elicitation_config = getattr(server_config, "elicitation", {})
+        if isinstance(elicitation_config, dict):
+            mode = elicitation_config.get("mode")
+        else:
+            mode = getattr(elicitation_config, "mode", None)
+
+        if mode:
+            if mode == "none":
+                logger.debug(f"Elicitation disabled by server config for agent {agent_config.name}")
+                return None  # Don't advertise elicitation capability
+            elif mode == "auto_cancel":
+                logger.debug(
+                    f"Using auto-cancel elicitation handler (server config) for agent {agent_config.name}"
+                )
+                return auto_cancel_elicitation_handler
+            else:  # "forms" or other
+                logger.debug(
+                    f"Using forms elicitation handler (server config) for agent {agent_config.name}"
+                )
+                return forms_elicitation_handler
+
+    # 3. Check global config file
+    elicitation_config = getattr(app_config, "elicitation", {})
+    if isinstance(elicitation_config, dict):
+        mode = elicitation_config.get("mode", "forms")
+    else:
+        mode = getattr(elicitation_config, "mode", "forms")
+
+    if mode == "none":
+        logger.debug(f"Elicitation disabled by global config for agent {agent_config.name}")
+        return None  # Don't advertise elicitation capability
+    elif mode == "auto_cancel":
+        logger.debug(
+            f"Using auto-cancel elicitation handler (global config) for agent {agent_config.name}"
+        )
+        return auto_cancel_elicitation_handler
+    else:  # "forms" or default
+        logger.debug(f"Using default forms elicitation handler for agent {agent_config.name}")
+        return forms_elicitation_handler

mcp_agent/mcp/elicitation_handlers.py

@@ -0,0 +1,155 @@
+"""
+Predefined elicitation handlers for different use cases.
+"""
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from mcp.shared.context import RequestContext
+from mcp.types import ElicitRequestParams, ElicitResult, ErrorData
+
+from mcp_agent.human_input.elicitation_handler import elicitation_input_callback
+from mcp_agent.human_input.types import HumanInputRequest
+from mcp_agent.logging.logger import get_logger
+from mcp_agent.mcp.helpers.server_config_helpers import get_server_config
+
+if TYPE_CHECKING:
+    from mcp import ClientSession
+
+logger = get_logger(__name__)
+
+
+async def auto_cancel_elicitation_handler(
+    context: RequestContext["ClientSession", Any],
+    params: ElicitRequestParams,
+) -> ElicitResult | ErrorData:
+    """Handler that automatically cancels all elicitation requests.
+    
+    Useful for production deployments where you want to advertise elicitation
+    capability but automatically decline all requests.
+    """
+    logger.info(f"Auto-cancelling elicitation request: {params.message}")
+    return ElicitResult(action="cancel")
+
+
+async def forms_elicitation_handler(
+    context: RequestContext["ClientSession", Any], params: ElicitRequestParams
+) -> ElicitResult:
+    """
+    Interactive forms-based elicitation handler using enhanced input handler.
+    """
+    logger.info(f"Eliciting response for params: {params}")
+
+    # Get server config for additional context
+    server_config = get_server_config(context)
+    server_name = server_config.name if server_config else "Unknown Server"
+    server_info = (
+        {"command": server_config.command} if server_config and server_config.command else None
+    )
+
+    # Get agent name - try multiple sources in order of preference
+    agent_name: str | None = None
+
+    # 1. Check if we have an MCPAgentClientSession in the context
+    from mcp_agent.mcp.mcp_agent_client_session import MCPAgentClientSession
+    if hasattr(context, "session") and isinstance(context.session, MCPAgentClientSession):
+        agent_name = context.session.agent_name
+
+    # 2. If no agent name yet, use a sensible default
+    if not agent_name:
+        agent_name = "Unknown Agent"
+
+    # Create human input request
+    request = HumanInputRequest(
+        prompt=params.message,
+        description=f"Schema: {params.requestedSchema}" if params.requestedSchema else None,
+        request_id=f"elicit_{id(params)}",
+        metadata={
+            "agent_name": agent_name,
+            "server_name": server_name,
+            "elicitation": True,
+            "requested_schema": params.requestedSchema,
+        },
+    )
+
+    try:
+        # Call the enhanced elicitation handler
+        response = await elicitation_input_callback(
+            request=request,
+            agent_name=agent_name,
+            server_name=server_name,
+            server_info=server_info,
+        )
+
+        # Check for special action responses
+        response_data = response.response.strip()
+
+        # Handle special responses
+        if response_data == "__DECLINED__":
+            return ElicitResult(action="decline")
+        elif response_data == "__CANCELLED__":
+            return ElicitResult(action="cancel")
+        elif response_data == "__DISABLE_SERVER__":
+            # Log that user wants to disable elicitation for this server
+            logger.warning(f"User requested to disable elicitation for server: {server_name}")
+            # For now, just cancel - in a full implementation, this would update server config
+            return ElicitResult(action="cancel")
+
+        # Parse response based on schema if provided
+        if params.requestedSchema:
+            # Check if the response is already JSON (from our form)
+            try:
+                # Try to parse as JSON first (from schema-driven form)
+                content = json.loads(response_data)
+                # Validate that all required fields are present
+                required_fields = params.requestedSchema.get("required", [])
+                for field in required_fields:
+                    if field not in content:
+                        logger.warning(f"Missing required field '{field}' in elicitation response")
+                        return ElicitResult(action="decline")
+            except json.JSONDecodeError:
+                # Not JSON, try to handle as simple text response
+                # This is a fallback for simple schemas or text-based responses
+                properties = params.requestedSchema.get("properties", {})
+                if len(properties) == 1:
+                    # Single field schema - try to parse based on type
+                    field_name = list(properties.keys())[0]
+                    field_def = properties[field_name]
+                    field_type = field_def.get("type")
+
+                    if field_type == "boolean":
+                        # Parse boolean values
+                        if response_data.lower() in ["yes", "y", "true", "1"]:
+                            content = {field_name: True}
+                        elif response_data.lower() in ["no", "n", "false", "0"]:
+                            content = {field_name: False}
+                        else:
+                            return ElicitResult(action="decline")
+                    elif field_type == "string":
+                        content = {field_name: response_data}
+                    elif field_type in ["number", "integer"]:
+                        try:
+                            value = (
+                                int(response_data)
+                                if field_type == "integer"
+                                else float(response_data)
+                            )
+                            content = {field_name: value}
+                        except ValueError:
+                            return ElicitResult(action="decline")
+                    else:
+                        # Unknown type, just pass as string
+                        content = {field_name: response_data}
+                else:
+                    # Multiple fields but text response - can't parse reliably
+                    logger.warning("Text response provided for multi-field schema")
+                    return ElicitResult(action="decline")
+        else:
+            # No schema, just return the raw response
+            content = {"response": response_data}
+
+        # Return the response wrapped in ElicitResult with accept action
+        return ElicitResult(action="accept", content=content)
+    except (KeyboardInterrupt, EOFError, TimeoutError):
+        # User cancelled or timeout
+        return ElicitResult(action="cancel")

mcp_agent/mcp/helpers/content_helpers.py

@@ -11,6 +11,7 @@ from mcp.types import (
     BlobResourceContents,
     EmbeddedResource,
     ImageContent,
+    ReadResourceResult,
     TextContent,
     TextResourceContents,
 )
@@ -114,3 +115,29 @@ def is_resource_content(content: Union[TextContent, ImageContent, EmbeddedResour
         True if the content is EmbeddedResource, False otherwise
     """
     return isinstance(content, EmbeddedResource)
+
+
+def get_resource_text(result: ReadResourceResult, index: int = 0) -> Optional[str]:
+    """
+    Extract text content from a ReadResourceResult at the specified index.
+
+    Args:
+        result: A ReadResourceResult from an MCP resource read operation
+        index: Index of the content item to extract text from (default: 0)
+
+    Returns:
+        The text content as a string or None if not available or not text content
+
+    Raises:
+        IndexError: If the index is out of bounds for the contents list
+    """
+    if index >= len(result.contents):
+        raise IndexError(
+            f"Index {index} out of bounds for contents list of length {len(result.contents)}"
+        )
+
+    content = result.contents[index]
+    if isinstance(content, TextResourceContents):
+        return content.text
+
+    return None

mcp_agent/mcp/helpers/server_config_helpers.py

@@ -1,14 +1,12 @@
 """Helper functions for type-safe server config access."""
 
-from typing import TYPE_CHECKING, Optional
-
-from mcp import ClientSession
+from typing import TYPE_CHECKING, Any, Optional
 
 if TYPE_CHECKING:
     from mcp_agent.config import MCPServerSettings
 
 
-def get_server_config(ctx: ClientSession) -> Optional["MCPServerSettings"]:
+def get_server_config(ctx: Any) -> Optional["MCPServerSettings"]:
     """Extract server config from context if available.
     
     Type guard helper that safely accesses server_config with proper type checking.
@@ -16,8 +14,12 @@ def get_server_config(ctx: ClientSession) -> Optional["MCPServerSettings"]:
     # Import here to avoid circular import
     from mcp_agent.mcp.mcp_agent_client_session import MCPAgentClientSession
     
-    if (hasattr(ctx, "session") and 
-        isinstance(ctx.session, MCPAgentClientSession) and
-        ctx.session.server_config):
-        return ctx.session.server_config
+    # Check if ctx has a session attribute (RequestContext case)
+    if hasattr(ctx, "session"):
+        if isinstance(ctx.session, MCPAgentClientSession) and hasattr(ctx.session, 'server_config'):
+            return ctx.session.server_config
+    # Also check if ctx itself is MCPAgentClientSession (direct call case)
+    elif isinstance(ctx, MCPAgentClientSession) and hasattr(ctx, 'server_config'):
+        return ctx.server_config
+    
     return None

mcp_agent/mcp/interfaces.py

@@ -21,7 +21,7 @@ from typing import (
     runtime_checkable,
 )
 
-from a2a_types.types import AgentCard
+from a2a.types import AgentCard
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
 from deprecated import deprecated
 from mcp import ClientSession

mcp_agent/mcp/mcp_agent_client_session.py

@@ -13,7 +13,12 @@ from mcp.shared.session import (
     ReceiveResultT,
     SendRequestT,
 )
-from mcp.types import Implementation, ListRootsResult, Root, ToolListChangedNotification
+from mcp.types import (
+    Implementation,
+    ListRootsResult,
+    Root,
+    ToolListChangedNotification,
+)
 from pydantic import FileUrl
 
 from mcp_agent.context_dependent import ContextDependent
@@ -71,6 +76,10 @@ class MCPAgentClientSession(ClientSession, ContextDependent):
         self.server_config: MCPServerSettings | None = kwargs.pop("server_config", None)
         # Extract agent_model if provided (for auto_sampling fallback)
         self.agent_model: str | None = kwargs.pop("agent_model", None)
+        # Extract agent_name if provided
+        self.agent_name: str | None = kwargs.pop("agent_name", None)
+        # Extract custom elicitation handler if provided
+        custom_elicitation_handler = kwargs.pop("elicitation_handler", None)
 
         # Only register callbacks if the server_config has the relevant settings
         list_roots_cb = list_roots if (self.server_config and self.server_config.roots) else None
@@ -90,12 +99,46 @@ class MCPAgentClientSession(ClientSession, ContextDependent):
             # Auto-sampling enabled at application level
             sampling_cb = sample
 
+        # Use custom elicitation handler if provided, otherwise resolve using factory
+        if custom_elicitation_handler is not None:
+            elicitation_handler = custom_elicitation_handler
+        else:
+            # Try to resolve using factory
+            elicitation_handler = None
+            try:
+                from mcp_agent.context import get_current_context
+                from mcp_agent.core.agent_types import AgentConfig
+                from mcp_agent.mcp.elicitation_factory import resolve_elicitation_handler
+
+                context = get_current_context()
+                if context and context.config:
+                    # Create a minimal agent config for the factory
+                    agent_config = AgentConfig(
+                        name=self.agent_name or "unknown",
+                        model=self.agent_model or "unknown",
+                        elicitation_handler=None,  # No decorator-level handler since we're in the else block
+                    )
+                    elicitation_handler = resolve_elicitation_handler(
+                        agent_config, context.config, self.server_config
+                    )
+            except Exception:
+                # If factory resolution fails, we'll use default fallback
+                pass
+
+            # Fallback to forms handler only if factory resolution wasn't attempted
+            # If factory was attempted and returned None, respect that (means no elicitation capability)
+            if elicitation_handler is None and not self.server_config:
+                from mcp_agent.mcp.elicitation_handlers import forms_elicitation_handler
+
+                elicitation_handler = forms_elicitation_handler
+
         super().__init__(
             *args,
             **kwargs,
             list_roots_callback=list_roots_cb,
             sampling_callback=sampling_cb,
             client_info=fast_agent,
+            elicitation_callback=elicitation_handler,
         )
 
     def _should_enable_auto_sampling(self) -> bool:

mcp_agent/mcp/mcp_aggregator.py

@@ -217,19 +217,30 @@ class MCPAggregator(ContextDependent):
 
                 # Create a wrapper to capture the parameters for the client session
                 def session_factory(read_stream, write_stream, read_timeout, **kwargs):
-                    # Get agent's model if this aggregator is part of an agent
-                    agent_model = None
-                    if hasattr(self, 'config') and self.config and hasattr(self.config, 'model'):
+                    # Get agent's model and name if this aggregator is part of an agent
+                    agent_model: str | None = None
+                    agent_name: str | None = None
+                    elicitation_handler = None
+
+                    # Check if this aggregator is part of an Agent (which has config)
+                    # Import here to avoid circular dependency
+                    from mcp_agent.agents.base_agent import BaseAgent
+
+                    if isinstance(self, BaseAgent):
                         agent_model = self.config.model
-                    
+                        agent_name = self.config.name
+                        elicitation_handler = self.config.elicitation_handler
+
                     return MCPAgentClientSession(
                         read_stream,
                         write_stream,
                         read_timeout,
                         server_name=server_name,
                         agent_model=agent_model,
+                        agent_name=agent_name,
+                        elicitation_handler=elicitation_handler,
                         tool_list_changed_callback=self._handle_tool_list_changed,
-                        **kwargs  # Pass through any additional kwargs like server_config
+                        **kwargs,  # Pass through any additional kwargs like server_config
                     )
 
                 await self._persistent_connection_manager.get_server(
@@ -278,19 +289,27 @@ class MCPAggregator(ContextDependent):
             else:
                 # Create a factory function for the client session
                 def create_session(read_stream, write_stream, read_timeout, **kwargs):
-                    # Get agent's model if this aggregator is part of an agent
-                    agent_model = None
-                    if hasattr(self, 'config') and self.config and hasattr(self.config, 'model'):
+                    # Get agent's model and name if this aggregator is part of an agent
+                    agent_model: str | None = None
+                    agent_name: str | None = None
+
+                    # Check if this aggregator is part of an Agent (which has config)
+                    # Import here to avoid circular dependency
+                    from mcp_agent.agents.base_agent import BaseAgent
+
+                    if isinstance(self, BaseAgent):
                         agent_model = self.config.model
-                    
+                        agent_name = self.config.name
+
                     return MCPAgentClientSession(
                         read_stream,
                         write_stream,
                         read_timeout,
                         server_name=server_name,
                         agent_model=agent_model,
+                        agent_name=agent_name,
                         tool_list_changed_callback=self._handle_tool_list_changed,
-                        **kwargs  # Pass through any additional kwargs like server_config
+                        **kwargs,  # Pass through any additional kwargs like server_config
                     )
 
                 async with gen_client(
@@ -812,7 +831,9 @@ class MCPAggregator(ContextDependent):
             messages=[],
         )
 
-    async def list_prompts(self, server_name: str | None = None, agent_name: str | None = None) -> Mapping[str, List[Prompt]]:
+    async def list_prompts(
+        self, server_name: str | None = None, agent_name: str | None = None
+    ) -> Mapping[str, List[Prompt]]:
         """
         List available prompts from one or all servers.
 
@@ -940,11 +961,23 @@ class MCPAggregator(ContextDependent):
                 if self.connection_persistence:
                     # Create a factory function that will include our parameters
                     def create_session(read_stream, write_stream, read_timeout):
+                        # Get agent name if available
+                        agent_name: str | None = None
+
+                        # Import here to avoid circular dependency
+                        from mcp_agent.agents.base_agent import BaseAgent
+
+                        if isinstance(self, BaseAgent):
+                            agent_name = self.config.name
+                            elicitation_handler = self.config.elicitation_handler
+
                         return MCPAgentClientSession(
                             read_stream,
                             write_stream,
                             read_timeout,
                             server_name=server_name,
+                            agent_name=agent_name,
+                            elicitation_handler=elicitation_handler,
                             tool_list_changed_callback=self._handle_tool_list_changed,
                         )
 
@@ -956,11 +989,23 @@ class MCPAggregator(ContextDependent):
                 else:
                     # Create a factory function for the client session
                     def create_session(read_stream, write_stream, read_timeout):
+                        # Get agent name if available
+                        agent_name: str | None = None
+
+                        # Import here to avoid circular dependency
+                        from mcp_agent.agents.base_agent import BaseAgent
+
+                        if isinstance(self, BaseAgent):
+                            agent_name = self.config.name
+                            elicitation_handler = self.config.elicitation_handler
+
                         return MCPAgentClientSession(
                             read_stream,
                             write_stream,
                             read_timeout,
                             server_name=server_name,
+                            agent_name=agent_name,
+                            elicitation_handler=elicitation_handler,
                             tool_list_changed_callback=self._handle_tool_list_changed,
                         )
 

mcp_agent/mcp/mcp_connection_manager.py

@@ -166,10 +166,7 @@ class ServerConnection:
         )
 
         session = self._client_session_factory(
-            read_stream, 
-            send_stream, 
-            read_timeout,
-            server_config=self.server_config
+            read_stream, send_stream, read_timeout, server_config=self.server_config
         )
 
         self.session = session
@@ -220,19 +217,34 @@ async def _server_lifecycle_task(server_conn: ServerConnection) -> None:
 
         if "ExceptionGroup" in type(exc).__name__ and hasattr(exc, "exceptions"):
             # Handle ExceptionGroup better by extracting the actual errors
-            error_messages = []
-            for subexc in exc.exceptions:
-                if isinstance(subexc, HTTPStatusError):
-                    # Special handling for HTTP errors to make them more user-friendly
-                    error_messages.append(
-                        f"HTTP Error: {subexc.response.status_code} {subexc.response.reason_phrase} for URL: {subexc.request.url}"
-                    )
-                else:
-                    error_messages.append(f"Error: {type(subexc).__name__}: {subexc}")
-                if hasattr(subexc, "__cause__") and subexc.__cause__:
-                    error_messages.append(
-                        f"Caused by: {type(subexc.__cause__).__name__}: {subexc.__cause__}"
-                    )
+            def extract_errors(exception_group):
+                """Recursively extract meaningful errors from ExceptionGroups"""
+                messages = []
+                for subexc in exception_group.exceptions:
+                    if "ExceptionGroup" in type(subexc).__name__ and hasattr(subexc, "exceptions"):
+                        # Recursively handle nested ExceptionGroups
+                        messages.extend(extract_errors(subexc))
+                    elif isinstance(subexc, HTTPStatusError):
+                        # Special handling for HTTP errors to make them more user-friendly
+                        messages.append(
+                            f"HTTP Error: {subexc.response.status_code} {subexc.response.reason_phrase} for URL: {subexc.request.url}"
+                        )
+                    else:
+                        # Show the exception type and message, plus the root cause if available
+                        error_msg = f"{type(subexc).__name__}: {subexc}"
+                        messages.append(error_msg)
+
+                        # If there's a root cause, show that too as it's often the most informative
+                        if hasattr(subexc, "__cause__") and subexc.__cause__:
+                            messages.append(
+                                f"Caused by: {type(subexc.__cause__).__name__}: {subexc.__cause__}"
+                            )
+                return messages
+
+            error_messages = extract_errors(exc)
+            # If we didn't extract any meaningful errors, fall back to the original exception
+            if not error_messages:
+                error_messages = [f"{type(exc).__name__}: {exc}"]
             server_conn._error_message = error_messages
         else:
             # For regular exceptions, keep the traceback but format it more cleanly
@@ -309,7 +321,7 @@ class MCPConnectionManager(ContextDependent):
             self._tg = self._task_group
             logger.info(f"Auto-created task group for server: {server_name}")
 
-        config = self.server_registry.registry.get(server_name)
+        config = self.server_registry.get_server_config(server_name)
         if not config:
             raise ValueError(f"Server '{server_name}' not found in registry.")
 

mcp_agent/mcp_server/agent_server.py

@@ -65,6 +65,8 @@ class AgentMCPServer:
         @self.mcp_server.tool(
             name=f"{agent_name}_send",
             description=f"Send a message to the {agent_name} agent",
+            structured_output=False,
+            # MCP 1.10.1 turns every tool in to a structured output
         )
         async def send_message(message: str, ctx: MCPContext) -> str:
             """Send a message to the agent and return its response."""

mcp_agent/mcp_server_registry.py

@@ -73,7 +73,11 @@ class ServerRegistry:
         """
         if config is None:
             self.registry = self.load_registry_from_file(config_path)
-        elif config.mcp is not None and hasattr(config.mcp, 'servers') and config.mcp.servers is not None:
+        elif (
+            config.mcp is not None
+            and hasattr(config.mcp, "servers")
+            and config.mcp.servers is not None
+        ):
             # Ensure config.mcp exists, has a 'servers' attribute, and it's not None
             self.registry = config.mcp.servers
         else:
@@ -95,13 +99,17 @@ class ServerRegistry:
         Raises:
             ValueError: If the configuration is invalid.
         """
-        servers = {} 
+        servers = {}
 
         settings = get_settings(config_path)
-        
-        if settings.mcp is not None and hasattr(settings.mcp, 'servers') and settings.mcp.servers is not None:
+
+        if (
+            settings.mcp is not None
+            and hasattr(settings.mcp, "servers")
+            and settings.mcp.servers is not None
+        ):
             return settings.mcp.servers
-        
+
         return servers
 
     @asynccontextmanager
@@ -164,7 +172,7 @@ class ServerRegistry:
                     read_stream,
                     write_stream,
                     read_timeout_seconds,
-                    None,  # No callback for stdio
+                    server_config=config,
                 )
                 async with session:
                     logger.info(f"{server_name}: Connected to server using stdio transport.")
@@ -192,7 +200,7 @@ class ServerRegistry:
                     read_stream,
                     write_stream,
                     read_timeout_seconds,
-                    None,  # No callback for stdio
+                    server_config=config,
                 )
                 async with session:
                     logger.info(f"{server_name}: Connected to server using SSE transport.")
@@ -216,7 +224,7 @@ class ServerRegistry:
                     read_stream,
                     write_stream,
                     read_timeout_seconds,
-                    None,  # No callback for stdio
+                    server_config=config,
                 )
                 async with session:
                     logger.info(f"{server_name}: Connected to server using HTTP transport.")