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

universal_mcp/stores/store.py

@@ -9,109 +9,119 @@ from universal_mcp.exceptions import KeyNotFoundError, StoreError
 
 
 class BaseStore(ABC):
-    """
-    Abstract base class defining the interface for credential stores.
-    All credential stores must implement get, set and delete methods.
+    """Abstract base class defining a common interface for credential stores.
+
+    This class outlines the essential methods (`get`, `set`, `delete`)
+    that all concrete store implementations must provide. It ensures a
+    consistent API for managing sensitive data across various storage
+    backends like in-memory dictionaries, environment variables, or
+    system keyrings.
     """
 
     @abstractmethod
     def get(self, key: str) -> Any:
-        """
-        Retrieve a value from the store by key.
+        """Retrieve data from the store.
 
         Args:
-            key (str): The key to look up
+            key (str): The key for which to retrieve the value.
 
         Returns:
-            Any: The stored value
+            Any: The value associated with the key.
 
         Raises:
-            KeyNotFoundError: If the key is not found in the store
-            StoreError: If there is an error accessing the store
+            KeyNotFoundError: If the specified key is not found in the store.
+            StoreError: For other store-related operational errors.
         """
         pass
 
     @abstractmethod
-    def set(self, key: str, value: str) -> None:
-        """
-        Store a value in the store with the given key.
+    def set(self, key: str, value: Any) -> None:
+        """Set or update a key-value pair in the store.
+
+        If the key already exists, its value should be updated. If the key
+        does not exist, it should be created.
 
         Args:
-            key (str): The key to store the value under
-            value (str): The value to store
+            key (str): The key to set or update.
+            value (Any): The value to associate with the key.
 
         Raises:
-            StoreError: If there is an error storing the value
+            StoreError: For store-related operational errors (e.g., write failures).
         """
         pass
 
     @abstractmethod
     def delete(self, key: str) -> None:
-        """
-        Delete a value from the store by key.
+        """Delete a key-value pair from the store.
 
         Args:
-            key (str): The key to delete
+            key (str): The key to delete.
 
         Raises:
-            KeyNotFoundError: If the key is not found in the store
-            StoreError: If there is an error deleting the value
+            KeyNotFoundError: If the specified key is not found in the store.
+            StoreError: For other store-related operational errors (e.g., delete failures).
         """
         pass
 
-    def __repr__(self):
+    def __repr__(self) -> str:
+        """Returns an unambiguous string representation of the store instance."""
         return f"{self.__class__.__name__}()"
 
-    def __str__(self):
+    def __str__(self) -> str:
+        """Returns a human-readable string representation of the store instance."""
         return self.__repr__()
 
 
 class MemoryStore(BaseStore):
-    """
-    In-memory credential store implementation.
-    Stores credentials in a dictionary that persists only for the duration of the program execution.
+    """In-memory credential and data store using a Python dictionary.
+
+    This store implementation holds all data within a dictionary in memory.
+    It is simple and fast but is not persistent; all stored data will be
+    lost when the application process terminates. Primarily useful for
+    testing, transient data, or development scenarios where persistence
+    is not required.
+
+    Attributes:
+        data (dict[str, Any]): The dictionary holding the stored key-value pairs.
     """
 
     def __init__(self):
-        """Initialize an empty dictionary to store the data."""
+        """Initializes the MemoryStore with an empty dictionary."""
         self.data: dict[str, Any] = {}
 
     def get(self, key: str) -> Any:
-        """
-        Retrieve a value from the in-memory store by key.
+        """Retrieves the value associated with the given key from the in-memory store.
 
         Args:
-            key (str): The key to look up
+            key (str): The key whose value is to be retrieved.
 
         Returns:
-            Any: The stored value
+            Any: The value associated with the key.
 
         Raises:
-            KeyNotFoundError: If the key is not found in the store
+            KeyNotFoundError: If the key is not found in the store.
         """
         if key not in self.data:
             raise KeyNotFoundError(f"Key '{key}' not found in memory store")
         return self.data[key]
 
-    def set(self, key: str, value: str) -> None:
-        """
-        Store a value in the in-memory store with the given key.
+    def set(self, key: str, value: Any) -> None:
+        """Sets or updates the value for a given key in the in-memory store.
 
         Args:
-            key (str): The key to store the value under
-            value (str): The value to store
+            key (str): The key to set or update.
+            value (Any): The value to associate with the key.
         """
-        self.data[key] = value
+        self.data[key] = value  # type: ignore
 
     def delete(self, key: str) -> None:
-        """
-        Delete a value from the in-memory store by key.
+        """Deletes a key-value pair from the in-memory store.
 
         Args:
-            key (str): The key to delete
+            key (str): The key to delete.
 
         Raises:
-            KeyNotFoundError: If the key is not found in the store
+            KeyNotFoundError: If the key is not found in the store.
         """
         if key not in self.data:
             raise KeyNotFoundError(f"Key '{key}' not found in memory store")
@@ -119,48 +129,51 @@ class MemoryStore(BaseStore):
 
 
 class EnvironmentStore(BaseStore):
-    """
-    Environment variable-based credential store implementation.
-    Uses OS environment variables to store and retrieve credentials.
+    """Credential and data store using operating system environment variables.
+
+    This store implementation interacts directly with environment variables
+    using `os.getenv`, `os.environ[]`, and `del os.environ[]`.
+    Changes made via `set` or `delete` will affect the environment of the
+    current Python process and potentially its subprocesses, but typically
+    do not persist beyond the life of the parent shell or system session
+    unless explicitly managed externally.
     """
 
     def get(self, key: str) -> Any:
-        """
-        Retrieve a value from environment variables by key.
+        """Retrieves the value of an environment variable.
 
         Args:
-            key (str): The environment variable name to look up
+            key (str): The name of the environment variable.
 
         Returns:
-            Any: The stored value
+            Any: The value of the environment variable as a string.
 
         Raises:
-            KeyNotFoundError: If the environment variable is not found
+            KeyNotFoundError: If the environment variable is not set.
         """
         value = os.getenv(key)
         if value is None:
             raise KeyNotFoundError(f"Environment variable '{key}' not found")
         return value
 
-    def set(self, key: str, value: str) -> None:
-        """
-        Set an environment variable.
+    def set(self, key: str, value: Any) -> None:
+        """Sets an environment variable in the current process.
 
         Args:
-            key (str): The environment variable name
-            value (str): The value to set
+            key (str): The name of the environment variable.
+            value (Any): The value to set for the environment variable.
+                         It will be converted to a string.
         """
-        os.environ[key] = value
+        os.environ[key] = str(value)
 
     def delete(self, key: str) -> None:
-        """
-        Delete an environment variable.
+        """Deletes an environment variable from the current process.
 
         Args:
-            key (str): The environment variable name to delete
+            key (str): The name of the environment variable to delete.
 
         Raises:
-            KeyNotFoundError: If the environment variable is not found
+            KeyNotFoundError: If the environment variable is not set.
         """
         if key not in os.environ:
             raise KeyNotFoundError(f"Environment variable '{key}' not found")
@@ -168,73 +181,93 @@ class EnvironmentStore(BaseStore):
 
 
 class KeyringStore(BaseStore):
-    """
-    System keyring-based credential store implementation.
-    Uses the system's secure credential storage facility via the keyring library.
+    """Secure credential store using the system's keyring service.
+
+    This store leverages the `keyring` library to interact with the
+    operating system's native secure credential management system
+    (e.g., macOS Keychain, Windows Credential Manager, Freedesktop Secret
+    Service / KWallet on Linux). It is suitable for storing sensitive
+    data like API keys and passwords persistently and securely.
+
+    Attributes:
+        app_name (str): The service name under which credentials are stored
+                        in the system keyring. This helps namespace credentials
+                        for different applications.
     """
 
     def __init__(self, app_name: str = "universal_mcp"):
-        """
-        Initialize the keyring store.
+        """Initializes the KeyringStore.
 
         Args:
-            app_name (str): The application name to use in keyring, defaults to "universal_mcp"
+            app_name (str, optional): The service name to use when interacting
+                with the system keyring. This helps to namespace credentials.
+                Defaults to "universal_mcp".
         """
         self.app_name = app_name
 
-    def get(self, key: str) -> Any:
-        """
-        Retrieve a password from the system keyring.
+    def get(self, key: str) -> str:
+        """Retrieves a secret (password) from the system keyring.
 
         Args:
-            key (str): The key to look up
+            key (str): The username or key associated with the secret.
 
         Returns:
-            Any: The stored value
+            str: The stored secret string.
 
         Raises:
-            KeyNotFoundError: If the key is not found in the keyring
-            StoreError: If there is an error accessing the keyring
+            KeyNotFoundError: If the key is not found in the keyring under
+                              `self.app_name`, or if `keyring` library errors occur.
         """
         try:
-            logger.info(f"Getting password for {key} from keyring")
+            logger.info(f"Getting password for {key} from keyring for app {self.app_name}")
             value = keyring.get_password(self.app_name, key)
             if value is None:
-                raise KeyNotFoundError(f"Key '{key}' not found in keyring")
+                raise KeyNotFoundError(f"Key '{key}' not found in keyring for app '{self.app_name}'")
             return value
-        except Exception as e:
-            raise KeyNotFoundError(f"Key '{key}' not found in keyring") from e
+        except Exception as e:  # Catches keyring specific errors too
+            # Log the original exception e if needed
+            raise KeyNotFoundError(
+                f"Failed to retrieve key '{key}' from keyring for app '{self.app_name}'. Original error: {type(e).__name__}"
+            ) from e  # Keep original exception context
 
-    def set(self, key: str, value: str) -> None:
-        """
-        Store a password in the system keyring.
+    def set(self, key: str, value: Any) -> None:
+        """Stores a secret (password) in the system keyring.
 
         Args:
-            key (str): The key to store the password under
-            value (str): The password to store
+            key (str): The username or key to associate with the secret.
+            value (Any): The secret to store. It will be converted to a string.
 
         Raises:
-            StoreError: If there is an error storing in the keyring
+            StoreError: If storing the secret in the keyring fails.
         """
         try:
-            logger.info(f"Setting password for {key} in keyring")
-            keyring.set_password(self.app_name, key, value)
+            logger.info(f"Setting password for {key} in keyring for app {self.app_name}")
+            keyring.set_password(self.app_name, key, str(value))
         except Exception as e:
-            raise StoreError(f"Error storing in keyring: {str(e)}") from e
+            raise StoreError(f"Error storing key '{key}' in keyring for app '{self.app_name}': {str(e)}") from e
 
     def delete(self, key: str) -> None:
-        """
-        Delete a password from the system keyring.
+        """Deletes a secret (password) from the system keyring.
 
         Args:
-            key (str): The key to delete
+            key (str): The username or key of the secret to delete.
 
         Raises:
-            KeyNotFoundError: If the key is not found in the keyring
-            StoreError: If there is an error deleting from the keyring
+            KeyNotFoundError: If the key is not found in the keyring (note: some
+                              keyring backends might not raise an error for
+                              non-existent keys, this tries to standardize).
+            StoreError: If deleting the secret from the keyring fails for other
+                        reasons.
         """
         try:
-            logger.info(f"Deleting password for {key} from keyring")
+            logger.info(f"Deleting password for {key} from keyring for app {self.app_name}")
+            # Attempt to get first to see if it exists, as delete might not error
+            # This is a workaround for keyring's inconsistent behavior
+            existing_value = keyring.get_password(self.app_name, key)
+            if existing_value is None:
+                raise KeyNotFoundError(f"Key '{key}' not found in keyring for app '{self.app_name}', cannot delete.")
             keyring.delete_password(self.app_name, key)
-        except Exception as e:
-            raise KeyNotFoundError(f"Key '{key}' not found in keyring") from e
+        except KeyNotFoundError:  # Re-raise if found by the get_password check
+            raise
+        except Exception as e:  # Catch other keyring errors
+            raise StoreError(f"Error deleting key '{key}' from keyring for app '{self.app_name}': {str(e)}") from e

universal_mcp/tools/adapters.py

@@ -102,3 +102,19 @@ def convert_tool_to_openai_tool(
     }
     logger.debug(f"Successfully converted tool '{tool.name}' to OpenAI format")
     return openai_tool
+
+
+def transform_mcp_tool_to_openai_tool(mcp_tool: Tool):
+    """Convert an MCP tool to an OpenAI tool."""
+    from openai.types import FunctionDefinition
+    from openai.types.chat import ChatCompletionToolParam
+
+    return ChatCompletionToolParam(
+        type="function",
+        function=FunctionDefinition(
+            name=mcp_tool.name,
+            description=mcp_tool.description or "",
+            parameters=mcp_tool.inputSchema,
+            strict=False,
+        ),
+    )

universal_mcp/tools/func_metadata.py

@@ -227,7 +227,7 @@ if __name__ == "__main__":
         sys.path.insert(0, str(package_source_parent_dir))
         print(f"DEBUG: Added to sys.path: {package_source_parent_dir}")
 
-    from universal_mcp.utils.docstring_parser import parse_docstring
+    from universal_mcp.tools.docstring_parser import parse_docstring
 
     def post_crm_v_objects_emails_create(self, associations, properties) -> dict[str, Any]:
         """

