universal-mcp 0.1.24rc2__py3-none-any.whl → 0.1.24rc4__py3-none-any.whl

universal_mcp/agentr/README.md

@@ -0,0 +1,201 @@
+# AgentR Python SDK
+
+The official Python SDK for the AgentR platform, a component of the Universal MCP framework.
+Currently in beta, breaking changes are expected.
+
+The AgentR Python SDK provides convenient access to the AgentR REST API from any Python 3.10+
+application, allowing for dynamic loading and management of tools and integrations.
+
+## Installation
+```bash
+pip install universal-mcp
+```
+
+## Usage
+The AgentR platform is designed to seamlessly integrate a wide array of tools into your agentic applications. The primary entry point for this is the `Agentr` class, which provides a high-level interface for loading and listing tools.
+
+### High-Level Client (`Agentr`)
+This is the recommended way to get started. It abstracts away the details of the registry and tool management.
+
+```python
+import os
+from universal_mcp.agentr import Agentr
+from universal_mcp.tools import ToolFormat
+
+# Initialize the main client
+# It reads from environment variables by default (AGENTR_API_KEY, AGENTR_BASE_URL)
+agentr = Agentr(
+    api_key=os.environ.get("AGENTR_API_KEY")
+)
+
+# Load specific tools from the AgentR server into the tool manager
+agentr.load_tools(["reddit_search_subreddits", "google_drive_list_files"])
+
+# List the tools that are now loaded and ready to be used
+# You can specify a format compatible with your LLM (e.g., OPENAI)
+tools = agentr.list_tools(format=ToolFormat.OPENAI)
+print(tools)
+```
+
+### Low-Level API
+
+For more granular control over the AgentR platform, you can use the lower-level components directly.
+
+### AgentrClient
+The `AgentrClient` provides direct access to the AgentR REST API endpoints.
+
+#### Methods
+```python
+import os
+from universal_mcp.agentr import AgentrClient
+from universal_mcp.exceptions import NotAuthorizedError
+
+# Initialize the low-level client
+client = AgentrClient(
+    api_key=os.environ.get("AGENTR_API_KEY")
+)
+
+# Fetch all available applications from the AgentR server
+apps = client.fetch_apps()
+print(apps)
+
+# Get credentials for a specific integration
+# This will raise a NotAuthorizedError if the user needs to authenticate
+try:
+    credentials = client.get_credentials("reddit")
+    print("Reddit credentials found.")
+except NotAuthorizedError as e:
+    print(e) # "Please ask the user to visit the following url to authorize..."
+
+# Example of fetching a single app and its actions
+if apps:
+    app_id = apps[0].id  # Assuming AppConfig has an 'id' attribute
+
+    # Fetch a single app's configuration
+    app_config = client.fetch_app(app_id)
+    print(f"Fetched config for app {app_id}:", app_config)
+
+    # List all actions for that app
+    actions = client.list_actions(app_id)
+    print(f"Actions for app {app_id}:", actions)
+
+# List all apps (returns raw JSON data)
+all_apps = client.list_all_apps()
+print("All available apps:", all_apps)
+```
+
+### AgentrIntegration
+This class handles the authentication and authorization flow for a single integration (e.g., "reddit"). It's used under the hood by applications to acquire credentials.
+
+#### Methods
+```python
+from universal_mcp.agentr import AgentrIntegration, AgentrClient
+from universal_mcp.exceptions import NotAuthorizedError
+
+client = AgentrClient()
+
+# Create an integration for a specific service
+reddit_integration = AgentrIntegration(name="reddit", client=client)
+
+# If credentials are not present, this will raise NotAuthorizedError
+try:
+    creds = reddit_integration.credentials
+    print("Successfully retrieved credentials.")
+except NotAuthorizedError:
+    # Get the URL to send the user to for authentication
+    auth_url = reddit_integration.authorize()
+    print(f"Please authorize here: {auth_url}")
+
+# You can also use the get_credentials() method
+try:
+    creds = reddit_integration.get_credentials()
+    print("Successfully retrieved credentials again.")
+except NotAuthorizedError:
+    print("Still not authorized.")
+```
+
+### AgentrRegistry
+The registry is responsible for discovering which tools are available on the AgentR platform.
+
+#### Methods
+```python
+import asyncio
+from universal_mcp.agentr import AgentrRegistry, AgentrClient
+
+client = AgentrClient()
+registry = AgentrRegistry(client=client)
+
+async def main():
+    # List all apps available on the AgentR platform
+    available_apps = await registry.list_apps()
+    print(available_apps)
+
+    if available_apps:
+        app_id = available_apps[0]['id']
+        # Get details for a specific app
+        app_details = await registry.get_app_details(app_id)
+        print(f"Details for {app_id}:", app_details)
+
+    # The load_tools method is used internally by the high-level Agentr client
+    # but can be called directly if needed.
+    # from universal_mcp.tools import ToolManager
+    # tool_manager = ToolManager()
+    # registry.load_tools(["reddit_search_subreddits"], tool_manager)
+    # print(tool_manager.list_tools())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### AgentrServer
+For server-side deployments, `AgentrServer` can be used to load all configured applications and their tools from an AgentR instance on startup.
+
+```python
+from universal_mcp.config import ServerConfig
+from universal_mcp.agentr.server import AgentrServer
+
+# Configuration for the server
+config = ServerConfig(
+    type="agentr",
+    api_key="your-agentr-api-key"
+)
+
+# The server will automatically fetch and register all tools on initialization
+server = AgentrServer(config=config)
+
+# The tool manager is now populated with tools from the AgentR instance
+tool_manager = server.tool_manager
+print(tool_manager.list_tools())
+```
+
+## Executing Tools
+Once tools are loaded, you can execute them using the `call_tool` method on the `ToolManager` instance, which is available via `agentr.manager`.
+
+```python
+import os
+import asyncio
+from universal_mcp.agentr import Agentr
+
+async def main():
+    # 1. Initialize Agentr
+    agentr = Agentr(api_key=os.environ.get("AGENTR_API_KEY"))
+
+    # 2. Load the tool(s) you want to use
+    tool_name = "reddit_search_subreddits"
+    agentr.load_tools([tool_name])
+
+    # 3. Execute the tool using the tool manager
+    try:
+        # Note the 'await' since call_tool is an async method
+        result = await agentr.manager.call_tool(
+            name=tool_name,
+            arguments={"query": "elon musk", "limit": 5, "sort": "relevance"}
+        )
+        print("Execution result:", result)
+    except Exception as e:
+        print(f"An error occurred: {e}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```

universal_mcp/agentr/__init__.py

@@ -0,0 +1,6 @@
+from .agentr import Agentr
+from .client import AgentrClient
+from .integration import AgentrIntegration
+from .registry import AgentrRegistry
+
+__all__ = ["Agentr", "AgentrClient", "AgentrRegistry", "AgentrIntegration"]

universal_mcp/agentr/agentr.py

@@ -0,0 +1,30 @@
+import os
+
+from universal_mcp.tools import Tool, ToolFormat, ToolManager
+
+from .client import AgentrClient
+from .registry import AgentrRegistry
+
+
+class Agentr:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        registry: AgentrRegistry | None = None,
+        format: ToolFormat | None = None,
+        manager: ToolManager | None = None,
+    ):
+        self.api_key = api_key or os.getenv("AGENTR_API_KEY")
+        self.base_url = base_url or os.getenv("AGENTR_BASE_URL")
+        self.client = AgentrClient(api_key=self.api_key, base_url=self.base_url)
+        self.registry = registry or AgentrRegistry(client=self.client)
+        self.format = format or ToolFormat.NATIVE
+        self.manager = manager or ToolManager()
+
+    def load_tools(self, tool_names: list[str]) -> None:
+        self.registry.load_tools(tool_names, self.manager)
+        return
+
+    def list_tools(self, format: ToolFormat | None = None) -> list[Tool]:
+        return self.manager.list_tools(format=format or self.format)

