universal-mcp 0.1.23rc1__py3-none-any.whl → 0.1.24rc2__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,16 +40,27 @@ 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:
@@ -53,15 +78,22 @@ class Analytics:
         app_name: str,
         status: str,
         error: str = None,
-        user_id=None,
+        user_id=None,  # Note: user_id is captured in PostHog but not used from this param
     ):
-        """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.
+            user_id (str, optional): An optional user identifier.
+                                   Note: Currently, the class uses an internally
+                                   generated user_id for PostHog events.
         """
         if not self.enabled:
             return