universal-mcp 0.1.15rc5__py3-none-any.whl → 0.1.16__py3-none-any.whl

universal_mcp/tools/manager.py

@@ -1,5 +1,5 @@
 from collections.abc import Callable
-from typing import Any, Literal
+from typing import Any
 
 from loguru import logger
 
@@ -7,98 +7,159 @@ from universal_mcp.analytics import analytics
 from universal_mcp.applications.application import BaseApplication
 from universal_mcp.exceptions import ToolError
 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
 
+# Constants
+DEFAULT_IMPORTANT_TAG = "important"
+TOOL_NAME_SEPARATOR = "_"
+
+
+def _filter_by_name(tools: list[Tool], tool_names: list[str]) -> list[Tool]:
+    if not tool_names:
+        return tools
+    return [tool for tool in tools if tool.name in tool_names]
+
+
+def _filter_by_tags(tools: list[Tool], tags: list[str] | None) -> list[Tool]:
+    tags = tags or [DEFAULT_IMPORTANT_TAG]
+    return [tool for tool in tools if any(tag in tool.tags for tag in tags)]
+
 
 class ToolManager:
-    """Manages FastMCP tools."""
+    """Manages FastMCP 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.
+    """
 
     def __init__(self, warn_on_duplicate_tools: bool = True):
+        """Initialize the ToolManager.
+
+        Args:
+            warn_on_duplicate_tools: Whether to warn when duplicate tool names are detected.
+        """
         self._tools: dict[str, Tool] = {}
         self.warn_on_duplicate_tools = warn_on_duplicate_tools
 
     def get_tool(self, name: str) -> Tool | None:
-        """Get tool by name."""
+        """Get tool by name.
+
+        Args:
+            name: The name of the tool to retrieve.
+
+        Returns:
+            The Tool instance if found, None otherwise.
+        """
         return self._tools.get(name)
 
     def list_tools(
-        self, format: Literal["mcp", "langchain", "openai"] = "mcp"
+        self,
+        format: ToolFormat = ToolFormat.MCP,
+        tags: list[str] | None = None,
     ) -> list[Tool]:
-        """List all registered tools."""
-        if format == "mcp":
-            return [convert_tool_to_mcp_tool(tool) for tool in self._tools.values()]
-        elif format == "langchain":
-            return [
-                convert_tool_to_langchain_tool(tool) for tool in self._tools.values()
-            ]
-        elif format == "openai":
-            return [convert_tool_to_openai_tool(tool) for tool in self._tools.values()]
+        """List all registered tools in the specified format.
+
+        Args:
+            format: The format to convert tools to.
+
+        Returns:
+            List of tools in the specified format.
+
+        Raises:
+            ValueError: If an invalid format is provided.
+        """
+
+        tools = list(self._tools.values())
+        if tags:
+            tools = _filter_by_tags(tools, tags)
+
+        if format == ToolFormat.MCP:
+            tools = [convert_tool_to_mcp_tool(tool) for tool in tools]
+        elif format == ToolFormat.LANGCHAIN:
+            tools = [convert_tool_to_langchain_tool(tool) for tool in tools]
+        elif format == ToolFormat.OPENAI:
+            tools = [convert_tool_to_openai_tool(tool) for tool in tools]
         else:
             raise ValueError(f"Invalid format: {format}")
 
