aip-agents-binary 0.5.20__py3-none-any.whl → 0.5.22__py3-none-any.whl

aip_agents/mcp/client/base_mcp_client.pyi

@@ -0,0 +1,148 @@
+from _typeshed import Incomplete
+from abc import ABC, abstractmethod
+from aip_agents.mcp.client.persistent_session import PersistentMCPSession as PersistentMCPSession
+from aip_agents.mcp.client.session_pool import MCPSessionPool as MCPSessionPool
+from aip_agents.utils.logger import get_logger as get_logger
+from gllm_tools.mcp.client.client import MCPClient
+from gllm_tools.mcp.client.config import MCPConfiguration as MCPConfiguration
+from mcp.types import CallToolResult, Tool as Tool
+from typing import Any
+
+logger: Incomplete
+
+class BaseMCPClient(MCPClient, ABC):
+    """Base MCP Client with persistent session management for aip-agents.
+
+    This class provides:
+    - Persistent session management across tool calls
+    - One-time tool registration and caching
+    - Automatic connection health monitoring and reconnection
+    - Centralized cleanup of all MCP resources
+    - Generic tool discovery from all configured MCP servers
+
+    Subclasses should implement SDK-specific tool conversion in _process_tool() method.
+    """
+    session_pool: Incomplete
+    def __init__(self, servers: dict[str, MCPConfiguration]) -> None:
+        """Initialize the base MCP client with session pool.
+
+        Args:
+            servers (dict[str, MCPConfiguration]): Dictionary of MCP server configurations by server name
+        """
+    async def initialize(self) -> None:
+        """Initialize all MCP sessions and cache tools once.
+
+        This method is idempotent and only performs initialization if not already done.
+        It establishes persistent connections to all configured MCP servers and caches
+        available tools for efficient access.
+
+        Raises:
+            Exception: If any session initialization fails
+        """
+    @abstractmethod
+    async def get_tools(self, server: str | None = None) -> list[Any]:
+        """Get framework-specific tools from MCP servers.
+
+        This method must be implemented by subclasses to provide framework-specific
+        tool conversion (e.g., StructuredTool for LangChain, FunctionTool for Google ADK).
+
+        Args:
+            server (str | None): Optional server name to filter tools from a specific server.
+                    If None, returns tools from all configured servers.
+
+        Returns:
+            list[Any]: List of framework-specific tool objects.
+        """
+    async def get_raw_mcp_tools(self, server: str | None = None) -> list[Tool]:
+        """Get raw MCP tools - for subclasses to perform framework-specific conversions.
+
+        This method provides access to the cached raw MCP Tool objects.
+        Subclasses use this to convert to framework-specific tools.
+
+        Args:
+            server (str | None): Optional server name to filter tools from a specific server.
+                    If None, returns tools from all configured servers.
+
+        Returns:
+            list[Tool]: List of raw MCP Tool objects. Empty list if not initialized or no tools available.
+        """
+    def get_tools_count(self, server: str | None = None) -> int:
+        """Get count of raw MCP tools without expensive copying.
+
+        This is an efficient way to get tool counts for logging/metrics
+        without the overhead of copying tool lists.
+
+        Args:
+            server (str | None): Optional server name to filter tools from a specific server.
+                    If None, returns count from all configured servers.
+
+        Returns:
+            int: Count of raw MCP tools available.
+        """
+    async def get_session(self, server_name: str) -> PersistentMCPSession:
+        """Get a persistent session for a specific server.
+
+        Args:
+            server_name (str): The name of the MCP server
+
+        Returns:
+            PersistentMCPSession: Persistent MCP session for the specified server
+
+        Raises:
+            KeyError: If the server is not configured or no active session exists
+        """
+    async def call_tool(self, server_name: str, tool_name: str, arguments: dict[str, Any]) -> CallToolResult:
+        """Execute a tool on a specific MCP server using persistent session.
+
+        Args:
+            server_name (str): The MCP server to execute the tool on
+            tool_name (str): The name of the tool to execute
+            arguments (dict[str, Any]): Arguments for the tool execution
+
+        Returns:
+            CallToolResult: The result of the tool execution
+
+        Raises:
+            KeyError: If the server doesn't exist
+            Exception: If tool execution fails
+        """
+    async def read_resource(self, server_name: str, resource_uri: str):
+        """Read an MCP resource from a specific server using persistent session.
+
+        Args:
+            server_name (str): The MCP server to read the resource from
+            resource_uri (str): The URI of the resource to read
+
+        Returns:
+            Any: The resource content
+
+        Raises:
+            KeyError: If the server doesn't exist
+            Exception: If resource reading fails
+        """
+    async def cleanup(self) -> None:
+        """Clean up all MCP resources and close sessions.
+
+        This method properly closes all persistent sessions and cleans up resources.
+        It can be called multiple times safely.
+        """
+    @property
+    def is_initialized(self) -> bool:
+        """Check if the client is fully initialized.
+
+        Returns:
+            bool: True if sessions are initialized and tools are cached, False otherwise
+        """
+    @property
+    def active_sessions(self) -> dict[str, PersistentMCPSession]:
+        """Get all active persistent sessions.
+
+        Returns:
+            dict[str, PersistentMCPSession]: Dictionary of active sessions by server name
+        """
+    def get_session_count(self) -> int:
+        """Get the number of active MCP sessions.
+
+        Returns:
+            Number of active persistent sessions
+        """

