universal-mcp 0.1.11rc3__py3-none-any.whl → 0.1.13__py3-none-any.whl

universal_mcp/applications/__init__.py

@@ -1,4 +1,7 @@
 import importlib
+import os
+import subprocess
+import sys
 
 from loguru import logger
 
@@ -8,19 +11,84 @@ from universal_mcp.applications.application import (
     GraphQLApplication,
 )
 
+UNIVERSAL_MCP_HOME = os.path.join(os.path.expanduser("~"), ".universal-mcp", "packages")
+
+if not os.path.exists(UNIVERSAL_MCP_HOME):
+    os.makedirs(UNIVERSAL_MCP_HOME)
+
+# set python path to include the universal-mcp home directory
+sys.path.append(UNIVERSAL_MCP_HOME)
+
+
 # Name are in the format of "app-name", eg, google-calendar
-# Folder name is "app_name", eg, google_calendar
 # Class name is NameApp, eg, GoogleCalendarApp
 
 
+def _import_class(module_path: str, class_name: str):
+    """
+    Helper to import a class by name from a module.
+    Raises ModuleNotFoundError if module or class does not exist.
+    """
+    try:
+        module = importlib.import_module(module_path)
+    except ModuleNotFoundError as e:
+        logger.debug(f"Import failed for module '{module_path}': {e}")
+        raise
+    try:
+        return getattr(module, class_name)
+    except AttributeError as e:
+        logger.error(f"Class '{class_name}' not found in module '{module_path}'")
+        raise ModuleNotFoundError(
+            f"Class '{class_name}' not found in module '{module_path}'"
+        ) from e
+
+
+def _install_package(slug_clean: str):
+    """
+    Helper to install a package via pip from the universal-mcp GitHub repository.
+    """
+    repo_url = f"git+https://github.com/universal-mcp/{slug_clean}"
+    cmd = ["uv", "pip", "install", repo_url, "--target", UNIVERSAL_MCP_HOME]
+    logger.info(f"Installing package '{slug_clean}' with command: {' '.join(cmd)}")
+    try:
+        subprocess.check_call(cmd)
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Installation failed for '{slug_clean}': {e}")
+        raise ModuleNotFoundError(
+            f"Installation failed for package '{slug_clean}'"
+        ) from e
+    else:
+        logger.info(f"Package '{slug_clean}' installed successfully")
+
+
 def app_from_slug(slug: str):