-    # Modified add_tool to accept name override explicitly
-    def add_tool(
-        self, fn: Callable[..., Any] | Tool, name: str | None = None
-    ) -> Tool:  # Changed any to Any
-        """Add a tool to the server, allowing name override."""
-        # Create the Tool object using the provided name if available
+        return tools
+
+    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.
+
+        Returns:
+            The registered Tool instance.
+
+        Raises:
+            ValueError: If the tool name is invalid.
+        """
         tool = fn if isinstance(fn, Tool) else Tool.from_function(fn, name=name)
+
+        if not tool.name or not isinstance(tool.name, str):
+            raise ValueError("Tool name must be a non-empty string")
+
         existing = self._tools.get(tool.name)
         if existing:
             if self.warn_on_duplicate_tools:
-                # Check if it's the *exact* same function object being added again
                 if existing.fn is not tool.fn:
                     logger.warning(
                         f"Tool name '{tool.name}' conflicts with an existing tool. Skipping addition of new function."
                     )
                 else:
-                    logger.debug(
-                        f"Tool '{tool.name}' with the same function already exists."
-                    )
-            return existing  # Return the existing tool if name conflicts
+                    logger.debug(f"Tool '{tool.name}' with the same function already exists.")
+            return existing
 
         logger.debug(f"Adding tool: {tool.name}")
         self._tools[tool.name] = tool
         return tool
 
-    async def call_tool(
-        self,
-        name: str,
-        arguments: dict[str, Any],
-        context=None,
-    ) -> Any:
-        """Call a tool by name with arguments."""
-        tool = self.get_tool(name)
-        if not tool:
-            raise ToolError(f"Unknown tool: {name}")
-        try:
-            result = await tool.run(arguments)
-            analytics.track_tool_called(name, "success")
-            return result
-        except Exception as e:
-            analytics.track_tool_called(name, "error", str(e))
-            raise
+    def register_tools(self, tools: list[Tool]) -> None:
+        """Register a list of tools."""
+        for tool in tools:
+            self.add_tool(tool)
 
-    def get_tools_by_tags(self, tags: list[str]) -> list[Tool]:
-        """Get tools by tags."""
-        return [
-            tool
-            for tool in self._tools.values()
-            if any(tag in tool.tags for tag in tags)
-        ]
+    def remove_tool(self, name: str) -> bool:
+        """Remove a tool by name.
+
+        Args:
+            name: The name of the tool to remove.
+
+        Returns:
+            True if the tool was removed, False if it didn't exist.
+        """
+        if name in self._tools:
+            del self._tools[name]
+            return True
+        return False
+
+    def clear_tools(self) -> None:
+        """Remove all registered tools."""
+        self._tools.clear()
 
     def register_tools_from_app(
         self,
         app: BaseApplication,
-        tools: list[str] | None = None,
-        tags: list[str] | None = None,
+        tool_names: list[str] = None,
+        tags: list[str] = None,
     ) -> None:
+        """Register tools from an application.
+
+        Args:
+            app: The application to register tools from.
+            tools: Optional list of specific tool names to register.
+            tags: Optional list of tags to filter tools by.
+        """
         try:
-            available_tool_functions = app.list_tools()
+            functions = app.list_tools()
         except TypeError as e:
             logger.error(f"Error calling list_tools for app '{app.name}'. Error: {e}")
             return
@@ -106,75 +167,60 @@ class ToolManager:
             logger.error(f"Failed to get tool list from app '{app.name}': {e}")
             return
 
-        if not isinstance(available_tool_functions, list):
-            logger.error(
-                f"App '{app.name}' list_tools() did not return a list. Skipping registration."
-            )
+        if not isinstance(functions, list):
+            logger.error(f"App '{app.name}' list_tools() did not return a list. Skipping registration.")
             return
 
-        # Determine the effective filter lists *before* the loop for efficiency
-        # Use an empty list if None is passed, simplifies checks later
-        tools_name_filter = tools or []
-
-        # For tags, determine the filter list based on priority: passed 'tags' or default 'important'
-        # This list is only used if tools_name_filter is empty.
-        active_tags_filter = tags if tags else ["important"]  # Default filter
-
-        logger.debug(
-            f"Registering tools for '{app.name}'. Name filter: {tools_name_filter or 'None'}. Tag filter (if name filter empty): {active_tags_filter}"
-        )
-
-        for tool_func in available_tool_functions:
-            if not callable(tool_func):
-                logger.warning(
-                    f"Item returned by {app.name}.list_tools() is not callable: {tool_func}. Skipping."
-                )
+        tools = []
+        for function in functions:
+            if not callable(function):
+                logger.warning(f"Non-callable tool from {app.name}: {function}")
                 continue
 
             try:
-                # Create the Tool metadata object from the function.
-                # This parses docstring (including tags), gets signature etc.
-                tool_instance = Tool.from_function(tool_func)
+                tool_instance = Tool.from_function(function)
+                tool_instance.name = f"{app.name}{TOOL_NAME_SEPARATOR}{tool_instance.name}"
+                tool_instance.tags.append(app.name) if app.name not in tool_instance.tags else None
+                tools.append(tool_instance)
             except Exception as e:
-                logger.error(
-                    f"Failed to create Tool object from function '{getattr(tool_func, '__name__', 'unknown')}' in app '{app.name}': {e}"
-                )
-                continue  # Skip this tool if metadata creation fails
-
-            # --- Modify the Tool instance before filtering/registration ---
-            original_name = tool_instance.name
-            prefixed_name = f"{app.name}_{original_name}"
-            tool_instance.name = prefixed_name  # Update the name
-
-            # Add the app name itself as a tag for categorization
-            if app.name not in tool_instance.tags:
-                tool_instance.tags.append(app.name)
-
-            # --- Filtering Logic ---
-            should_register = False  # Default to not registering
-
-            if tools_name_filter:
-                # --- Primary Filter: Check against specific tool names ---
-                if tool_instance.name in tools_name_filter:
-                    should_register = True
-                    logger.debug(f"Tool '{tool_instance.name}' matched name filter.")
-                # If not in the name filter, it's skipped (should_register remains False)
-
-            else:
-                # --- Secondary Filter: Check against tags (since tools_name_filter is empty) ---
-                # Check if *any* tag in active_tags_filter exists in the tool's tags
-                # tool_instance.tags includes tags parsed from the docstring + app.name
-                if any(tag in tool_instance.tags for tag in active_tags_filter):
-                    should_register = True
-                    logger.debug(
-                        f"Tool '{tool_instance.name}' matched tag filter {active_tags_filter}."
-                    )
-                # else:
-                #     logger.debug(f"Tool '{tool_instance.name}' did NOT match tag filter {active_tags_filter}. Tool tags: {tool_instance.tags}")
-
-            # --- Add the tool if it passed the filters ---
-            if should_register:
-                # Pass the fully configured Tool *instance* to add_tool
-                self.add_tool(tool_instance)
-            # else: If not registered, optionally log it for debugging:
-            #    logger.trace(f"Tool '{tool_instance.name}' skipped due to filters.") # Use trace level
+                tool_name = getattr(function, "__name__", "unknown")
+                logger.error(f"Failed to create Tool from '{tool_name}' in {app.name}: {e}")
+
+        tools = _filter_by_name(tools, tool_names)
+        tools = _filter_by_tags(tools, tags)
+        self.register_tools(tools)
+        return
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any],
+        context: dict[str, Any] | None = None,
+    ) -> Any:
+        """Call a tool by name with arguments.
+
+        Args:
+            name: The name of the tool to call.
+            arguments: The arguments to pass to the tool.
+            context: Optional context information for the tool execution.
+
+        Returns:
+            The result of the tool execution.
+
+        Raises:
+            ToolError: If the tool is not found or execution fails.
+        """
+        logger.debug(f"Calling tool: {name} with arguments: {arguments}")
+        tool = self.get_tool(name)
+        if not tool:
+            raise ToolError(f"Unknown tool: {name}")
+
+        try:
+            result = await tool.run(arguments, context)
+            app_name = tool.name.split(TOOL_NAME_SEPARATOR)[0]
+            analytics.track_tool_called(name, app_name, "success")
+            return result
+        except Exception as e:
+            app_name = tool.name.split(TOOL_NAME_SEPARATOR)[0]
+            analytics.track_tool_called(name, app_name, "error", str(e))
+            raise ToolError(f"Tool execution failed: {str(e)}") from e

universal_mcp/tools/tools.py

@@ -20,20 +20,15 @@ class Tool(BaseModel):
     args_description: dict[str, str] = Field(
         default_factory=dict, description="Descriptions of arguments from the docstring"
     )
-    returns_description: str = Field(
-        default="", description="Description of the return value from the docstring"
-    )
+    returns_description: str = Field(default="", description="Description of the return value from the docstring")
     raises_description: dict[str, str] = Field(
         default_factory=dict,
         description="Descriptions of exceptions raised from the docstring",
     )
-    tags: list[str] = Field(
-        default_factory=list, description="Tags for categorizing the tool"
-    )
+    tags: list[str] = Field(default_factory=list, description="Tags for categorizing the tool")
     parameters: dict[str, Any] = Field(description="JSON schema for tool parameters")
     fn_metadata: FuncMetadata = Field(
-        description="Metadata about the function including a pydantic model for tool"
-        " arguments"
+        description="Metadata about the function including a pydantic model for tool arguments"
     )
     is_async: bool = Field(description="Whether the tool is async")
 
@@ -55,9 +50,7 @@ class Tool(BaseModel):
 
         is_async = inspect.iscoroutinefunction(fn)
 
-        func_arg_metadata = FuncMetadata.func_metadata(
-            fn,
-        )
+        func_arg_metadata = FuncMetadata.func_metadata(fn, arg_description=parsed_doc["args"])
         parameters = func_arg_metadata.arg_model.model_json_schema()
 
         return cls(
@@ -76,12 +69,12 @@ class Tool(BaseModel):
     async def run(
         self,
         arguments: dict[str, Any],
-        context=None,
+        context: dict[str, Any] | None = None,
     ) -> Any:
         """Run the tool with arguments."""
         try:
             return await self.fn_metadata.call_fn_with_arg_validation(
-                self.fn, self.is_async, arguments, None
+                self.fn, self.is_async, arguments, None, context=context
             )
         except NotAuthorizedError as e:
             message = f"Not authorized to call tool {self.name}: {e.message}"

universal_mcp/utils/agentr.py

@@ -26,9 +26,7 @@ class AgentrClient(metaclass=Singleton):
                 "API key for AgentR is missing. Please visit https://agentr.dev to create an API key, then set it as AGENTR_API_KEY environment variable."
             )
             raise ValueError("AgentR API key required - get one at https://agentr.dev")
-        self.base_url = (
-            base_url or os.getenv("AGENTR_BASE_URL", "https://api.agentr.dev")
-        ).rstrip("/")
+        self.base_url = (base_url or os.getenv("AGENTR_BASE_URL", "https://api.agentr.dev")).rstrip("/")
 
     def get_credentials(self, integration_name: str) -> dict:
         """Get credentials for an integration from the AgentR API.