aip_agents/mcp/client/connection_manager.pyi

@@ -0,0 +1,48 @@
+from _typeshed import Incomplete
+from aip_agents.mcp.client.transports import TransportType as TransportType, create_transport as create_transport
+from aip_agents.utils.logger import get_logger as get_logger
+from gllm_tools.mcp.client.config import MCPConfiguration
+from typing import Any
+
+logger: Incomplete
+
+class MCPConnectionManager:
+    """Manages MCP connection lifecycle following mcp-use patterns.
+
+    This connection manager handles the transport connection lifecycle in a background
+    task to avoid cancel scope issues during cleanup. It supports automatic transport
+    negotiation (HTTP -> SSE fallback) and graceful shutdown. Invalid explicit transports
+    are normalized via aliases (e.g., 'streamable_http' -> 'http') or fall back to
+    auto-detection with a warning.
+    """
+    TRANSPORT_ALIASES: Incomplete
+    server_name: Incomplete
+    config: Incomplete
+    transport_type: Incomplete
+    max_retries: Incomplete
+    initial_retry_delay: Incomplete
+    def __init__(self, server_name: str, config: MCPConfiguration) -> None:
+        """Initialize connection manager.
+
+        Args:
+            server_name (str): Name of the MCP server
+            config (MCPConfiguration): MCP server configuration
+        """
+    async def start(self) -> tuple[Any, Any]:
+        """Start connection in background task.
+
+        Returns:
+            tuple[Any, Any]: Tuple of (read_stream, write_stream) for ClientSession
+
+        Raises:
+            Exception: If connection establishment fails
+        """
+    async def stop(self) -> None:
+        """Stop connection gracefully."""
+    @property
+    def is_connected(self) -> bool:
+        """Check if connection is active.
+
+        Returns:
+            bool: True if connected, False otherwise
+        """

aip_agents/mcp/client/google_adk/__init__.pyi

@@ -0,0 +1,3 @@
+from aip_agents.mcp.client.google_adk.client import GoogleADKMCPClient as GoogleADKMCPClient
+
+__all__ = ['GoogleADKMCPClient']

aip_agents/mcp/client/google_adk/client.pyi