universal_mcp/{utils/agentr.py → agentr/client.py}

@@ -82,6 +82,22 @@ class AgentrClient:
         data = response.json()
         return [AppConfig.model_validate(app) for app in data]
 
+    def fetch_app(self, app_id: str) -> dict:
+        """Fetch a specific app from AgentR API.
+
+        Args:
+            app_id (str): ID of the app to fetch
+
+        Returns:
+            dict: App configuration data
+
+        Raises:
+            httpx.HTTPError: If API request fails
+        """
+        response = self.client.get(f"/apps/{app_id}/")
+        response.raise_for_status()
+        return response.json()
+
     def list_all_apps(self) -> list:
         """List all apps from AgentR API.
 
@@ -92,16 +108,16 @@ class AgentrClient:
         response.raise_for_status()
         return response.json()
 
-    def list_actions(self, app_name: str):
+    def list_actions(self, app_id: str):
         """List actions for an app.
 
         Args:
-            app_name (str): Name of the app to list actions for
+            app_id (str): ID of the app to list actions for
 
         Returns:
             List of action configurations
         """
 
-        response = self.client.get(f"/apps/{app_name}/actions/")
+        response = self.client.get(f"/apps/{app_id}/actions/")
         response.raise_for_status()
         return response.json()

universal_mcp/agentr/integration.py

@@ -0,0 +1,104 @@
+from universal_mcp.integrations.integration import Integration
+
+from .client import AgentrClient
+
+
+class AgentrIntegration(Integration):
+    """Manages authentication and authorization via the AgentR platform.
+
+    This integration uses an `AgentrClient` to interact with the AgentR API
+    for operations like retrieving authorization URLs and fetching stored
+    credentials. It simplifies integration with services supported by AgentR.
+
+    Attributes:
+        name (str): Name of the integration (e.g., "github", "google").
+        store (BaseStore): Store, typically not used directly by this class
+                       as AgentR manages the primary credential storage.
+        client (AgentrClient): Client for communicating with the AgentR API.
+        _credentials (dict | None): Cached credentials.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        client: AgentrClient | None = None,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        **kwargs,
+    ):
+        """Initializes the AgentRIntegration.
+
+        Args:
+            name (str): The name of the service integration as configured on
+                        the AgentR platform (e.g., "github").
+            client (AgentrClient | None, optional): The AgentR client. If not provided,
+                                                   a new `AgentrClient` will be created.
+            api_key (str | None, optional): API key for AgentR. If not provided,
+                                           will be loaded from environment variables.
+            base_url (str | None, optional): Base URL for AgentR API. If not provided,
+                                            will be loaded from environment variables.
+            **kwargs: Additional arguments passed to the parent `Integration`.
+        """
+        super().__init__(name, **kwargs)
+        self.type = "agentr"
+        self.client = client or AgentrClient(api_key=api_key, base_url=base_url)
+        self._credentials = None
+
+    def set_credentials(self, credentials: dict[str, str] | None = None) -> str:
+        """Not used for direct credential setting; initiates authorization instead.
+
+        For AgentR integrations, credentials are set via the AgentR platform's
+        OAuth flow. This method effectively redirects to the `authorize` flow.
+
+        Args:
+            credentials (dict | None, optional): Not used by this implementation.
+
+        Returns:
+            str: The authorization URL or message from the `authorize()` method.
+        """
+        raise NotImplementedError("AgentR integrations do not support direct credential setting")
+
+    @property
+    def credentials(self):
+        """Retrieves credentials from the AgentR API, with caching.
+
+        If credentials are not cached locally (in `_credentials`), this property
+        fetches them from the AgentR platform using `self.client.get_credentials`.
+
+        Returns:
+            dict: The credentials dictionary obtained from AgentR.
+
+        Raises:
+            NotAuthorizedError: If credentials are not found (e.g., 404 from AgentR).
+            httpx.HTTPStatusError: For other API errors from AgentR.
+        """
+        if self._credentials is not None:
+            return self._credentials
+        self._credentials = self.client.get_credentials(self.name)
+        return self._credentials
+
+    def get_credentials(self):
+        """Retrieves credentials from the AgentR API. Alias for `credentials` property.
+
+        Returns:
+            dict: The credentials dictionary obtained from AgentR.
+
+        Raises:
+            NotAuthorizedError: If credentials are not found.
+            httpx.HTTPStatusError: For other API errors.
+        """
+        return self.credentials
+
+    def authorize(self) -> str:
+        """Retrieves the authorization URL from the AgentR platform.
+
+        This URL should be presented to the user to initiate the OAuth flow
+        managed by AgentR for the service associated with `self.name`.
+
+        Returns:
+            str: The authorization URL.
+
+        Raises:
+            httpx.HTTPStatusError: If the API request to AgentR fails.
+        """
+        return self.client.get_authorization_url(self.name)

