universal-mcp 0.1.12__py3-none-any.whl → 0.1.13rc2__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

@@ -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]
+