universal_mcp/tools/manager.py

@@ -88,7 +88,7 @@ class ToolManager:
     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:
@@ -97,6 +97,7 @@ class ToolManager:
         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.
@@ -125,7 +126,7 @@ class ToolManager:
 
     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,
@@ -144,6 +145,9 @@ 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)
         # Apply filters
@@ -207,6 +211,13 @@ class ToolManager:
             app_name: Application name to group the tools under.
         """
         for tool in tools:
+            # Add app name to tool name if not already present
+            if app_name not in tool.name:
+                tool.name = f"{app_name}{TOOL_NAME_SEPARATOR}{tool.name}"
+
+            if tool.name in self._all_tools:
+                logger.warning(f"Tool '{tool.name}' already exists. Skipping registration.")
+                continue
             self.add_tool(tool, app_name=app_name)
 
     def remove_tool(self, name: str) -> bool:
@@ -317,6 +328,7 @@ class ToolManager:
         app_name = name.split(TOOL_NAME_SEPARATOR, 1)[0] if TOOL_NAME_SEPARATOR in name else DEFAULT_APP_NAME
         tool = self.get_tool(name)
         if not tool:
+            logger.error(f"Unknown tool: {name}")
             raise ToolError(f"Unknown tool: {name}")
         try:
             result = await tool.run(arguments, context)
@@ -324,4 +336,4 @@ class ToolManager:
             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/tools.py

@@ -6,7 +6,7 @@ import httpx
 from pydantic import BaseModel, Field
 
 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
 
@@ -87,7 +87,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/utils/agentr.py

@@ -18,7 +18,8 @@ class AgentrClient:
         base_url (str, optional): Base URL for AgentR API. Defaults to https://api.agentr.dev
     """
 
-    def __init__(self, api_key: str, base_url: str = "https://api.agentr.dev"):
+    def __init__(self, api_key: str | None = None, base_url: str | None = None):
+        base_url = base_url or os.getenv("AGENTR_BASE_URL", "https://api.agentr.dev")
         self.base_url = base_url.rstrip("/")
         self.api_key = api_key or os.getenv("AGENTR_API_KEY")
         if not self.api_key:
@@ -62,9 +63,7 @@ class AgentrClient:
         Raises:
             HTTPError: If API request fails
         """
-        response = self.client.get(
-            f"/api/{integration_name}/authorize/",
-        )
+        response = self.client.get(f"/api/{integration_name}/authorize/")
         response.raise_for_status()
         url = response.json()
         return f"Please ask the user to visit the following url to authorize the application: {url}. Render the url in proper markdown format with a clickable link."

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"],

universal_mcp/utils/openapi/api_generator.py

@@ -55,10 +55,32 @@ def test_correct_output(gen_file: Path):
     return True
 
 
+def format_with_black(file_path: Path) -> bool:
+    """Format the given Python file with Black. Returns True if successful, False otherwise."""
+    try:
+        import black
+
+        content = file_path.read_text(encoding="utf-8")
+
+        formatted_content = black.format_file_contents(content, fast=False, mode=black.FileMode())
+
+        file_path.write_text(formatted_content, encoding="utf-8")
+
+        logger.info("Black formatting applied successfully to: %s", file_path)
+        return True
+    except ImportError:
+        logger.warning("Black not installed. Skipping formatting for: %s", file_path)
+        return False
+    except Exception as e:
+        logger.warning("Black formatting failed for %s: %s", file_path, e)
+        return False
+
+
 def generate_api_from_schema(
     schema_path: Path,
     output_path: Path | None = None,
     class_name: str | None = None,
+    filter_config_path: str | None = None,
 ) -> tuple[Path, Path]:
     """
     Generate API client from OpenAPI schema and write to app.py with a README.
