universal-mcp 0.1.14__py3-none-any.whl → 0.1.15__py3-none-any.whl

universal_mcp/analytics.py

@@ -48,7 +48,12 @@ class Analytics:
             logger.error(f"Failed to track app_loaded event: {e}")
 
     def track_tool_called(
-        self, tool_name: str, status: str, error: str = None, user_id=None
+        self,
+        tool_name: str,
+        app_name: str,
+        status: str,
+        error: str = None,
+        user_id=None,
     ):
         """Track when a tool is called
 
@@ -63,6 +68,7 @@ class Analytics:
         try:
             properties = {
                 "tool_name": tool_name,
+                "app_name": app_name,
                 "status": status,
                 "error": error,
                 "version": self.get_version(),

universal_mcp/applications/README.md

@@ -0,0 +1,122 @@
+# Universal MCP Applications Module
+
+This module provides the core functionality for managing and integrating applications within the Universal MCP system. It offers a flexible framework for creating, managing, and interacting with various types of applications through a unified interface.
+
+## Overview
+
+The applications module provides three main base classes for building application integrations:
+
+1. `BaseApplication`: The abstract base class that defines the common interface for all applications
+2. `APIApplication`: A concrete implementation for applications that communicate via HTTP APIs
+3. `GraphQLApplication`: A specialized implementation for applications that use GraphQL APIs
+
+## Key Features
+
+- **Dynamic Application Loading**: Applications can be loaded dynamically from external packages
+- **Unified Credential Management**: Centralized handling of application credentials
+- **HTTP API Support**: Built-in support for RESTful API interactions
+- **GraphQL Support**: Specialized support for GraphQL-based applications
+- **Automatic Package Installation**: Automatic installation of application packages from GitHub
+
+## Base Classes
+
+### BaseApplication
+
+The foundation class for all applications, providing:
+- Basic initialization
+- Credential management
+- Tool listing interface
+
+### APIApplication
+
+Extends BaseApplication to provide:
+- HTTP client management
+- Authentication handling
+- Common HTTP methods (GET, POST, PUT, DELETE, PATCH)
+- Request/response handling
+
+### GraphQLApplication
+
+Specialized for GraphQL-based applications, offering:
+- GraphQL client management
+- Query and mutation execution
+- Authentication handling
+
+## Usage
+
+### Creating a New Application
+
+1. Create a new package following the naming convention: `universal_mcp_<app_name>`
+2. Implement your application class inheriting from one of the base classes
+3. Name your class following the convention: `<AppName>App`
+
+Example:
+```python
+from universal_mcp.applications import APIApplication
+
+class MyApp(APIApplication):
+    def __init__(self, name: str, integration=None, **kwargs):
+        super().__init__(name, integration, **kwargs)
+        self.base_url = "https://api.example.com"
+
+    def list_tools(self):
+        return [self.my_tool]
+
+    def my_tool(self):
+        # Implementation here
+        pass
+```
+
+### Loading an Application
+
+```python
+from universal_mcp.applications import app_from_slug
+
+# The system will automatically install the package if needed
+MyApp = app_from_slug("my-app")
+app = MyApp("my-app-instance")
+```
+
+## Authentication
+
+The module supports various authentication methods:
+- API Keys
+- Access Tokens
+- Custom Headers
+- Bearer Tokens
+
+Credentials are managed through the integration system and can be accessed via the `credentials` property.
+
+## Error Handling
+
+The module includes comprehensive error handling for:
+- Package installation failures
+- Import errors
+- API request failures
+- Authentication issues
+
+## Logging
+
+All operations are logged using the `loguru` logger, providing detailed information about:
+- Application initialization
+- API requests
+- Authentication attempts
+- Package installation
+- Error conditions
+
+## Requirements
+
+- Python 3.8+
+- httpx
+- gql
+- loguru
+- uv (for package installation)
+
+## Contributing
+
+To contribute a new application:
+1. Create a new package following the naming conventions
+2. Implement the application class
+3. Add proper error handling and logging
+4. Include comprehensive documentation
+5. Submit a pull request to the Universal MCP repository

universal_mcp/applications/__init__.py

@@ -2,6 +2,7 @@ import importlib
 import os
 import subprocess
 import sys
+from importlib.metadata import version
 
 from loguru import logger
 
@@ -10,6 +11,12 @@ from universal_mcp.applications.application import (
     BaseApplication,
     GraphQLApplication,
 )
+from universal_mcp.utils.common import (
+    get_default_class_name,
+    get_default_module_path,
+    get_default_package_name,
+    get_default_repository_path,
+)
 
 UNIVERSAL_MCP_HOME = os.path.join(os.path.expanduser("~"), ".universal-mcp", "packages")
 
@@ -24,41 +31,36 @@ sys.path.append(UNIVERSAL_MCP_HOME)
 # Class name is NameApp, eg, GoogleCalendarApp
 
 
-def _import_class(module_path: str, class_name: str):
-    """
-    Helper to import a class by name from a module.
-    Raises ModuleNotFoundError if module or class does not exist.
-    """
-    try:
-        module = importlib.import_module(module_path)
-    except ModuleNotFoundError as e:
-        logger.debug(f"Import failed for module '{module_path}': {e}")
-        raise
-    try:
-        return getattr(module, class_name)
-    except AttributeError as e:
-        logger.error(f"Class '{class_name}' not found in module '{module_path}'")
-        raise ModuleNotFoundError(
-            f"Class '{class_name}' not found in module '{module_path}'"
-        ) from e
-
-
-def _install_package(slug_clean: str):
+def _install_or_upgrade_package(package_name: str, repository_path: str):
     """
     Helper to install a package via pip from the universal-mcp GitHub repository.
     """
-    repo_url = f"git+https://github.com/universal-mcp/{slug_clean}"
-    cmd = ["uv", "pip", "install", repo_url, "--target", UNIVERSAL_MCP_HOME]
-    logger.info(f"Installing package '{slug_clean}' with command: {' '.join(cmd)}")
+    try:
+        current_version = version(package_name)
+        logger.info(f"Current version of {package_name} is {current_version}")
+    except ImportError:
+        current_version = None
+    if current_version is not None:
+        return
+    cmd = [
+        "uv",
+        "pip",
+        "install",
+        "--upgrade",
+        repository_path,
+        "--target",
+        UNIVERSAL_MCP_HOME,
+    ]
+    logger.debug(f"Installing package '{package_name}' with command: {' '.join(cmd)}")
     try:
         subprocess.check_call(cmd)
     except subprocess.CalledProcessError as e:
-        logger.error(f"Installation failed for '{slug_clean}': {e}")
+        logger.error(f"Installation failed for '{package_name}': {e}")
         raise ModuleNotFoundError(
-            f"Installation failed for package '{slug_clean}'"
+            f"Installation failed for package '{package_name}'"
         ) from e
     else:
-        logger.info(f"Package '{slug_clean}' installed successfully")
+        logger.debug(f"Package {package_name} installed successfully")
 
 
 def app_from_slug(slug: str):
@@ -66,29 +68,29 @@ def app_from_slug(slug: str):
     Dynamically resolve and return the application class for the given slug.
     Attempts installation from GitHub if the package is not found locally.
     """
