universal-mcp 0.1.23rc2__py3-none-any.whl → 0.1.24rc3__py3-none-any.whl

universal_mcp/analytics.py

@@ -8,6 +8,14 @@ from loguru import logger
 
 
 class Analytics:
+    """A singleton class for tracking analytics events using PostHog.
+
+    This class handles the initialization of the PostHog client and provides
+    methods to track key events such as application loading and tool execution.
+    Telemetry can be disabled by setting the TELEMETRY_DISABLED environment
+    variable to "true".
+    """
+
     _instance = None
 
     def __new__(cls):
@@ -17,7 +25,13 @@ class Analytics:
         return cls._instance
 
     def _initialize(self):
-        """Initialize the Analytics singleton"""
+        """Initializes the PostHog client and sets up analytics properties.
+
+        This internal method configures the PostHog API key and host.
+        It also determines if analytics should be enabled based on the
+        TELEMETRY_DISABLED environment variable and generates a unique
+        user ID.
+        """
         posthog.host = "https://us.i.posthog.com"
         posthog.api_key = "phc_6HXMDi8CjfIW0l04l34L7IDkpCDeOVz9cOz1KLAHXh8"
         self.enabled = os.getenv("TELEMETRY_DISABLED", "false").lower() != "true"
@@ -26,24 +40,36 @@ class Analytics:
     @staticmethod
     @lru_cache(maxsize=1)
     def get_version():
-        """
-        Get the version of the Universal MCP
+        """Retrieves the installed version of the universal_mcp package.
+
+        Uses importlib.metadata to get the package version.
+        Caches the result for efficiency.
+
+        Returns:
+            str: The package version string, or "unknown" if not found.
         """
         try:
             return version("universal_mcp")
-        except ImportError:
+        except ImportError:  # Should be PackageNotFoundError, but matching existing code
             return "unknown"
 
     def track_app_loaded(self, app_name: str):
-        """Track when the app is loaded"""
+        """Tracks an event when an application is successfully loaded.
+
+        This event helps understand which applications are being utilized.
+
+        Args:
+            app_name (str): The name of the application that was loaded.
+        """
         if not self.enabled:
             return
         try:
             properties = {
                 "version": self.get_version(),
                 "app_name": app_name,
+                "user_id": self.user_id,
             }
-            posthog.capture(self.user_id, "app_loaded", properties)
+            posthog.capture("app_loaded", properties=properties)
         except Exception as e:
             logger.error(f"Failed to track app_loaded event: {e}")
 
@@ -52,16 +78,19 @@ class Analytics:
         tool_name: str,
         app_name: str,
         status: str,
-        error: str = None,
-        user_id=None,
+        error: str | None = None,
     ):
-        """Track when a tool is called
+        """Tracks an event when a tool is called within an application.
+
+        This event provides insights into tool usage patterns, success rates,
+        and potential errors.
 
         Args:
-            tool_name: Name of the tool being called
-            status: Status of the tool call (success/error)
-            error: Error message if status is error
-            user_id: Optional user ID to track
+            tool_name (str): The name of the tool that was called.
+            app_name (str): The name of the application the tool belongs to.
+            status (str): The status of the tool call (e.g., "success", "error").
+            error (str, optional): The error message if the tool call failed.
+                                 Defaults to None.
         """
         if not self.enabled:
             return
@@ -72,8 +101,9 @@ class Analytics:
                 "status": status,
                 "error": error,
                 "version": self.get_version(),
+                "user_id": self.user_id,
             }
-            posthog.capture(self.user_id, "tool_called", properties)
+            posthog.capture("tool_called", properties=properties)
         except Exception as e:
             logger.error(f"Failed to track tool_called event: {e}")
 

universal_mcp/applications/__init__.py

@@ -1,9 +1,3 @@
-import importlib
-import os
-import subprocess
-import sys
-from pathlib import Path
-
 from loguru import logger
 
 from universal_mcp.applications.application import (
@@ -11,92 +5,65 @@ from universal_mcp.applications.application import (
     BaseApplication,
     GraphQLApplication,
 )
+from universal_mcp.config import AppConfig
 from universal_mcp.utils.common import (
-    get_default_class_name,
-    get_default_module_path,
-    get_default_package_name,
-    get_default_repository_path,
+    load_app_from_local_file,
+    load_app_from_local_folder,
+    load_app_from_package,
+    load_app_from_remote_file,
+    load_app_from_remote_zip,
 )
 
-UNIVERSAL_MCP_HOME = Path.home() / ".universal-mcp" / "packages"
-
-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(str(UNIVERSAL_MCP_HOME))
-
-
-# Name are in the format of "app-name", eg, google-calendar
-# Class name is NameApp, eg, GoogleCalendarApp
-
 app_cache: dict[str, type[BaseApplication]] = {}
 
 
-def _install_or_upgrade_package(package_name: str, repository_path: str):
+def app_from_slug(slug: str) -> type[BaseApplication]:
     """
-    Helper to install a package via pip from the universal-mcp GitHub repository.
+    Dynamically resolve and return the application class based on slug.
     """
-    uv_path = os.getenv("UV_PATH")
-    uv_executable = str(Path(uv_path) / "uv") if uv_path else "uv"
-    logger.info(f"Using uv executable: {uv_executable}")
-    cmd = [
-        uv_executable,
-        "pip",
-        "install",
-        "--upgrade",
-        repository_path,
-        "--target",
-        str(UNIVERSAL_MCP_HOME),
-    ]
-    logger.debug(f"Installing package '{package_name}' with command: {' '.join(cmd)}")
-    try:
-        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 '{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.debug(f"Package {package_name} installed successfully")
+    return app_from_config(AppConfig(name=slug, source_type="package"))
 
 
-def app_from_slug(slug: str):
+def app_from_config(config: AppConfig) -> type[BaseApplication]:
     """
-    Dynamically resolve and return the application class for the given slug.
-    Attempts installation from GitHub if the package is not found locally.
+    Dynamically resolve and return the application class based on AppConfig.
     """
-    if slug in app_cache:
-        return app_cache[slug]
-    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}'")
+    if config.name in app_cache:
+        return app_cache[config.name]
+
+    app_class = None
     try:
-        _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}'")
-        app_cache[slug] = class_
-        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
+        match config.source_type:
+            case "package":
+                app_class = load_app_from_package(config)
+            case "local_folder":
+                app_class = load_app_from_local_folder(config)
+            case "remote_zip":
+                app_class = load_app_from_remote_zip(config)
+            case "remote_file":
+                app_class = load_app_from_remote_file(config)
+            case "local_file":
+                app_class = load_app_from_local_file(config)
+            case _:
+                raise ValueError(f"Unsupported source_type: {config.source_type}")
+
     except Exception as e:
-        raise Exception(f"Error importing module '{module_path}': {e}") from e
+        logger.error(
+            f"Failed to load application '{config.name}' from source '{config.source_type}': {e}",
+            exc_info=True,
+        )
+        raise
+
+    if not app_class:
+        raise ImportError(f"Could not load application class for '{config.name}'")
+
+    logger.debug(f"Loaded class '{app_class.__name__}' for app '{config.name}'")
+    app_cache[config.name] = app_class
+    return app_class
 
 
 __all__ = [
-    "app_from_slug",
+    "app_from_config",
     "BaseApplication",
     "APIApplication",
     "GraphQLApplication",