@@ -48,9 +46,7 @@ class AgentrClient(metaclass=Singleton):
             headers={"accept": "application/json", "X-API-KEY": self.api_key},
         )
         if response.status_code == 404:
-            logger.warning(
-                f"No credentials found for {integration_name}. Requesting authorization..."
-            )
+            logger.warning(f"No credentials found for {integration_name}. Requesting authorization...")
             action = self.get_authorization_url(integration_name)
             raise NotAuthorizedError(action)
         response.raise_for_status()

universal_mcp/utils/common.py

@@ -0,0 +1,33 @@
+def get_default_repository_path(slug: str) -> str:
+    """
+    Convert a repository slug to a repository URL.
+    """
+    slug = slug.strip().lower()
+    return f"universal-mcp-{slug}"
+
+
+def get_default_package_name(slug: str) -> str:
+    """
+    Convert a repository slug to a package name.
+    """
+    slug = slug.strip().lower()
+    package_name = f"universal_mcp_{slug.replace('-', '_')}"
+    return package_name
+
+
+def get_default_module_path(slug: str) -> str:
+    """
+    Convert a repository slug to a module path.
+    """
+    package_name = get_default_package_name(slug)
+    module_path = f"{package_name}.app"
+    return module_path
+
+
+def get_default_class_name(slug: str) -> str:
+    """
+    Convert a repository slug to a class name.
+    """
+    slug = slug.strip().lower()
+    class_name = "".join(part.capitalize() for part in slug.split("-")) + "App"
+    return class_name

