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

universal_mcp/applications/application.py

@@ -1,7 +1,10 @@
 from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any
 
 import httpx
-from gql import Client, gql
+from gql import Client as GraphQLClient
+from gql import gql
 from gql.transport.requests import RequestsHTTPTransport
 from graphql import DocumentNode
 from loguru import logger
@@ -12,41 +15,93 @@ from universal_mcp.integrations import Integration
 
 class BaseApplication(ABC):
     """
-    BaseApplication is the base class for all applications.
+    Base class for all applications in the Universal MCP system.
+
+    This abstract base class defines the common interface and functionality
+    that all applications must implement. It provides basic initialization
+    and credential management capabilities.
+
+    Attributes:
+        name (str): The name of the application
+        _credentials (Optional[Dict[str, Any]]): Cached credentials for the application
     """
 
-    def __init__(self, name: str, **kwargs):
+    def __init__(self, name: str, **kwargs: Any) -> None:
+        """
+        Initialize the base application.
+
+        Args:
+            name: The name of the application
+            **kwargs: Additional keyword arguments passed to the application
+        """
         self.name = name
         logger.debug(f"Initializing Application '{name}' with kwargs: {kwargs}")
         analytics.track_app_loaded(name)  # Track app loading
 
     @abstractmethod
-    def list_tools(self):
+    def list_tools(self) -> list[Callable]:
+        """
+        List all available tools for the application.
+
+        Returns:
+            List[Any]: A list of tools available in the application
+        """
         pass
 
 
 class APIApplication(BaseApplication):
     """
-    APIApplication is an application that uses an API to interact with the world.
+    Application that uses HTTP APIs to interact with external services.
+
+    This class provides a base implementation for applications that communicate
+    with external services via HTTP APIs. It handles authentication, request
+    management, and response processing.
+
+    Attributes:
+        name (str): The name of the application
+        integration (Optional[Integration]): The integration configuration
+        default_timeout (int): Default timeout for HTTP requests in seconds
+        base_url (str): Base URL for API requests
     """
 
