universal-mcp 0.1.12__py3-none-any.whl → 0.1.13rc1__py3-none-any.whl

universal_mcp/tools/README.md

@@ -0,0 +1,86 @@
+# Universal MCP Tools
+
+This directory contains the core tooling infrastructure for Universal MCP, providing a flexible and extensible framework for defining, managing, and converting tools across different formats.
+
+## Components
+
+### `tools.py`
+The main module containing the core tool management functionality:
+
+- `Tool` class: Represents a tool with metadata, validation, and execution capabilities
+- `ToolManager` class: Manages tool registration, lookup, and execution
+- Conversion utilities for different tool formats (OpenAI, LangChain, MCP)
+
+### `adapters.py`
+Contains adapters for converting tools between different formats:
+- `convert_tool_to_mcp_tool`: Converts a tool to MCP format
+- `convert_tool_to_langchain_tool`: Converts a tool to LangChain format
+
+### `func_metadata.py`
+Provides function metadata and argument validation:
+- `FuncMetadata` class: Handles function signature analysis and argument validation
+- `ArgModelBase` class: Base model for function arguments
+- Utilities for parsing and validating function signatures
+
+## Usage
+
+### Creating a Tool
+
+```python
+from universal_mcp.tools import Tool
+
+def my_tool(param1: str, param2: int) -> str:
+    """A simple tool that does something.
+    
+    Args:
+        param1: Description of param1
+        param2: Description of param2
+        
+    Returns:
+        Description of return value
+    """
+    return f"Result: {param1} {param2}"
+
+tool = Tool.from_function(my_tool)
+```
+
+### Managing Tools
+
+```python
+from universal_mcp.tools import ToolManager
+
+manager = ToolManager()
+manager.add_tool(my_tool)
+
+# Get a tool by name
+tool = manager.get_tool("my_tool")
+
+# List all tools in a specific format
+tools = manager.list_tools(format="openai")  # or "langchain" or "mcp"
+```
+
+### Converting Tools
+
+```python
+from universal_mcp.tools import convert_tool_to_langchain_tool
+
+langchain_tool = convert_tool_to_langchain_tool(tool)
+```
+
+## Features
+
+- Automatic docstring parsing for tool metadata
+- Type validation using Pydantic
+- Support for both sync and async tools
+- JSON schema generation for tool parameters
+- Error handling and analytics tracking
+- Tag-based tool organization
+- Multiple format support (OpenAI, LangChain, MCP)
+
+## Best Practices
+
+1. Always provide clear docstrings for your tools
+2. Use type hints for better validation
+3. Handle errors appropriately in your tool implementations
+4. Use tags to organize related tools
+5. Consider async implementations for I/O-bound operations

universal_mcp/tools/tools.py

@@ -261,7 +261,7 @@ class ToolManager:
             available_tool_functions = app.list_tools()
         except TypeError as e:
             logger.error(
-                f"Error calling list_tools for app '{app.name}'. Does its list_tools method accept arguments? It shouldn't. Error: {e}"
+                f"Error calling list_tools for app '{app.name}'. Error: {e}"
             )
             return
         except Exception as e:

universal_mcp/utils/agentr.py