@@ -0,0 +1,75 @@
+from _typeshed import Incomplete
+from aip_agents.mcp.client.base_mcp_client import BaseMCPClient as BaseMCPClient
+from aip_agents.utils.logger import get_logger as get_logger
+from gllm_tools.mcp.client.config import MCPConfiguration as MCPConfiguration
+from google.adk.tools import FunctionTool
+from mcp.types import EmbeddedResource, ImageContent
+
+NonTextContent = ImageContent | EmbeddedResource
+logger: Incomplete
+
+class GoogleADKMCPClient(BaseMCPClient):
+    '''Google ADK MCP Client with Persistent Sessions.
+
+    This client extends BaseMCPClient to provide Google ADK-specific tool conversion
+    while maintaining persistent MCP sessions and connection reuse across tool calls.
+    It converts MCP tools into ADK FunctionTool instances for seamless integration.
+
+    The client handles:
+    - Converting MCP tools to ADK FunctionTool instances using persistent sessions
+    - Managing MCP server connections with automatic reconnection
+    - Converting MCP resources to ADK-compatible formats
+    - Handling tool execution with proper error formatting for ADK agents
+
+    Example:
+        ```python
+        from aip_agents.mcp.client.google_adk.client import GoogleADKMCPClient
+        from gllm_tools.mcp.client.config import MCPConfiguration
+
+        servers = {
+            "filesystem": MCPConfiguration(
+                command="npx",
+                args=["-y", "@modelcontextprotocol/server-filesystem", "/path/to/folder"]
+            )
+        }
+
+        client = GoogleADKMCPClient(servers)
+        await client.initialize()  # Initialize persistent sessions
+        tools = await client.get_tools()  # Returns list of ADK FunctionTool instances
+        ```
+    '''
+    RESOURCE_FETCH_TIMEOUT: int
+    def __init__(self, servers: dict[str, MCPConfiguration]) -> None:
+        """Initialize Google ADK MCP client.
+
+        Args:
+            servers (dict[str, MCPConfiguration]): Dictionary of MCP server configurations
+        """
+    async def initialize(self) -> None:
+        """Initialize persistent MCP sessions for Google ADK integration.
+
+        This method ensures all MCP servers are connected with persistent sessions
+        and prepares the client for ADK tool conversion.
+
+        Raises:
+            Exception: If session initialization fails
+        """
+    async def get_tools(self, server: str | None = None) -> list[FunctionTool]:
+        """Get ADK-compatible FunctionTool instances with smart caching.
+
+        Converts MCP tools to ADK format and caches them for better performance
+        on repeated access. Cache is keyed by server parameter.
+
+        Args:
+            server (str | None): Optional server name to filter tools from a specific server.
+                    If None, returns tools from all configured servers.
+
+        Returns:
+            list[FunctionTool]: List of cached ADK FunctionTool instances.
+        """
+    async def cleanup(self) -> None:
+        """Clean up Google ADK MCP client resources.
+
+        This method ensures all persistent sessions are properly closed and
+        ADK-specific resources are cleaned up.
+        """

aip_agents/mcp/client/langchain/__init__.pyi

@@ -0,0 +1,3 @@
+from aip_agents.mcp.client.langchain.client import LangchainMCPClient as LangchainMCPClient
+
+__all__ = ['LangchainMCPClient']

aip_agents/mcp/client/langchain/client.pyi

@@ -0,0 +1,48 @@
+from _typeshed import Incomplete
+from aip_agents.mcp.client.base_mcp_client import BaseMCPClient as BaseMCPClient
+from aip_agents.utils.logger import get_logger as get_logger
+from gllm_tools.mcp.client.config import MCPConfiguration as MCPConfiguration
+from langchain_core.tools import StructuredTool
+from mcp.types import EmbeddedResource, ImageContent
+
+NonTextContent = ImageContent | EmbeddedResource
+logger: Incomplete
+
+class LangchainMCPClient(BaseMCPClient):
+    """Langchain MCP Client with Session Persistence.
+
+    This client extends BaseMCPClient to provide LangChain-specific tool conversion
+    while maintaining persistent MCP sessions and connection reuse across tool calls.
+    """
+    RESOURCE_FETCH_TIMEOUT: int
+    def __init__(self, servers: dict[str, MCPConfiguration]) -> None:
+        """Initialize LangChain MCP client.
+
+        Args:
+            servers (dict[str, MCPConfiguration]): Dictionary of MCP server configurations
+        """
+    async def initialize(self) -> None:
+        """Initialize all sessions for LangChain client.
+
+        This method initializes the base MCP sessions and prepares for tool caching.
+
+        Raises:
+            Exception: If base initialization fails
+        """
+    async def get_tools(self, server: str | None = None) -> list[StructuredTool]:
+        """Get LangChain StructuredTools with smart caching.
+
+        Converts MCP tools to LangChain format and caches them for better performance
+        on repeated access. Cache is keyed by server parameter.
+
+        Args:
+            server (str | None): Optional server name to filter tools. If None, returns all tools.
+
+        Returns:
+            list[StructuredTool]: List of cached LangChain StructuredTool instances
+        """
+    async def cleanup(self) -> None:
+        """Cleanup LangChain MCP resources.
+
+        This method extends base class cleanup and clears the LangChain tool cache.
+        """

