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

universal_mcp/tools/manager.py

@@ -5,14 +5,14 @@ from loguru import logger
 
 from universal_mcp.analytics import analytics
 from universal_mcp.applications.application import BaseApplication
-from universal_mcp.exceptions import ToolError
+from universal_mcp.exceptions import ToolNotFoundError
 from universal_mcp.tools.adapters import (
-    ToolFormat,
     convert_tool_to_langchain_tool,
     convert_tool_to_mcp_tool,
     convert_tool_to_openai_tool,
 )
 from universal_mcp.tools.tools import Tool
+from universal_mcp.types import ToolFormat
 
 # Constants
 DEFAULT_IMPORTANT_TAG = "important"
@@ -20,6 +20,17 @@ TOOL_NAME_SEPARATOR = "_"
 DEFAULT_APP_NAME = "common"
 
 
+def _get_app_and_tool_name(tool_name: str) -> tuple[str, str]:
+    """Get the app name from a tool name."""
+    if TOOL_NAME_SEPARATOR in tool_name:
+        app_name = tool_name.split(TOOL_NAME_SEPARATOR, 1)[0]
+        tool_name_without_app_name = tool_name.split(TOOL_NAME_SEPARATOR, 1)[1]
+    else:
+        app_name = DEFAULT_APP_NAME
+        tool_name_without_app_name = tool_name
+    return app_name, tool_name_without_app_name
+
+
 def _filter_by_name(tools: list[Tool], tool_names: list[str] | None) -> list[Tool]:
     """Filter tools by name using simple string matching.
 
@@ -81,22 +92,23 @@ def _filter_by_tags(tools: list[Tool], tags: list[str] | None) -> list[Tool]:
 
 
 class ToolManager:
-    """Manages FastMCP tools.
+    """
+    Manages tools
 
     This class provides functionality for registering, managing, and executing tools.
     It supports multiple tool formats and provides filtering capabilities based on names and tags.
     Tools are organized by their source application for better management.
     """
 
-    def __init__(self, warn_on_duplicate_tools: bool = True):
+    def __init__(self, warn_on_duplicate_tools: bool = True, default_format: ToolFormat = ToolFormat.MCP):
         """Initialize the ToolManager.
 
         Args:
             warn_on_duplicate_tools: Whether to warn when duplicate tool names are detected.
         """
-        self._tools_by_app: dict[str, dict[str, Tool]] = {}
         self._all_tools: dict[str, Tool] = {}
         self.warn_on_duplicate_tools = warn_on_duplicate_tools
+        self.default_format = default_format
 
     def get_tool(self, name: str) -> Tool | None:
         """Get tool by name.
@@ -109,25 +121,10 @@ class ToolManager:
         """
         return self._all_tools.get(name)
 
-    def get_tools_by_app(self, app_name: str | None = None) -> list[Tool]:
-        """Get all tools from a specific application.
-
-        Args:
-            app_name: The name of the application to get tools from.
-
-        Returns:
-            List of tools from the specified application.
-        """
-        if app_name:
-            return list(self._tools_by_app.get(app_name, {}).values())
-        else:
-            return list(self._all_tools.values())
-
     def list_tools(
         self,
-        format: ToolFormat = ToolFormat.MCP,
+        format: ToolFormat | None = None,
         tags: list[str] | None = None,
-        app_name: str | None = None,
         tool_names: list[str] | None = None,
     ) -> list:
         """List all registered tools in the specified format.
@@ -144,13 +141,18 @@ class ToolManager:
         Raises:
             ValueError: If an invalid format is provided.
         """
+        if format is None:
+            format = self.default_format
+
         # Start with app-specific tools or all tools
-        tools = self.get_tools_by_app(app_name)
+        tools = list(self._all_tools.values())
         # Apply filters
         tools = _filter_by_tags(tools, tags)
         tools = _filter_by_name(tools, tool_names)
 
         # Convert to requested format
