fast-agent-mcp 0.4.7__py3-none-any.whl

fast_agent/mcp/elicitation_factory.py

@@ -0,0 +1,84 @@
+"""
+Factory for resolving elicitation handlers with proper precedence.
+"""
+
+from typing import Any
+
+from mcp.client.session import ElicitationFnT
+
+from fast_agent.agents.agent_types import AgentConfig
+from fast_agent.core.logging.logger import get_logger
+from fast_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
+) -> ElicitationFnT | None:
+    """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

fast_agent/mcp/elicitation_handlers.py

@@ -0,0 +1,164 @@
+"""
+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 fast_agent.core.logging.logger import get_logger
+from fast_agent.human_input.elicitation_handler import elicitation_input_callback
+from fast_agent.human_input.types import HumanInputRequest
+from fast_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 fast_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__":
+            # Respect user's request: disable elicitation for this server for this session
+            logger.warning(
+                f"User requested to disable elicitation for server: {server_name} — disabling for session"
+            )
+            try:
+                from fast_agent.human_input.elicitation_state import elicitation_state
+
+                elicitation_state.disable_server(server_name)
+            except Exception:
+                # Do not fail the flow if state update fails
+                pass
+            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 = next(iter(properties))
+                    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")

fast_agent/mcp/gen_client.py

@@ -0,0 +1,83 @@
+from contextlib import asynccontextmanager
+from datetime import timedelta
+from typing import AsyncGenerator, Callable
+
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+from mcp import ClientSession
+
+from fast_agent.core.logging.logger import get_logger
+from fast_agent.mcp.interfaces import ServerRegistryProtocol
+from fast_agent.mcp.mcp_agent_client_session import MCPAgentClientSession
+
+logger = get_logger(__name__)
+
+
+@asynccontextmanager
+async def gen_client(
+    server_name: str,
+    server_registry: ServerRegistryProtocol,
+    client_session_factory: Callable[
+        [MemoryObjectReceiveStream, MemoryObjectSendStream, timedelta | None],
+        ClientSession,
+    ] = MCPAgentClientSession,
+) -> AsyncGenerator[ClientSession, None]:
+    """
+    Create a client session to the specified server.
+    Handles server startup, initialization, and message receive loop setup.
+    If required, callers can specify their own message receive loop and ClientSession class constructor to customize further.
+    For persistent connections, use connect() or MCPConnectionManager instead.
+    """
+    if not server_registry:
+        raise ValueError(
+            "Server registry not found in the context. Please specify one either on this method, or in the context."
+        )
+
+    async with server_registry.initialize_server(
+        server_name=server_name,
+        client_session_factory=client_session_factory,
+    ) as session:
+        yield session
+
+
+async def connect(
+    server_name: str,
+    server_registry: ServerRegistryProtocol,
+    client_session_factory: Callable[
+        [MemoryObjectReceiveStream, MemoryObjectSendStream, timedelta | None],
+        ClientSession,
+    ] = MCPAgentClientSession,
+) -> ClientSession:
+    """
+    Create a persistent client session to the specified server.
+    Handles server startup, initialization, and message receive loop setup.
+    If required, callers can specify their own message receive loop and ClientSession class constructor to customize further.
+    """
+    if not server_registry:
+        raise ValueError(
+            "Server registry not found in the context. Please specify one either on this method, or in the context."
+        )
+
+    server_connection = await server_registry.connection_manager.get_server(
+        server_name=server_name,
+        client_session_factory=client_session_factory,
+    )
+
+    return server_connection.session
+
+
+async def disconnect(
+    server_name: str | None,
+    server_registry: ServerRegistryProtocol,
+) -> None:
+    """
+    Disconnect from the specified server. If server_name is None, disconnect from all servers.
+    """
+    if not server_registry:
+        raise ValueError(
+            "Server registry not found in the context. Please specify one either on this method, or in the context."
+        )
+
+    if server_name:
+        await server_registry.connection_manager.disconnect_server(server_name=server_name)
+    else:
+        await server_registry.connection_manager.disconnect_all_servers()

fast_agent/mcp/helpers/__init__.py

@@ -0,0 +1,36 @@
+"""
+Helper modules for working with MCP content (Fast Agent namespace).
+
+This mirrors the legacy fast_agent.mcp.helpers API to provide a stable,
+cycle-free import path now that PromptMessageExtended lives in fast_agent.mcp.
+"""
+
+from .content_helpers import (
+    ensure_multipart_messages,
+    get_image_data,
+    get_resource_text,
+    get_resource_uri,
+    get_text,
+    is_image_content,
+    is_resource_content,
+    is_resource_link,
+    is_text_content,
+    normalize_to_extended_list,
+    split_thinking_content,
+    text_content,
+)
+
+__all__ = [
+    "get_text",
+    "get_image_data",
+    "get_resource_uri",
+    "is_text_content",
+    "is_image_content",
+    "is_resource_content",
+    "is_resource_link",
+    "get_resource_text",
+    "ensure_multipart_messages",
+    "normalize_to_extended_list",
+    "split_thinking_content",
+    "text_content",
+]