-    slug_clean = slug.strip().lower()
-    class_name = "".join(part.capitalize() for part in slug_clean.split("-")) + "App"
-    package_prefix = f"universal_mcp_{slug_clean.replace('-', '_')}"
-    module_path = f"{package_prefix}.app"
-
-    logger.info(
+    class_name = get_default_class_name(slug)
+    module_path = get_default_module_path(slug)
+    package_name = get_default_package_name(slug)
+    repository_path = get_default_repository_path(slug)
+    logger.debug(
         f"Resolving app for slug '{slug}' → module '{module_path}', class '{class_name}'"
     )
     try:
-        return _import_class(module_path, class_name)
-    except ModuleNotFoundError as orig_err:
-        logger.warning(
-            f"Module '{module_path}' not found locally: {orig_err}. Installing..."
-        )
-        _install_package(slug_clean)
-        # Retry import after installation
-        try:
-            return _import_class(module_path, class_name)
-        except ModuleNotFoundError as retry_err:
-            logger.error(
-                f"Still cannot import '{module_path}' after installation: {retry_err}"
-            )
-            raise
+        _install_or_upgrade_package(package_name, repository_path)
+        module = importlib.import_module(module_path)
+        class_ = getattr(module, class_name)
+        logger.debug(f"Loaded class '{class_}' from module '{module_path}'")
+        return class_
+    except ModuleNotFoundError as e:
+        raise ModuleNotFoundError(
+            f"Package '{module_path}' not found locally. Please install it first."
+        ) from e
+    except AttributeError as e:
+        raise AttributeError(
+            f"Class '{class_name}' not found in module '{module_path}'"
+        ) from e
+    except Exception as e:
+        raise Exception(f"Error importing module '{module_path}': {e}") from e
 
 
 __all__ = [

universal_mcp/applications/application.py

@@ -1,7 +1,10 @@
 from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any
 
 import httpx
-from gql import Client, gql
+from gql import Client as GraphQLClient
+from gql import gql
 from gql.transport.requests import RequestsHTTPTransport
 from graphql import DocumentNode
 from loguru import logger
@@ -12,41 +15,95 @@ from universal_mcp.integrations import Integration
 
 class BaseApplication(ABC):
     """
-    BaseApplication is the base class for all applications.
+    Base class for all applications in the Universal MCP system.
+
+    This abstract base class defines the common interface and functionality
+    that all applications must implement. It provides basic initialization
+    and credential management capabilities.
+
+    Attributes:
+        name (str): The name of the application
+        _credentials (Optional[Dict[str, Any]]): Cached credentials for the application
     """
 
-    def __init__(self, name: str, **kwargs):
+    def __init__(self, name: str, **kwargs: Any) -> None:
+        """
+        Initialize the base application.
+
+        Args:
+            name: The name of the application
+            **kwargs: Additional keyword arguments passed to the application
+        """
         self.name = name
         logger.debug(f"Initializing Application '{name}' with kwargs: {kwargs}")
         analytics.track_app_loaded(name)  # Track app loading
 
     @abstractmethod
-    def list_tools(self):
+    def list_tools(self) -> list[Callable]:
+        """
+        List all available tools for the application.
+
+        Returns:
+            List[Any]: A list of tools available in the application
+        """
         pass
 
 
 class APIApplication(BaseApplication):
     """
-    APIApplication is an application that uses an API to interact with the world.
+    Application that uses HTTP APIs to interact with external services.
+
+    This class provides a base implementation for applications that communicate
+    with external services via HTTP APIs. It handles authentication, request
+    management, and response processing.
+
+    Attributes:
+        name (str): The name of the application
+        integration (Optional[Integration]): The integration configuration
+        default_timeout (int): Default timeout for HTTP requests in seconds
+        base_url (str): Base URL for API requests
     """
 
-    def __init__(self, name: str, integration: Integration = None, **kwargs):
+    def __init__(
+        self,
+        name: str,
+        integration: Integration | None = None,
+        client: httpx.Client | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialize the API application.
+
+        Args:
+            name: The name of the application
+            integration: Optional integration configuration
+            **kwargs: Additional keyword arguments
+        """
         super().__init__(name, **kwargs)
-        self.default_timeout = 180
-        self.integration = integration
+        self.default_timeout: int = 180
+        self.integration: Integration | None = integration
         logger.debug(
             f"Initializing APIApplication '{name}' with integration: {integration}"
         )
-        self._client = None
-        # base_url should be set by subclasses, e.g., self.base_url = "https://api.example.com"
+        self._client: httpx.Client | None = client
         self.base_url: str = ""  # Initialize, but subclasses should set this
 
-    def _get_headers(self):
+    def _get_headers(self) -> dict[str, str]:
+        """
+        Get the headers for API requests.
+
+        This method constructs the appropriate headers based on the available
+        credentials. It supports various authentication methods including
+        direct headers, API keys, and access tokens.
+
+        Returns:
+            Dict[str, str]: Headers to be used in API requests
+        """
         if not self.integration:
             logger.debug("No integration configured, returning empty headers")
             return {}
         credentials = self.integration.get_credentials()
-        logger.debug(f"Got credentials for integration: {credentials.keys()}")
+        logger.debug("Got credentials for integration")
 
         # Check if direct headers are provided
         headers = credentials.get("headers")
@@ -79,36 +136,74 @@ class APIApplication(BaseApplication):
         return {}
 
     @property
-    def client(self):
+    def client(self) -> httpx.Client:
+        """
+        Get the HTTP client instance.
+
+        This property ensures that the HTTP client is properly initialized
+        with the correct base URL and headers.
+
+        Returns:
+            httpx.Client: The initialized HTTP client
+        """
         if not self._client:
             headers = self._get_headers()
             if not self.base_url:
                 logger.warning(f"APIApplication '{self.name}' base_url is not set.")
-                # Fallback: Initialize client without base_url, requiring full URLs in methods
                 self._client = httpx.Client(
                     headers=headers, timeout=self.default_timeout
                 )
             else:
                 self._client = httpx.Client(
-                    base_url=self.base_url,  # Pass the base_url here
+                    base_url=self.base_url,
                     headers=headers,
                     timeout=self.default_timeout,
                 )
         return self._client
 
-    def _get(self, url, params=None):
+    def _get(self, url: str, params: dict[str, Any] | None = None) -> httpx.Response:
+        """
+        Make a GET request to the specified URL.
+
+        Args:
+            url: The URL to send the request to
+            params: Optional query parameters
+
+        Returns:
+            httpx.Response: The response from the server
+
+        Raises:
+            httpx.HTTPError: If the request fails
+        """
         logger.debug(f"Making GET request to {url} with params: {params}")
         response = self.client.get(url, params=params)
         response.raise_for_status()
         logger.debug(f"GET request successful with status code: {response.status_code}")
         return response
 
-    def _post(self, url, data, params=None):
+    def _post(
+        self, url: str, data: dict[str, Any], params: dict[str, Any] | None = None
+    ) -> httpx.Response:
+        """
+        Make a POST request to the specified URL.
+
+        Args:
+            url: The URL to send the request to
+            data: The data to send in the request body
+            params: Optional query parameters
+
+        Returns:
+            httpx.Response: The response from the server
+
+        Raises:
+            httpx.HTTPError: If the request fails
+        """
         logger.debug(
             f"Making POST request to {url} with params: {params} and data: {data}"
         )
-        response = self.client.post(
+        response = httpx.post(
             url,
+            headers=self._get_headers(),
             json=data,
             params=params,
         )
@@ -118,7 +213,23 @@ class APIApplication(BaseApplication):
         )
         return response
 
-    def _put(self, url, data, params=None):
+    def _put(
+        self, url: str, data: dict[str, Any], params: dict[str, Any] | None = None
+    ) -> httpx.Response:
+        """
+        Make a PUT request to the specified URL.
+
+        Args:
+            url: The URL to send the request to
+            data: The data to send in the request body
+            params: Optional query parameters
+
+        Returns:
+            httpx.Response: The response from the server
+
+        Raises:
+            httpx.HTTPError: If the request fails
+        """
         logger.debug(
             f"Making PUT request to {url} with params: {params} and data: {data}"
         )
@@ -131,8 +242,20 @@ class APIApplication(BaseApplication):
         logger.debug(f"PUT request successful with status code: {response.status_code}")
         return response
 
-    def _delete(self, url, params=None):
-        # Now `url` can be a relative path if base_url is set in the client
+    def _delete(self, url: str, params: dict[str, Any] | None = None) -> httpx.Response:
+        """
+        Make a DELETE request to the specified URL.
+
+        Args:
+            url: The URL to send the request to
+            params: Optional query parameters
+
+        Returns:
+            httpx.Response: The response from the server
+
+        Raises:
+            httpx.HTTPError: If the request fails
+        """
         logger.debug(f"Making DELETE request to {url} with params: {params}")
         response = self.client.delete(url, params=params, timeout=self.default_timeout)
         response.raise_for_status()
@@ -141,8 +264,23 @@ class APIApplication(BaseApplication):
         )
         return response
 
-    def _patch(self, url, data, params=None):
-        # Now `url` can be a relative path if base_url is set in the client
+    def _patch(
+        self, url: str, data: dict[str, Any], params: dict[str, Any] | None = None
+    ) -> httpx.Response:
+        """
+        Make a PATCH request to the specified URL.
+
+        Args:
+            url: The URL to send the request to
+            data: The data to send in the request body
+            params: Optional query parameters
+
+        Returns:
+            httpx.Response: The response from the server
+
+        Raises:
+            httpx.HTTPError: If the request fails
+        """
         logger.debug(
             f"Making PATCH request to {url} with params: {params} and data: {data}"
         )
@@ -157,25 +295,55 @@ class APIApplication(BaseApplication):
         )
         return response
 
-    def validate(self):
-        pass
-
 
 class GraphQLApplication(BaseApplication):
     """
-    GraphQLApplication is a collection of tools that can be used by an agent.
+    Application that uses GraphQL to interact with external services.
+
+    This class provides a base implementation for applications that communicate
+    with external services via GraphQL. It handles authentication, query execution,
+    and response processing.
+
+    Attributes:
+        name (str): The name of the application
+        base_url (str): Base URL for GraphQL endpoint
+        integration (Optional[Integration]): The integration configuration
     """
 
     def __init__(
-        self, name: str, base_url: str, integration: Integration = None, **kwargs
-    ):
+        self,
+        name: str,
+        base_url: str,
+        integration: Integration | None = None,
+        client: GraphQLClient | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialize the GraphQL application.
+
+        Args:
+            name: The name of the application
+            base_url: The base URL for the GraphQL endpoint
+            integration: Optional integration configuration
+            **kwargs: Additional keyword arguments
+        """
         super().__init__(name, **kwargs)
         self.base_url = base_url
+        self.integration = integration
         logger.debug(f"Initializing Application '{name}' with kwargs: {kwargs}")
-        analytics.track_app_loaded(name)  # Track app loading
-        self._client = None
+        self._client: GraphQLClient | None = client
+
+    def _get_headers(self) -> dict[str, str]:
+        """
+        Get the headers for GraphQL requests.
 
-    def _get_headers(self):
+        This method constructs the appropriate headers based on the available
+        credentials. It supports various authentication methods including
+        direct headers, API keys, and access tokens.
+
+        Returns:
+            Dict[str, str]: Headers to be used in GraphQL requests
+        """
         if not self.integration:
             logger.debug("No integration configured, returning empty headers")
             return {}
@@ -211,23 +379,64 @@ class GraphQLApplication(BaseApplication):
         return {}
 
     @property
-    def client(self):
+    def client(self) -> GraphQLClient:
+        """
+        Get the GraphQL client instance.
+
+        This property ensures that the GraphQL client is properly initialized
+        with the correct transport and headers.
+
+        Returns:
+            Client: The initialized GraphQL client
+        """
         if not self._client:
             headers = self._get_headers()
             transport = RequestsHTTPTransport(url=self.base_url, headers=headers)
-            self._client = Client(transport=transport, fetch_schema_from_transport=True)
+            self._client = GraphQLClient(
+                transport=transport, fetch_schema_from_transport=True
+            )
         return self._client
 
-    def mutate(self, mutation: str | DocumentNode, variables: dict = None):
+    def mutate(
+        self,
+        mutation: str | DocumentNode,
+        variables: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Execute a GraphQL mutation.
+
+        Args:
+            mutation: The GraphQL mutation string or DocumentNode
+            variables: Optional variables for the mutation
+
+        Returns:
+            Dict[str, Any]: The result of the mutation
+
+        Raises:
+            Exception: If the mutation execution fails
+        """
         if isinstance(mutation, str):
             mutation = gql(mutation)
         return self.client.execute(mutation, variable_values=variables)
 
-    def query(self, query: str | DocumentNode, variables: dict = None):
+    def query(
+        self,
+        query: str | DocumentNode,
+        variables: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Execute a GraphQL query.
+
+        Args:
+            query: The GraphQL query string or DocumentNode
+            variables: Optional variables for the query
+
+        Returns:
+            Dict[str, Any]: The result of the query
+
+        Raises:
+            Exception: If the query execution fails
+        """
         if isinstance(query, str):
             query = gql(query)
         return self.client.execute(query, variable_values=variables)
-
-    @abstractmethod
-    def list_tools(self):
-        pass