+        if format == ToolFormat.NATIVE:
+            return [tool.fn for tool in tools]
         if format == ToolFormat.MCP:
             return [convert_tool_to_mcp_tool(tool) for tool in tools]
         elif format == ToolFormat.LANGCHAIN:
@@ -160,15 +162,12 @@ class ToolManager:
         else:
             raise ValueError(f"Invalid format: {format}")
 
-    def add_tool(
-        self, fn: Callable[..., Any] | Tool, name: str | None = None, app_name: str = DEFAULT_APP_NAME
-    ) -> Tool:
+    def add_tool(self, fn: Callable[..., Any] | Tool, name: str | None = None) -> Tool:
         """Add a tool to the manager.
 
         Args:
             fn: The tool function or Tool instance to add.
             name: Optional name override for the tool.
-            app_name: Application name to group the tool under.
 
         Returns:
             The registered Tool instance.
@@ -189,17 +188,11 @@ class ToolManager:
                     logger.debug(f"Tool '{tool.name}' with the same function already exists.")
             return existing
 
-        logger.debug(f"Adding tool: {tool.name} to app: {app_name}")
+        logger.debug(f"Adding tool: {tool.name}")
         self._all_tools[tool.name] = tool
-
-        # Group tool by application
-        if app_name not in self._tools_by_app:
-            self._tools_by_app[app_name] = {}
-        self._tools_by_app[app_name][tool.name] = tool
-
         return tool
 
-    def register_tools(self, tools: list[Tool], app_name: str = DEFAULT_APP_NAME) -> None:
+    def register_tools(self, tools: list[Tool]) -> None:
         """Register a list of tools.
 
         Args:
@@ -207,7 +200,12 @@ class ToolManager:
             app_name: Application name to group the tools under.
         """
         for tool in tools:
-            self.add_tool(tool, app_name=app_name)
+            app_name, tool_name = _get_app_and_tool_name(tool.name)
+
+            # Add prefix to tool name, if not already present
+            tool.name = f"{app_name}{TOOL_NAME_SEPARATOR}{tool_name}"
+            tool.tags.append(app_name)
+            self.add_tool(tool)
 
     def remove_tool(self, name: str) -> bool:
         """Remove a tool by name.
@@ -219,23 +217,13 @@ class ToolManager:
             True if the tool was removed, False if it didn't exist.
         """
         if name in self._all_tools:
-            self._all_tools[name]
             del self._all_tools[name]
-
-            # Remove from app-specific grouping if present
-            for app_tools in self._tools_by_app.values():
-                if name in app_tools:
-                    del app_tools[name]
-                    # PERFORMANCE: Break after finding and removing to avoid unnecessary iterations
-                    break
-
             return True
         return False
 
     def clear_tools(self) -> None:
         """Remove all registered tools."""
         self._all_tools.clear()
-        self._tools_by_app.clear()
 
     def register_tools_from_app(
         self,
@@ -272,7 +260,6 @@ class ToolManager:
             try:
                 tool_instance = Tool.from_function(function)
                 tool_instance.name = f"{app.name}{TOOL_NAME_SEPARATOR}{tool_instance.name}"
-                # BUG FIX: Avoid duplicate tags - check if app.name is already in tags before adding
                 if app.name not in tool_instance.tags:
                     tool_instance.tags.append(app.name)
                 tools.append(tool_instance)
@@ -280,19 +267,16 @@ class ToolManager:
                 tool_name = getattr(function, "__name__", "unknown")
                 logger.error(f"Failed to create Tool from '{tool_name}' in {app.name}: {e}")
 
-        # BUG FIX: Apply filtering logic correctly - if both tool_names and tags are provided,
-        # we should filter by both, not use default important tag
         if tags:
             tools = _filter_by_tags(tools, tags)
 
         if tool_names:
             tools = _filter_by_name(tools, tool_names)
 
-        # BUG FIX: Only use default important tag if NO filters are provided at all
         if not tool_names and not tags:
             tools = _filter_by_tags(tools, [DEFAULT_IMPORTANT_TAG])
 
-        self.register_tools(tools, app_name=app.name)
+        self.register_tools(tools)
 
     async def call_tool(
         self,
@@ -314,14 +298,15 @@ class ToolManager:
             ToolError: If the tool is not found or execution fails.
         """
         logger.debug(f"Calling tool: {name} with arguments: {arguments}")