universal_mcp/agentr/registry.py

@@ -0,0 +1,91 @@
+from loguru import logger
+
+from universal_mcp.agentr.client import AgentrClient
+from universal_mcp.applications import app_from_slug
+from universal_mcp.tools.manager import ToolManager, _get_app_and_tool_name
+from universal_mcp.tools.registry import ToolRegistry
+
+from .integration import AgentrIntegration
+
+
+class AgentrRegistry(ToolRegistry):
+    """Platform manager implementation for AgentR platform."""
+
+    def __init__(self, client: AgentrClient | None = None, **kwargs):
+        """Initialize the AgentR platform manager."""
+
+        self.client = client or AgentrClient(**kwargs)
+        logger.debug("AgentrRegistry initialized successfully")
+
+    async def list_apps(self) -> list[dict[str, str]]:
+        """Get list of available apps from AgentR.
+
+        Returns:
+            List of app dictionaries with id, name, description, and available fields
+        """
+        try:
+            all_apps = await self.client.list_all_apps()
+            available_apps = [
+                {"id": app["id"], "name": app["name"], "description": app.get("description", "")}
+                for app in all_apps
+                if app.get("available", False)
+            ]
+            logger.info(f"Found {len(available_apps)} available apps from AgentR")
+            return available_apps
+        except Exception as e:
+            logger.error(f"Error fetching apps from AgentR: {e}")
+            return []
+
+    async def get_app_details(self, app_id: str) -> dict[str, str]:
+        """Get detailed information about a specific app from AgentR.
+
+        Args:
+            app_id: The ID of the app to get details for
+
+        Returns:
+            Dictionary containing app details
+        """
+        try:
+            app_info = await self.client.fetch_app(app_id)
+            return {
+                "id": app_info.get("id"),
+                "name": app_info.get("name"),
+                "description": app_info.get("description"),
+                "category": app_info.get("category"),
+                "available": app_info.get("available", True),
+            }
+        except Exception as e:
+            logger.error(f"Error getting details for app {app_id}: {e}")
+            return {
+                "id": app_id,
+                "name": app_id,
+                "description": "Error loading details",
+                "category": "Unknown",
+                "available": True,
+            }
+
+    def load_tools(self, tools: list[str] | None, tool_manager: ToolManager) -> None:
+        """Load tools from AgentR and register them as tools.
+
+        Args:
+            tools: The list of tools to load ( prefixed with app name )
+            tool_manager: The tool manager to register tools with
+        """
+        if not tools:
+            return
+        logger.info(f"Loading all actions for app: {tools}")
+        # Group all tools by app_name, tools
+        tools_by_app = {}
+        for tool_name in tools:
+            app_name, _ = _get_app_and_tool_name(tool_name)
+            if app_name not in tools_by_app:
+                tools_by_app[app_name] = []
+            tools_by_app[app_name].append(tool_name)
+
+        for app_name, tool_names in tools_by_app.items():
+            app = app_from_slug(app_name)
+            integration = AgentrIntegration(name=app_name)
+            # TODO: Import with name param, some apps are written incorrectly and hence passing name fails
+            app_instance = app(integration=integration)
+            tool_manager.register_tools_from_app(app_instance, tool_names=tool_names)
+        return

