alita-sdk 0.3.435__py3-none-any.whl → 0.3.449__py3-none-any.whl

alita_sdk/runtime/tools/mcp_remote_tool.py

@@ -0,0 +1,166 @@
+"""
+MCP Remote Tool for direct HTTP/SSE invocation.
+This tool is used for remote MCP servers accessed via HTTP/SSE.
+"""
+
+import asyncio
+import json
+import logging
+import time
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Dict, Optional
+
+from .mcp_server_tool import McpServerTool
+from pydantic import Field
+from ..utils.mcp_oauth import (
+    McpAuthorizationRequired,
+    canonical_resource,
+    extract_resource_metadata_url,
+    fetch_resource_metadata_async,
+    infer_authorization_servers_from_realm,
+)
+from ..utils.mcp_sse_client import McpSseClient
+
+logger = logging.getLogger(__name__)
+
+
+class McpRemoteTool(McpServerTool):
+    """
+    Tool for invoking remote MCP server tools via HTTP/SSE.
+    Extends McpServerTool and overrides _run to use direct HTTP calls instead of client.mcp_tool_call.
+    """
+    
+    # Remote MCP connection details
+    server_url: str = Field(..., description="URL of the remote MCP server")
+    server_headers: Optional[Dict[str, str]] = Field(default=None, description="HTTP headers for authentication")
+    original_tool_name: Optional[str] = Field(default=None, description="Original tool name from MCP server (before optimization)")
+    is_prompt: bool = False  # Flag to indicate if this is a prompt tool
+    prompt_name: Optional[str] = None  # Original prompt name if this is a prompt
+    session_id: Optional[str] = Field(default=None, description="MCP session ID for stateful SSE servers")
+    
+    def model_post_init(self, __context: Any) -> None:
+        """Update metadata with session info after model initialization."""
+        super().model_post_init(__context)
+        self._update_metadata_with_session()
+    
+    def _update_metadata_with_session(self):
+        """Update the metadata dict with current session information."""
+        if self.session_id:
+            if self.metadata is None:
+                self.metadata = {}
+            self.metadata.update({
+                'mcp_session_id': self.session_id,
+                'mcp_server_url': canonical_resource(self.server_url)
+            })
+    
+    def __getstate__(self):
+        """Custom serialization for pickle compatibility."""
+        state = super().__getstate__()
+        # Ensure headers are serializable
+        if 'server_headers' in state and state['server_headers'] is not None:
+            state['server_headers'] = dict(state['server_headers'])
+        return state
+
+    def _run(self, *args, **kwargs):
+        """
+        Execute the MCP tool via direct HTTP/SSE call to the remote server.
+        Overrides the parent method to avoid using client.mcp_tool_call.
+        """
+        try:
+            # Always create a new event loop for sync context
+            with ThreadPoolExecutor() as executor:
+                future = executor.submit(self._run_in_new_loop, kwargs)
+                return future.result(timeout=self.tool_timeout_sec)
+        except McpAuthorizationRequired:
+            # Bubble up so LangChain can surface a tool error with useful metadata
+            raise
+        except Exception as e:
+            logger.error(f"Error executing remote MCP tool '{self.name}': {e}")
+            return f"Error executing tool: {e}"
+
+    def _run_in_new_loop(self, kwargs: Dict[str, Any]) -> str:
+        """Run the async tool invocation in a new event loop."""
+        return asyncio.run(self._execute_remote_tool(kwargs))
+
+    async def _execute_remote_tool(self, kwargs: Dict[str, Any]) -> str:
+        """Execute the actual remote MCP tool call using SSE client."""
+        from ...tools.utils import TOOLKIT_SPLITTER
+        
+        # Check for session_id requirement
+        if not self.session_id:
+            logger.error(f"[MCP Session] Missing session_id for tool '{self.name}'")
+            raise Exception("sessionId required. Frontend must generate UUID and send with mcp_tokens.")
+        
+        # Use the original tool name from discovery for MCP server invocation
+        tool_name_for_server = self.original_tool_name
+        if not tool_name_for_server:
+            tool_name_for_server = self.name.rsplit(TOOLKIT_SPLITTER, 1)[-1] if TOOLKIT_SPLITTER in self.name else self.name
+            logger.warning(f"original_tool_name not set for '{self.name}', using extracted: {tool_name_for_server}")
+        
+        logger.info(f"[MCP SSE] Executing tool '{tool_name_for_server}' with session {self.session_id}")
+        
+        try:
+            # Prepare headers
+            headers = {}
+            if self.server_headers:
+                headers.update(self.server_headers)
+            
+            # Create SSE client
+            client = McpSseClient(
+                url=self.server_url,
+                session_id=self.session_id,
+                headers=headers,
+                timeout=self.tool_timeout_sec
+            )
+            
+            # Execute tool call via SSE
+            result = await client.call_tool(tool_name_for_server, kwargs)
+            
+            # Format the result
+            if isinstance(result, dict):
+                # Check for content array (common in MCP responses)
+                if "content" in result:
+                    content_items = result["content"]
+                    if isinstance(content_items, list):
+                        # Extract text from content items
+                        text_parts = []
+                        for item in content_items:
+                            if isinstance(item, dict):
+                                if item.get("type") == "text" and "text" in item:
+                                    text_parts.append(item["text"])
+                                elif "text" in item:
+                                    text_parts.append(item["text"])
+                                else:
+                                    text_parts.append(json.dumps(item))
+                            else:
+                                text_parts.append(str(item))
+                        return "\n".join(text_parts)
+                
+                # Return formatted JSON if no content field
+                return json.dumps(result, indent=2)
+            
+            # Return as string for other types
+            return str(result)
+            
+        except Exception as e:
+            logger.error(f"[MCP SSE] Tool execution failed: {e}", exc_info=True)
+            raise
+
+    def _parse_sse(self, text: str) -> Dict[str, Any]:
+        """Parse Server-Sent Events (SSE) format response."""
+        for line in text.split('\n'):
+            line = line.strip()
+            if line.startswith('data:'):
+                json_str = line[5:].strip()
+                return json.loads(json_str)
+        raise ValueError("No data found in SSE response")
+    
+    def get_session_metadata(self) -> dict:
+        """Return session metadata to be included in tool responses."""
+        if self.session_id:
+            return {
+                'mcp_session_id': self.session_id,
+                'mcp_server_url': canonical_resource(self.server_url)
+            }
+        return {}