@@ -0,0 +1,90 @@
+from loguru import logger
+import os
+import httpx
+from universal_mcp.config import AppConfig
+from universal_mcp.utils.singleton import Singleton
+
+class AgentrClient(metaclass=Singleton):
+    """Helper class for AgentR API operations.
+
+    This class provides utility methods for interacting with the AgentR API,
+    including authentication, authorization, and credential management.
+
+    Args:
+        api_key (str, optional): AgentR API key. If not provided, will look for AGENTR_API_KEY env var
+        base_url (str, optional): Base URL for AgentR API. Defaults to https://api.agentr.dev
+    """
+
+    def __init__(self, api_key: str = None, base_url: str = None):
+        self.api_key = api_key or os.getenv("AGENTR_API_KEY")
+        if not self.api_key:
+            logger.error(
+                "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("/")
+
+    def get_credentials(self, integration_name: str) -> dict:
+        """Get credentials for an integration from the AgentR API.
+
+        Args:
+            integration_name (str): Name of the integration to get credentials for
+
+        Returns:
+            dict: Credentials data from API response
+
+        Raises:
+            NotAuthorizedError: If credentials are not found (404 response)
+            HTTPError: For other API errors
+        """
+        response = httpx.get(
+            f"{self.base_url}/api/{integration_name}/credentials/",
+            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..."
+            )
+            action = self.get_authorization_url(integration_name)
+            raise NotAuthorizedError(action)
+        response.raise_for_status()
+        return response.json()
+
+    def get_authorization_url(self, integration_name: str) -> str:
+        """Get authorization URL for an integration.
+
+        Args:
+            integration_name (str): Name of the integration to get authorization URL for
+
+        Returns:
+            str: Message containing authorization URL
+
+        Raises:
+            HTTPError: If API request fails
+        """
+        response = httpx.get(
+            f"{self.base_url}/api/{integration_name}/authorize/",
+            headers={"X-API-KEY": self.api_key},
+        )
+        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."
+
+    def fetch_apps(self) -> list[dict]:
+        """Fetch available apps from AgentR API.
+
+        Returns:
+            List of application configurations
+
+        Raises:
+            httpx.HTTPError: If API request fails
+        """
+        response = httpx.get(
+            f"{self.base_url}/api/apps/",
+            headers={"X-API-KEY": self.api_key},
+            timeout=10,
+        )
+        response.raise_for_status()
+        data = response.json()
+        return [AppConfig.model_validate(app) for app in data]
+

universal_mcp/utils/api_generator.py

@@ -1,40 +1,13 @@
-import ast
-import importlib.util
 import inspect
 import os
-import traceback
 from pathlib import Path
+from loguru import logger
+import shutil
+import importlib.util
+from jinja2 import Environment, FileSystemLoader, TemplateError, select_autoescape
 
-from universal_mcp.utils.docgen import process_file
 from universal_mcp.utils.openapi import generate_api_client, load_schema
 
-README_TEMPLATE = """
-# {name} MCP Server
-
-An MCP Server for the {name} API.
-
-## Supported Integrations
-
-- AgentR
-- API Key (Coming Soon)
-- OAuth (Coming Soon)
-
-## Tools
-
-{tools}
-
-## Usage
-
-- Login to AgentR
-- Follow the quickstart guide to setup MCP Server for your client
-- Visit Apps Store and enable the {name} app
-- Restart the MCP Server
-
-### Local Development
-
-- Follow the README to test with the local MCP Server
-"""
-
 
 def echo(message: str, err: bool = False) -> None:
     """Echo a message to the console, with optional error flag."""
@@ -53,70 +26,6 @@ def validate_and_load_schema(schema_path: Path) -> dict:
         echo(f"Error loading schema: {e}", err=True)
         raise
 
-
-def write_and_verify_code(output_path: Path, code: str) -> None:
-    """Write generated code to file and verify its contents."""
-    with open(output_path, "w") as f:
-        f.write(code)
-    echo(f"Generated API client at: {output_path}")
-
-    try:
-        with open(output_path) as f:
-            file_content = f.read()
-            echo(f"Successfully wrote {len(file_content)} bytes to {output_path}")
-            ast.parse(file_content)
-            echo("Python syntax check passed")
-    except SyntaxError as e:
-        echo(f"Warning: Generated file has syntax error: {e}", err=True)
-    except Exception as e:
-        echo(f"Error verifying output file: {e}", err=True)
-
-
-async def generate_docstrings(script_path: str) -> dict[str, int]:
-    """Generate docstrings for the given script file."""
-    echo(f"Adding docstrings to {script_path}...")
-
-    if not os.path.exists(script_path):
-        echo(f"Warning: File {script_path} does not exist", err=True)
-        return {"functions_processed": 0}
-
-    try:
-        with open(script_path) as f:
-            content = f.read()
-            echo(f"Successfully read {len(content)} bytes from {script_path}")
-    except Exception as e:
-        echo(f"Error reading file for docstring generation: {e}", err=True)
-        return {"functions_processed": 0}
-
-    try:
-        processed = process_file(script_path)
-        return {"functions_processed": processed}
-    except Exception as e:
-        echo(f"Error running docstring generation: {e}", err=True)
-        traceback.print_exc()
-        return {"functions_processed": 0}
-
-
-def setup_app_directory(folder_name: str, source_file: Path) -> tuple[Path, Path]:
-    """Set up application directory structure and copy generated code."""
-    applications_dir = Path(__file__).parent.parent / "applications"
-    app_dir = applications_dir / folder_name
-    app_dir.mkdir(exist_ok=True)
-
-    init_file = app_dir / "__init__.py"
-    if not init_file.exists():
-        with open(init_file, "w") as f:
-            f.write("")
-
-    app_file = app_dir / "app.py"
-    with open(source_file) as src, open(app_file, "w") as dest:
-        app_content = src.read()
-        dest.write(app_content)
-
-    echo(f"API client installed at: {app_file}")
-    return app_dir, app_file
-
-
 def get_class_info(module: any) -> tuple[str | None, any]:
     """Find the main class in the generated module."""
     for name, obj in inspect.getmembers(module):
@@ -124,146 +33,195 @@ def get_class_info(module: any) -> tuple[str | None, any]:
             return name, obj
     return None, None
 
-
-def collect_tools(class_obj: any, folder_name: str) -> list[tuple[str, str]]:
-    """Collect tool information from the class."""
-    tools = []
-
-    # Try to get tools from list_tools method
-    if class_obj and hasattr(class_obj, "list_tools"):
-        try:
-            instance = class_obj()
-            tool_list = instance.list_tools()
-
-            for tool in tool_list:
-                func_name = tool.__name__
-                if func_name.startswith("_") or func_name in ("__init__", "list_tools"):
-                    continue
-
-                doc = tool.__doc__ or f"Function for {func_name.replace('_', ' ')}"
-                summary = doc.split("\n\n")[0].strip()
-                tools.append((func_name, summary))
-        except Exception as e:
-            echo(f"Note: Couldn't instantiate class to get tool list: {e}")
-
-    # Fall back to inspecting class methods directly
-    if not tools and class_obj:
-        for name, method in inspect.getmembers(class_obj, inspect.isfunction):
-            if name.startswith("_") or name in ("__init__", "list_tools"):
-                continue
-
-            doc = method.__doc__ or f"Function for {name.replace('_', ' ')}"
-            summary = doc.split("\n\n")[0].strip()
-            tools.append((name, summary))
-
-    return tools
-
-
 def generate_readme(
-    app_dir: Path, folder_name: str, tools: list[tuple[str, str]]
+    app_dir: Path, folder_name: str, tools: list
 ) -> Path:
-    """Generate README.md with API documentation."""
+    """Generate README.md with API documentation.
+    
+    Args:
+        app_dir: Directory where the README will be generated
+        folder_name: Name of the application folder
+        tools: List of Function objects from the OpenAPI schema
+        
+    Returns:
+        Path to the generated README file
+        
+    Raises:
+        FileNotFoundError: If the template directory doesn't exist
+        TemplateError: If there's an error rendering the template
+        IOError: If there's an error writing the README file
+    """
     app = folder_name.replace("_", " ").title()
+    logger.info(f"Generating README for {app} in {app_dir}")
 
-    tools_content = f"This is automatically generated from OpenAPI schema for the {folder_name.replace('_', ' ').title()} API.\n\n"
-    tools_content += "## Supported Integrations\n\n"
-    tools_content += (
-        "This tool can be integrated with any service that supports HTTP requests.\n\n"
-    )
-    tools_content += "## Tool List\n\n"
-
-    if tools:
-        tools_content += "| Tool | Description |\n|------|-------------|\n"
-        for tool_name, tool_desc in tools:
-            tools_content += f"| {tool_name} | {tool_desc} |\n"
-        tools_content += "\n"
-    else:
-        tools_content += (
-            "No tools with documentation were found in this API client.\n\n"
+    # Format tools into (name, description) tuples
+    formatted_tools = []
+    for tool in tools:
+        name = tool.__name__
+        description = tool.__doc__.strip().split("\n")[0]
+        formatted_tools.append((name, description))
+
+    # Set up Jinja2 environment
+    template_dir = Path(__file__).parent.parent / "templates"
+    if not template_dir.exists():
+        logger.error(f"Template directory not found: {template_dir}")
+        raise FileNotFoundError(f"Template directory not found: {template_dir}")
+
+    try:
+        env = Environment(
+            loader=FileSystemLoader(template_dir),
+            autoescape=select_autoescape()
         )
+        template = env.get_template("README.md.j2")
+    except Exception as e:
+        logger.error(f"Error loading template: {e}")
+        raise TemplateError(f"Error loading template: {e}")
+
+    # Render the template
+    try:
+        readme_content = template.render(
+            name=app,
+            tools=formatted_tools
+        )
+    except Exception as e:
+        logger.error(f"Error rendering template: {e}")
+        raise TemplateError(f"Error rendering template: {e}")
 
-    readme_content = README_TEMPLATE.format(
-        name=app,
-        tools=tools_content,
-        usage="",
-    )
+    # Write the README file
     readme_file = app_dir / "README.md"
-    with open(readme_file, "w") as f:
-        f.write(readme_content)
+    try:
+        with open(readme_file, "w") as f:
+            f.write(readme_content)
+        logger.info(f"Documentation generated at: {readme_file}")
+    except Exception as e:
+        logger.error(f"Error writing README file: {e}")
+        raise IOError(f"Error writing README file: {e}")
 
-    echo(f"Documentation generated at: {readme_file}")
     return readme_file
 
+def test_correct_output(gen_file: Path):
+    # Check file is non-empty
+    if gen_file.stat().st_size == 0:
+        msg = f"Generated file {gen_file} is empty."
+        logger.error(msg)
+        return False
+
+    # Basic import test on generated code
+    try:
+        spec = importlib.util.spec_from_file_location("temp_module", gen_file)
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)  # type: ignore
+        logger.info("Intermediate code import test passed.")
+        return True
+    except Exception as e:
+        logger.error(f"Import test failed for generated code: {e}")
+        return False
+    return True
 
-async def generate_api_from_schema(
+
+def generate_api_from_schema(
     schema_path: Path,
     output_path: Path | None = None,
     add_docstrings: bool = True,
-) -> dict[str, str | None]:
+) -> tuple[Path, Path]:
+    """
+    Generate API client from OpenAPI schema and write to app.py with a README.
+
+    Steps:
+    1. Parse and validate the OpenAPI schema.
+    2. Generate client code.
+    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.
     """
-    Generate API client from OpenAPI schema with optional docstring generation.
+    # Local imports for logging and file operations
 
-    Args:
-        schema_path: Path to the OpenAPI schema file
-        output_path: Output file path - should match the API name (e.g., 'twitter.py' for Twitter API)
-        add_docstrings: Whether to add docstrings to the generated code
 
-    Returns:
-        dict: A dictionary with information about the generated files
-    """
+    logger.info("Starting API generation for schema: %s", schema_path)
+
+    # 1. Parse and validate schema
     try:
         schema = validate_and_load_schema(schema_path)
+        logger.info("Schema loaded and validated successfully.")
+    except Exception as e:
+        logger.error("Failed to load or validate schema: %s", e)
+        raise
+
+    # 2. Generate client code
+    try:
         code = generate_api_client(schema)
+        logger.info("API client code generated.")
+    except Exception as e:
+        logger.error("Code generation failed: %s", e)
+        raise
 
-        if not output_path:
-            return {"code": code}
+    # If no output_path provided, return raw code
+    if not output_path:
+        logger.debug("No output_path provided, returning code as string.")
+        return {"code": code}
+
+    # 3. Ensure output directory exists
+    target_dir = output_path
+    if not target_dir.exists():
+        logger.info("Creating output directory: %s", target_dir)
+        target_dir.mkdir(parents=True, exist_ok=True)
+
+    # 4. Write to intermediate file and perform basic checks
+    gen_file = target_dir / "app_generated.py"
+    logger.info("Writing generated code to intermediate file: %s", gen_file)
+    with open(gen_file, "w") as f:
+        f.write(code)
 
-        folder_name = output_path.stem
-        temp_output_path = output_path
+    if not test_correct_output(gen_file):
+        logger.error("Generated code validation failed for '%s'. Aborting generation.", gen_file)
+        logger.info("Next steps:")
+        logger.info(" 1) Review your OpenAPI schema for potential mismatches.")
+        logger.info(" 2) Inspect '%s' for syntax or logic errors in the generated code.", gen_file)
+        logger.info(" 3) Correct the issues and re-run the command.")
+        return {"error": "Validation failed. See logs above for detailed instructions."}
+
+    # 5. Copy to final app.py (overwrite if exists)
+    app_file = target_dir / "app.py"
+    if app_file.exists():
+        logger.warning("Overwriting existing file: %s", app_file)
+    else:
+        logger.info("Creating new file: %s", app_file)
+    shutil.copy(gen_file, app_file)
+    logger.info("App file written to: %s", app_file)
 
-        write_and_verify_code(temp_output_path, code)
+    # 6. Collect tools and generate README
+    import importlib.util
+    import sys
 
-        if add_docstrings:
-            result = await generate_docstrings(str(temp_output_path))
-            if result:
-                if "functions_processed" in result:
-                    echo(f"Processed {result['functions_processed']} functions")
-            else:
-                echo("Docstring generation failed", err=True)
-        else:
-            echo("Skipping docstring generation as requested")
+    # Load the generated module as "temp_module"
+    spec = importlib.util.spec_from_file_location("temp_module", str(app_file))
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["temp_module"] = module
+    spec.loader.exec_module(module)
 
-        app_dir, app_file = setup_app_directory(folder_name, temp_output_path)
+    # Retrieve the generated API class
+    class_name, cls = get_class_info(module)
 
+    # Instantiate client and collect its tools
+    tools = []
+    if cls:
         try:
-            echo("Generating README.md from function information...")
-            spec = importlib.util.spec_from_file_location("temp_module", app_file)
-            module = importlib.util.module_from_spec(spec)
-            spec.loader.exec_module(module)
+            client = cls()
+            tools = client.list_tools()
+        except Exception as e:
+            logger.warning("Failed to instantiate '%s' or list tools: %s", class_name, e)
+    else:
+        logger.warning("No generated class found in module 'temp_module'")
+    readme_file = generate_readme(target_dir, output_path.stem, tools)
+    logger.info("README generated at: %s", readme_file)
 
-            class_name, class_obj = get_class_info(module)
-            if not class_name:
-                class_name = folder_name.capitalize() + "App"
 
-            tools = collect_tools(class_obj, folder_name)
-            readme_file = generate_readme(app_dir, folder_name, tools)
+    # Cleanup intermediate file
+    try:
+        os.remove(gen_file)
+        logger.debug("Cleaned up intermediate file: %s", gen_file)
+    except Exception as e:
+        logger.warning("Could not remove intermediate file %s: %s", gen_file, e)
 
-        except Exception as e:
-            echo(f"Error generating documentation: {e}", err=True)
-            readme_file = None
-
-        return {
-            "app_file": str(app_file),
-            "readme_file": str(readme_file) if readme_file else None,
-        }
-
-    finally:
-        if output_path and output_path.exists():
-            try:
-                output_path.unlink()
-                echo(f"Cleaned up temporary file: {output_path}")
-            except Exception as e:
-                echo(
-                    f"Warning: Could not remove temporary file {output_path}: {e}",
-                    err=True,
-                )
+    return app_file, readme_file