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

universal_mcp/applications/firecrawl/app.py

@@ -1,10 +1,8 @@
 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
 
 
@@ -12,57 +10,38 @@ 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).
+    Requires a Firecrawl API key configured via integration.
     """
 
     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."
+
+    def _set_api_key(self):
+        """
+        Ensures the API key is loaded from the integration.
+        Raises ValueError if the integration or key is missing/misconfigured.
+        """
+        if self.api_key:
+            return
+
+        if not self.integration:
+            raise ValueError(
+                "Integration is None. Cannot retrieve Firecrawl API Key."
             )
-            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."
+
+        credentials = self.integration.get_credentials()
+        if not credentials:
+            raise ValueError(
+                f"Failed to retrieve Firecrawl API Key using integration '{self.integration.name}'. "
+                f"Check store configuration (e.g., ensure the correct source like environment variable is set)."
             )
 
+        self.api_key = credentials
+        
+    def _get_client(self) -> FirecrawlApiClient:
+        """Initializes and returns the Firecrawl client after ensuring API key is set."""
+        self._set_api_key()
         return FirecrawlApiClient(api_key=self.api_key)
 
     def scrape_url(
@@ -74,21 +53,17 @@ class FirecrawlApp(APIApplication):
         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.
+            A dictionary containing the scraped data 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()
+            client = self._get_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(
@@ -99,29 +74,19 @@ class FirecrawlApp(APIApplication):
 
         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'}
+            params: Optional dictionary of search parameters.
 
         Returns:
-            A dictionary containing the search results (typically {'success': bool, 'data': [...]})
-            on success, or a string containing an error message on failure.
+            A dictionary containing the search results 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
+            client = self._get_client()
             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,
@@ -130,68 +95,43 @@ class FirecrawlApp(APIApplication):
     ) -> 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.
+            params: Optional dictionary of parameters to customize the crawl.
+            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.
+            A dictionary containing the job initiation response 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
+            client = self._get_client()
             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'.
+            A dictionary containing the job status details on success,
+            or a string containing an error message on failure.
         """
-        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')}"
-            )
+            client = self._get_client()
+            status = client.check_crawl_status(id=job_id)    
             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:
@@ -202,23 +142,19 @@ class FirecrawlApp(APIApplication):
             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.
+            A dictionary confirming the cancellation status 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()
+            client = self._get_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}"
-            )
+
+        except Exception as e:            
             return f"Error cancelling crawl job ID {job_id}: {type(e).__name__} - {e}"
 