aip_agents/mcp/client/persistent_session.pyi

@@ -0,0 +1,113 @@
+from _typeshed import Incomplete
+from aip_agents.mcp.client.connection_manager import MCPConnectionManager as MCPConnectionManager
+from aip_agents.mcp.utils.config_validator import validate_allowed_tools_list as validate_allowed_tools_list
+from aip_agents.utils.logger import get_logger as get_logger
+from gllm_tools.mcp.client.config import MCPConfiguration
+from mcp import ClientSession
+from mcp.types import CallToolResult, Tool as Tool
+from typing import Any
+
+logger: Incomplete
+
+class PersistentMCPSession:
+    """Persistent MCP session that reuses connections.
+
+    This session wrapper manages the connection lifecycle and caches tools
+    to avoid repeated initialization overhead. It provides automatic reconnection
+    and thread-safe operations.
+
+    Tool Filtering:
+        When allowed_tools is configured, tools are filtered inline during list_tools()
+        and permission checked in call_tool() using set lookup.
+    """
+    server_name: Incomplete
+    config: Incomplete
+    connection_manager: Incomplete
+    client_session: ClientSession | None
+    tools: list[Tool]
+    def __init__(self, server_name: str, config: MCPConfiguration, allowed_tools: list[str] | None = None) -> None:
+        """Initialize persistent session.
+
+        Args:
+            server_name: Name of the MCP server
+            config: MCP server configuration
+            allowed_tools: Optional list of tool names to allow. None or empty means all tools allowed.
+        """
+    async def initialize(self) -> None:
+        """Initialize session once and cache tools.
+
+        This method is idempotent and can be called multiple times safely.
+
+        Raises:
+            Exception: If session initialization fails
+        """
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> CallToolResult:
+        """Call MCP tool using persistent session.
+
+        Args:
+            name (str): Tool name
+            arguments (dict[str, Any]): Tool arguments
+
+        Returns:
+            CallToolResult: Tool call result
+
+        Raises:
+            Exception: If tool call fails
+        """
+    async def read_resource(self, uri: str) -> Any:
+        """Read an MCP resource using persistent session.
+
+        Args:
+            uri (str): The URI of the resource to read
+
+        Returns:
+            Any: The resource content
+
+        Raises:
+            Exception: If resource reading fails
+        """
+    async def list_tools(self) -> list[Tool]:
+        """Get cached tools list with allowed tools filtering applied.
+
+        Returns:
+            list[Tool]: a copy of list of available tools, filtered to only allowed tools if configured
+        """
+    def get_tools_count(self) -> int:
+        """Get count of allowed tools.
+
+        Returns:
+            Count of allowed tools
+        """
+    async def ensure_connected(self) -> None:
+        """Ensure connection is healthy, reconnect if needed.
+
+        This method provides automatic reconnection capability.
+
+        Raises:
+            Exception: If reconnection fails
+        """
+    async def disconnect(self) -> None:
+        """Disconnect session gracefully.
+
+        This method cleans up all resources and connections.
+        """
+    @property
+    def is_initialized(self) -> bool:
+        """Check if session is initialized.
+
+        Returns:
+            bool: True if initialized and connected, False otherwise
+        """
+    def update_allowed_tools(self, allowed_tools: list[str] | None) -> bool:
+        """Update the list of allowed tools for this session.
+
+        Args:
+            allowed_tools: New list of allowed tool names or None for no restriction.
+                None and empty list both mean 'no restrictions, allow all tools'.
+
+        Returns:
+            bool: True if the configuration changed, False otherwise.
+
+        Raises:
+            ValueError: If allowed_tools contains invalid entries.
+        """

