aixtools 0.2.18__tar.gz → 0.2.20__tar.gz

{aixtools-0.2.18 → aixtools-0.2.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aixtools
-Version: 0.2.18
+Version: 0.2.20
 Summary: Tools for AI exploration and debugging
 Requires-Python: >=3.11.2
 Description-Content-Type: text/markdown

{aixtools-0.2.18 → aixtools-0.2.20}/aixtools/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.18'
-__version_tuple__ = version_tuple = (0, 2, 18)
+__version__ = version = '0.2.20'
+__version_tuple__ = version_tuple = (0, 2, 20)
 
-__commit_id__ = commit_id = 'gda0a23c48'
+__commit_id__ = commit_id = 'ge7f4f14bb'

{aixtools-0.2.18 → aixtools-0.2.20}/aixtools/a2a/google_sdk/utils.py

@@ -11,6 +11,7 @@ from a2a.utils import AGENT_CARD_WELL_KNOWN_PATH, PREV_AGENT_CARD_WELL_KNOWN_PAT
 from aixtools.a2a.google_sdk.remote_agent_connection import RemoteAgentConnection
 from aixtools.context import DEFAULT_SESSION_ID, DEFAULT_USER_ID, SessionIdTuple
 from aixtools.logging.logging_config import get_logger
+from aixtools.server.utils import create_session_headers
 
 logger = get_logger(__name__)
 
@@ -23,6 +24,7 @@ class AgentCardLoadFailedError(Exception):
 
 async def get_agent_card(client: httpx.AsyncClient, address: str) -> AgentCard:
     """Retrieve the agent card from the given agent address."""
+    warnings = []
     for card_path in [AGENT_CARD_WELL_KNOWN_PATH, PREV_AGENT_CARD_WELL_KNOWN_PATH]:
         try:
             card_resolver = A2ACardResolver(client, address, card_path)
@@ -30,8 +32,10 @@ async def get_agent_card(client: httpx.AsyncClient, address: str) -> AgentCard:
             card.url = address
             return card
         except Exception as e:
-            logger.warning(f"Error retrieving agent card from {address} at path {card_path}: {e}")
+            warnings.append(f"Error retrieving agent card from {address} at path {card_path}: {e}")
 
+    for warning in warnings:
+        logger.warning(warning)
     raise AgentCardLoadFailedError(f"Failed to load agent card from {address}")
 
 
@@ -65,15 +69,19 @@ class _AgentCardResolver:
 
 
 async def get_a2a_clients(
-    ctx: SessionIdTuple, agent_hosts: list[str], *, timeout: float = DEFAULT_A2A_TIMEOUT
+    agent_hosts: list[str],
+    session_id_tuple: SessionIdTuple,
+    auth_token: str = None,
+    *,
+    timeout: float = DEFAULT_A2A_TIMEOUT,
 ) -> dict[str, RemoteAgentConnection]:
     """Get A2A clients for all agents defined in the configuration."""
-    headers = {
-        "user-id": ctx[0],
-        "session-id": ctx[1],
-    }
+    headers = create_session_headers(session_id_tuple, auth_token)
     httpx_client = httpx.AsyncClient(headers=headers, timeout=timeout, follow_redirects=True)
-    return await _AgentCardResolver(httpx_client).get_a2a_clients(agent_hosts)
+    clients = await _AgentCardResolver(httpx_client).get_a2a_clients(agent_hosts)
+    for client in clients.values():
+        logger.info("Using A2A server at: %s", client.get_agent_card().url)
+    return clients
 
 
 def card2description(card: AgentCard) -> str:

{aixtools-0.2.18 → aixtools-0.2.20}/aixtools/mcp/__init__.py

@@ -4,8 +4,12 @@ Model Context Protocol (MCP) implementation for AI agent communication.
 
 from aixtools.mcp.exceptions import AixToolError
 from aixtools.mcp.fast_mcp_log import FastMcpLog
+from aixtools.mcp.middleware import AixErrorHandlingMiddleware
+from aixtools.mcp.server import create_mcp_server
 
 __all__ = [
-    "FastMcpLog",
+    "AixErrorHandlingMiddleware",
     "AixToolError",
+    "FastMcpLog",
+    "create_mcp_server",
 ]

{aixtools-0.2.18 → aixtools-0.2.20}/aixtools/mcp/client.py

@@ -3,6 +3,7 @@
 import asyncio
 import logging
 from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
 from datetime import timedelta
 from typing import Any, AsyncGenerator
 
@@ -21,6 +22,7 @@ from pydantic_ai.toolsets.abstract import ToolsetTool
 
 from aixtools.context import SessionIdTuple
 from aixtools.logging.logging_config import get_logger
+from aixtools.server.utils import create_session_headers
 
 MCP_TOOL_CACHE_TTL = 300  # 5 minutes
 DEFAULT_MCP_CONNECTION_TIMEOUT = 30
@@ -49,6 +51,14 @@ async def default_mcp_log_handler(message: LogMessage):
     logger.log(level, msg, extra=extra)
 
 
+@dataclass
+class MCPConfig:
+    """Configuration for an MCP server retrieved from config.yaml"""
+
+    url: str
+    read_timeout: float = field(default=DEFAULT_MCP_READ_TIMEOUT)
+
+
 def get_mcp_client(
     url: str | None = None,
     command: str | None = None,
@@ -73,57 +83,50 @@ def get_mcp_client(
     raise ValueError("Either url or command must be provided to create MCP client.")
 
 
-def get_mcp_headers(session_id_tuple: SessionIdTuple) -> dict[str, str] | None:
+def get_mcp_servers(
+    mcp_configs: list[MCPConfig],
+    session_id_tuple: SessionIdTuple,
+    auth_token: str = None,
+    *,
+    timeout: float = DEFAULT_MCP_CONNECTION_TIMEOUT,
+):
     """
-    Generate headers for MCP server requests.
+    Create cached MCP server instances with robust error handling and isolation.
 
-    This function creates a dictionary of headers to be used in requests to
-    the MCP servers. If a `user_id` or `session_id` is provided, they are
-    included in the headers.
+    This function creates and returns a list of `CachedMCPServerStreamableHTTP` instances
+    based on the provided URLs. Each server instance includes:
+    - TTL-based caching for tool lists (5 minutes default)
+    - Complete task isolation to prevent cancellation propagation
+    - Comprehensive error handling and fallback mechanisms
+    - Optional user/session headers for request authentication
 
     Args:
-        session_id_tuple (SessionIdTuple): user_id and session_id tuple
+        mcp_configs (list[MCPConfig]): A list of MCP server configurations to use.
+        session_id_tuple (SessionIdTuple): A tuple containing (user_id, session_id).
+        auth_token (str, optional): The authentication token for the user. Defaults to None.
+        timeout (float, optional): Timeout in seconds for MCP server connections.
     Returns:
-        dict[str, str] | None: A dictionary of headers for MCP server requests,
-                               or None if neither user_id nor session_id is
-                               provided. When None is returned, default headers
-                               from the client or transport will be used.
+        list[CachedMCPServerStreamableHTTP]: List of cached MCP server instances with
+                                            isolation and error handling. Each server
+                                            operates independently - failures in one
+                                            server won't affect others.
     """
-    headers = None
-    user_id, session_id = session_id_tuple
-    if session_id or user_id:
-        headers = {}
-        if session_id:
-            headers["session-id"] = session_id
-        if user_id:
-            headers["user-id"] = user_id
-    return headers
+    headers = create_session_headers(session_id_tuple, auth_token)
+    servers = []
+    for config in mcp_configs:
+        server = CachedMCPServerStreamableHTTP(
+            url=config.url, headers=headers, timeout=timeout, read_timeout=config.read_timeout
+        )
+        logger.info("Using MCP server at %s", config.url)
+        servers.append(server)
+    return servers
 
 
 def get_configured_mcp_servers(
     session_id_tuple: SessionIdTuple, mcp_urls: list[str], timeout: int = DEFAULT_MCP_CONNECTION_TIMEOUT
 ):
-    """
-    Retrieve the configured MCP server instances with optional caching.
-
-    Context values `user_id` and `session_id` are included in the headers for each server request.
-
-    Each server is wrapped in a try-except block to isolate them from each other.
-    If one server fails, it won't affect the others.
-
-    Args:
-        session_id_tuple (SessionIdTuple): A tuple containing (user_id, session_id).
-        mcp_urls: (list[str], optional): A list of MCP server URLs to use.
-        timeout (int, optional): Timeout in seconds for MCP server connections. Defaults to 30 seconds.
-    Returns:
-        list[MCPServerStreamableHTTP]: A list of configured MCP server instances. If
-                              neither user_id nor session_id is provided, the
-                              server instances will use default headers defined
-                              by the underlying HTTP implementation.
-    """
-    headers = get_mcp_headers(session_id_tuple)
-
-    return [CachedMCPServerStreamableHTTP(url=url, headers=headers, timeout=timeout) for url in mcp_urls]
+    """Create MCP server instances from a list of URLs."""
+    return get_mcp_servers([MCPConfig(url=url) for url in mcp_urls], session_id_tuple, timeout=timeout)
 
 
 class CachedMCPServerStreamableHTTP(MCPServerStreamableHTTP):
@@ -259,7 +262,7 @@ class CachedMCPServerStreamableHTTP(MCPServerStreamableHTTP):
 
         # First, check if we have a valid cached result
         if CACHE_KEY in self._tools_cache:
-            logger.info("Using cached tools for %s", self.url)
+            logger.debug("Using cached tools for %s", self.url)
             return self._tools_cache[CACHE_KEY]
 
         # Create isolated task to prevent cancellation propagation

aixtools-0.2.18/aixtools/logging/mcp_middleware.py → aixtools-0.2.20/aixtools/mcp/middleware.py

@@ -7,7 +7,7 @@ import traceback
 from fastmcp.server.middleware.error_handling import ErrorHandlingMiddleware
 from fastmcp.server.middleware.middleware import MiddlewareContext
 
-from aixtools.mcp import AixToolError
+from aixtools.mcp.exceptions import AixToolError
 
 
 class AixErrorHandlingMiddleware(ErrorHandlingMiddleware):

aixtools-0.2.20/aixtools/mcp/server.py

@@ -0,0 +1,72 @@
+"""Utilities for FastMCP servers."""
+
+from typing import Any
+
+from fastmcp import FastMCP
+from fastmcp.server.middleware.logging import LoggingMiddleware
+from fastmcp.server.middleware.timing import TimingMiddleware
+from fastmcp.utilities.types import NotSet
+
+from aixtools.auth.auth import AccessTokenAuthProvider
+from aixtools.logging.logging_config import get_logger
+from aixtools.mcp.middleware import AixErrorHandlingMiddleware
+
+
+def create_mcp_server(
+    *,
+    name: str,
+    instructions: str | None = None,
+    **kwargs: Any,
+) -> FastMCP:
+    """
+    MCP server instance with preconfigured auth and middleware.
+
+    All FastMCP constructor parameters are supported via **kwargs.
+
+    Args:
+        name: Server name
+        instructions: Optional server instructions
+        **kwargs: All other FastMCP constructor parameters:
+            - version: str | None
+            - auth: AuthProvider | None (AccessTokenAuthProvider if not set, pass None to disable)
+            - middleware: list[Middleware] | None (custom middleware if not set, pass None to disable)
+            - lifespan: Callable | None
+            - tool_serializer: Callable[[Any], str] | None
+            - cache_expiration_seconds: float | None
+            - on_duplicate_tools: DuplicateBehavior | None
+            - on_duplicate_resources: DuplicateBehavior | None
+            - on_duplicate_prompts: DuplicateBehavior | None
+            - resource_prefix_format: Literal["protocol", "path"] | None
+            - mask_error_details: bool | None
+            - tools: list[Tool | Callable] | None
+            - tool_transformations: dict[str, ToolTransformConfig] | None
+            - dependencies: list[str] | None
+            - include_tags: set[str] | None
+            - exclude_tags: set[str] | None
+            - include_fastmcp_meta: bool | None
+
+    Returns:
+        Configured FastMCP server instance
+    """
+    middleware = kwargs.pop("middleware", NotSet)
+    auth = kwargs.pop("auth", NotSet)
+
+    if middleware is NotSet:
+        middleware = [
+            LoggingMiddleware(include_payloads=True, logger=get_logger("middleware.log")),
+            AixErrorHandlingMiddleware(include_traceback=True, logger=get_logger("middleware.err")),
+            TimingMiddleware(logger=get_logger("middleware.timing")),
+        ]
+
+    if auth is NotSet:
+        auth = AccessTokenAuthProvider()
+
+    mcp_args = {
+        "name": name,
+        "instructions": instructions,
+        "auth": auth,
+        "middleware": middleware,
+        **kwargs,
+    }
+
+    return FastMCP(**mcp_args)

{aixtools-0.2.18 → aixtools-0.2.20}/aixtools/server/utils.py

@@ -8,10 +8,13 @@ from functools import wraps
 from fastmcp import Context
 from fastmcp.server import dependencies
 
-from ..context import DEFAULT_SESSION_ID, DEFAULT_USER_ID, session_id_var, user_id_var
+from ..context import DEFAULT_SESSION_ID, DEFAULT_USER_ID, SessionIdTuple, session_id_var, user_id_var
+from ..logging.logging_config import get_logger
 
+logger = get_logger(__name__)
 
-def get_session_id_tuple(ctx: Context | None = None) -> tuple[str, str]:
+
+def get_session_id_tuple(ctx: Context | None = None) -> SessionIdTuple:
     """
     Get the user and session IDs from the user session.
     If `ctx` is None, the current FastMCP request HTTP headers are used.
@@ -60,6 +63,37 @@ def get_session_id_str(ctx: Context | None = None) -> str:
     return f"{user_id}:{session_id}"
 
 
+def create_session_headers(session_id_tuple: SessionIdTuple, auth_token: str | None = None) -> dict[str, str]:
+    """
+    Generate headers for MCP or A2A server requests.
+
+    This function creates a dictionary of headers to be used in requests to
+    the MCP servers. If a `user_id` or `session_id` is provided, they are
+    included in the headers.
+
+    Args:
+        session_id_tuple (SessionIdTuple): user_id and session_id tuple
+        auth_token (str | None): Optional authorization token to include in headers
+
+    Returns:
+        dict[str, str]: A dictionary of headers for MCP server requests.
+                       May be empty if no user_id, session_id, or auth_token is provided.
+    """
+    headers = {}
+    user_id, session_id = session_id_tuple
+    if auth_token:
+        logger.debug("Using auth token for MCP server authentication for user:%s, session_id:%s", user_id, session_id)
+        headers["Authorization"] = f"Bearer {auth_token}"
+    else:
+        logger.warning("No auth token found to forward to MCP/A2A servers.")
+
+    if session_id:
+        headers["session-id"] = session_id
+    if user_id:
+        headers["user-id"] = user_id
+    return headers
+
+
 def run_in_thread(func):
     """decorator to run blocking function with `asyncio.to_thread`"""
 

{aixtools-0.2.18 → aixtools-0.2.20}/aixtools.egg-info/SOURCES.txt

@@ -61,7 +61,6 @@ aixtools/logging/log_objects.py
 aixtools/logging/logging_config.py
 aixtools/logging/mcp_log_models.py
 aixtools/logging/mcp_logger.py
-aixtools/logging/mcp_middleware.py
 aixtools/logging/model_patch_logging.py
 aixtools/logging/open_telemetry.py
 aixtools/mcp/__init__.py
@@ -71,6 +70,8 @@ aixtools/mcp/example_server.py
 aixtools/mcp/exceptions.py
 aixtools/mcp/fast_mcp_log.py
 aixtools/mcp/faulty_mcp.py
+aixtools/mcp/middleware.py
+aixtools/mcp/server.py
 aixtools/model_patch/model_patch.py
 aixtools/server/__init__.py
 aixtools/server/app_mounter.py