+
     def start_batch_scrape(
         self,
         urls: list[str],
@@ -226,67 +162,44 @@ class FirecrawlApp(APIApplication):
         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.
+        Starts a batch scrape job for multiple URLs using Firecrawl.
 
         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.
+            params: Optional dictionary of parameters applied to all scrapes.
             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.
+            A dictionary containing the job initiation response 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()
+            client = self._get_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.
+            A dictionary containing the job status details 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')}"
-            )
+            client = self._get_client()
+            status = client.check_batch_scrape_status(id=job_id)            
             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(
@@ -296,74 +209,45 @@ class FirecrawlApp(APIApplication):
         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.
+        Starts an extraction job for one or more URLs using Firecrawl.
 
         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'}}}}
+            params: Dictionary of parameters. MUST include 'prompt' or 'schema'.
             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.
+            A dictionary containing the job initiation response 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
+            client = self._get_client()
             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'.
+            A dictionary containing the job status details on success,
+            or a string containing an error message on failure.
         """
-        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')}"
-            )
+            client = self._get_client()
+            status = client.get_extract_status(job_id=job_id)
             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):
@@ -378,4 +262,4 @@ class FirecrawlApp(APIApplication):
             self.check_batch_scrape_status,
             self.start_extract,
             self.check_extract_status,
-        ]
+        ]

universal_mcp/applications/markitdown/app.py

@@ -9,16 +9,27 @@ class MarkitdownApp(Application):
         self.markitdown = MarkItDown()
 
     async def convert_to_markdown(self, uri: str) -> str:
-        """Convert a web page, file, or data URI to markdown format.
+        """Fetches content from a URI and converts its primary textual representation into Markdown.
+
+        This tool aims to extract the main text content from various sources. It supports:
+        - Web Pages: General HTML, specific handlers for RSS/Atom feeds, Wikipedia articles (main content), YouTube (transcripts if available), Bing SERPs.
+        - Documents: PDF (attempts OCR), DOCX, XLSX, PPTX, XLS, EPUB, Outlook MSG, IPYNB notebooks.
+        - Plain Text files.
+        - Images: Extracts metadata and attempts OCR to get text.
+        - Audio: Extracts metadata and attempts transcription to get text.
+        - Archives: ZIP (extracts and attempts to convert supported files within, concatenating results).
+
+        Note: Conversion quality depends on the source format. Complex layouts, encrypted files, or missing transcripts/OCR data may limit output.
+        Enhanced PDF/Image processing via Azure Document Intelligence may be active if configured server-side.
 
         Args:
-            uri (str): The URI to convert. Supported URI schemes:
-                - http:// or https:// for web pages
-                - file:// for local files
-                - data: for data URIs
+            uri (str): The URI pointing to the resource. Supported schemes:
+                       - http:// or https:// (Web pages, feeds, APIs)
+                       - file:// (Local or accessible network files)
+                       - data: (Embedded data)
 
         Returns:
-            str: The markdown representation of the resource content.
+            str: The extracted content converted to Markdown format.
 
         Example:
             >>> await convert_to_markdown("https://example.com")

universal_mcp/applications/notion/README.md

@@ -1,4 +1,15 @@
-# Notion Tool
+
+# Notion MCP Server
+
+An MCP Server for the Notion API.
+
+## Supported Integrations
+
+- AgentR
+- API Key (Coming Soon)
+- OAuth (Coming Soon)
+
+## Tools
 
 This is automatically generated from OpenAPI schema for the Notion API.
 
@@ -10,23 +21,35 @@ This tool can be integrated with any service that supports HTTP requests.
 
 | Tool | Description |
 |------|-------------|
-| notion_retrieve_auser | Retrieves user information from the Notion API by user ID. |
-| notion_list_all_users | Fetches and returns a list of all users from the Notion API. |
-| notion_retrieve_your_token_sbot_user | Retrieves the current user's token data from the Notion API. |
-| notion_retrieve_adatabase | Retrieves a Notion database by its unique identifier. |
-| notion_update_adatabase | Updates a Notion database with the given ID and request body data. |
-| notion_query_adatabase | Executes a query on a Notion database using the Notion API. |
-| notion_create_adatabase | Creates a new database in Notion using the provided request body. |
-| notion_create_apage | Creates a new page in Notion by sending a POST request with the specified request body. |
-| notion_retrieve_apage | Retrieves a page from the Notion API using a given page ID. |
-| notion_update_page_properties | Updates the properties of a Notion page identified by a given ID. |
-| notion_retrieve_apage_property_item | Retrieves a specific property item from a page in Notion using the page and property IDs. |
-| notion_retrieve_block_children | Retrieves the child blocks of a specified Notion block. |
-| notion_append_block_children | Appends child blocks to a block in Notion using its API. |
-| notion_retrieve_ablock | Retrieves a block from the Notion API using the specified block ID. |
-| notion_delete_ablock | Deletes a block from the Notion database using the specified block ID. |
-| notion_update_ablock | Updates a block in Notion with the given ID and request body. |
-| notion_search | Executes a search request to the Notion API and returns the response in JSON format. |
-| notion_retrieve_comments | Retrieves comments from a Notion block using the Notion API. |
-| notion_add_comment_to_page | Adds a comment to a specified Notion page using the provided request body. |
+| retrieve_a_user | Retrieves user details from the server using the specified user ID. |
+| list_a_ll_users | Fetches a list of all users from the API endpoint and returns the data as a dictionary. |
+| retrieve_your_token_sbot_user | Retrieves the authentication token for the current user from the SBOT service. |
+| retrieve_a_database | Retrieves database details from a specified endpoint using the provided database ID. |
+| update_a_database | Updates a database entry with the given ID using a PATCH request. |
+| query_a_database | Executes a query on a specified database using an identifier and an optional request body. |
+| create_a_database | Creates a new database on the server using the specified request body. |
+| create_a_page | Creates a new page by sending a POST request to the specified endpoint. |
+| retrieve_a_page | Retrieves a page by its unique identifier from a remote server. |
+| update_page_properties | Updates the properties of a page identified by its ID using the provided request body. |
+| retrieve_a_page_property_item | Retrieves the property item of a page using specified page and property identifiers. |
+| retrieve_block_children | Retrieves the children of a specified block using its unique identifier. |
+| append_block_children | Appends child elements to a block identified by its ID and returns the updated block data. |
+| retrieve_a_block | Retrieves a block of data from a given API endpoint using the specified block ID. |
+| delete_a_block | Deletes a block by its unique identifier and returns the server's response. |
+| update_a_block | Updates a block by sending a PATCH request to the specified endpoint. |
+| search | Executes a search query using the specified request body and returns the results. |
+| retrieve_comments | Fetches comments from a remote server for a specified block, with optional pagination. |
+| add_comment_to_page | Adds a comment to a page by sending a POST request with the provided request body. |
+
+
+
+## Usage
+
+- Login to AgentR
+- Follow the quickstart guide to setup MCP Server for your client
+- Visit Apps Store and enable the Notion app
+- Restart the MCP Server
+
+### Local Development
 
+- Follow the README to test with the local MCP Server