alita-sdk 0.3.379__py3-none-any.whl → 0.3.462__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

@@ -3,7 +3,7 @@ from logging import getLogger
 from typing import Any, Type, Literal, Optional, Union, List
 
 from langchain_core.tools import BaseTool
-from pydantic import BaseModel, Field, create_model, EmailStr, constr
+from pydantic import BaseModel, Field, create_model, EmailStr, constr, ConfigDict
 
 from ...tools.utils import TOOLKIT_SPLITTER
 
@@ -19,6 +19,7 @@ class McpServerTool(BaseTool):
     server: str
     tool_timeout_sec: int = 60
 
+    model_config = ConfigDict(arbitrary_types_allowed=True)
 
     @staticmethod
     def create_pydantic_model_from_schema(schema: dict, model_name: str = "ArgsSchema"):
@@ -90,6 +91,7 @@ class McpServerTool(BaseTool):
         return create_model(model_name, **fields)
 
     def _run(self, *args, **kwargs):
+        # Extract the actual tool/prompt name (remove toolkit prefix)
         call_data = {
             "server": self.server,
             "tool_timeout_sec": self.tool_timeout_sec,

alita_sdk/runtime/tools/sandbox.py

@@ -2,9 +2,12 @@ import asyncio
 import logging
 import subprocess
 import os
-from typing import Any, Type, Optional, Dict, List, Literal
+from typing import Any, Type, Optional, Dict, List, Literal, Union
+from copy import deepcopy
+from pathlib import Path
 
 from langchain_core.tools import BaseTool, BaseToolkit
+from langchain_core.messages import ToolCall
 from pydantic import BaseModel, create_model, ConfigDict, Field
 from pydantic.fields import FieldInfo
 
@@ -19,7 +22,7 @@ def get_tools(tools_list: list, alita_client=None, llm=None, memory_store=None):
 
     Args:
         tools_list: List of tool configurations
-        alita_client: Alita client instance (unused for sandbox)
+        alita_client: Alita client instance for sandbox tools
         llm: LLM client instance (unused for sandbox)
         memory_store: Optional memory store instance (unused for sandbox)
 
@@ -34,6 +37,7 @@ def get_tools(tools_list: list, alita_client=None, llm=None, memory_store=None):
                 toolkit_instance = SandboxToolkit.get_toolkit(
                     stateful=tool['settings'].get('stateful', False),
                     allow_net=tool['settings'].get('allow_net', True),
+                    alita_client=alita_client,
                     toolkit_name=tool.get('toolkit_name', '')
                 )
                 all_tools.extend(toolkit_instance.get_tools())
@@ -60,36 +64,10 @@ def _is_deno_available() -> bool:
 
 
 def _setup_pyodide_cache_env() -> None:
-    """Setup Pyodide caching environment variables for performance optimization"""
+    """Setup Pyodide caching environment variables for performance optimization [NO-OP]"""
     try:
-        # Check if cache environment file exists and source it
-        cache_env_file = os.path.expanduser("~/.pyodide_cache_env")
-        if os.path.exists(cache_env_file):
-            with open(cache_env_file, 'r') as f:
-                for line in f:
-                    line = line.strip()
-                    if line.startswith('export ') and '=' in line:
-                        # Parse export VAR=value format
-                        var_assignment = line[7:]  # Remove 'export '
-                        if '=' in var_assignment:
-                            key, value = var_assignment.split('=', 1)
-                            # Remove quotes if present
-                            value = value.strip('"').strip("'")
-                            os.environ[key] = value
-                            logger.debug(f"Set Pyodide cache env: {key}={value}")
-
-        # Set default caching environment variables if not already set
-        cache_defaults = {
-            'PYODIDE_PACKAGES_PATH': os.path.expanduser('~/.cache/pyodide'),
-            'DENO_DIR': os.path.expanduser('~/.cache/deno'),
-            'PYODIDE_CACHE_DIR': os.path.expanduser('~/.cache/pyodide'),
-        }
-
-        for key, default_value in cache_defaults.items():
-            if key not in os.environ:
-                os.environ[key] = default_value
-                logger.debug(f"Set default Pyodide env: {key}={default_value}")
-
+        for key in ["SANDBOX_BASE", "DENO_DIR"]:
+            logger.info("Sandbox env: %s -> %s", key, os.environ.get(key, "n/a"))
     except Exception as e:
         logger.warning(f"Could not setup Pyodide cache environment: {e}")
 
@@ -126,6 +104,7 @@ class PyodideSandboxTool(BaseTool):
     allow_net: bool = True
     session_bytes: Optional[bytes] = None
     session_metadata: Optional[Dict] = None
+    alita_client: Optional[Any] = None
 
     def __init__(self, **kwargs: Any) -> None:
         super().__init__(**kwargs)
@@ -134,6 +113,28 @@ class PyodideSandboxTool(BaseTool):
         _setup_pyodide_cache_env()
         self._initialize_sandbox()
 
+    def _prepare_pyodide_input(self, code: str) -> str:
+        """Prepare input for PyodideSandboxTool by injecting state and alita_client into the code block."""
+        pyodide_predata = ""
+
+        # Add alita_client if available
+        if self.alita_client:
+            try:
+                # Get the directory of the current file and construct the path to sandbox_client.py
+                current_dir = Path(__file__).parent
+                sandbox_client_path = current_dir.parent / 'clients' / 'sandbox_client.py'
+
+                with open(sandbox_client_path, 'r') as f:
+                    sandbox_client_code = f.read()
+                pyodide_predata += f"{sandbox_client_code}\n"
+                pyodide_predata += (f"alita_client = SandboxClient(base_url='{self.alita_client.base_url}',"
+                                    f"project_id={self.alita_client.project_id},"
+                                    f"auth_token='{self.alita_client.auth_token}')\n")
+            except FileNotFoundError:
+                logger.error(f"sandbox_client.py not found. Ensure the file exists.")
+
+        return f"#elitea simplified client\n{pyodide_predata}{code}"
+
     def _initialize_sandbox(self) -> None:
         """Initialize the PyodideSandbox instance with optimized settings"""
         try:
@@ -148,9 +149,19 @@ class PyodideSandboxTool(BaseTool):
 
             from langchain_sandbox import PyodideSandbox
 
+            # Air-gapped settings
+            sandbox_base = os.environ.get("SANDBOX_BASE", os.path.expanduser('~/.cache/pyodide'))
+            sandbox_tmp = os.path.join(sandbox_base, "tmp")
+            deno_cache = os.environ.get("DENO_DIR", os.path.expanduser('~/.cache/deno'))
+
             # Configure sandbox with performance optimizations
             self._sandbox = PyodideSandbox(
                 stateful=self.stateful,
+                #
+                allow_env=["SANDBOX_BASE"],
+                allow_read=[sandbox_base, sandbox_tmp, deno_cache],
+                allow_write=[sandbox_tmp, deno_cache],
+                #
                 allow_net=self.allow_net,
                 # Use auto node_modules_dir for better caching
                 node_modules_dir="auto"
@@ -180,6 +191,9 @@ class PyodideSandboxTool(BaseTool):
             if self._sandbox is None:
                 self._initialize_sandbox()
 
+            # Prepare code with state and client injection
+            prepared_code = self._prepare_pyodide_input(code)
+
             # Check if we're already in an async context
             try:
                 loop = asyncio.get_running_loop()
@@ -187,11 +201,11 @@ class PyodideSandboxTool(BaseTool):
                 # We'll need to use a different approach
                 import concurrent.futures
                 with concurrent.futures.ThreadPoolExecutor() as executor:
-                    future = executor.submit(asyncio.run, self._arun(code))
+                    future = executor.submit(asyncio.run, self._arun(prepared_code))
                     return future.result()
             except RuntimeError:
                 # No running loop, safe to use asyncio.run
-                return asyncio.run(self._arun(code))
+                return asyncio.run(self._arun(prepared_code))
         except (ImportError, RuntimeError) as e:
             # Handle specific dependency errors gracefully
             error_msg = str(e)
@@ -250,7 +264,7 @@ class PyodideSandboxTool(BaseTool):
 
         except Exception as e:
             logger.error(f"Error executing code in sandbox: {e}")
-            return f"Error executing code: {str(e)}"
+            return {"error": f"Error executing code: {str(e)}"}
 
 
 class StatefulPyodideSandboxTool(PyodideSandboxTool):
@@ -278,7 +292,7 @@ class StatefulPyodideSandboxTool(PyodideSandboxTool):
 
 
 # Factory function for creating sandbox tools
-def create_sandbox_tool(stateful: bool = False, allow_net: bool = True) -> BaseTool:
+def create_sandbox_tool(stateful: bool = False, allow_net: bool = True, alita_client: Optional[Any] = None) -> BaseTool:
     """
     Factory function to create sandbox tools with specified configuration.
 
@@ -302,22 +316,22 @@ def create_sandbox_tool(stateful: bool = False, allow_net: bool = True) -> BaseT
         - Cached wheels reduce package download time from ~4.76s to near-instant
     """
     if stateful:
-        return StatefulPyodideSandboxTool(allow_net=allow_net)
+        return StatefulPyodideSandboxTool(allow_net=allow_net, alita_client=alita_client)
     else:
-        return PyodideSandboxTool(stateful=False, allow_net=allow_net)
+        return PyodideSandboxTool(stateful=False, allow_net=allow_net, alita_client=alita_client)
 
 
 class SandboxToolkit(BaseToolkit):
     tools: List[BaseTool] = []
 
     @staticmethod
-    def toolkit_config_schema() -> BaseModel:
+    def toolkit_config_schema() -> Type[BaseModel]:
         # Create sample tools to get their schemas
         sample_tools = [
             PyodideSandboxTool(),
             StatefulPyodideSandboxTool()
         ]
-        selected_tools = {x.name: x.args_schema.schema() for x in sample_tools}
+        selected_tools = {x.name: x.args_schema.model_json_schema() for x in sample_tools}
 
         return create_model(
             'sandbox',
@@ -338,24 +352,24 @@ class SandboxToolkit(BaseToolkit):
         )
 
     @classmethod
-    def get_toolkit(cls, stateful: bool = False, allow_net: bool = True, **kwargs):
+    def get_toolkit(cls, stateful: bool = False, allow_net: bool = True, alita_client=None, **kwargs):
         """
         Get toolkit with sandbox tools.
 
         Args:
             stateful: Whether to maintain state between executions
             allow_net: Whether to allow network access
+            alita_client: Alita client instance for sandbox tools
             **kwargs: Additional arguments
         """
         tools = []
 
         if stateful:
-            tools.append(StatefulPyodideSandboxTool(allow_net=allow_net))
+            tools.append(StatefulPyodideSandboxTool(allow_net=allow_net, alita_client=alita_client))
         else:
-            tools.append(PyodideSandboxTool(stateful=False, allow_net=allow_net))
+            tools.append(PyodideSandboxTool(stateful=False, allow_net=allow_net, alita_client=alita_client))
 
         return cls(tools=tools)
 
     def get_tools(self):
         return self.tools
-

alita_sdk/runtime/tools/vectorstore.py

@@ -414,7 +414,8 @@ class VectorStoreWrapper(BaseToolApiWrapper):
                 return {"status": "error", "message": f"Error: {format_exc()}"}
         if _documents:
             add_documents(vectorstore=self.vectorstore, documents=_documents)
-        return {"status": "ok", "message": f"successfully indexed {documents_count} documents"}
+        return {"status": "ok", "message": f"successfully indexed {documents_count} documents" if documents_count > 0
+        else "No new documents to index."}
 
     def search_documents(self, query:str, doctype: str = 'code', 
                          filter:dict|str={}, cut_off: float=0.5,

alita_sdk/runtime/tools/vectorstore_base.py

@@ -1,9 +1,9 @@
 import json
-import math
 from collections import OrderedDict
 from logging import getLogger
 from typing import Any, Optional, List, Dict, Generator
 
+import math
 from langchain_core.documents import Document
 from langchain_core.messages import HumanMessage
 from langchain_core.tools import ToolException
@@ -12,7 +12,7 @@ from pydantic import BaseModel, model_validator, Field
 
 from alita_sdk.tools.elitea_base import BaseToolApiWrapper
 from alita_sdk.tools.vector_adapters.VectorStoreAdapter import VectorStoreAdapterFactory
-from ..utils.logging import dispatch_custom_event
+from ...runtime.utils.utils import IndexerKeywords
 
 logger = getLogger(__name__)
 
@@ -222,6 +222,21 @@ class VectorStoreWrapperBase(BaseToolApiWrapper):
             raise RuntimeError(f"Multiple index_meta documents found: {index_metas}")
         return index_metas[0] if index_metas else None
 
+    def get_indexed_count(self, index_name: str) -> int:
+        from sqlalchemy.orm import Session
+        from sqlalchemy import func, or_
+
+        with Session(self.vectorstore.session_maker.bind) as session:
+            return session.query(
+                self.vectorstore.EmbeddingStore.id,
+            ).filter(
+                func.jsonb_extract_path_text(self.vectorstore.EmbeddingStore.cmetadata, 'collection') == index_name,
+                or_(
+                    func.jsonb_extract_path_text(self.vectorstore.EmbeddingStore.cmetadata, 'type').is_(None),
+                    func.jsonb_extract_path_text(self.vectorstore.EmbeddingStore.cmetadata, 'type') != IndexerKeywords.INDEX_META_TYPE.value
+                )
+            ).count()
+
     def _clean_collection(self, index_name: str = ''):
         """
         Clean the vectorstore collection by deleting all indexed data.
@@ -308,7 +323,8 @@ class VectorStoreWrapperBase(BaseToolApiWrapper):
                 return {"status": "error", "message": f"Error: {format_exc()}"}
         if _documents:
             add_documents(vectorstore=self.vectorstore, documents=_documents)
-        return {"status": "ok", "message": f"successfully indexed {documents_count} documents"}
+        return {"status": "ok", "message": f"successfully indexed {documents_count} documents" if documents_count > 0
+        else "no documents to index"}
 
     def search_documents(self, query:str, doctype: str = 'code', 
                          filter:dict|str={}, cut_off: float=0.5,

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