-    def __init__(self, name: str, integration: Integration = None, **kwargs):
+    def __init__(
+        self,
+        name: str,
+        integration: Integration | None = None,
+        client: httpx.Client | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialize the API application.
+
+        Args:
+            name: The name of the application
+            integration: Optional integration configuration
+            **kwargs: Additional keyword arguments
+        """
         super().__init__(name, **kwargs)
-        self.default_timeout = 180
-        self.integration = integration
-        logger.debug(
-            f"Initializing APIApplication '{name}' with integration: {integration}"
-        )
-        self._client = None
-        # base_url should be set by subclasses, e.g., self.base_url = "https://api.example.com"
-        self.base_url: str = ""  # Initialize, but subclasses should set this
+        self.default_timeout: int = 180
+        self.integration: Integration | None = integration
+        logger.debug(f"Initializing APIApplication '{name}' with integration: {integration}")
+        self._client: httpx.Client | None = client
+        self.base_url: str = ""
+
+    def _get_headers(self) -> dict[str, str]:
+        """
+        Get the headers for API requests.
+
+        This method constructs the appropriate headers based on the available
+        credentials. It supports various authentication methods including
+        direct headers, API keys, and access tokens.
 
-    def _get_headers(self):
+        Returns:
+            Dict[str, str]: Headers to be used in API requests
+        """
         if not self.integration:
             logger.debug("No integration configured, returning empty headers")
             return {}
         credentials = self.integration.get_credentials()
-        logger.debug(f"Got credentials for integration: {credentials.keys()}")
+        logger.debug("Got credentials for integration")
 
         # Check if direct headers are provided
         headers = credentials.get("headers")
@@ -55,11 +110,7 @@ class APIApplication(BaseApplication):
             return headers
 
         # Check if api key is provided
-        api_key = (
-            credentials.get("api_key")
-            or credentials.get("API_KEY")
-            or credentials.get("apiKey")
-        )
+        api_key = credentials.get("api_key") or credentials.get("API_KEY") or credentials.get("apiKey")
         if api_key:
             logger.debug("Using API key from credentials")
             return {
@@ -79,49 +130,87 @@ class APIApplication(BaseApplication):
         return {}
 
     @property
-    def client(self):
+    def client(self) -> httpx.Client:
+        """
+        Get the HTTP client instance.
+
+        This property ensures that the HTTP client is properly initialized
+        with the correct base URL and headers.
+
+        Returns:
+            httpx.Client: The initialized HTTP client
+        """
         if not self._client:
             headers = self._get_headers()
-            if not self.base_url:
-                logger.warning(f"APIApplication '{self.name}' base_url is not set.")
-                # Fallback: Initialize client without base_url, requiring full URLs in methods
-                self._client = httpx.Client(
-                    headers=headers, timeout=self.default_timeout
-                )
-            else:
-                self._client = httpx.Client(
-                    base_url=self.base_url,  # Pass the base_url here
-                    headers=headers,
-                    timeout=self.default_timeout,
-                )
+            self._client = httpx.Client(
+                base_url=self.base_url,
+                headers=headers,
+                timeout=self.default_timeout,
+            )
         return self._client
 
-    def _get(self, url, params=None):
+    def _get(self, url: str, params: dict[str, Any] | None = None) -> httpx.Response:
+        """
+        Make a GET request to the specified URL.
+
+        Args:
+            url: The URL to send the request to
+            params: Optional query parameters
+
+        Returns:
+            httpx.Response: The response from the server
+
+        Raises:
+            httpx.HTTPError: If the request fails
+        """
         logger.debug(f"Making GET request to {url} with params: {params}")
         response = self.client.get(url, params=params)
         response.raise_for_status()
         logger.debug(f"GET request successful with status code: {response.status_code}")
         return response
 
-    def _post(self, url, data, params=None):
-        logger.debug(
-            f"Making POST request to {url} with params: {params} and data: {data}"
-        )
-        response = self.client.post(
+    def _post(self, url: str, data: dict[str, Any], params: dict[str, Any] | None = None) -> httpx.Response:
+        """
+        Make a POST request to the specified URL.
+
+        Args:
+            url: The URL to send the request to
+            data: The data to send in the request body
+            params: Optional query parameters
+
+        Returns:
+            httpx.Response: The response from the server
+
+        Raises:
+            httpx.HTTPError: If the request fails
+        """
+        logger.debug(f"Making POST request to {url} with params: {params} and data: {data}")
+        response = httpx.post(
             url,
+            headers=self._get_headers(),
             json=data,
             params=params,
         )
         response.raise_for_status()
-        logger.debug(
-            f"POST request successful with status code: {response.status_code}"
-        )
+        logger.debug(f"POST request successful with status code: {response.status_code}")
         return response
 
-    def _put(self, url, data, params=None):
-        logger.debug(
-            f"Making PUT request to {url} with params: {params} and data: {data}"
-        )
+    def _put(self, url: str, data: dict[str, Any], params: dict[str, Any] | None = None) -> httpx.Response:
+        """
+        Make a PUT request to the specified URL.
+
+        Args:
+            url: The URL to send the request to
+            data: The data to send in the request body
+            params: Optional query parameters
+
+        Returns:
+            httpx.Response: The response from the server
+
+        Raises:
+            httpx.HTTPError: If the request fails
+        """
+        logger.debug(f"Making PUT request to {url} with params: {params} and data: {data}")
         response = self.client.put(
             url,
             json=data,
@@ -131,51 +220,100 @@ class APIApplication(BaseApplication):
         logger.debug(f"PUT request successful with status code: {response.status_code}")
         return response
 
-    def _delete(self, url, params=None):
-        # Now `url` can be a relative path if base_url is set in the client
+    def _delete(self, url: str, params: dict[str, Any] | None = None) -> httpx.Response:
+        """
+        Make a DELETE request to the specified URL.
+
+        Args:
+            url: The URL to send the request to
+            params: Optional query parameters
+
+        Returns:
+            httpx.Response: The response from the server
+
+        Raises:
+            httpx.HTTPError: If the request fails
+        """
         logger.debug(f"Making DELETE request to {url} with params: {params}")
         response = self.client.delete(url, params=params, timeout=self.default_timeout)
         response.raise_for_status()
-        logger.debug(
-            f"DELETE request successful with status code: {response.status_code}"
-        )
+        logger.debug(f"DELETE request successful with status code: {response.status_code}")
         return response
 
-    def _patch(self, url, data, params=None):
-        # Now `url` can be a relative path if base_url is set in the client
-        logger.debug(
-            f"Making PATCH request to {url} with params: {params} and data: {data}"
-        )
+    def _patch(self, url: str, data: dict[str, Any], params: dict[str, Any] | None = None) -> httpx.Response:
+        """
+        Make a PATCH request to the specified URL.
+
+        Args:
+            url: The URL to send the request to
+            data: The data to send in the request body
+            params: Optional query parameters
+
+        Returns:
+            httpx.Response: The response from the server
+
+        Raises:
+            httpx.HTTPError: If the request fails
+        """
+        logger.debug(f"Making PATCH request to {url} with params: {params} and data: {data}")
         response = self.client.patch(
             url,
             json=data,
             params=params,
         )
         response.raise_for_status()
-        logger.debug(
-            f"PATCH request successful with status code: {response.status_code}"
-        )
+        logger.debug(f"PATCH request successful with status code: {response.status_code}")
         return response
 
-    def validate(self):
-        pass
-
 
 class GraphQLApplication(BaseApplication):
     """
-    GraphQLApplication is a collection of tools that can be used by an agent.
+    Application that uses GraphQL to interact with external services.
+
+    This class provides a base implementation for applications that communicate
+    with external services via GraphQL. It handles authentication, query execution,
+    and response processing.
+
+    Attributes:
+        name (str): The name of the application
+        base_url (str): Base URL for GraphQL endpoint
+        integration (Optional[Integration]): The integration configuration
     """
 
     def __init__(
-        self, name: str, base_url: str, integration: Integration = None, **kwargs
-    ):
+        self,
+        name: str,
+        base_url: str,
+        integration: Integration | None = None,
+        client: GraphQLClient | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialize the GraphQL application.
+
+        Args:
+            name: The name of the application
+            base_url: The base URL for the GraphQL endpoint
+            integration: Optional integration configuration
+            **kwargs: Additional keyword arguments
+        """
         super().__init__(name, **kwargs)
         self.base_url = base_url
+        self.integration = integration
         logger.debug(f"Initializing Application '{name}' with kwargs: {kwargs}")
-        analytics.track_app_loaded(name)  # Track app loading
-        self._client = None
+        self._client: GraphQLClient | None = client
 
-    def _get_headers(self):
+    def _get_headers(self) -> dict[str, str]:
+        """
+        Get the headers for GraphQL requests.
+
+        This method constructs the appropriate headers based on the available
+        credentials. It supports various authentication methods including
+        direct headers, API keys, and access tokens.
+
+        Returns:
+            Dict[str, str]: Headers to be used in GraphQL requests
+        """
         if not self.integration:
             logger.debug("No integration configured, returning empty headers")
             return {}
@@ -189,11 +327,7 @@ class GraphQLApplication(BaseApplication):
             return headers
 
         # Check if api key is provided
-        api_key = (
-            credentials.get("api_key")
-            or credentials.get("API_KEY")
-            or credentials.get("apiKey")
-        )
+        api_key = credentials.get("api_key") or credentials.get("API_KEY") or credentials.get("apiKey")
         if api_key:
             logger.debug("Using API key from credentials")
             return {
@@ -211,23 +345,62 @@ class GraphQLApplication(BaseApplication):
         return {}
 
     @property
-    def client(self):
+    def client(self) -> GraphQLClient:
+        """
+        Get the GraphQL client instance.
+
+        This property ensures that the GraphQL client is properly initialized
+        with the correct transport and headers.
+
+        Returns:
+            Client: The initialized GraphQL client
+        """
         if not self._client:
             headers = self._get_headers()
             transport = RequestsHTTPTransport(url=self.base_url, headers=headers)
-            self._client = Client(transport=transport, fetch_schema_from_transport=True)
+            self._client = GraphQLClient(transport=transport, fetch_schema_from_transport=True)
         return self._client
 
-    def mutate(self, mutation: str | DocumentNode, variables: dict = None):
+    def mutate(
+        self,
+        mutation: str | DocumentNode,
+        variables: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Execute a GraphQL mutation.
+
+        Args:
+            mutation: The GraphQL mutation string or DocumentNode
+            variables: Optional variables for the mutation
+
+        Returns:
+            Dict[str, Any]: The result of the mutation
+
+        Raises:
+            Exception: If the mutation execution fails
+        """
         if isinstance(mutation, str):
             mutation = gql(mutation)
         return self.client.execute(mutation, variable_values=variables)
 
-    def query(self, query: str | DocumentNode, variables: dict = None):
+    def query(
+        self,
+        query: str | DocumentNode,
+        variables: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Execute a GraphQL query.
+
+        Args:
+            query: The GraphQL query string or DocumentNode
+            variables: Optional variables for the query
+
+        Returns:
+            Dict[str, Any]: The result of the query
+
+        Raises:
+            Exception: If the query execution fails
+        """
         if isinstance(query, str):
             query = gql(query)
         return self.client.execute(query, variable_values=variables)
-
-    @abstractmethod
-    def list_tools(self):
-        pass

universal_mcp/cli.py

@@ -7,8 +7,7 @@ from rich.panel import Panel
 
 from universal_mcp.utils.installation import (
     get_supported_apps,
-    install_claude,
-    install_cursor,
+    install_app,
 )
 
 # Setup rich console and logging
@@ -39,7 +38,7 @@ def generate(
     This name will be used for the folder in applications/.
     """
     # Import here to avoid circular imports
-    from universal_mcp.utils.api_generator import generate_api_from_schema
+    from universal_mcp.utils.openapi.api_generator import generate_api_from_schema
 
     if not schema_path.exists():
         console.print(f"[red]Error: Schema file {schema_path} does not exist[/red]")
@@ -62,17 +61,11 @@ def generate(
 @app.command()
 def readme(
     file_path: Path = typer.Argument(..., help="Path to the Python file to process"),
-    class_name: str = typer.Option(
-        None,
-        "--class-name",
-        "-c",
-        help="Class name to use for the API client",
-    ),
 ):
     """Generate a README.md file for the API client."""
-    from universal_mcp.utils.readme import generate_readme
+    from universal_mcp.utils.openapi.readme import generate_readme
 
-    readme_file = generate_readme(file_path, class_name)
+    readme_file = generate_readme(file_path)
     console.print(f"[green]README.md file generated at: {readme_file}[/green]")
 
 
@@ -91,7 +84,7 @@ def docgen(
     This command uses litellm with structured output to generate high-quality
     Google-style docstrings for all functions in the specified Python file.
     """
-    from universal_mcp.utils.docgen import process_file
+    from universal_mcp.utils.openapi.docgen import process_file
 
     if not file_path.exists():
         console.print(f"[red]Error: File not found: {file_path}[/red]")
@@ -107,9 +100,7 @@ def docgen(
 
 @app.command()
 def run(
-    config_path: Path | None = typer.Option(
-        None, "--config", "-c", help="Path to the config file"
-    ),
+    config_path: Path | None = typer.Option(None, "--config", "-c", help="Path to the config file"),
 ):
     """Run the MCP server"""
     from universal_mcp.config import ServerConfig
@@ -118,10 +109,7 @@ def run(
 
     setup_logger()
 
-    if config_path:
-        config = ServerConfig.model_validate_json(config_path.read_text())
-    else:
-        config = ServerConfig()
+    config = ServerConfig.model_validate_json(config_path.read_text()) if config_path else ServerConfig()
     server = server_from_config(config)
     server.run(transport=config.transport)
 
@@ -157,14 +145,7 @@ def install(app_name: str = typer.Argument(..., help="Name of app to install")):
         type=str,
     )
     try:
-        if app_name == "claude":
-            console.print(f"[blue]Installing mcp server for: {app_name}[/blue]")
-            install_claude(api_key)
-            console.print("[green]App installed successfully[/green]")
-        elif app_name == "cursor":
-            console.print(f"[blue]Installing mcp server for: {app_name}[/blue]")
-            install_cursor(api_key)
-            console.print("[green]App installed successfully[/green]")
+        install_app(app_name, api_key)
     except Exception as e:
         console.print(f"[red]Error installing app: {e}[/red]")
         raise typer.Exit(1) from e
@@ -213,7 +194,7 @@ def init(
             prompt_suffix=" (e.g., reddit, youtube): ",
         ).strip()
     validate_pattern(app_name, "app name")
-
+    app_name = app_name.lower()
     if not output_dir:
         path_str = typer.prompt(
             "Enter the output directory for the project",
@@ -225,18 +206,12 @@ def init(
     if not output_dir.exists():
         try:
             output_dir.mkdir(parents=True, exist_ok=True)
-            console.print(
-                f"[green]✅ Created output directory at '{output_dir}'[/green]"
-            )
+            console.print(f"[green]✅ Created output directory at '{output_dir}'[/green]")
         except Exception as e:
-            console.print(
-                f"[red]❌ Failed to create output directory '{output_dir}': {e}[/red]"
-            )
+            console.print(f"[red]❌ Failed to create output directory '{output_dir}': {e}[/red]")
             raise typer.Exit(code=1) from e
     elif not output_dir.is_dir():
-        console.print(
-            f"[red]❌ Output path '{output_dir}' exists but is not a directory.[/red]"
-        )
+        console.print(f"[red]❌ Output path '{output_dir}' exists but is not a directory.[/red]")
         raise typer.Exit(code=1)
 
     # Integration type
@@ -247,9 +222,7 @@ def init(
             prompt_suffix=" (api_key, oauth, agentr, none): ",
         ).lower()
     if integration_type not in ("api_key", "oauth", "agentr", "none"):
-        console.print(
-            "[red]❌ Integration type must be one of: api_key, oauth, agentr, none[/red]"
-        )
+        console.print("[red]❌ Integration type must be one of: api_key, oauth, agentr, none[/red]")
         raise typer.Exit(code=1)
 
     console.print("[blue]🚀 Generating project using cookiecutter...[/blue]")
@@ -264,11 +237,22 @@ def init(
             },
         )
     except Exception as exc:
-        console.print(f"❌ Project generation failed: {exc}", fg=typer.colors.RED)
+        console.print(f"❌ Project generation failed: {exc}")
         raise typer.Exit(code=1) from exc
 
-    project_dir = output_dir / f"universal-mcp-{app_name}"
-    console.print(f"✅ Project created at {project_dir}", fg=typer.colors.GREEN)
+    project_dir = output_dir / f"{app_name}"
+    console.print(f"✅ Project created at {project_dir}")
+
+
+@app.command()
+def preprocess(
+    schema_path: Path = typer.Option(None, "--schema", "-s", help="Path to the OpenAPI schema file."),
+    output_path: Path = typer.Option(None, "--output", "-o", help="Path to save the processed schema."),
+):
+    from universal_mcp.utils.openapi.preprocessor import run_preprocessing
+
+    """Preprocess an OpenAPI schema using LLM to fill or enhance descriptions."""
+    run_preprocessing(schema_path, output_path)
 
 
 if __name__ == "__main__":