universal-mcp 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

universal_mcp/applications/__init__.py

@@ -1,31 +1,26 @@
-from universal_mcp.applications.zenquotes.app import ZenQuoteApp
-from universal_mcp.applications.tavily.app import TavilyApp
-from universal_mcp.applications.github.app import GithubApp
-from universal_mcp.applications.google_calendar.app import GoogleCalendarApp
-from universal_mcp.applications.google_mail.app import GmailApp
-from universal_mcp.applications.resend.app import ResendApp
-from universal_mcp.applications.reddit.app import RedditApp
-from universal_mcp.applications.application import Application, APIApplication
+import importlib
 
-def app_from_name(name: str):
-    name = name.lower().strip()
-    name = name.replace(" ", "-")
-    if name == "zenquotes":
-        return ZenQuoteApp
-    elif name == "tavily":
-        return TavilyApp
-    elif name == "github":
-        return GithubApp
-    elif name == "google-calendar":
-        return GoogleCalendarApp
-    elif name == "google-mail":
-        return GmailApp
-    elif name == "resend":
-        return ResendApp
-    elif name == "reddit":
-        return RedditApp
-    else:
-        raise ValueError(f"App {name} not found")
+from loguru import logger
 
+from universal_mcp.applications.application import APIApplication, Application
 
-__all__ = ["app_from_name", "Application", "APIApplication"]
+# 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 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
+
+
+__all__ = [
+    "app_from_slug",
+    "Application",
+    "APIApplication",
+]

universal_mcp/applications/application.py

@@ -1,31 +1,37 @@
-from abc import ABC
+from abc import ABC, abstractmethod
+
+import httpx
 from loguru import logger
+
 from universal_mcp.exceptions import NotAuthorizedError
 from universal_mcp.integrations import Integration
-import httpx
+
 
 class Application(ABC):
     """
     Application is collection of tools that can be used by an agent.
     """
+
     def __init__(self, name: str, **kwargs):
         self.name = name
-        self.tools = []
 
+    @abstractmethod
     def list_tools(self):
-        return self.tools
+        pass
+
 
 class APIApplication(Application):
     """
     APIApplication is an application that uses an API to interact with the world.
     """
+
     def __init__(self, name: str, integration: Integration = None, **kwargs):
         super().__init__(name, **kwargs)
         self.integration = integration
 
     def _get_headers(self):
         return {}
-    
+
     def _get(self, url, params=None):
         try:
             headers = self._get_headers()
@@ -39,7 +45,6 @@ class APIApplication(Application):
             logger.error(f"Error getting {url}: {e}")
             raise e
 
-    
     def _post(self, url, data, params=None):
         try:
             headers = self._get_headers()
@@ -95,7 +100,7 @@ class APIApplication(Application):
             raise e
         except Exception as e:
             logger.error(f"Error patching {url}: {e}")
-            raise e       
+            raise e
 
     def validate(self):
-        pass
+        pass

universal_mcp/applications/e2b/app.py

@@ -0,0 +1,74 @@
+from e2b_code_interpreter import Sandbox
+from loguru import logger
+
+from universal_mcp.applications.application import APIApplication
+from universal_mcp.integrations import Integration
+
+
+class E2BApp(APIApplication):
+    """
+    Application for interacting with the E2B secure cloud sandboxes
+    to execute Python code.
+    """
+
+    def __init__(self, integration: Integration | None = None) -> None:
+        super().__init__(name="e2b", integration=integration)
+        self.api_key: str | None = None
+
+    def _set_api_key(self):
+        if self.api_key:
+            return
+
+        if not self.integration:
+            raise ValueError("Integration is None. Cannot retrieve E2B API Key.")
+
+        credentials = self.integration.get_credentials()
+        if not credentials:
+            raise ValueError(
+                f"Failed to retrieve E2B API Key using integration '{self.integration.name}'. "
+                f"Check store configuration (e.g., ensure the correct environment variable is set)."
+            )
+
+        self.api_key = credentials
+        logger.info("E2B API Key successfully retrieved via integration.")
+
+    def _format_execution_output(self, logs) -> str:
+        """Helper function to format the E2B execution logs nicely."""
+        output_parts = []
+
+        if logs.stdout:
+            stdout_content = "".join(logs.stdout).strip()
+            if stdout_content:
+                output_parts.append(f"\n{stdout_content}")
+
+        if logs.stderr:
+            stderr_content = "".join(logs.stderr).strip()
+            if stderr_content:
+                output_parts.append(f"--- ERROR ---\n{stderr_content}")
+
+        if not output_parts:
+            return "Execution finished with no output (stdout/stderr)."
+        return "\n\n".join(output_parts)
+
+    def execute_python_code(self, code: str) -> str:
+        """
+        Executes Python code within a secure E2B cloud sandbox.
+
+        Args:
+            code: The string containing the Python code to execute.
+
+        Returns:
+            A string containing the formatted standard output (stdout) and standard error (stderr)
+            from the execution. If an error occurs during setup or execution, an
+            error message string is returned.
+        """
+        self._set_api_key()
+        with Sandbox(api_key=self.api_key) as sandbox:
+            execution = sandbox.run_code(code=code)
+            result = self._format_execution_output(execution.logs)
+            return result
+
+    def list_tools(self):
+        return [
+            self.execute_python_code,
+        ]