alita_sdk/runtime/tools/mcp_server_tool.py

@@ -15,63 +15,12 @@ class McpServerTool(BaseTool):
     description: str
     args_schema: Optional[Type[BaseModel]] = None
     return_type: str = "str"
-    client: Any = Field(default=None, exclude=True)  # Exclude from serialization
+    client: Any
     server: str
     tool_timeout_sec: int = 60
-    is_prompt: bool = False  # Flag to indicate if this is a prompt tool
-    prompt_name: Optional[str] = None  # Original prompt name if this is a prompt
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
-    def __getstate__(self):
-        """Custom serialization to exclude non-serializable objects."""
-        state = self.__dict__.copy()
-        # Remove the client since it contains threading objects that can't be pickled
-        state['client'] = None
-        # Store args_schema as a schema dict instead of the dynamic class
-        if hasattr(self, 'args_schema') and self.args_schema is not None:
-            # Convert the Pydantic model back to schema dict for pickling
-            try:
-                state['_args_schema_dict'] = self.args_schema.model_json_schema()
-                state['args_schema'] = None
-            except Exception as e:
-                logger.warning(f"Failed to serialize args_schema: {e}")
-                # If conversion fails, just remove it
-                state['args_schema'] = None
-                state['_args_schema_dict'] = {}
-        return state
-
-    def __setstate__(self, state):
-        """Custom deserialization to handle missing objects."""
-        # Restore the args_schema from the stored schema dict
-        args_schema_dict = state.pop('_args_schema_dict', {})
-
-        # Initialize required Pydantic internal attributes
-        if '__pydantic_fields_set__' not in state:
-            state['__pydantic_fields_set__'] = set(state.keys())
-        if '__pydantic_extra__' not in state:
-            state['__pydantic_extra__'] = None
-        if '__pydantic_private__' not in state:
-            state['__pydantic_private__'] = None
-
-        # Directly update the object's __dict__ to bypass Pydantic validation
-        self.__dict__.update(state)
-
-        # Recreate the args_schema from the stored dict if available
-        if args_schema_dict:
-            try:
-                recreated_schema = self.create_pydantic_model_from_schema(args_schema_dict)
-                self.__dict__['args_schema'] = recreated_schema
-            except Exception as e:
-                logger.warning(f"Failed to recreate args_schema: {e}")
-                self.__dict__['args_schema'] = None
-        else:
-            self.__dict__['args_schema'] = None
-
-        # Note: client will be None after unpickling
-        # The toolkit should reinitialize the client when needed
-
-
     @staticmethod
     def create_pydantic_model_from_schema(schema: dict, model_name: str = "ArgsSchema"):
         def parse_type(field: dict, name: str = "Field") -> Any:
@@ -143,30 +92,14 @@ class McpServerTool(BaseTool):
 
     def _run(self, *args, **kwargs):
         # Extract the actual tool/prompt name (remove toolkit prefix)
-        actual_name = self.name.rsplit(TOOLKIT_SPLITTER)[1] if TOOLKIT_SPLITTER in self.name else self.name
-        
-        if self.is_prompt:
-            # For prompts, use prompts/get endpoint
-            call_data = {
-                "server": self.server,
-                "tool_timeout_sec": self.tool_timeout_sec,
-                "tool_call_id": str(uuid.uuid4()),
-                "method": "prompts/get",
-                "params": {
-                    "name": self.prompt_name or actual_name.replace("prompt_", ""),
-                    "arguments": kwargs.get("arguments", kwargs)
-                }
-            }
-        else:
-            # For regular tools, use tools/call endpoint
-            call_data = {
-                "server": self.server,
-                "tool_timeout_sec": self.tool_timeout_sec,
-                "tool_call_id": str(uuid.uuid4()),
-                "params": {
-                    "name": actual_name,
-                    "arguments": kwargs
-                }
+        call_data = {
+            "server": self.server,
+            "tool_timeout_sec": self.tool_timeout_sec,
+            "tool_call_id": str(uuid.uuid4()),
+            "params": {
+                "name": self.name.rsplit(TOOLKIT_SPLITTER)[1] if TOOLKIT_SPLITTER in self.name else self.name,
+                "arguments": kwargs
             }
+        }
         
         return self.client.mcp_tool_call(call_data)

alita_sdk/runtime/utils/mcp_oauth.py

@@ -0,0 +1,164 @@
+import json
+import logging
+import re
+from typing import Any, Dict, Optional
+from urllib.parse import urlparse
+
+import requests
+from langchain_core.tools import ToolException
+
+logger = logging.getLogger(__name__)
+
+
+class McpAuthorizationRequired(ToolException):
+    """Raised when an MCP server requires OAuth authorization before use."""
+
+    def __init__(
+        self,
+        message: str,
+        server_url: str,
+        resource_metadata_url: Optional[str] = None,
+        www_authenticate: Optional[str] = None,
+        resource_metadata: Optional[Dict[str, Any]] = None,
+        status: Optional[int] = None,
+        tool_name: Optional[str] = None,
+    ):
+        super().__init__(message)
+        self.server_url = server_url
+        self.resource_metadata_url = resource_metadata_url
+        self.www_authenticate = www_authenticate
+        self.resource_metadata = resource_metadata
+        self.status = status
+        self.tool_name = tool_name
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "message": str(self),
+            "server_url": self.server_url,
+            "resource_metadata_url": self.resource_metadata_url,
+            "www_authenticate": self.www_authenticate,
+            "resource_metadata": self.resource_metadata,
+            "status": self.status,
+            "tool_name": self.tool_name,
+        }
+
+
+def extract_resource_metadata_url(www_authenticate: Optional[str], server_url: Optional[str] = None) -> Optional[str]:
+    """
+    Pull the resource_metadata URL from a WWW-Authenticate header if present.
+    If not found and server_url is provided, try to construct resource metadata URLs.
+    """
+    if not www_authenticate and not server_url:
+        return None
+
+    # RFC9728 returns `resource_metadata="<url>"` inside the header value
+    if www_authenticate:
+        match = re.search(r'resource_metadata\s*=\s*\"?([^\", ]+)\"?', www_authenticate)
+        if match:
+            return match.group(1)
+    
+    # For servers that don't provide resource_metadata in WWW-Authenticate,
+    # we'll return None and rely on inferring authorization servers from the realm
+    # or using well-known OAuth discovery endpoints directly
+    return None
+
+
+def fetch_oauth_authorization_server_metadata(base_url: str, timeout: int = 10) -> Optional[Dict[str, Any]]:
+    """
+    Fetch OAuth authorization server metadata from well-known endpoints.
+    Tries both oauth-authorization-server and openid-configuration discovery endpoints.
+    """
+    discovery_endpoints = [
+        f"{base_url}/.well-known/oauth-authorization-server",
+        f"{base_url}/.well-known/openid-configuration",
+    ]
+    
+    for endpoint in discovery_endpoints:
+        try:
+            resp = requests.get(endpoint, timeout=timeout)
+            if resp.status_code == 200:
+                return resp.json()
+        except Exception as exc:
+            logger.debug(f"Failed to fetch OAuth metadata from {endpoint}: {exc}")
+            continue
+    
+    return None
+
+
+def infer_authorization_servers_from_realm(www_authenticate: Optional[str], server_url: str) -> Optional[list]:
+    """
+    Infer authorization server URLs from WWW-Authenticate realm or server URL.
+    This is used when the server doesn't provide resource_metadata endpoint.
+    """
+    if not www_authenticate and not server_url:
+        return None
+    
+    authorization_servers = []
+    
+    # Try to extract realm from WWW-Authenticate header
+    realm = None
+    if www_authenticate:
+        realm_match = re.search(r'realm\s*=\s*\"([^\"]+)\"', www_authenticate)
+        if realm_match:
+            realm = realm_match.group(1)
+    
+    # Parse the server URL to get base domain
+    parsed = urlparse(server_url)
+    base_url = f"{parsed.scheme}://{parsed.netloc}"
+    
+    # Return the base authorization server URL (not the discovery endpoint)
+    # The client will append .well-known paths when fetching metadata
+    authorization_servers.append(base_url)
+    
+    return authorization_servers if authorization_servers else None
+
+
+def fetch_resource_metadata(resource_metadata_url: str, timeout: int = 10) -> Optional[Dict[str, Any]]:
+    """Fetch and parse the protected resource metadata document."""
+    try:
+        resp = requests.get(resource_metadata_url, timeout=timeout)
+        resp.raise_for_status()
+        return resp.json()
+    except Exception as exc:  # broad catch – we want to surface auth requirement even if this fails
+        logger.warning("Failed to fetch resource metadata from %s: %s", resource_metadata_url, exc)
+        return None
+
+
+async def fetch_resource_metadata_async(resource_metadata_url: str, session=None, timeout: int = 10) -> Optional[Dict[str, Any]]:
+    """Async variant for fetching protected resource metadata."""
+    try:
+        import aiohttp
+
+        client_timeout = aiohttp.ClientTimeout(total=timeout)
+        if session:
+            async with session.get(resource_metadata_url, timeout=client_timeout) as resp:
+                text = await resp.text()
+        else:
+            async with aiohttp.ClientSession(timeout=client_timeout) as local_session:
+                async with local_session.get(resource_metadata_url) as resp:
+                    text = await resp.text()
+
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            logger.warning("Resource metadata at %s is not valid JSON: %s", resource_metadata_url, text[:200])
+            return None
+    except Exception as exc:
+        logger.warning("Failed to fetch resource metadata from %s: %s", resource_metadata_url, exc)
+        return None
+
+
+def canonical_resource(server_url: str) -> str:
+    """Produce a canonical resource identifier for the MCP server."""
+    parsed = urlparse(server_url)
+    # Normalize scheme/host casing per RFC guidance
+    normalized = parsed._replace(
+        scheme=parsed.scheme.lower(),
+        netloc=parsed.netloc.lower(),
+    )
+    resource = normalized.geturl()
+
+    # Prefer form without trailing slash unless path is meaningful
+    if resource.endswith("/") and parsed.path in ("", "/"):
+        resource = resource[:-1]
+    return resource