-        app_name = name.split(TOOL_NAME_SEPARATOR, 1)[0] if TOOL_NAME_SEPARATOR in name else DEFAULT_APP_NAME
+        app_name, _ = _get_app_and_tool_name(name)
         tool = self.get_tool(name)
         if not tool:
-            raise ToolError(f"Unknown tool: {name}")
+            logger.error(f"Unknown tool: {name}")
+            raise ToolNotFoundError(f"Unknown tool: {name}")
         try:
             result = await tool.run(arguments, context)
             analytics.track_tool_called(name, app_name, "success")
             return result
         except Exception as e:
             analytics.track_tool_called(name, app_name, "error", str(e))
-            raise ToolError(f"Tool execution failed: {str(e)}") from e
+            raise e

universal_mcp/tools/registry.py

@@ -0,0 +1,41 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class ToolRegistry(ABC):
+    """Abstract base class for platform-specific functionality.
+
+    This class abstracts away platform-specific operations like fetching apps,
+    loading actions, and managing integrations. This allows the AutoAgent to
+    work with different platforms without being tightly coupled to any specific one.
+    """
+
+    @abstractmethod
+    async def list_apps(self) -> list[dict[str, Any]]:
+        """Get list of available apps from the platform.
+
+        Returns:
+            Return a list of apps with their details
+        """
+        pass
+
+    @abstractmethod
+    async def get_app_details(self, app_id: str) -> dict[str, Any]:
+        """Get detailed information about a specific app.
+
+        Args:
+            app_id: The ID of the app to get details for
+
+        Returns:
+            Dictionary containing app details
+        """
+        pass
+
+    @abstractmethod
+    async def load_tools(self, tools: list[str]) -> None:
+        """Load tools from the platform and register them as tools.
+
+        Args:
+            tools: The list of tools to load
+        """
+        pass

universal_mcp/tools/tools.py

@@ -3,14 +3,30 @@ from collections.abc import Callable
 from typing import Any
 
 import httpx
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, create_model
 
 from universal_mcp.exceptions import NotAuthorizedError, ToolError
-from universal_mcp.utils.docstring_parser import parse_docstring
+from universal_mcp.tools.docstring_parser import parse_docstring
 
 from .func_metadata import FuncMetadata
 
 
+def _get_return_type_schema(return_annotation: Any) -> dict[str, Any] | None:
+    """Convert return type annotation to JSON schema using Pydantic."""
+    if return_annotation == inspect.Signature.empty or return_annotation == Any:
+        return None
+
+    try:
+        temp_model = create_model("ReturnTypeModel", return_value=(return_annotation, ...))
+
+        full_schema = temp_model.model_json_schema()
+        return_field_schema = full_schema.get("properties", {}).get("return_value")
+
+        return return_field_schema
+    except Exception:
+        return None
+
+
 class Tool(BaseModel):
     """Internal tool registration info."""
 
@@ -27,6 +43,7 @@ class Tool(BaseModel):
     )
     tags: list[str] = Field(default_factory=list, description="Tags for categorizing the tool")
     parameters: dict[str, Any] = Field(description="JSON schema for tool parameters")
+    output_schema: dict[str, Any] | None = Field(default=None, description="JSON schema for tool output")
     fn_metadata: FuncMetadata = Field(
         description="Metadata about the function including a pydantic model for tool arguments"
     )
@@ -53,6 +70,9 @@ class Tool(BaseModel):
         func_arg_metadata = FuncMetadata.func_metadata(fn, arg_description=parsed_doc["args"])
         parameters = func_arg_metadata.arg_model.model_json_schema()
 