universal_mcp/applications/firecrawl/app.py

@@ -0,0 +1,381 @@
+from typing import Any
+
+from firecrawl import FirecrawlApp as FirecrawlApiClient
+from loguru import logger
+
+from universal_mcp.applications.application import APIApplication
+from universal_mcp.exceptions import NotAuthorizedError
+from universal_mcp.integrations import Integration
+
+
+class FirecrawlApp(APIApplication):
+    """
+    Application for interacting with the Firecrawl service (firecrawl.dev)
+    to scrape web pages, perform searches, and manage crawl/batch scrape/extract jobs.
+    Requires a Firecrawl API key configured via integration
+    (e.g., FIRECRAWL_API_KEY environment variable).
+    """
+
+    def __init__(self, integration: Integration | None = None) -> None:
+        super().__init__(name="firecrawl", integration=integration)
+        self.api_key: str | None = None
+        self._attempt_initial_key_load()
+
+    def _attempt_initial_key_load(self):
+        """Attempts to load the API key during initialization."""
+        if self.integration:
+            credentials = self.integration.get_credentials()
+            if credentials and credentials.get("api_key"):
+                self.api_key = credentials["api_key"]
+                logger.info(
+                    "Firecrawl API Key successfully retrieved via integration during init."
+                )
+            else:
+                logger.warning(
+                    "Firecrawl API Key not found in credentials during init. Will try again on first use."
+                )
+
+    def _get_firecrawl_client(self) -> FirecrawlApiClient:
+        """Ensures the API key is available and returns an initialized Firecrawl client."""
+        if not self.api_key:
+            logger.debug(
+                "Firecrawl API key not loaded, attempting retrieval via integration."
+            )
+            if not self.integration:
+                raise NotAuthorizedError("Firecrawl integration is not configured.")
+
+            credentials = self.integration.get_credentials()
+            if credentials and credentials.get("api_key"):
+                self.api_key = credentials["api_key"]
+                logger.info("Firecrawl API Key successfully retrieved via integration.")
+            else:
+                action = (
+                    self.integration.authorize()
+                    if hasattr(self.integration, "authorize")
+                    else "Configure API Key"
+                )
+                raise NotAuthorizedError(
+                    f"Firecrawl API Key not found in provided integration credentials. Action required: {action}"
+                )
+
+        if not self.api_key:
+            raise NotAuthorizedError(
+                "Firecrawl API Key is missing or could not be loaded."
+            )
+
+        return FirecrawlApiClient(api_key=self.api_key)
+
+    def scrape_url(
+        self, url: str, params: dict[str, Any] | None = None
+    ) -> dict[str, Any] | str:
+        """
+        Scrapes a single URL using Firecrawl and returns the extracted data.
+
+        Args:
+            url: The URL of the web page to scrape.
+            params: Optional dictionary of parameters to customize the scrape.
+                    Refer to Firecrawl documentation for 'pageOptions', 'extractorOptions', 'jsonOptions'.
+                    Example: {'pageOptions': {'onlyMainContent': True}}
+
+        Returns:
+            A dictionary containing the scraped data (e.g., 'content', 'markdown', 'metadata')
+            on success, or a string containing an error message on failure.
+        """
+        logger.info(f"Attempting to scrape URL: {url} with params: {params}")
+        try:
+            client = self._get_firecrawl_client()
+            response_data = client.scrape_url(url=url, params=params)
+            logger.info(f"Successfully scraped URL: {url}")
+            return response_data
+        except Exception as e:
+            logger.error(f"Failed to scrape URL {url}: {type(e).__name__} - {e}")
+            return f"Error scraping URL {url}: {type(e).__name__} - {e}"
+
+    def search(
+        self, query: str, params: dict[str, Any] | None = None
+    ) -> dict[str, Any] | str:
+        """
+        Performs a web search using Firecrawl's search capability.
+
+        Args:
+            query: The search query string.
+            params: Optional dictionary of search parameters (e.g., limit, lang, country, scrapeOptions).
+                    Refer to Firecrawl documentation for details.
+                    Example: {'limit': 3, 'country': 'DE'}
+
+        Returns:
+            A dictionary containing the search results (typically {'success': bool, 'data': [...]})
+            on success, or a string containing an error message on failure.
+        """
+        logger.info(f"Attempting search for query: '{query}' with params: {params}")
+        try:
+            client = self._get_firecrawl_client()
+            # The library method returns the full response dictionary
+            response = client.search(query=query, params=params)
+            logger.info(f"Successfully performed search for query: '{query}'")
+            return response
+        except Exception as e:
+            logger.error(
+                f"Failed to perform search for '{query}': {type(e).__name__} - {e}"
+            )
+            return f"Error performing search for '{query}': {type(e).__name__} - {e}"
+
+    # --- Asynchronous Job Pattern Tools ---
+
+    def start_crawl(
+        self,
+        url: str,
+        params: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any] | str:
+        """
+        Starts a crawl job for a given URL using Firecrawl. Returns the job ID immediately.
+        Use 'check_crawl_status' to monitor progress and retrieve results.
+
+        Args:
+            url: The starting URL for the crawl.
+            params: Optional dictionary of parameters to customize the crawl (e.g., crawlerOptions).
+                    Example: {'crawlerOptions': {'excludes': ['blog/'], 'maxDepth': 2}}
+            idempotency_key: Optional unique key to prevent duplicate jobs if the request is retried.
+
+        Returns:
+            A dictionary containing the job initiation response (e.g., {'success': bool, 'id': str})
+            on success, or a string containing an error message on failure.
+        """
+        logger.info(
+            f"Attempting to start crawl job for URL: {url} with params: {params}"
+        )
+        try:
+            client = self._get_firecrawl_client()
+            # Use the library's async method which returns the job ID response
+            response = client.async_crawl_url(
+                url=url, params=params, idempotency_key=idempotency_key
+            )
+            if response.get("success"):
+                logger.info(
+                    f"Successfully started crawl job for URL: {url}. Job ID: {response.get('id')}"
+                )
+            else:
+                logger.error(
+                    f"Failed to start crawl job for URL {url}. Response: {response}"
+                )
+            return response
+        except Exception as e:
+            logger.error(
+                f"Failed to start crawl for URL {url}: {type(e).__name__} - {e}"
+            )
+            return f"Error starting crawl for URL {url}: {type(e).__name__} - {e}"
+
+    def check_crawl_status(self, job_id: str) -> dict[str, Any] | str:
+        """
+        Checks the status of a previously initiated Firecrawl crawl job.
+        If the job is completed, this retrieves the results (potentially paginated).
+
+        Args:
+            job_id: The ID of the crawl job to check.
+
+        Returns:
+            A dictionary containing the job status details (e.g., 'status', 'progress', 'data' if completed)
+            on success, or a string containing an error message on failure.
+            Common status values: 'pending', 'queued', 'scraping', 'completed', 'failed'.
+        """
+        logger.info(f"Attempting to check status for crawl job ID: {job_id}")
+        try:
+            client = self._get_firecrawl_client()
+            # Library method handles pagination for completed jobs
+            status = client.check_crawl_status(id=job_id)
+            logger.info(
+                f"Successfully checked status for job ID: {job_id}. Status: {status.get('status', 'unknown')}"
+            )
+            return status
+        except Exception as e:
+            logger.error(
+                f"Failed to check crawl status for job ID {job_id}: {type(e).__name__} - {e}"
+            )
+            return f"Error checking crawl status for job ID {job_id}: {type(e).__name__} - {e}"
+
+    def cancel_crawl(self, job_id: str) -> dict[str, Any] | str:
+        """
+        Cancels a currently running Firecrawl crawl job.
+
+        Args:
+            job_id: The ID of the crawl job to cancel.
+
+        Returns:
+            A dictionary confirming the cancellation status (e.g., {'success': bool, 'status': 'cancelled'})
+            on success, or a string containing an error message on failure.
+        """
+        logger.info(f"Attempting to cancel crawl job ID: {job_id}")
+        try:
+            client = self._get_firecrawl_client()
+            response = client.cancel_crawl(id=job_id)
+            logger.info(
+                f"Successfully requested cancellation for job ID: {job_id}. Response: {response}"
+            )
+            return response
+        except Exception as e:
+            logger.error(
+                f"Failed to cancel crawl job ID {job_id}: {type(e).__name__} - {e}"
+            )
+            return f"Error cancelling crawl job ID {job_id}: {type(e).__name__} - {e}"
+
+    def start_batch_scrape(
+        self,
+        urls: list[str],
+        params: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any] | str:
+        """
+        Starts a batch scrape job for multiple URLs using Firecrawl. Returns the job ID immediately.
+        Use 'check_batch_scrape_status' to monitor progress and retrieve results.
+
+        Args:
+            urls: A list of URLs to scrape.
+            params: Optional dictionary of parameters applied to all scrapes in the batch.
+                    Refer to Firecrawl documentation for scrape parameters.
+            idempotency_key: Optional unique key to prevent duplicate jobs.
+
+        Returns:
+            A dictionary containing the job initiation response (e.g., {'success': bool, 'id': str})
+            on success, or a string containing an error message on failure.
+        """
+        url_count = len(urls)
+        logger.info(
+            f"Attempting to start batch scrape job for {url_count} URLs with params: {params}"
+        )
+        if not urls:
+            return "Error: No URLs provided for batch scrape."
+        try:
+            client = self._get_firecrawl_client()
+            response = client.async_batch_scrape_urls(
+                urls=urls, params=params, idempotency_key=idempotency_key
+            )
+            if response.get("success"):
+                logger.info(
+                    f"Successfully started batch scrape job for {url_count} URLs. Job ID: {response.get('id')}"
+                )
+            else:
+                logger.error(
+                    f"Failed to start batch scrape job for {url_count} URLs. Response: {response}"
+                )
+            return response
+        except Exception as e:
+            logger.error(f"Failed to start batch scrape: {type(e).__name__} - {e}")
+            return f"Error starting batch scrape: {type(e).__name__} - {e}"
+
+    def check_batch_scrape_status(self, job_id: str) -> dict[str, Any] | str:
+        """
+        Checks the status of a previously initiated Firecrawl batch scrape job.
+        If the job is completed, this retrieves the results for all URLs.
+
+        Args:
+            job_id: The ID of the batch scrape job to check.
+
+        Returns:
+            A dictionary containing the job status details (e.g., 'status', 'progress', 'data' list if completed)
+            on success, or a string containing an error message on failure.
+        """
+        logger.info(f"Attempting to check status for batch scrape job ID: {job_id}")
+        try:
+            client = self._get_firecrawl_client()
+            status = client.check_batch_scrape_status(id=job_id)
+            logger.info(
+                f"Successfully checked status for batch scrape job ID: {job_id}. Status: {status.get('status', 'unknown')}"
+            )
+            return status
+        except Exception as e:
+            logger.error(
+                f"Failed to check batch scrape status for job ID {job_id}: {type(e).__name__} - {e}"
+            )
+            return f"Error checking batch scrape status for job ID {job_id}: {type(e).__name__} - {e}"
+
+    def start_extract(
+        self,
+        urls: list[str],
+        params: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any] | str:
+        """
+        Starts an extraction job for one or more URLs using Firecrawl. Returns the job ID immediately.
+        Use 'check_extract_status' to monitor progress and retrieve results. Requires 'prompt' or 'schema' in params.
+
+        Args:
+            urls: A list of URLs to extract data from.
+            params: Dictionary of parameters. MUST include 'prompt' (string) or 'schema' (JSON schema dict or Pydantic model).
+                    Optional: 'enableWebSearch', 'systemPrompt', etc. See Firecrawl docs.
+                    Example: {'prompt': 'Extract the main headlines'}
+                    Example: {'schema': {'type': 'object', 'properties': {'title': {'type': 'string'}}}}
+            idempotency_key: Optional unique key to prevent duplicate jobs.
+
+        Returns:
+            A dictionary containing the job initiation response (e.g., {'success': bool, 'id': str})
+            on success, or a string containing an error message on failure.
+        """
+        logger.info(
+            f"Attempting to start extraction job for URLs: {urls} with params: {params}"
+        )
+        if not urls:
+            return "Error: No URLs provided for extraction."
+        if not params or (not params.get("prompt") and not params.get("schema")):
+            return "Error: 'params' dictionary must include either a 'prompt' string or a 'schema' definition."
+        try:
+            client = self._get_firecrawl_client()
+            # Pass params directly; the library handles schema conversion if needed
+            response = client.async_extract(
+                urls=urls, params=params, idempotency_key=idempotency_key
+            )
+            if response.get("success"):
+                logger.info(
+                    f"Successfully started extraction job for URLs. Job ID: {response.get('id')}"
+                )
+            else:
+                logger.error(
+                    f"Failed to start extraction job for URLs. Response: {response}"
+                )
+            return response
+        except Exception as e:
+            logger.error(f"Failed to start extraction: {type(e).__name__} - {e}")
+            return f"Error starting extraction: {type(e).__name__} - {e}"
+
+    def check_extract_status(self, job_id: str) -> dict[str, Any] | str:
+        """
+        Checks the status of a previously initiated Firecrawl extraction job.
+        If the job is completed, this retrieves the extracted data.
+
+        Args:
+            job_id: The ID of the extraction job to check.
+
+        Returns:
+            A dictionary containing the job status details (e.g., 'status', 'data' if completed)
+            on success, or a string containing an error message on failure.
+            Common status values: 'pending', 'processing', 'completed', 'failed'.
+        """
+        logger.info(f"Attempting to check status for extraction job ID: {job_id}")
+        try:
+            client = self._get_firecrawl_client()
+            status = client.get_extract_status(
+                job_id=job_id
+            )  # Correct library method name
+            logger.info(
+                f"Successfully checked status for extraction job ID: {job_id}. Status: {status.get('status', 'unknown')}"
+            )
+            return status
+        except Exception as e:
+            logger.error(
+                f"Failed to check extraction status for job ID {job_id}: {type(e).__name__} - {e}"
+            )
+            return f"Error checking extraction status for job ID {job_id}: {type(e).__name__} - {e}"
+
+    def list_tools(self):
+        """Returns a list of methods exposed as tools."""
+        return [
+            self.scrape_url,
+            self.search,
+            self.start_crawl,
+            self.check_crawl_status,
+            self.cancel_crawl,
+            self.start_batch_scrape,
+            self.check_batch_scrape_status,
+            self.start_extract,
+            self.check_extract_status,
+        ]

universal_mcp/applications/github/README.md

@@ -0,0 +1,35 @@
+
+# Github MCP Server
+
+An MCP Server for the Github API.
+
+## Supported Integrations
+
+- AgentR
+- API Key (Coming Soon)
+- OAuth (Coming Soon)
+
+## Tools
+
+This is automatically generated from OpenAPI schema for the Github API.
+
+## Supported Integrations
+
+This tool can be integrated with any service that supports HTTP requests.
+
+## Tool List
+
+No tools with documentation were found in this API client.
+
+
+
+## Usage
+
+- Login to AgentR
+- Follow the quickstart guide to setup MCP Server for your client
+- Visit Apps Store and enable the Github app
+- Restart the MCP Server
+
+### Local Development
+
+- Follow the README to test with the local MCP Server