-    name = slug.lower().strip()
-    app_name = "".join(word.title() for word in name.split("-")) + "App"
-    folder_name = name.replace("-", "_").lower()
-    logger.info(f"Importing {app_name} from {folder_name}")
-    module = importlib.import_module(f"universal_mcp.applications.{folder_name}.app")
-    app_class = getattr(module, app_name)
-    return app_class
+    """
+    Dynamically resolve and return the application class for the given slug.
+    Attempts installation from GitHub if the package is not found locally.
+    """
+    slug_clean = slug.strip().lower()
+    class_name = "".join(part.capitalize() for part in slug_clean.split("-")) + "App"
+    package_prefix = f"universal_mcp_{slug_clean.replace('-', '_')}"
+    module_path = f"{package_prefix}.app"
+
+    logger.info(
+        f"Resolving app for slug '{slug}' → module '{module_path}', class '{class_name}'"
+    )
+    try:
+        return _import_class(module_path, class_name)
+    except ModuleNotFoundError as orig_err:
+        logger.warning(
+            f"Module '{module_path}' not found locally: {orig_err}. Installing..."
+        )
+        _install_package(slug_clean)
+        # Retry import after installation
+        try:
+            return _import_class(module_path, class_name)
+        except ModuleNotFoundError as retry_err:
+            logger.error(
+                f"Still cannot import '{module_path}' after installation: {retry_err}"
+            )
+            raise
 
 
 __all__ = [

universal_mcp/cli.py

@@ -1,5 +1,4 @@
-import asyncio
-import os
+import re
 from pathlib import Path
 
 import typer
@@ -24,8 +23,11 @@ def generate(
         "-o",
         help="Output file path - should match the API name (e.g., 'twitter.py' for Twitter API)",
     ),
-    add_docstrings: bool = typer.Option(
-        True, "--docstrings/--no-docstrings", help="Add docstrings to generated code"
+    class_name: str = typer.Option(
+        None,
+        "--class-name",
+        "-c",
+        help="Class name to use for the API client",
     ),
 ):
     """Generate API client from OpenAPI schema with optional docstring generation.
@@ -42,42 +44,44 @@ def generate(
 
     try:
         # Run the async function in the event loop
-        result = asyncio.run(
-            generate_api_from_schema(
-                schema_path=schema_path,
-                output_path=output_path,
-                add_docstrings=add_docstrings,
-            )
+        app_file = generate_api_from_schema(
+            schema_path=schema_path,
+            output_path=output_path,
+            class_name=class_name,
         )
-
-        if not output_path:
-            # Print to stdout if no output path
-            print(result["code"])
-        else:
-            typer.echo("API client successfully generated and installed.")
-            if "app_file" in result:
-                typer.echo(f"Application file: {result['app_file']}")
-            if "readme_file" in result and result["readme_file"]:
-                typer.echo(f"Documentation: {result['readme_file']}")
+        typer.echo("API client successfully generated and installed.")
+        typer.echo(f"Application file: {app_file}")
     except Exception as e:
         typer.echo(f"Error generating API client: {e}", err=True)
         raise typer.Exit(1) from e
 
 
+@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
+
+    readme_file = generate_readme(file_path, class_name)
+    typer.echo(f"README.md file generated at: {readme_file}")
+
+
 @app.command()
 def docgen(
     file_path: Path = typer.Argument(..., help="Path to the Python file to process"),
     model: str = typer.Option(
-        "anthropic/claude-3-5-sonnet-20241022",
+        "perplexity/sonar",
         "--model",
         "-m",
         help="Model to use for generating docstrings",
     ),
-    api_key: str = typer.Option(
-        None,
-        "--api-key",
-        help="Anthropic API key (can also be set via ANTHROPIC_API_KEY environment variable)",
-    ),
 ):
     """Generate docstrings for Python files using LLMs.
 
@@ -90,10 +94,6 @@ def docgen(
         typer.echo(f"Error: File not found: {file_path}", err=True)
         raise typer.Exit(1)
 
-    # Set API key if provided
-    if api_key:
-        os.environ["ANTHROPIC_API_KEY"] = api_key
-
     try:
         processed = process_file(str(file_path), model)
         typer.echo(f"Successfully processed {processed} functions")
@@ -168,5 +168,111 @@ def install(app_name: str = typer.Argument(..., help="Name of app to install")):
         raise typer.Exit(1) from e
 
 
+@app.command()
+def init(
+    output_dir: Path | None = typer.Option(
+        None,
+        "--output-dir",
+        "-o",
+        help="Output directory for the project (must exist)",
+    ),
+    app_name: str | None = typer.Option(
+        None,
+        "--app-name",
+        "-a",
+        help="App name (letters, numbers, hyphens, underscores only)",
+    ),
+    integration_type: str | None = typer.Option(
+        None,
+        "--integration-type",
+        "-i",
+        help="Integration type (api_key, oauth, agentr, none)",
+        case_sensitive=False,
+        show_choices=True,
+    ),
+):
+    """Initialize a new MCP project using the cookiecutter template."""
+    from cookiecutter.main import cookiecutter
+
+    NAME_PATTERN = r"^[a-zA-Z0-9_-]+$"
+
+    def validate_pattern(value: str, field_name: str) -> None:
+        if not re.match(NAME_PATTERN, value):
+            typer.secho(
+                f"❌ Invalid {field_name}; only letters, numbers, hyphens, and underscores allowed.",
+                fg=typer.colors.RED,
+            )
+            raise typer.Exit(code=1)
+
+    # App name
+    if not app_name:
+        app_name = typer.prompt(
+            "Enter the app name",
+            default="app_name",
+            prompt_suffix=" (e.g., reddit, youtube): ",
+        ).strip()
+    validate_pattern(app_name, "app name")
+
+    if not output_dir:
+        path_str = typer.prompt(
+            "Enter the output directory for the project",
+            default=str(Path.cwd()),
+            prompt_suffix=": ",
+        ).strip()
+        output_dir = Path(path_str)
+
+    if not output_dir.exists():
+        try:
+            output_dir.mkdir(parents=True, exist_ok=True)
+            typer.secho(
+                f"✅ Created output directory at '{output_dir}'",
+                fg=typer.colors.GREEN,
+            )
+        except Exception as e:
+            typer.secho(
+                f"❌ Failed to create output directory '{output_dir}': {e}",
+                fg=typer.colors.RED,
+            )
+            raise typer.Exit(code=1) from e
+    elif not output_dir.is_dir():
+        typer.secho(
+            f"❌ Output path '{output_dir}' exists but is not a directory.",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(code=1)
+
+    # Integration type
+    if not integration_type:
+        integration_type = typer.prompt(
+            "Choose the integration type",
+            default="agentr",
+            prompt_suffix=" (api_key, oauth, agentr, none): ",
+        ).lower()
+    if integration_type not in ("api_key", "oauth", "agentr", "none"):
+        typer.secho(
+            "❌ Integration type must be one of: api_key, oauth, agentr, none",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(code=1)
+
+    typer.secho("🚀 Generating project using cookiecutter...", fg=typer.colors.BLUE)
+    try:
+        cookiecutter(
+            "https://github.com/AgentrDev/universal-mcp-app-template.git",
+            output_dir=str(output_dir),
+            no_input=True,
+            extra_context={
+                "app_name": app_name,
+                "integration_type": integration_type,
+            },
+        )
+    except Exception as exc:
+        typer.secho(f"❌ Project generation failed: {exc}", fg=typer.colors.RED)
+        raise typer.Exit(code=1) from exc
+
+    project_dir = output_dir / f"universal-mcp-{app_name}"
+    typer.secho(f"✅ Project created at {project_dir}", fg=typer.colors.GREEN)
+
+
 if __name__ == "__main__":
     app()

universal_mcp/integrations/__init__.py

@@ -1,6 +1,6 @@
 from universal_mcp.config import IntegrationConfig
-from universal_mcp.integrations.agentr import AgentRIntegration
 from universal_mcp.integrations.integration import (
+    AgentRIntegration,
     ApiKeyIntegration,
     Integration,
     OAuthIntegration,

universal_mcp/integrations/integration.py

@@ -7,6 +7,7 @@ from loguru import logger
 from universal_mcp.exceptions import NotAuthorizedError
 from universal_mcp.stores import BaseStore
 from universal_mcp.stores.store import KeyNotFoundError
+from universal_mcp.utils.agentr import AgentrClient
 
 
 def sanitize_api_key_name(name: str) -> str:
@@ -296,3 +297,81 @@ class OAuthIntegration(Integration):
         credentials = response.json()
         self.store.set(self.name, credentials)
         return credentials
+
+
+class AgentRIntegration(Integration):
+    """Integration class for AgentR API authentication and authorization.
+
+    This class handles API key authentication and OAuth authorization flow for AgentR services.
+
+    Args:
+        name (str): Name of the integration
+        api_key (str, optional): AgentR API key. If not provided, will look for AGENTR_API_KEY env var
+        **kwargs: Additional keyword arguments passed to parent Integration class
+
+    Raises:
+        ValueError: If no API key is provided or found in environment variables
+    """
+
+    def __init__(self, name: str, api_key: str = None, **kwargs):
+        super().__init__(name, **kwargs)
+        self.client = AgentrClient(api_key=api_key)
+        self._credentials = None
+
+    def set_credentials(self, credentials: dict | None = None):
+        """Set credentials for the integration.
+
+        This method is not implemented for AgentR integration. Instead it redirects to the authorize flow.
+
+        Args:
+            credentials (dict | None, optional): Credentials dict (not used). Defaults to None.
+
+        Returns:
+            str: Authorization URL from authorize() method
+        """
+        return self.authorize()
+
+    @property
+    def credentials(self):
+        """Get credentials for the integration from the AgentR API.
+
+        Makes API request to retrieve stored credentials for this integration.
+
+        Returns:
+            dict: Credentials data from API response
+
+        Raises:
+            NotAuthorizedError: If credentials are not found (404 response)
+            HTTPError: For other API errors
+        """
+        if self._credentials is not None:
+            return self._credentials
+        self._credentials = self.client.get_credentials(self.name)
+        return self._credentials
+
+    def get_credentials(self):
+        """Get credentials for the integration from the AgentR API.
+
+        Makes API request to retrieve stored credentials for this integration.
+
+        Returns:
+            dict: Credentials data from API response
+
+        Raises:
+            NotAuthorizedError: If credentials are not found (404 response)
+            HTTPError: For other API errors
+        """
+        return self.credentials
+
+    def authorize(self):
+        """Get authorization URL for the integration.
+
+        Makes API request to get OAuth authorization URL.
+
+        Returns:
+            str: Message containing authorization URL
+
+        Raises:
+            HTTPError: If API request fails
+        """
+        return self.client.get_authorization_url(self.name)

universal_mcp/servers/README.md

@@ -0,0 +1,79 @@
+# Servers
+
+This package provides server implementations for hosting and managing MCP (Model Control Protocol) applications.
+
+## Overview
+
+The server implementations provide different ways to host and expose MCP applications and their tools. The base `BaseServer` class provides common functionality that all server implementations inherit.
+
+## Supported Server Types
+
+### Local Server
+The `LocalServer` class provides a local development server implementation that:
+- Loads applications from local configuration
+- Manages a local store for data persistence
+- Supports integration with external services
+- Exposes application tools through the MCP protocol
+
+### AgentR Server
+The `AgentRServer` class provides a server implementation that:
+- Connects to the AgentR API
+- Dynamically fetches and loads available applications
+- Manages AgentR-specific integrations
+- Requires an API key for authentication
+
+### Single MCP Server
+The `SingleMCPServer` class provides a minimal server implementation that:
+- Hosts a single application instance
+- Ideal for development and testing
+- Does not manage integrations or stores internally
+- Exposes only the tools from the provided application
+
+## Core Features
+
+All server implementations provide:
+
+- Tool management and registration
+- Application loading and configuration
+- Error handling and logging
+- MCP protocol compliance
+- Integration support
+
+## Usage
+
+Each server implementation can be initialized with a `ServerConfig` object that specifies:
+- Server name and description
+- Port configuration
+- Application configurations
+- Store configuration (where applicable)
+
+Example:
+```python
+from universal_mcp.servers import LocalServer
+from universal_mcp.config import ServerConfig
+
+config = ServerConfig(
+    name="My Local Server",
+    description="Development server for testing applications",
+    port=8000,
+    # ... additional configuration
+)
+
+server = LocalServer(config)
+```
+
+## Tool Management
+
+Servers provide methods for:
+- Adding individual tools
+- Listing available tools
+- Calling tools with proper error handling
+- Formatting tool results
+
+## Error Handling
+
+All servers implement comprehensive error handling for:
+- Tool execution failures
+- Application loading errors
+- Integration setup issues
+- API communication problems

universal_mcp/servers/server.py

@@ -1,8 +1,6 @@
-import os
 from abc import ABC, abstractmethod
 from collections.abc import Callable
 from typing import Any
-from urllib.parse import urlparse
 
 import httpx
 from loguru import logger
@@ -13,7 +11,8 @@ from universal_mcp.applications import BaseApplication, app_from_slug
 from universal_mcp.config import AppConfig, ServerConfig, StoreConfig
 from universal_mcp.integrations import AgentRIntegration, integration_from_config
 from universal_mcp.stores import BaseStore, store_from_config
-from universal_mcp.tools.tools import ToolManager
+from universal_mcp.tools import ToolManager
+from universal_mcp.utils.agentr import AgentrClient
 
 
 class BaseServer(FastMCP, ABC):
@@ -28,7 +27,7 @@ class BaseServer(FastMCP, ABC):
     """
 
     def __init__(self, config: ServerConfig, **kwargs):
-        super().__init__(config.name, config.description, **kwargs)
+        super().__init__(config.name, config.description, port=config.port, **kwargs)
         logger.info(
             f"Initializing server: {config.name} ({config.type}) with store: {config.store}"
         )
@@ -169,16 +168,9 @@ class AgentRServer(BaseServer):
     """
 
     def __init__(self, config: ServerConfig, api_key: str | None = None, **kwargs):
-        self.api_key = api_key or os.getenv("AGENTR_API_KEY")
-        self.base_url = os.getenv("AGENTR_BASE_URL", "https://api.agentr.dev")
-
-        if not self.api_key:
-            raise ValueError("API key required - get one at https://agentr.dev")
-        parsed = urlparse(self.base_url)
-        if not all([parsed.scheme, parsed.netloc]):
-            raise ValueError(f"Invalid base URL format: {self.base_url}")
+        self.client = AgentrClient(api_key=api_key)
         super().__init__(config, **kwargs)
-        self.integration = AgentRIntegration(name="agentr", api_key=self.api_key)
+        self.integration = AgentRIntegration(name="agentr", api_key=self.client.api_key)
         self._load_apps()
 
     def _fetch_apps(self) -> list[AppConfig]:
@@ -191,13 +183,8 @@ class AgentRServer(BaseServer):
             httpx.HTTPError: If API request fails
         """
         try:
-            response = httpx.get(
-                f"{self.base_url}/api/apps/",
-                headers={"X-API-KEY": self.api_key},
-                timeout=10,
-            )
-            response.raise_for_status()
-            return [AppConfig.model_validate(app) for app in response.json()]
+            apps = self.client.fetch_apps()
+            return [AppConfig.model_validate(app) for app in apps]
         except httpx.HTTPError as e:
             logger.error(f"Failed to fetch apps from AgentR: {e}", exc_info=True)
             raise
@@ -214,7 +201,7 @@ class AgentRServer(BaseServer):
         try:
             integration = (
                 AgentRIntegration(
-                    name=app_config.integration.name, api_key=self.api_key
+                    name=app_config.integration.name, api_key=self.client.api_key
                 )
                 if app_config.integration
                 else None
@@ -259,17 +246,16 @@ class SingleMCPServer(BaseServer):
         config: ServerConfig | None = None,
         **kwargs,
     ):
-        server_config = ServerConfig(
-            type="local",
-            name=f"{app_instance.name.title()} MCP Server for Local Development"
-            if app_instance
-            else "Unnamed MCP Server",
-            description=f"Minimal MCP server for the local {app_instance.name} application."
-            if app_instance
-            else "Minimal MCP server with no application loaded.",
-        )
         if not config:
-            config = server_config
+            config = ServerConfig(
+                type="local",
+                name=f"{app_instance.name.title()} MCP Server for Local Development"
+                if app_instance
+                else "Unnamed MCP Server",
+                description=f"Minimal MCP server for the local {app_instance.name} application."
+                if app_instance
+                else "Minimal MCP server with no application loaded.",
+            )
         super().__init__(config, **kwargs)
 
         self.app_instance = app_instance

universal_mcp/stores/README.md

@@ -0,0 +1,74 @@
+# Universal MCP Stores
+
+The stores module provides a flexible and secure way to manage credentials and sensitive data across different storage backends. It implements a common interface for storing, retrieving, and deleting sensitive information.
+
+## Features
+
+- Abstract base class defining a consistent interface for credential stores
+- Multiple storage backend implementations:
+  - In-memory store (temporary storage)
+  - Environment variable store
+  - System keyring store (secure credential storage)
+- Exception handling for common error cases
+- Type hints and comprehensive documentation
+
+## Available Store Implementations
+
+### MemoryStore
+A simple in-memory store that persists data only for the duration of program execution. Useful for testing or temporary storage.
+
+```python
+from universal_mcp.stores import MemoryStore
+
+store = MemoryStore()
+store.set("api_key", "secret123")
+value = store.get("api_key")  # Returns "secret123"
+```
+
+### EnvironmentStore
+Uses environment variables to store and retrieve credentials. Useful for containerized environments or CI/CD pipelines.
+
+```python
+from universal_mcp.stores import EnvironmentStore
+
+store = EnvironmentStore()
+store.set("API_KEY", "secret123")
+value = store.get("API_KEY")  # Returns "secret123"
+```
+
+### KeyringStore
+Leverages the system's secure credential storage facility. Provides the most secure option for storing sensitive data.
+
+```python
+from universal_mcp.stores import KeyringStore
+
+store = KeyringStore(app_name="my_app")
+store.set("api_key", "secret123")
+value = store.get("api_key")  # Returns "secret123"
+```
+
+## Error Handling
+
+The module provides specific exception types for handling errors:
+
+- `StoreError`: Base exception for all store-related errors
+- `KeyNotFoundError`: Raised when a requested key is not found in the store
+
+## Best Practices
+
+1. Use `KeyringStore` for production environments where security is a priority
+2. Use `EnvironmentStore` for containerized or cloud environments
+3. Use `MemoryStore` for testing or temporary storage only
+4. Always handle `StoreError` and `KeyNotFoundError` exceptions appropriately
+
+## Dependencies
+
+- `keyring`: Required for the KeyringStore implementation
+- `loguru`: Used for logging operations in the KeyringStore
+
+## Contributing
+
+New store implementations should inherit from `BaseStore` and implement all required abstract methods:
+- `get(key: str) -> Any`
+- `set(key: str, value: str) -> None`
+- `delete(key: str) -> None`