aip-agents-binary 0.5.25b8__py3-none-any.whl → 0.6.0__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.py

@@ -60,6 +60,9 @@ class MCPConnectionManager:
     async def start(self) -> tuple[Any, Any]:
         """Start connection in background task.
 
+        For HTTP/SSE transports, establishes connection directly to avoid anyio context issues.
+        For stdio transport, uses background task to manage subprocess lifecycle.
+
         Returns:
             tuple[Any, Any]: Tuple of (read_stream, write_stream) for ClientSession
 
@@ -67,6 +70,17 @@ class MCPConnectionManager:
             Exception: If connection establishment fails
         """
         logger.debug(f"Starting connection manager for {self.server_name}")
+
+        # Determine transport type first
+        self.transport_type = self._get_transport_type()
+
+        # For HTTP/SSE: connect directly (no background task needed)
+        # This avoids anyio.BrokenResourceError when streams cross task boundaries
+        if self.transport_type in (TransportType.HTTP, TransportType.SSE):
+            await self._establish_connection()
+            return self._connection
+
+        # For stdio: use background task to manage subprocess
         self._task = asyncio.create_task(self._connection_task())
         await self._ready_event.wait()
 
@@ -78,6 +92,20 @@ class MCPConnectionManager:
     async def stop(self) -> None:
         """Stop connection gracefully."""
         logger.debug(f"Stopping connection manager for {self.server_name}")
+
+        # For HTTP/SSE (no background task), just close transport
+        if self.transport_type in (TransportType.HTTP, TransportType.SSE):
+            if self._transport:
+                try:
+                    close_result = self._transport.close()
+                    if inspect.isawaitable(close_result):
+                        await close_result
+                except Exception as exc:
+                    logger.warning(f"Failed to close transport cleanly for {self.server_name}: {exc}")
+            self._connection = None
+            return
+
+        # For stdio (with background task), wait for task to finish
         if self._task and not self._task.done():
             self._stop_event.set()
             try:
@@ -94,6 +122,11 @@ class MCPConnectionManager:
         Returns:
             bool: True if connected, False otherwise
         """
+        # For HTTP/SSE (no background task), just check if connection exists
+        if self.transport_type in (TransportType.HTTP, TransportType.SSE):
+            return self._connection is not None
+
+        # For stdio (with background task), check task status too
         return (
             self._connection is not None
             and self._task is not None
@@ -144,7 +177,9 @@ class MCPConnectionManager:
         Raises:
             ConnectionError: If all connection attempts fail
         """
-        self.transport_type = self._get_transport_type()
+        # transport_type may already be set by start() for HTTP/SSE
+        if not self.transport_type:
+            self.transport_type = self._get_transport_type()
         details = f"URL: {self.config.get('url', 'N/A')}, Command: {self.config.get('command', 'N/A')}"
         logger.info(f"Establishing connection to {self.server_name} via {self.transport_type} ({details})")
 

aip_agents/mcp/client/connection_manager.pyi

@@ -0,0 +1,51 @@
+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.
+
+        For HTTP/SSE transports, establishes connection directly to avoid anyio context issues.
+        For stdio transport, uses background task to manage subprocess lifecycle.
+
+        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.
+        """