universal_mcp/utils/docstring_parser.py

@@ -81,17 +81,13 @@ def parse_docstring(docstring: str | None) -> dict[str, Any]:
         elif stripped_lower.startswith(("raises ", "errors ", "exceptions ")):
             section_type = "raises"
             # Capture content after header word and potential colon/space
-            parts = re.split(
-                r"[:\s]+", line.strip(), maxsplit=1
-            )  # B034: Use keyword maxsplit
+            parts = re.split(r"[:\s]+", line.strip(), maxsplit=1)  # B034: Use keyword maxsplit
             if len(parts) > 1:
                 header_content = parts[1].strip()
         elif stripped_lower.startswith(("tags",)):
             section_type = "tags"
             # Capture content after header word and potential colon/space
-            parts = re.split(
-                r"[:\s]+", line.strip(), maxsplit=1
-            )  # B034: Use keyword maxsplit
+            parts = re.split(r"[:\s]+", line.strip(), maxsplit=1)  # B034: Use keyword maxsplit
             if len(parts) > 1:
                 header_content = parts[1].strip()
 
@@ -117,9 +113,7 @@ def parse_docstring(docstring: str | None) -> dict[str, Any]:
         stripped_line = line.strip()
         original_indentation = len(line) - len(line.lstrip(" "))
 
-        is_new_section_header, new_section_type_this_line, header_content_this_line = (
-            check_for_section_header(line)
-        )
+        is_new_section_header, new_section_type_this_line, header_content_this_line = check_for_section_header(line)
 
         should_finalize_previous = False
 
@@ -156,10 +150,7 @@ def parse_docstring(docstring: str | None) -> dict[str, Any]:
             or (
                 current_section in ["args", "raises"]
                 and current_key is not None
-                and (
-                    key_pattern.match(line)
-                    or (original_indentation == 0 and stripped_line)
-                )
+                and (key_pattern.match(line) or (original_indentation == 0 and stripped_line))
             )
             or (
                 current_section in ["returns", "tags", "other"]