@@ -69,7 +91,8 @@ def generate_api_from_schema(
     3. Ensure output directory exists.
     4. Write code to an intermediate app_generated.py and perform basic import checks.
     5. Copy/overwrite intermediate file to app.py.
-    6. Collect tools and generate README.md.
+    6. Format the final app.py file with Black.
+    7. Collect tools and generate README.md.
     """
     # Local imports for logging and file operations
 
@@ -85,7 +108,7 @@ def generate_api_from_schema(
 
     # 2. Generate client code
     try:
-        code = generate_api_client(schema, class_name)
+        code = generate_api_client(schema, class_name, filter_config_path)
         logger.info("API client code generated.")
     except Exception as e:
         logger.error("Code generation failed: %s", e)
@@ -128,6 +151,9 @@ def generate_api_from_schema(
     shutil.copy(gen_file, app_file)
     logger.info("App file written to: %s", app_file)
 
+    # 6. Format the final app.py file with Black
+    format_with_black(app_file)
+
     # Cleanup intermediate file
     try:
         os.remove(gen_file)

universal_mcp/utils/openapi/api_splitter.py

@@ -15,11 +15,11 @@ class APISegmentBase:
     def _get(self, url: str, params: dict = None, **kwargs):
         return self.main_app_client._get(url, params=params, **kwargs)
 
-    def _post(self, url: str, data: Any = None, files: Any = None, params: dict = None, content_type: str = None, **kwargs):
-        return self.main_app_client._post(url, data=data, files=files, params=params, content_type=content_type, **kwargs)
+    def _post(self, url: str, data: Any = None, params: dict = None, content_type: str = None, files: Any = None, **kwargs):
+        return self.main_app_client._post(url, data=data, params=params, content_type=content_type, files=files, **kwargs)
 
-    def _put(self, url: str, data: Any = None, files: Any = None, params: dict = None, content_type: str = None, **kwargs):
-        return self.main_app_client._put(url, data=data, files=files, params=params, content_type=content_type, **kwargs)
+    def _put(self, url: str, data: Any = None, params: dict = None, content_type: str = None, files: Any = None, **kwargs):
+        return self.main_app_client._put(url, data=data, params=params, content_type=content_type, files=files, **kwargs)
 
     def _patch(self, url: str, data: Any = None, params: dict = None, **kwargs):
         return self.main_app_client._patch(url, data=data, params=params, **kwargs)
@@ -27,20 +27,9 @@ class APISegmentBase:
     def _delete(self, url: str, params: dict = None, **kwargs):
         return self.main_app_client._delete(url, params=params, **kwargs)
 
-    def _get_json(self, url: str, params: dict = None, **kwargs):
-        return self.main_app_client._get_json(url, params=params, **kwargs)
+    def _handle_response(self, response):
+        return self.main_app_client._handle_response(response)
 
-    def _post_json(self, url: str, data: Any = None, files: Any = None, params: dict = None, content_type: str = "application/json", **kwargs):
-        return self.main_app_client._post_json(url, data=data, files=files, params=params, content_type=content_type, **kwargs)
-
-    def _put_json(self, url: str, data: Any = None, files: Any = None, params: dict = None, content_type: str = "application/json", **kwargs):
-        return self.main_app_client._put_json(url, data=data, files=files, params=params, content_type=content_type, **kwargs)
-
-    def _patch_json(self, url: str, data: Any = None, params: dict = None, **kwargs):
-        return self.main_app_client._patch_json(url, data=data, params=params, **kwargs)
-
-    def _delete_json(self, url: str, params: dict = None, **kwargs):
-        return self.main_app_client._delete_json(url, params=params, **kwargs)
 """
 
 
@@ -165,7 +154,7 @@ class MethodTransformer(ast.NodeTransformer):
         return self.generic_visit(node)
 
 
-def split_generated_app_file(input_app_file: Path, output_dir: Path):
+def split_generated_app_file(input_app_file: Path, output_dir: Path, package_name: str = None):
     content = input_app_file.read_text()
     tree = ast.parse(content)
 
@@ -515,7 +504,7 @@ def split_generated_app_file(input_app_file: Path, output_dir: Path):
         # Adjust import path for segments subfolder
         final_main_module_imports.append(
             ast.ImportFrom(
-                module=f".{segments_foldername}.{seg_detail['module_name']}",
+                module=f"universal_mcp_{package_name}.{segments_foldername}.{seg_detail['module_name']}",
                 names=[ast.alias(name=seg_detail["class_name"])],
                 level=0,
             )