+        sig = inspect.signature(fn)
+        output_schema = _get_return_type_schema(sig.return_annotation)
+
         simple_args_descriptions: dict[str, str] = {}
         if parsed_doc.get("args"):
             for arg_name, arg_details in parsed_doc["args"].items():
@@ -68,6 +88,7 @@ class Tool(BaseModel):
             raises_description=parsed_doc["raises"],
             tags=parsed_doc["tags"],
             parameters=parameters,
+            output_schema=output_schema,
             fn_metadata=func_arg_metadata,
             is_async=is_async,
         )
@@ -87,7 +108,7 @@ class Tool(BaseModel):
             return message
         except httpx.HTTPStatusError as e:
             error_body = e.response.text or "<empty response>"
-            message = f"HTTP {e.response.status_code}: {error_body}"
+            message = f"HTTP Error, status code: {e.response.status_code}, error body: {error_body}"
             raise ToolError(message) from e
         except ValueError as e:
             message = f"Invalid arguments for tool {self.name}: {e}"

universal_mcp/types.py

@@ -0,0 +1,10 @@
+from enum import Enum
+
+
+class ToolFormat(str, Enum):
+    """Supported tool formats."""
+
+    NATIVE = "native"
+    MCP = "mcp"
+    LANGCHAIN = "langchain"
+    OPENAI = "openai"

universal_mcp/utils/common.py

