universal-mcp 0.1.7rc2__py3-none-any.whl → 0.1.8rc2__py3-none-any.whl

universal_mcp/applications/zenquotes/app.py

@@ -6,10 +6,20 @@ class ZenquotesApp(APIApplication):
         super().__init__(name="zenquote", **kwargs)
 
     def get_quote(self) -> str:
-        """Get an inspirational quote from the Zen Quotes API
-
+        """
+        Fetches a random inspirational quote from the Zen Quotes API.
+        
         Returns:
-            A random inspirational quote
+            A formatted string containing the quote and its author in the format 'quote - author'
+        
+        Raises:
+            RequestException: If the HTTP request to the Zen Quotes API fails
+            JSONDecodeError: If the API response contains invalid JSON
+            IndexError: If the API response doesn't contain any quotes
+            KeyError: If the quote data doesn't contain the expected 'q' or 'a' fields
+        
+        Tags:
+            fetch, quotes, api, http, important
         """
         url = "https://zenquotes.io/api/random"
         response = self._get(url)

universal_mcp/exceptions.py

@@ -1,6 +1,12 @@
 class NotAuthorizedError(Exception):
     """Raised when a user is not authorized to access a resource or perform an action."""
 
-    def __init__(self, message="Not authorized to perform this action"):
+    def __init__(self, message: str):
         self.message = message
-        super().__init__(self.message)
+
+
+class ToolError(Exception):
+    """Raised when a tool is not found or fails to execute."""
+
+class InvalidSignature(Exception):
+    """Raised when a signature is invalid."""

universal_mcp/integrations/__init__.py

@@ -1,8 +1,22 @@
+from universal_mcp.config import IntegrationConfig
 from universal_mcp.integrations.agentr import AgentRIntegration
 from universal_mcp.integrations.integration import (
     ApiKeyIntegration,
     Integration,
     OAuthIntegration,
 )
+from universal_mcp.stores.store import BaseStore
 
-__all__ = ["AgentRIntegration", "Integration", "ApiKeyIntegration", "OAuthIntegration"]
+
+def integration_from_config(config: IntegrationConfig, store: BaseStore | None = None, **kwargs) -> Integration:
+    if config.type == "api_key":
+        return ApiKeyIntegration(config.name, store=store, **kwargs)
+    elif config.type == "agentr":
+        api_key = kwargs.get("api_key")
+        if not api_key:
+            raise ValueError("api_key is required for AgentR integration")
+        return AgentRIntegration(config.name, api_key=api_key)
+    else:
+        raise ValueError(f"Unsupported integration type: {config.type}")
+
+__all__ = ["AgentRIntegration", "Integration", "ApiKeyIntegration", "OAuthIntegration", "integration_from_config"]

universal_mcp/integrations/integration.py

@@ -1,10 +1,12 @@
 from abc import ABC, abstractmethod
+from typing import Any
 
 import httpx
 from loguru import logger
 
 from universal_mcp.exceptions import NotAuthorizedError
-from universal_mcp.stores.store import Store
+from universal_mcp.stores import BaseStore
+from universal_mcp.stores.store import KeyNotFoundError
 
 
 def sanitize_api_key_name(name: str) -> str:
@@ -30,37 +32,43 @@ class Integration(ABC):
         store: Store instance for persisting credentials and other data
     """
 
-    def __init__(self, name: str, store: Store = None):
+    def __init__(self, name: str, store: BaseStore | None = None):
         self.name = name
         self.store = store
 
     @abstractmethod
-    def authorize(self):
+    def authorize(self) -> str | dict[str, Any]:
         """Authorize the integration.
 
         Returns:
-            str: Authorization URL.
+            Union[str, Dict[str, Any]]: Authorization URL or parameters needed for authorization.
+
+        Raises:
+            ValueError: If required configuration is missing.
         """
         pass
 
     @abstractmethod
