adcp 0.1.2__py3-none-any.whl → 1.0.1__py3-none-any.whl

adcp/protocols/mcp.py

@@ -1,19 +1,31 @@
+from __future__ import annotations
+
 """MCP protocol adapter using official Python MCP SDK."""
 
-from typing import Any
+import asyncio
+import logging
+import time
+from contextlib import AsyncExitStack
+from typing import TYPE_CHECKING, Any
 from urllib.parse import urlparse
 
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from mcp import ClientSession
+
 try:
-    from mcp import ClientSession  # type: ignore[import-not-found]
-    from mcp.client.sse import sse_client  # type: ignore[import-not-found]
+    from mcp import ClientSession as _ClientSession
+    from mcp.client.sse import sse_client
+    from mcp.client.streamable_http import streamablehttp_client
 
     MCP_AVAILABLE = True
 except ImportError:
     MCP_AVAILABLE = False
-    ClientSession = None
 
+from adcp.exceptions import ADCPConnectionError, ADCPTimeoutError
 from adcp.protocols.base import ProtocolAdapter
-from adcp.types.core import TaskResult, TaskStatus
+from adcp.types.core import DebugInfo, TaskResult, TaskStatus
 
 
 class MCPAdapter(ProtocolAdapter):
@@ -29,73 +41,221 @@ class MCPAdapter(ProtocolAdapter):
         self._exit_stack: Any = None
 
     async def _get_session(self) -> ClientSession:
-        """Get or create MCP client session."""
+        """
+        Get or create MCP client session with URL fallback handling.
+
+        Raises:
+            ADCPConnectionError: If connection to agent fails
+        """
         if self._session is not None:
-            return self._session
+            return self._session  # type: ignore[no-any-return]
+
+        logger.debug(f"Creating MCP session for agent {self.agent_config.id}")
 
         # Parse the agent URI to determine transport type
         parsed = urlparse(self.agent_config.agent_uri)
 
         # Use SSE transport for HTTP/HTTPS endpoints
         if parsed.scheme in ("http", "https"):
-            from contextlib import AsyncExitStack
-
             self._exit_stack = AsyncExitStack()
 
             # Create SSE client with authentication header
             headers = {}
             if self.agent_config.auth_token:
-                headers["x-adcp-auth"] = self.agent_config.auth_token
+                # Support custom auth headers and types
+                if self.agent_config.auth_type == "bearer":
+                    headers[self.agent_config.auth_header] = (
+                        f"Bearer {self.agent_config.auth_token}"
+                    )
+                else:
+                    headers[self.agent_config.auth_header] = self.agent_config.auth_token
 
-            read, write = await self._exit_stack.enter_async_context(
-                sse_client(self.agent_config.agent_uri, headers=headers)
-            )
+            # Try the user's exact URL first
+            urls_to_try = [self.agent_config.agent_uri]
+
+            # If URL doesn't end with /mcp, also try with /mcp suffix
+            if not self.agent_config.agent_uri.rstrip("/").endswith("/mcp"):
+                base_uri = self.agent_config.agent_uri.rstrip("/")
+                urls_to_try.append(f"{base_uri}/mcp")
+
+            last_error = None
+            for url in urls_to_try:
+                try:
+                    # Choose transport based on configuration
+                    if self.agent_config.mcp_transport == "streamable_http":
+                        # Use streamable HTTP transport (newer, bidirectional)
+                        read, write, _get_session_id = await self._exit_stack.enter_async_context(
+                            streamablehttp_client(
+                                url, headers=headers, timeout=self.agent_config.timeout
+                            )
+                        )
+                    else:
+                        # Use SSE transport (legacy, but widely supported)
+                        read, write = await self._exit_stack.enter_async_context(
+                            sse_client(url, headers=headers)
+                        )
+
+                    self._session = await self._exit_stack.enter_async_context(
+                        _ClientSession(read, write)
+                    )
 
-            self._session = await self._exit_stack.enter_async_context(ClientSession(read, write))
+                    # Initialize the session
+                    await self._session.initialize()
 
-            # Initialize the session
-            await self._session.initialize()
+                    logger.info(
+                        f"Connected to MCP agent {self.agent_config.id} at {url} "
+                        f"using {self.agent_config.mcp_transport} transport"
+                    )
+                    if url != self.agent_config.agent_uri:
+                        logger.info(
+                            f"Note: Connected using fallback URL {url} "
+                            f"(configured: {self.agent_config.agent_uri})"
+                        )
 