aip_agents/mcp/client/session_pool.pyi

@@ -0,0 +1,101 @@
+from _typeshed import Incomplete
+from aip_agents.mcp.client.persistent_session import PersistentMCPSession as PersistentMCPSession
+from aip_agents.mcp.utils.config_validator import validate_allowed_tools_config as validate_allowed_tools_config, validate_allowed_tools_list as validate_allowed_tools_list
+from aip_agents.utils.logger import get_logger as get_logger
+from gllm_tools.mcp.client.config import MCPConfiguration
+from mcp.types import Tool as Tool
+
+logger: Incomplete
+
+class MCPSessionPool:
+    """Manages pool of persistent MCP sessions.
+
+    This pool provides centralized management of MCP sessions, including
+    initialization, tool collection, and resource cleanup. Sessions are
+    reused across the agent lifecycle.
+    """
+    sessions: dict[str, PersistentMCPSession]
+    def __init__(self) -> None:
+        """Initialize empty session pool."""
+    async def get_or_create_session(self, server_name: str, config: MCPConfiguration, allowed_tools: list[str] | None = None) -> PersistentMCPSession:
+        """Get existing session or create new one.
+
+        Args:
+            server_name (str): Name of the MCP server
+            config (MCPConfiguration): MCP server configuration
+            allowed_tools (list[str] | None): Optional list of tool names to allow. None means all tools allowed.
+
+        Returns:
+            PersistentMCPSession: Persistent MCP session
+
+        Raises:
+            Exception: If session creation fails
+        """
+    async def initialize_all_sessions(self, server_configs: dict[str, MCPConfiguration]) -> None:
+        """Initialize all sessions and cache tools.
+
+        This method initializes all configured MCP servers concurrently
+        for better performance.
+
+        Args:
+            server_configs (dict[str, MCPConfiguration]): Dictionary of server configurations
+
+        Raises:
+            Exception: If any session initialization fails
+        """
+    def get_all_active_sessions(self) -> dict[str, PersistentMCPSession]:
+        """Get all active sessions.
+
+        Returns:
+            dict[str, PersistentMCPSession]: Dictionary of active sessions by server name
+        """
+    @property
+    def active_sessions(self) -> list[str]:
+        """Get list of active session names.
+
+        Returns:
+            list[str]: List of active session names
+        """
+    async def get_all_tools(self) -> list[Tool]:
+        """Get all cached tools from all active sessions.
+
+        Returns:
+            list[Tool]: List of all available tools across all sessions
+        """
+    async def close_session(self, server_name: str) -> None:
+        """Close specific session.
+
+        Args:
+            server_name (str): Name of the server session to close
+        """
+    async def close_all_sessions(self) -> None:
+        """Close all sessions gracefully.
+
+        This method ensures all resources are cleaned up properly.
+        """
+    @property
+    def is_initialized(self) -> bool:
+        """Check if session pool is initialized.
+
+        Returns:
+            bool: True if initialized, False otherwise
+        """
+    @property
+    def session_count(self) -> int:
+        """Get number of active sessions.
+
+        Returns:
+            int: Number of active sessions
+        """
+    def get_session(self, server_name: str) -> PersistentMCPSession:
+        """Get specific session by name.
+
+        Args:
+            server_name (str): Name of the server
+
+        Returns:
+            PersistentMCPSession: The requested session
+
+        Raises:
+            KeyError: If session doesn't exist
+        """

aip_agents/mcp/client/transports.pyi

