universal-mcp 0.1.7rc2__py3-none-any.whl → 0.1.8__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,13 @@
 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,31 @@
+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/agentr.py

@@ -29,7 +29,10 @@ class AgentRIntegration(Integration):
                 "API key for AgentR is missing. Please visit https://agentr.dev to create an API key, then set it as AGENTR_API_KEY environment variable."
             )
             raise ValueError("AgentR API key required - get one at https://agentr.dev")
-        self.base_url = os.getenv("AGENTR_BASE_URL", "https://api.agentr.dev")
+        self.base_url = os.getenv("AGENTR_BASE_URL", "https://api.agentr.dev").rstrip(
+            "/"
+        )
+        self._credentials = None
 
     def set_credentials(self, credentials: dict | None = None):
         """Set credentials for the integration.
@@ -43,9 +46,9 @@ class AgentRIntegration(Integration):
             str: Authorization URL from authorize() method
         """
         return self.authorize()
-        # raise NotImplementedError("AgentR Integration does not support setting credentials. Visit the authorize url to set credentials.")
 
-    def get_credentials(self):
+    @property
+    def credentials(self):
         """Get credentials for the integration from the AgentR API.
 
         Makes API request to retrieve stored credentials for this integration.
@@ -57,16 +60,36 @@ class AgentRIntegration(Integration):
             NotAuthorizedError: If credentials are not found (404 response)
             HTTPError: For other API errors
         """
+        if self._credentials is not None:
+            return self._credentials
         response = httpx.get(
             f"{self.base_url}/api/{self.name}/credentials/",
             headers={"accept": "application/json", "X-API-KEY": self.api_key},
         )
         if response.status_code == 404:
+            logger.warning(
+                f"No credentials found for {self.name}. Requesting authorization..."
+            )
             action = self.authorize()
             raise NotAuthorizedError(action)
         response.raise_for_status()
         data = response.json()
-        return data
+        self._credentials = data
+        return self._credentials
+
+    def get_credentials(self):
+        """Get credentials for the integration from the AgentR API.
+
+        Makes API request to retrieve stored credentials for this integration.
+
+        Returns:
+            dict: Credentials data from API response
+
+        Raises:
+            NotAuthorizedError: If credentials are not found (404 response)
+            HTTPError: For other API errors
+        """
+        return self.credentials
 
     def authorize(self):
         """Get authorization URL for the integration.

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,93 @@ 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):
+        self.type = "api_key"
         sanitized_name = sanitize_api_key_name(name)
         super().__init__(sanitized_name, store, **kwargs)
         logger.info(f"Initializing API Key Integration: {name} with store: {store}")
+        self._api_key: str | None = None
+
+    @property
+    def api_key(self) -> str | None:
+        if not self._api_key:
+            try:
+                credentials = self.store.get(self.name)
+                self.api_key = credentials
+            except KeyNotFoundError as e:
+                action = self.authorize()
+                raise NotAuthorizedError(action) from e
+        return self._api_key
+
+    def get_credentials(self) -> dict[str, str]:
+        """Get API key credentials.
 
-    def get_credentials(self):
-        credentials = self.store.get(self.name)
-        if credentials is None:
-            action = self.authorize()
-            raise NotAuthorizedError(action)
-        return {"api_key": credentials}
+        Returns:
+            Dict[str, str]: Dictionary containing the API key.
 
-    def set_credentials(self, credentials: dict):
+        Raises:
+            NotAuthorizedError: If API key is not found.
+        """
+        return {"api_key": self.api_key}
+
+    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 +186,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 +237,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 +266,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/logger.py

@@ -1,70 +1,17 @@
-import os
 import sys
-import uuid
-from functools import lru_cache
 
 from loguru import logger
 
 
-@lru_cache(maxsize=1)
-def get_version():
-    """
-    Get the version of the Universal MCP
-    """
-    try:
-        from importlib.metadata import version
-
-        return version("universal_mcp")
-    except ImportError:
-        return "unknown"
-
-
-def get_user_id():
-    """
-    Generate a unique user ID for the current session
-    """
-    return "universal_" + str(uuid.uuid4())[:8]
-
-
-def posthog_sink(message, user_id=get_user_id()):
-    """
-    Custom sink for sending logs to PostHog
-    """
-    try:
-        import posthog
-
-        posthog.host = "https://us.i.posthog.com"
-        posthog.api_key = "phc_6HXMDi8CjfIW0l04l34L7IDkpCDeOVz9cOz1KLAHXh8"
-
-        record = message.record
-        properties = {
-            "level": record["level"].name,
-            "module": record["name"],
-            "function": record["function"],
-            "line": record["line"],
-            "message": record["message"],
-            "version": get_version(),
-        }
-        posthog.capture(user_id, "universal_mcp", properties)
-    except Exception:
-        # Silently fail if PostHog capture fails - don't want logging to break the app
-        pass
-
-
 def setup_logger():
     logger.remove()
+    # STDOUT cant be used as a sink because it will break the stream
     # logger.add(
     #     sink=sys.stdout,
-    #     format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
     #     level="INFO",
-    #     colorize=True,
     # )
+    # STDERR
     logger.add(
         sink=sys.stderr,
-        format="<red>{time:YYYY-MM-DD HH:mm:ss}</red> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
-        level="WARNING",
-        colorize=True,
+        level="INFO",
     )
-    telemetry_enabled = os.getenv("TELEMETRY_ENABLED", "true").lower() == "true"
-    if telemetry_enabled:
-        logger.add(posthog_sink, level="INFO")  # PostHog telemetry

universal_mcp/servers/__init__.py

@@ -4,20 +4,12 @@ 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,
-        )
+        return AgentRServer(config=config, api_key=config.api_key)
+
     elif config.type == "local":
-        return LocalServer(
-            name=config.name,
-            description=config.description,
-            store=config.store,
-            apps_list=config.apps,
-            port=config.port,
-        )
+        return LocalServer(config=config)
+    else:
+        raise ValueError(f"Unsupported server type: {config.type}")
 
 
-__all__ = [AgentRServer, LocalServer]
+__all__ = [AgentRServer, LocalServer, server_from_config]