-            return self._session
+                    return self._session  # type: ignore[no-any-return]
+                except Exception as e:
+                    last_error = e
+                    # Clean up the exit stack on failure to avoid async scope issues
+                    if self._exit_stack is not None:
+                        old_stack = self._exit_stack
+                        self._exit_stack = None  # Clear immediately to prevent reuse
+                        self._session = None
+                        try:
+                            await old_stack.aclose()
+                        except asyncio.CancelledError:
+                            # Expected during shutdown
+                            pass
+                        except RuntimeError as cleanup_error:
+                            # Known MCP SDK async cleanup issue
+                            if (
+                                "async context" in str(cleanup_error).lower()
+                                or "cancel scope" in str(cleanup_error).lower()
+                            ):
+                                logger.debug(
+                                    "Ignoring MCP SDK async context error during cleanup: "
+                                    f"{cleanup_error}"
+                                )
+                            else:
+                                logger.warning(
+                                    f"Unexpected RuntimeError during cleanup: {cleanup_error}"
+                                )
+                        except Exception as cleanup_error:
+                            # Unexpected cleanup errors should be logged
+                            logger.warning(
+                                f"Unexpected error during cleanup: {cleanup_error}", exc_info=True
+                            )
+
+                    # If this isn't the last URL to try, create a new exit stack and continue
+                    if url != urls_to_try[-1]:
+                        logger.debug(f"Retrying with next URL after error: {last_error}")
+                        self._exit_stack = AsyncExitStack()
+                        continue
+                    # If this was the last URL, raise the error
+                    logger.error(
+                        f"Failed to connect to MCP agent {self.agent_config.id} using "
+                        f"{self.agent_config.mcp_transport} transport. "
+                        f"Tried URLs: {', '.join(urls_to_try)}"
+                    )
+
+                    # Classify error type for better exception handling
+                    error_str = str(last_error).lower()
+                    if "401" in error_str or "403" in error_str or "unauthorized" in error_str:
+                        from adcp.exceptions import ADCPAuthenticationError
+
+                        raise ADCPAuthenticationError(
+                            f"Authentication failed: {last_error}",
+                            agent_id=self.agent_config.id,
+                            agent_uri=self.agent_config.agent_uri,
+                        ) from last_error
+                    elif "timeout" in error_str:
+                        raise ADCPTimeoutError(
+                            f"Connection timeout: {last_error}",
+                            agent_id=self.agent_config.id,
+                            agent_uri=self.agent_config.agent_uri,
+                            timeout=self.agent_config.timeout,
+                        ) from last_error
+                    else:
+                        raise ADCPConnectionError(
+                            f"Failed to connect: {last_error}",
+                            agent_id=self.agent_config.id,
+                            agent_uri=self.agent_config.agent_uri,
+                        ) from last_error
+
+            # This shouldn't be reached, but just in case
+            raise RuntimeError(f"Failed to connect to MCP agent at {self.agent_config.agent_uri}")
         else:
             raise ValueError(f"Unsupported transport scheme: {parsed.scheme}")
 
     async def call_tool(self, tool_name: str, params: dict[str, Any]) -> TaskResult[Any]:
         """Call a tool using MCP protocol."""
+        start_time = time.time() if self.agent_config.debug else None
+        debug_info = None
+
         try:
             session = await self._get_session()
 
+            if self.agent_config.debug:
+                debug_request = {
+                    "protocol": "MCP",
+                    "tool": tool_name,
+                    "params": params,
+                    "transport": self.agent_config.mcp_transport,
+                }
+
             # Call the tool using MCP client session
             result = await session.call_tool(tool_name, params)
 
+            if self.agent_config.debug and start_time:
+                duration_ms = (time.time() - start_time) * 1000
+                debug_info = DebugInfo(
+                    request=debug_request,
+                    response={
+                        "content": result.content,
+                        "is_error": result.isError if hasattr(result, "isError") else False,
+                    },
+                    duration_ms=duration_ms,
+                )
+
             # MCP tool results contain a list of content items
             # For AdCP, we expect the data in the content
             return TaskResult[Any](
                 status=TaskStatus.COMPLETED,
                 data=result.content,
                 success=True,
+                debug_info=debug_info,
             )
 
         except Exception as e:
+            if self.agent_config.debug and start_time:
+                duration_ms = (time.time() - start_time) * 1000
+                debug_info = DebugInfo(
+                    request=debug_request if self.agent_config.debug else {},
+                    response={"error": str(e)},
+                    duration_ms=duration_ms,
+                )
             return TaskResult[Any](
                 status=TaskStatus.FAILED,
                 error=str(e),
                 success=False,
+                debug_info=debug_info,
             )
 
     async def list_tools(self) -> list[str]:
         """List available tools from MCP agent."""
-        try:
-            session = await self._get_session()
-            result = await session.list_tools()
-            return [tool.name for tool in result.tools]
-        except Exception:
-            # Return empty list on error
-            return []
+        session = await self._get_session()
+        result = await session.list_tools()
+        return [tool.name for tool in result.tools]
 
     async def close(self) -> None:
         """Close the MCP session."""
         if self._exit_stack is not None:
-            await self._exit_stack.aclose()
+            old_stack = self._exit_stack
             self._exit_stack = None
             self._session = None
+            try:
+                await old_stack.aclose()
+            except (asyncio.CancelledError, RuntimeError):
+                # Cleanup errors during shutdown are expected
+                pass
+            except Exception as e:
+                logger.debug(f"Error during MCP session cleanup: {e}")

adcp/types/__init__.py

@@ -1,9 +1,12 @@
+from __future__ import annotations
+
 """Type definitions for AdCP client."""
 
 from adcp.types.core import (
     Activity,
     ActivityType,
     AgentConfig,
+    DebugInfo,
     Protocol,
     TaskResult,
     TaskStatus,
@@ -18,4 +21,5 @@ __all__ = [
     "WebhookMetadata",
     "Activity",
     "ActivityType",
+    "DebugInfo",
 ]

adcp/types/core.py

@@ -1,9 +1,11 @@
+from __future__ import annotations
+
 """Core type definitions."""
 
 from enum import Enum
 from typing import Any, Generic, Literal, TypeVar
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 
 
 class Protocol(str, Enum):
@@ -21,6 +23,68 @@ class AgentConfig(BaseModel):
     protocol: Protocol
     auth_token: str | None = None
     requires_auth: bool = False
+    auth_header: str = "x-adcp-auth"  # Header name for authentication
+    auth_type: str = "token"  # "token" for direct value, "bearer" for "Bearer {token}"
+    timeout: float = 30.0  # Request timeout in seconds
+    mcp_transport: str = (
+        "streamable_http"  # "streamable_http" (default, modern) or "sse" (legacy fallback)
+    )
+    debug: bool = False  # Enable debug mode to capture request/response details
+
+    @field_validator("agent_uri")
+    @classmethod
+    def validate_agent_uri(cls, v: str) -> str:
+        """Validate agent URI format."""
+        if not v:
+            raise ValueError("agent_uri cannot be empty")
+
+        if not v.startswith(("http://", "https://")):
+            raise ValueError(
+                f"agent_uri must start with http:// or https://, got: {v}\n"
+                "Example: https://agent.example.com"
+            )
+
+        # Remove trailing slash for consistency
+        return v.rstrip("/")
+
+    @field_validator("timeout")
+    @classmethod
+    def validate_timeout(cls, v: float) -> float:
+        """Validate timeout is reasonable."""
+        if v <= 0:
+            raise ValueError(f"timeout must be positive, got: {v}")
+
+        if v > 300:  # 5 minutes
+            raise ValueError(
+                f"timeout is very large ({v}s). Consider a value under 300 seconds.\n"
+                "Large timeouts can cause long hangs if agent is unresponsive."
+            )
+
+        return v
+
+    @field_validator("mcp_transport")
+    @classmethod
+    def validate_mcp_transport(cls, v: str) -> str:
+        """Validate MCP transport type."""
+        valid_transports = ["streamable_http", "sse"]
+        if v not in valid_transports:
+            raise ValueError(
+                f"mcp_transport must be one of {valid_transports}, got: {v}\n"
+                "Use 'streamable_http' for modern agents (recommended)"
+            )
+        return v
+
+    @field_validator("auth_type")
+    @classmethod
+    def validate_auth_type(cls, v: str) -> str:
+        """Validate auth type."""
+        valid_types = ["token", "bearer"]
+        if v not in valid_types:
+            raise ValueError(
+                f"auth_type must be one of {valid_types}, got: {v}\n"
+                "Use 'bearer' for OAuth2/standard Authorization header"
+            )
+        return v
 
 
 class TaskStatus(str, Enum):
@@ -50,6 +114,14 @@ class NeedsInputInfo(BaseModel):
     field: str | None = None
 
 
+class DebugInfo(BaseModel):
+    """Debug information for troubleshooting."""
+
+    request: dict[str, Any]
+    response: dict[str, Any]
+    duration_ms: float | None = None
+
+
 class TaskResult(BaseModel, Generic[T]):
     """Result from task execution."""
 
@@ -60,6 +132,7 @@ class TaskResult(BaseModel, Generic[T]):
     error: str | None = None
     success: bool = Field(default=True)
     metadata: dict[str, Any] | None = None
+    debug_info: DebugInfo | None = None
 
     class Config:
         arbitrary_types_allowed = True
@@ -78,6 +151,8 @@ class ActivityType(str, Enum):
 class Activity(BaseModel):
     """Activity event for observability."""
 
+    model_config = {"frozen": True}
+
     type: ActivityType
     operation_id: str
     agent_id: str