universal_mcp/agentr/server.py

@@ -0,0 +1,51 @@
+from loguru import logger
+
+from universal_mcp.applications import app_from_config
+from universal_mcp.config import AppConfig, ServerConfig
+from universal_mcp.servers.server import BaseServer
+from universal_mcp.tools import ToolManager
+
+from .client import AgentrClient
+from .integration import AgentrIntegration
+
+
+def load_from_agentr_server(client: AgentrClient, tool_manager: ToolManager) -> None:
+    """Load apps from AgentR server and register their tools."""
+    try:
+        apps = client.fetch_apps()
+        for app in apps:
+            try:
+                app_config = AppConfig.model_validate(app)
+                integration = (
+                    AgentrIntegration(name=app_config.integration.name, client=client)  # type: ignore
+                    if app_config.integration
+                    else None
+                )
+                app_instance = app_from_config(app_config)(integration=integration)
+                tool_manager.register_tools_from_app(app_instance, app_config.actions)
+                logger.info(f"Loaded app from AgentR: {app_config.name}")
+            except Exception as e:
+                logger.error(f"Failed to load app from AgentR: {e}", exc_info=True)
+    except Exception as e:
+        logger.error(f"Failed to fetch apps from AgentR: {e}", exc_info=True)
+        raise
+
+
+class AgentrServer(BaseServer):
+    """Server that loads apps from AgentR server."""
+
+    def __init__(self, config: ServerConfig, **kwargs):
+        super().__init__(config, **kwargs)
+        self._tools_loaded = False
+        self.api_key = config.api_key.get_secret_value() if config.api_key else None
+        self.base_url = config.base_url
+        self.client = AgentrClient(api_key=self.api_key, base_url=self.base_url)
+
+    @property
+    def tool_manager(self) -> ToolManager:
+        if self._tool_manager is None:
+            self._tool_manager = ToolManager(warn_on_duplicate_tools=True)
+        if not self._tools_loaded:
+            load_from_agentr_server(self.client, self._tool_manager)
+            self._tools_loaded = True
+        return self._tool_manager

universal_mcp/agents/__init__.py

@@ -0,0 +1,6 @@
+from .auto import AutoAgent
+from .base import BaseAgent
+from .react import ReactAgent
+from .simple import SimpleAgent
+
+__all__ = ["BaseAgent", "ReactAgent", "SimpleAgent", "AutoAgent"]