universal-mcp 0.1.15rc5__py3-none-any.whl → 0.1.16__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

@@ -1,7 +1,7 @@
 import importlib
-import os
 import subprocess
 import sys
+from pathlib import Path
 
 from loguru import logger
 
@@ -10,55 +10,56 @@ 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")
+UNIVERSAL_MCP_HOME = Path.home() / ".universal-mcp" / "packages"
 
-if not os.path.exists(UNIVERSAL_MCP_HOME):
-    os.makedirs(UNIVERSAL_MCP_HOME)
+if not UNIVERSAL_MCP_HOME.exists():
+    UNIVERSAL_MCP_HOME.mkdir(parents=True, exist_ok=True)
 
 # set python path to include the universal-mcp home directory
-sys.path.append(UNIVERSAL_MCP_HOME)
+sys.path.append(str(UNIVERSAL_MCP_HOME))
 
 
 # Name are in the format of "app-name", eg, google-calendar
 # 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)}")
+    cmd = [
+        "uv",
+        "pip",
+        "install",
+        "--upgrade",
+        repository_path,
+        "--target",
+        str(UNIVERSAL_MCP_HOME),
+    ]
+    logger.debug(f"Installing package '{package_name}' with command: {' '.join(cmd)}")
     try:
-        subprocess.check_call(cmd)
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if result.stdout:
+            logger.info(f"Command stdout: {result.stdout}")
+        if result.stderr:
+            logger.info(f"Command stderr: {result.stderr}")
+        result.check_returncode()
     except subprocess.CalledProcessError as e:
-        logger.error(f"Installation failed for '{slug_clean}': {e}")
-        raise ModuleNotFoundError(
-            f"Installation failed for package '{slug_clean}'"
-        ) from e
+        logger.error(f"Installation failed for '{package_name}': {e}")
+        if e.stdout:
+            logger.error(f"Command stdout: {e.stdout}")
+        if e.stderr:
+            logger.error(f"Command stderr: {e.stderr}")
+        raise ModuleNotFoundError(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 +67,23 @@ 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(
-        f"Resolving app for slug '{slug}' → module '{module_path}', class '{class_name}'"
-    )
+    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__ = [