-    def get_credentials(self):
+    def get_credentials(self) -> dict[str, Any]:
         """Get credentials for the integration.
 
         Returns:
-            dict: Credentials for the integration.
+            Dict[str, Any]: Credentials for the integration.
 
         Raises:
-            NotAuthorizedError: If credentials are not found.
+            NotAuthorizedError: If credentials are not found or invalid.
         """
         pass
 
     @abstractmethod
-    def set_credentials(self, credentials: dict):
+    def set_credentials(self, credentials: dict[str, Any]) -> None:
         """Set credentials for the integration.
 
         Args:
-            credentials: Credentials for the integration.
+            credentials: Dictionary containing credentials for the integration.
+
+        Raises:
+            ValueError: If credentials are invalid or missing required fields.
         """
         pass
 
@@ -82,35 +90,85 @@ class ApiKeyIntegration(Integration):
         store: Store instance for persisting credentials and other data
     """
 
-    def __init__(self, name: str, store: Store = None, **kwargs):
+    def __init__(self, name: str, store: BaseStore | None = None, **kwargs):
         sanitized_name = sanitize_api_key_name(name)
         super().__init__(sanitized_name, store, **kwargs)
         logger.info(f"Initializing API Key Integration: {name} with store: {store}")
 
-    def get_credentials(self):
-        credentials = self.store.get(self.name)
-        if credentials is None:
+    def get_credentials(self) -> dict[str, str]:
+        """Get API key credentials.
+
+        Returns:
+            Dict[str, str]: Dictionary containing the API key.
+
+        Raises:
+            NotAuthorizedError: If API key is not found.
+        """
+        try:
+            credentials = self.store.get(self.name)
+        except KeyNotFoundError:
             action = self.authorize()
             raise NotAuthorizedError(action)
         return {"api_key": credentials}
 
-    def set_credentials(self, credentials: dict):
+    def set_credentials(self, credentials: dict[str, Any]) -> None:
+        """Set API key credentials.
+
+        Args:
+            credentials: Dictionary containing the API key.
+
+        Raises:
+            ValueError: If credentials are invalid or missing API key.
+        """
+        if not credentials or not isinstance(credentials, dict):
+            raise ValueError("Invalid credentials format")
         self.store.set(self.name, credentials)
 
-    def authorize(self):
+    def authorize(self) -> str:
+        """Get authorization instructions for API key.
+
+        Returns:
+            str: Instructions for setting up API key.
+        """
         return f"Please ask the user for api key and set the API Key for {self.name} in the store"
 
 
 class OAuthIntegration(Integration):
+    """Integration class for OAuth based authentication.
+
+    This class implements the Integration interface for services that use OAuth
+    authentication. It handles the OAuth flow including authorization, token exchange,
+    and token refresh.
+
+    Args:
+        name: The name identifier for this integration
+        store: Optional Store instance for persisting credentials and other data
+        client_id: OAuth client ID
+        client_secret: OAuth client secret
+        auth_url: OAuth authorization URL
+        token_url: OAuth token exchange URL
+        scope: OAuth scope string
+        **kwargs: Additional keyword arguments passed to parent class
+
+    Attributes:
+        name: The name identifier for this integration
+        store: Store instance for persisting credentials and other data
+        client_id: OAuth client ID
+        client_secret: OAuth client secret
+        auth_url: OAuth authorization URL
+        token_url: OAuth token exchange URL
+        scope: OAuth scope string
+    """
+
     def __init__(
         self,
         name: str,
-        store: Store = None,
-        client_id: str = None,
-        client_secret: str = None,
-        auth_url: str = None,
-        token_url: str = None,
-        scope: str = None,
+        store: BaseStore | None = None,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        auth_url: str | None = None,
+        token_url: str | None = None,
+        scope: str | None = None,
         **kwargs,
     ):
         super().__init__(name, store, **kwargs)
@@ -120,20 +178,41 @@ class OAuthIntegration(Integration):
         self.token_url = token_url
         self.scope = scope
 
-    def get_credentials(self):
+    def get_credentials(self) -> dict[str, Any] | None:
+        """Get OAuth credentials.
+
+        Returns:
+            Optional[Dict[str, Any]]: Dictionary containing OAuth tokens if found, None otherwise.
+        """
         credentials = self.store.get(self.name)
         if not credentials:
             return None
         return credentials
 
-    def set_credentials(self, credentials: dict):
+    def set_credentials(self, credentials: dict[str, Any]) -> None:
+        """Set OAuth credentials.
+
+        Args:
+            credentials: Dictionary containing OAuth tokens.
+
+        Raises:
+            ValueError: If credentials are invalid or missing required tokens.
+        """
         if not credentials or not isinstance(credentials, dict):
             raise ValueError("Invalid credentials format")
         if "access_token" not in credentials:
             raise ValueError("Credentials must contain access_token")
         self.store.set(self.name, credentials)
 
-    def authorize(self):
+    def authorize(self) -> dict[str, Any]:
+        """Get OAuth authorization parameters.
+
+        Returns:
+            Dict[str, Any]: Dictionary containing OAuth authorization parameters.
+
+        Raises:
+            ValueError: If required OAuth configuration is missing.
+        """
         if not all([self.client_id, self.client_secret, self.auth_url, self.token_url]):
             raise ValueError("Missing required OAuth configuration")
 
@@ -150,7 +229,19 @@ class OAuthIntegration(Integration):
             "token_url": self.token_url,
         }
 
-    def handle_callback(self, code: str):
+    def handle_callback(self, code: str) -> dict[str, Any]:
+        """Handle OAuth callback and exchange code for tokens.
+
+        Args:
+            code: Authorization code from OAuth callback.
+
+        Returns:
+            Dict[str, Any]: Dictionary containing OAuth tokens.
+
+        Raises:
+            ValueError: If required OAuth configuration is missing.
+            httpx.HTTPError: If token exchange request fails.
+        """
         if not all([self.client_id, self.client_secret, self.token_url]):
             raise ValueError("Missing required OAuth configuration")
 
@@ -167,15 +258,29 @@ class OAuthIntegration(Integration):
         self.store.set(self.name, credentials)
         return credentials
 
-    def refresh_token(self):
+    def refresh_token(self) -> dict[str, Any]:
+        """Refresh OAuth access token using refresh token.
+
+        Returns:
+            Dict[str, Any]: Dictionary containing new OAuth tokens.
+
+        Raises:
+            ValueError: If required OAuth configuration is missing.
+            httpx.HTTPError: If token refresh request fails.
+            KeyError: If refresh token is not found in current credentials.
+        """
         if not all([self.client_id, self.client_secret, self.token_url]):
             raise ValueError("Missing required OAuth configuration")
 
+        credentials = self.get_credentials()
+        if not credentials or "refresh_token" not in credentials:
+            raise KeyError("Refresh token not found in current credentials")
+
         token_params = {
             "client_id": self.client_id,
             "client_secret": self.client_secret,
             "grant_type": "refresh_token",
-            "refresh_token": self.credentials["refresh_token"],
+            "refresh_token": credentials["refresh_token"],
         }
 
         response = httpx.post(self.token_url, data=token_params)

universal_mcp/servers/__init__.py

@@ -4,20 +4,11 @@ from universal_mcp.servers.server import AgentRServer, LocalServer
 
 def server_from_config(config: ServerConfig):
     if config.type == "agentr":
-        return AgentRServer(
-            name=config.name,
-            description=config.description,
-            api_key=config.api_key,
-            port=config.port,
-        )
-    elif config.type == "local":
-        return LocalServer(
-            name=config.name,
-            description=config.description,
-            store=config.store,
-            apps_list=config.apps,
-            port=config.port,
-        )
+        return AgentRServer(config=config, api_key=config.api_key)
 
+    elif config.type == "local":
+        return LocalServer(config=config)
+    else:
+        raise ValueError(f"Unsupported server type: {config.type}")
 
-__all__ = [AgentRServer, LocalServer]
+__all__ = [AgentRServer, LocalServer, server_from_config]