@@ -0,0 +1,123 @@
+from _typeshed import Incomplete
+from abc import ABC, abstractmethod
+from aip_agents.utils.logger import get_logger as get_logger
+from collections.abc import AsyncIterator as AsyncIterator
+from enum import StrEnum
+from gllm_tools.mcp.client.config import MCPConfiguration
+from typing import Any, Protocol
+
+class TransportContext(Protocol):
+    """Protocol defining the interface for async context managers used in MCP transport connections."""
+    async def __aenter__(self) -> None:
+        """Enter the async context, establishing the connection and returning read/write streams."""
+    async def __aexit__(self, _exc_type, _exc_val, _exc_tb) -> None:
+        """Exit the async context, performing cleanup and closing the connection.
+
+        Args:
+            _exc_type: Exception type if an exception occurred.
+            _exc_val: Exception value if an exception occurred.
+            _exc_tb: Exception traceback if an exception occurred.
+        """
+
+logger: Incomplete
+DEFAULT_TIMEOUT: float
+
+class TransportType(StrEnum):
+    """Enum for supported MCP transport types."""
+    HTTP: str
+    SSE: str
+    STDIO: str
+
+class Transport(ABC):
+    """Abstract base class for MCP transports."""
+    server_name: Incomplete
+    config: Incomplete
+    ctx: Any
+    def __init__(self, server_name: str, config: MCPConfiguration) -> None:
+        """Initialize the transport.
+
+        Args:
+            server_name (str): Name of the MCP server.
+            config (MCPConfiguration): Configuration for the transport.
+        """
+    @abstractmethod
+    async def connect(self) -> tuple[AsyncIterator[bytes], AsyncIterator[bytes], TransportContext]:
+        """Establish connection and return read/write streams and context manager.
+
+        Returns:
+            tuple[AsyncIterator[bytes], AsyncIterator[bytes], Any]:
+                (read_stream, write_stream, ctx)
+            Where:
+                - read_stream: AsyncIterator[bytes] for reading from the server.
+                - write_stream: AsyncIterator[bytes] for writing to the server.
+                - ctx: The async context manager instance for cleanup via __aexit__.
+
+        Raises:
+            ValueError: If required config (e.g., URL or command) is missing.
+            ConnectionError: If connection establishment fails.
+        """
+    async def close(self) -> None:
+        """Clean up the transport connection."""
+
+class SSETransport(Transport):
+    """SSE transport handler."""
+    ctx: Incomplete
+    async def connect(self) -> tuple[AsyncIterator[bytes], AsyncIterator[bytes], TransportContext]:
+        """Connect using SSE transport.
+
+        Builds SSE URL from config, initializes client with timeout, and enters context.
+
+        Returns:
+            tuple[AsyncIterator[bytes], AsyncIterator[bytes], Any]: (read_stream, write_stream, ctx)
+
+        Raises:
+            ValueError: If URL is missing.
+            ConnectionError: If SSE connection fails.
+        """
+
+class HTTPTransport(Transport):
+    """Streamable HTTP transport handler."""
+    ctx: Incomplete
+    async def connect(self) -> tuple[AsyncIterator[bytes], AsyncIterator[bytes], TransportContext]:
+        """Connect using streamable HTTP transport.
+
+        Builds MCP URL from config, initializes client with timeout, and enters context.
+
+        Returns:
+            tuple[AsyncIterator[bytes], AsyncIterator[bytes], Any]: (read_stream, write_stream, ctx)
+
+        Raises:
+            ValueError: If URL is missing.
+            ConnectionError: If HTTP connection fails.
+        """
+
+class StdioTransport(Transport):
+    """STDIO transport handler."""
+    ctx: Incomplete
+    async def connect(self) -> tuple[AsyncIterator[bytes], AsyncIterator[bytes], TransportContext]:
+        """Connect using STDIO transport.
+
+        Initializes stdio client from command/args/env in config and enters context.
+
+        Returns:
+            tuple[AsyncIterator[bytes], AsyncIterator[bytes], Any]: (read_stream, write_stream, ctx)
+
+        Raises:
+            ValueError: If command is missing.
+            ConnectionError: If STDIO connection fails.
+        """
+
+def create_transport(server_name: str, config: MCPConfiguration, transport_type: TransportType | str) -> Transport:
+    """Factory to create the appropriate transport instance.
+
+    Args:
+        server_name (str): Server name
+        config (MCPConfiguration): Config
+        transport_type (str): Transport type ('http', 'sse', 'stdio')
+
+    Returns:
+        Transport: Concrete transport instance
+
+    Raises:
+        ValueError: If transport_type is unsupported.
+    """