@@ -1,3 +1,38 @@
+import hashlib
+import importlib
+import importlib.util
+import inspect
+import io
+import os
+import subprocess
+import sys
+import zipfile
+from pathlib import Path
+
+import httpx
+from loguru import logger
+
+from universal_mcp.applications.application import BaseApplication
+from universal_mcp.config import AppConfig
+
+# --- Global Constants and Setup ---
+
+UNIVERSAL_MCP_HOME = Path.home() / ".universal-mcp" / "packages"
+REMOTE_CACHE_DIR = UNIVERSAL_MCP_HOME / "remote_cache"
+
+if not UNIVERSAL_MCP_HOME.exists():
+    UNIVERSAL_MCP_HOME.mkdir(parents=True, exist_ok=True)
+if not REMOTE_CACHE_DIR.exists():
+    REMOTE_CACHE_DIR.mkdir(exist_ok=True)
+
+# set python path to include the universal-mcp home directory
+if str(UNIVERSAL_MCP_HOME) not in sys.path:
+    sys.path.append(str(UNIVERSAL_MCP_HOME))
+
+
+# --- Default Name Generators ---
+
+
 def get_default_repository_path(slug: str) -> str:
     """
     Convert a repository slug to a repository URL.
@@ -31,3 +66,213 @@ def get_default_class_name(slug: str) -> str:
     slug = slug.strip().lower()
     class_name = "".join(part.capitalize() for part in slug.split("-")) + "App"
     return class_name
+
+
+# --- Installation and Loading Helpers ---
+
+
+def install_or_upgrade_package(package_name: str, repository_path: str):
+    """
+    Helper to install a package via pip from the universal-mcp GitHub repository.
+    """
+    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, check=True)
+        if result.stdout:
+            logger.info(f"Command stdout: {result.stdout}")
+        if result.stderr:
+            logger.warning(f"Command stderr: {result.stderr}")
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Installation failed for '{package_name}': {e}")
+        logger.error(f"Command stdout:\n{e.stdout}")
+        logger.error(f"Command stderr:\n{e.stderr}")
+        raise ModuleNotFoundError(f"Installation failed for package '{package_name}'") from e
+    else:
+        logger.debug(f"Package {package_name} installed successfully")
+
+
+def install_dependencies_from_path(project_root: Path, target_install_dir: Path):
+    """
+    Installs dependencies from pyproject.toml or requirements.txt found in project_root.
+    """
+    uv_path = os.getenv("UV_PATH")
+    uv_executable = str(Path(uv_path) / "uv") if uv_path else "uv"
+    cmd = []
+
+    if (project_root / "pyproject.toml").exists():
+        logger.info(f"Found pyproject.toml in {project_root}, installing dependencies.")
+        cmd = [uv_executable, "pip", "install", ".", "--target", str(target_install_dir)]
+    elif (project_root / "requirements.txt").exists():
+        logger.info(f"Found requirements.txt in {project_root}, installing dependencies.")
+        cmd = [
+            uv_executable,
+            "pip",
+            "install",
+            "-r",
+            "requirements.txt",
+            "--target",
+            str(target_install_dir),
+        ]
+    else:
+        logger.debug(f"No dependency file found in {project_root}. Skipping dependency installation.")
+        return
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, check=True, cwd=project_root)
+        if result.stdout:
+            logger.info(f"Dependency installation stdout:\n{result.stdout}")
+        if result.stderr:
+            logger.warning(f"Dependency installation stderr:\n{result.stderr}")
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Dependency installation failed for project at '{project_root}': {e}")
+        logger.error(f"Command stdout:\n{e.stdout}")
+        logger.error(f"Command stderr:\n{e.stderr}")
+        raise RuntimeError(f"Failed to install dependencies for {project_root}") from e
+
+
+def _load_class_from_project_root(project_root: Path, config: AppConfig) -> type[BaseApplication]:
+    """Internal helper to load an application class from a local project directory."""
+    logger.debug(f"Attempting to load '{config.name}' from project root: {project_root}")
+    src_path = project_root / "src"
+    if not src_path.is_dir():
+        raise FileNotFoundError(f"Required 'src' directory not found in project at {project_root}")
+
+    install_dependencies_from_path(project_root, UNIVERSAL_MCP_HOME)
+
+    if str(src_path) not in sys.path:
+        sys.path.insert(0, str(src_path))
+        logger.debug(f"Added to sys.path: {src_path}")
+
+    module_path_str = get_default_module_path(config.name)
+    class_name_str = get_default_class_name(config.name)
+
+    try:
+        module = importlib.import_module(module_path_str)
+        importlib.reload(module)  # Reload to pick up changes
+        app_class = getattr(module, class_name_str)
+        return app_class
+    except (ModuleNotFoundError, AttributeError) as e:
+        logger.error(f"Failed to load module/class '{module_path_str}.{class_name_str}': {e}")
+        raise
+
+
+# --- Application Loaders ---
+
+
+def load_app_from_package(config: AppConfig) -> type[BaseApplication]:
+    """Loads an application from a pip-installable package."""
+    logger.debug(f"Loading '{config.name}' as a package.")
+    slug = config.name
+    repository_path = get_default_repository_path(slug)
+    package_name = get_default_package_name(slug)
+    install_or_upgrade_package(package_name, repository_path)
+
+    module_path_str = get_default_module_path(slug)
+    class_name_str = get_default_class_name(slug)
+    module = importlib.import_module(module_path_str)
+    return getattr(module, class_name_str)
+
+
+def load_app_from_local_folder(config: AppConfig) -> type[BaseApplication]:
+    """Loads an application from a local folder path."""
+    project_path = Path(config.source_path).resolve()
+    return _load_class_from_project_root(project_path, config)
+
+
+def load_app_from_remote_zip(config: AppConfig) -> type[BaseApplication]:
+    """Downloads, caches, and loads an application from a remote .zip file."""
+    url_hash = hashlib.sha256(config.source_path.encode()).hexdigest()[:16]
+    project_path = REMOTE_CACHE_DIR / f"{config.name}-{url_hash}"
+
+    if not project_path.exists():
+        logger.info(f"Downloading remote project for '{config.name}' from {config.source_path}")
+        project_path.mkdir(parents=True, exist_ok=True)
+        response = httpx.get(config.source_path, follow_redirects=True, timeout=120)
+        response.raise_for_status()
+        with zipfile.ZipFile(io.BytesIO(response.content)) as z:
+            z.extractall(project_path)
+        logger.info(f"Extracted remote project to {project_path}")
+
+    return _load_class_from_project_root(project_path, config)
+
+
+def load_app_from_remote_file(config: AppConfig) -> type[BaseApplication]:
+    """Downloads, caches, and loads an application from a remote Python file."""
+    logger.debug(f"Loading '{config.name}' as a remote file from {config.source_path}")
+    url_hash = hashlib.sha256(config.source_path.encode()).hexdigest()[:16]
+    cached_file_path = REMOTE_CACHE_DIR / f"{config.name}-{url_hash}.py"
+
+    if not cached_file_path.exists():
+        logger.info(f"Downloading remote file for '{config.name}' from {config.source_path}")
+        try:
+            response = httpx.get(config.source_path, follow_redirects=True, timeout=60)
+            response.raise_for_status()
+            cached_file_path.write_text(response.text, encoding="utf-8")
+            logger.info(f"Cached remote file to {cached_file_path}")
+        except httpx.HTTPStatusError as e:
+            logger.error(f"Failed to download remote file: {e.response.status_code} {e.response.reason_phrase}")
+            raise
+        except Exception as e:
+            logger.error(f"An unexpected error occurred during download: {e}")
+            raise
+
+    if not cached_file_path.stat().st_size > 0:
+        raise ImportError(f"Remote file at {cached_file_path} is empty.")
+
+    module_name = f"remote_app_{config.name}_{url_hash}"
+    spec = importlib.util.spec_from_file_location(module_name, cached_file_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Could not create module spec for {cached_file_path}")
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+
+    for name, obj in inspect.getmembers(module, inspect.isclass):
+        if obj.__module__ == module_name and issubclass(obj, BaseApplication) and obj is not BaseApplication:
+            logger.debug(f"Found application class '{name}' defined in remote file for '{config.name}'.")
+            return obj
+
+    raise ImportError(f"No class inheriting from BaseApplication found in remote file {config.source_path}")
+
+
+def load_app_from_local_file(config: AppConfig) -> type[BaseApplication]:
+    """Loads an application from a local Python file."""
+    logger.debug(f"Loading '{config.name}' as a local file from {config.source_path}")
+    local_file_path = Path(config.source_path).resolve()
+
+    if not local_file_path.is_file():
+        raise FileNotFoundError(f"Local file not found at: {local_file_path}")
+
+    if not local_file_path.stat().st_size > 0:
+        raise ImportError(f"Local file at {local_file_path} is empty.")
+
+    path_hash = hashlib.sha256(str(local_file_path).encode()).hexdigest()[:16]
+    module_name = f"local_app_{config.name}_{path_hash}"
+
+    spec = importlib.util.spec_from_file_location(module_name, local_file_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Could not create module spec for {local_file_path}")
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+
+    for name, obj in inspect.getmembers(module, inspect.isclass):
+        if obj.__module__ == module_name and issubclass(obj, BaseApplication) and obj is not BaseApplication:
+            logger.debug(f"Found application class '{name}' in local file for '{config.name}'.")
+            return obj
+
+    raise ImportError(f"No class inheriting from BaseApplication found in local file {config.source_path}")

universal_mcp/utils/installation.py

@@ -2,6 +2,7 @@ import json
 import shutil
 import sys
 from pathlib import Path
+from typing import Any
 
 from loguru import logger
 from rich import print
@@ -27,7 +28,7 @@ def get_uvx_path() -> Path:
     logger.error(
         "uvx executable not found in PATH, falling back to 'uvx'. Please ensure uvx is installed and in your PATH"
     )
-    return None  # Fall back to just "uvx" if not found
+    return Path("uvx")
 
 
 def _create_file_if_not_exists(path: Path) -> None:
@@ -38,10 +39,8 @@ def _create_file_if_not_exists(path: Path) -> None:
             json.dump({}, f)
 
 
-def _generate_mcp_config(api_key: str) -> None:
+def _generate_mcp_config(api_key: str) -> dict[str, Any]:
     uvx_path = get_uvx_path()
-    if not uvx_path:
-        raise ValueError("uvx executable not found in PATH")
     return {
         "command": str(uvx_path),
         "args": ["universal_mcp@latest", "run"],