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

universal_mcp/templates/README.md.j2

@@ -0,0 +1,93 @@
+# {{ name }} MCP Server
+
+An MCP Server for the {{ name }} API.
+
+## 📋 Prerequisites
+
+Before you begin, ensure you have met the following requirements:
+* Python 3.11+ (Recommended)
+* [uv](https://github.com/astral-sh/uv) installed globally (`pip install uv`)
+
+## 🛠️ Setup Instructions
+
+Follow these steps to get the development environment up and running:
+
+### 1. Sync Project Dependencies
+Navigate to the project root directory (where `pyproject.toml` is located).
+```bash
+uv sync
+```
+This command uses `uv` to install all dependencies listed in `pyproject.toml` into a virtual environment (`.venv`) located in the project root.
+
+### 2. Activate the Virtual Environment
+Activating the virtual environment ensures that you are using the project's specific dependencies and Python interpreter.
+- On **Linux/macOS**:
+```bash
+source .venv/bin/activate
+```
+- On **Windows**:
+```bash
+.venv\\Scripts\\activate
+```
+
+### 3. Start the MCP Inspector
+Use the MCP CLI to start the application in development mode.
+```bash
+mcp dev src/{{ name.lower() }}/mcp.py
+```
+The MCP inspector should now be running. Check the console output for the exact address and port.
+
+## 🔌 Supported Integrations
+
+- AgentR
+- API Key (Coming Soon)
+- OAuth (Coming Soon)
+
+## 🛠️ Tool List
+
+This is automatically generated from OpenAPI schema for the {{ name }} API.
+
+{% if tools %}
+| Tool | Description |
+|------|-------------|
+{%- for tool_name, tool_desc in tools %}
+| `{{ tool_name }}` | {{ tool_desc }} |
+{%- endfor %}
+{% else %}
+No tools with documentation were found in this API client.
+{% endif %}
+
+## 📁 Project Structure
+
+The generated project has a standard layout:
+```
+.
+├── src/                  # Source code directory
+│   └── {{ name.lower() }}/
+│       ├── __init__.py
+│       └── mcp.py        # Server is launched here
+│       └── app.py        # Application tools are defined here
+├── tests/                # Directory for project tests
+├── .env                  # Environment variables (for local development)
+├── pyproject.toml        # Project dependencies managed by uv
+├── README.md             # This file
+```
+
+## 📝 License
+
+This project is licensed under the MIT License.
+
+---
+
+_This project was generated using **MCP CLI** — Happy coding! 🚀_
+
+## 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 

universal_mcp/templates/api_client.py.j2

@@ -0,0 +1,27 @@
+from typing import Any, Annotated
+from universal_mcp.applications import APIApplication
+from universal_mcp.integrations import Integration
+
+class {{ class_name }}(APIApplication):
+    def __init__(self, integration: Integration = None, **kwargs) -> None:
+        super().__init__(name='{{ class_name.lower() }}', integration=integration, **kwargs)
+        self.base_url = "{{ base_url }}"
+
+{% for method in methods %}
+    def {{ method.name }}(self, {{ method.args_str }}) -> {{ method.return_type }}:
+        """
+        {{ method.description }}
+        {% if method.tags %}
+        Tags: {{ method.tags|join(', ') }}
+        {% endif %}
+        """
+        
+        {{ method.implementation|indent(8) }}
+{% endfor %}
+
+    def list_tools(self):
+        return [
+            {% for method in methods %}
+            self.{{ method.name }}{% if not loop.last %},{% endif %}
+            {%- endfor %}
+        ] 

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

@@ -260,9 +260,7 @@ class ToolManager:
         try:
             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}"
-            )
+            logger.error(f"Error calling list_tools for app '{app.name}'. Error: {e}")
             return
         except Exception as e:
             logger.error(f"Failed to get tool list from app '{app.name}': {e}")

universal_mcp/utils/agentr.py

@@ -0,0 +1,95 @@
+import os
+
+import httpx
+from loguru import logger
+
+from universal_mcp.config import AppConfig
+from universal_mcp.exceptions import NotAuthorizedError
+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,39 +1,12 @@
-import ast
 import importlib.util
 import inspect
 import os
-import traceback
+import shutil
 from pathlib import Path
 
-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
+from loguru import logger
 
-- 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
-"""
+from universal_mcp.utils.openapi import generate_api_client, load_schema
 
 
 def echo(message: str, err: bool = False) -> None:
@@ -54,69 +27,6 @@ def validate_and_load_schema(schema_path: Path) -> dict:
         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):
@@ -125,145 +35,106 @@ def get_class_info(module: any) -> tuple[str | None, any]:
     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()
+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
 
-            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]]
-) -> Path:
-    """Generate README.md with API documentation."""
-    app = folder_name.replace("_", " ").title()
-
-    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"
-        )
-
-    readme_content = README_TEMPLATE.format(
-        name=app,
-        tools=tools_content,
-        usage="",
-    )
-    readme_file = app_dir / "README.md"
-    with open(readme_file, "w") as f:
-        f.write(readme_content)
-
-    echo(f"Documentation generated at: {readme_file}")
-    return readme_file
+    # 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]:
+    class_name: str | None = None,
+) -> tuple[Path, Path]:
     """
-    Generate API client from OpenAPI schema with optional docstring generation.
+    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.
+    """
+    # 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
+    logger.info("Starting API generation for schema: %s", schema_path)
 
-    Returns:
-        dict: A dictionary with information about the generated files
-    """
+    # 1. Parse and validate schema
     try:
         schema = validate_and_load_schema(schema_path)
-        code = generate_api_client(schema)
-
-        if not output_path:
-            return {"code": code}
-
-        folder_name = output_path.stem
-        temp_output_path = output_path
-
-        write_and_verify_code(temp_output_path, code)
-
-        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")
-
-        app_dir, app_file = setup_app_directory(folder_name, temp_output_path)
+        logger.info("Schema loaded and validated successfully.")
+    except Exception as e:
+        logger.error("Failed to load or validate schema: %s", e)
+        raise
 
-        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)
+    # 2. Generate client code
+    try:
+        code = generate_api_client(schema, class_name)
+        logger.info("API client code generated.")
+    except Exception as e:
+        logger.error("Code generation failed: %s", e)
+        raise
 
-            class_name, class_obj = get_class_info(module)
-            if not class_name:
-                class_name = folder_name.capitalize() + "App"
+    # 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)
 
-            tools = collect_tools(class_obj, folder_name)
-            readme_file = generate_readme(app_dir, folder_name, tools)
+    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."}
 
-        except Exception as e:
-            echo(f"Error generating documentation: {e}", err=True)
-            readme_file = None
+    # 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)
 
-        return {
-            "app_file": str(app_file),
-            "readme_file": str(readme_file) if readme_file else None,
-        }
+    # 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)
 
-    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

universal_mcp/utils/docgen.py

@@ -176,7 +176,7 @@ def extract_json_from_text(text):
 
 
 def generate_docstring(
-    function_code: str, model: str = "perplexity/sonar-pro"
+    function_code: str, model: str = "perplexity/sonar"
 ) -> DocstringOutput:
     """
     Generate a docstring for a Python function using litellm with structured output.
@@ -509,7 +509,7 @@ def insert_docstring_into_function(function_code: str, docstring: str) -> str:
         return function_code
 
 
-def process_file(file_path: str, model: str = "perplexity/sonar-pro") -> int:
+def process_file(file_path: str, model: str = "perplexity/sonar") -> int:
     """
     Process a Python file and add docstrings to all functions in it.