universal-mcp-applications 0.1.33__py3-none-any.whl → 0.1.39rc16__py3-none-any.whl

universal_mcp/applications/file_system/app.py

@@ -1,7 +1,6 @@
 import os
 import shutil
 import uuid
-
 from universal_mcp.applications.application import BaseApplication
 
 
@@ -63,14 +62,7 @@ class FileSystemApp(BaseApplication):
             file_path = await FileSystemApp._generate_file_path()
         with open(file_path, "wb") as f:
             f.write(file_data)
-            result = {
-                "status": "success",
-                "data": {
-                    "url": file_path,
-                    "filename": file_path,
-                    "size": len(file_data),
-                },
-            }
+            result = {"status": "success", "data": {"url": file_path, "filename": file_path, "size": len(file_data)}}
             return result
 
     @staticmethod
@@ -98,7 +90,4 @@ class FileSystemApp(BaseApplication):
         return {"status": "success"}
 
     def list_tools(self):
-        return [
-            FileSystemApp.read_file,
-            FileSystemApp.write_file,
-        ]
+        return [FileSystemApp.read_file, FileSystemApp.write_file]

universal_mcp/applications/firecrawl/app.py

@@ -1,19 +1,13 @@
 from typing import Any
-
 from loguru import logger
 
 try:
-    from firecrawl import Firecrawl
+    from firecrawl import AsyncFirecrawl
 
-    FirecrawlApiClient: type[Firecrawl] | None = Firecrawl
+    FirecrawlApiClient: type[AsyncFirecrawl] | None = AsyncFirecrawl
 except ImportError:
     FirecrawlApiClient = None
-
-    logger.error(
-        "Failed to import FirecrawlApp. Please ensure 'firecrawl-py' is installed."
-    )
-
-
+    logger.error("Failed to import FirecrawlApp. Please ensure 'firecrawl-py' is installed.")
 from universal_mcp.applications.application import APIApplication
 from universal_mcp.exceptions import NotAuthorizedError, ToolError
 from universal_mcp.integrations import Integration
@@ -29,97 +23,56 @@ class FirecrawlApp(APIApplication):
 
     def __init__(self, integration: Integration | None = None, **kwargs: Any) -> None:
         super().__init__(name="firecrawl", integration=integration, **kwargs)
-        self._firecrawl_api_key: str | None = None  # Cache for the API key
+        self._firecrawl_api_key: str | None = None
         if FirecrawlApiClient is None:
-            logger.warning(
-                "Firecrawl SDK is not available. Firecrawl tools will not function."
-            )
+            logger.warning("Firecrawl SDK is not available. Firecrawl tools will not function.")
 
-    @property
-    def firecrawl_api_key(self) -> str:
+    async def get_firecrawl_api_key(self) -> str:
         """
         A property that lazily retrieves and caches the Firecrawl API key from the configured integration. On first access, it fetches credentials and raises a `NotAuthorizedError` if the key is unobtainable, ensuring all subsequent API calls within the application are properly authenticated before execution.
         """
         if self._firecrawl_api_key is None:
             if not self.integration:
-                logger.error(
-                    f"{self.name.capitalize()} App: Integration not configured."
-                )
-                raise NotAuthorizedError(
-                    f"Integration not configured for {self.name.capitalize()} App. Cannot retrieve API key."
-                )
-
+                logger.error(f"{self.name.capitalize()} App: Integration not configured.")
+                raise NotAuthorizedError(f"Integration not configured for {self.name.capitalize()} App. Cannot retrieve API key.")
             try:
-                credentials = self.integration.get_credentials()
+                credentials = await self.integration.get_credentials_async()
             except NotAuthorizedError as e:
-                logger.error(
-                    f"{self.name.capitalize()} App: Authorization error when fetching credentials: {e.message}"
-                )
-                raise  # Re-raise the original NotAuthorizedError
+                logger.error(f"{self.name.capitalize()} App: Authorization error when fetching credentials: {e.message}")
+                raise
             except Exception as e:
-                logger.error(
-                    f"{self.name.capitalize()} App: Unexpected error when fetching credentials: {e}",
-                    exc_info=True,
-                )
-                raise NotAuthorizedError(
-                    f"Failed to get {self.name.capitalize()} credentials: {e}"
-                )
-
-            api_key = (
-                credentials.get("api_key")
-                or credentials.get("API_KEY")  # Check common variations
-                or credentials.get("apiKey")
-            )
-
+                logger.error(f"{self.name.capitalize()} App: Unexpected error when fetching credentials: {e}", exc_info=True)
+                raise NotAuthorizedError(f"Failed to get {self.name.capitalize()} credentials: {e}")
+            api_key = credentials.get("api_key") or credentials.get("API_KEY") or credentials.get("apiKey")
             if not api_key:
-                logger.error(
-                    f"{self.name.capitalize()} App: API key not found in credentials."
-                )
-                action_message = (
-                    f"API key for {self.name.capitalize()} is missing. "
-                    "Please ensure it's set in the store via MCP frontend or configuration."
-                )
-                if hasattr(self.integration, "authorize") and callable(
-                    self.integration.authorize
-                ):
+                logger.error(f"{self.name.capitalize()} App: API key not found in credentials.")
+                action_message = f"API key for {self.name.capitalize()} is missing. Please ensure it's set in the store via MCP frontend or configuration."
+                if hasattr(self.integration, "authorize") and callable(self.integration.authorize):
                     try:
                         auth_details = self.integration.authorize()
                         if isinstance(auth_details, str):
                             action_message = auth_details
                         elif isinstance(auth_details, dict) and "url" in auth_details:
-                            action_message = (
-                                f"Please authorize via: {auth_details['url']}"
-                            )
-                        elif (
-                            isinstance(auth_details, dict) and "message" in auth_details
-                        ):
+                            action_message = f"Please authorize via: {auth_details['url']}"
+                        elif isinstance(auth_details, dict) and "message" in auth_details:
                             action_message = auth_details["message"]
                     except Exception as auth_e:
-                        logger.warning(
-                            f"Could not retrieve specific authorization action for {self.name.capitalize()}: {auth_e}"
-                        )
+                        logger.warning(f"Could not retrieve specific authorization action for {self.name.capitalize()}: {auth_e}")
                 raise NotAuthorizedError(action_message)
-
             self._firecrawl_api_key = api_key
-            logger.info(
-                f"{self.name.capitalize()} API Key successfully retrieved and cached."
-            )
+            logger.info(f"{self.name.capitalize()} API Key successfully retrieved and cached.")
         assert self._firecrawl_api_key is not None
         return self._firecrawl_api_key
 
-    def _get_client(self) -> Firecrawl:
+    async def get_firecrawl_client(self) -> AsyncFirecrawl:
         """
         Initializes and returns the Firecrawl client after ensuring API key is set.
         Raises NotAuthorizedError if API key cannot be obtained or SDK is not installed.
         """
         if FirecrawlApiClient is None:
             logger.error("Firecrawl SDK (firecrawl-py) is not available.")
-            raise ToolError(
-                "Firecrawl SDK (firecrawl-py) is not installed or failed to import."
-            )
-
-        # The property self.firecrawl_api_key will raise NotAuthorizedError if key is missing/unretrievable
-        current_api_key = self.firecrawl_api_key
+            raise ToolError("Firecrawl SDK (firecrawl-py) is not installed or failed to import.")
+        current_api_key = await self.get_firecrawl_api_key()
         return FirecrawlApiClient(api_key=current_api_key)
 
     def _handle_firecrawl_exception(self, e: Exception, operation_desc: str) -> str:
@@ -128,28 +81,17 @@ class FirecrawlApp(APIApplication):
         and returning an error string for other issues.
         This helper is designed to be used in tool methods.
         """
-        logger.error(
-            f"Firecrawl App: Error during {operation_desc}: {type(e).__name__} - {e}",
-            exc_info=True,
-        )
-        # Check for common authentication/authorization indicators
+        logger.error(f"Firecrawl App: Error during {operation_desc}: {type(e).__name__} - {e}", exc_info=True)
         error_str = str(e).lower()
         is_auth_error = (
             "unauthorized" in error_str
             or "api key" in error_str
             or "authentication" in error_str
-            or (
-                hasattr(e, "response")
-                and hasattr(e.response, "status_code")
-                and e.response.status_code == 401
-            )  # type: ignore
-            or (hasattr(e, "status_code") and e.status_code == 401)  # type: ignore
+            or (hasattr(e, "response") and hasattr(e.response, "status_code") and (e.response.status_code == 401))
+            or (hasattr(e, "status_code") and e.status_code == 401)
         )
         if is_auth_error:
-            raise NotAuthorizedError(
-                f"Firecrawl API authentication/authorization failed for {operation_desc}: {e}"
-            )
-
+            raise NotAuthorizedError(f"Firecrawl API authentication/authorization failed for {operation_desc}: {e}")
         return f"Error during {operation_desc}: {type(e).__name__} - {e}"
 
     def _to_serializable(self, obj: Any) -> Any:
@@ -158,23 +100,57 @@ class FirecrawlApp(APIApplication):
         """
         if isinstance(obj, list):
             return [self._to_serializable(item) for item in obj]
-        if hasattr(obj, "model_dump"):  # Pydantic v2
+        if hasattr(obj, "model_dump"):
             return obj.model_dump()
-        if hasattr(obj, "dict"):  # Pydantic v1
+        if hasattr(obj, "dict"):
             return obj.dict()
         return obj
 
-    def scrape_url(self, url: str) -> Any:
+    async def scrape_url(
+        self,
+        url: str,
+        formats: list[str | dict[str, Any]] | None = None,
+        only_main_content: bool | None = None,
+        timeout: int | None = None,
+        wait_for: int | None = None,
+        mobile: bool | None = None,
+        skip_tls_verification: bool | None = None,
+        schema: dict[str, Any] | None = None,
+        prompt: str | None = None,
+    ) -> Any:
         """
-        Synchronously scrapes a single URL, immediately returning its content. This provides a direct method for single-page scraping, contrasting with asynchronous, job-based functions like `start_crawl` (for entire sites) and `start_batch_scrape` (for multiple URLs).
+        Synchronously scrapes a single URL, immediately returning its content. This provides a direct method for single-page scraping.
+        Supports structured output via `schema` or `prompt` arguments, or by specifying `formats`.
 
         Args:
             url: The URL of the web page to scrape.
+            formats: Optional list of desired output formats (e.g. ["json"] or [{"type": "json", ...}]).
+            only_main_content: Only scrape the main content of the page.
+            timeout: Timeout in milliseconds.
+            wait_for: Wait for a specific duration (ms) before scraping.
+            mobile: Use mobile user agent.
+            skip_tls_verification: Skip TLS verification.
+            schema: JSON schema for structured output extraction (V2).
+            prompt: Prompt for structured output extraction (V2).
 
         Returns:
             A dictionary containing the scraped data on success,
             or a string containing an error message on failure.
 
+        Examples:
+            Basic scraping:
+            >>> app.scrape_url("https://example.com")
+
+            Structured extraction with Pydantic:
+            >>> from pydantic import BaseModel
+            >>> class Article(BaseModel):
+            ...     title: str
+            ...     summary: str
+            >>> app.scrape_url("https://example.com", schema=Article.model_json_schema())
+
+            Extraction with prompt:
+            >>> app.scrape_url("https://example.com", prompt="Extract the main article content.")
+
         Raises:
             NotAuthorizedError: If API key is missing or invalid.
             ToolError: If the Firecrawl SDK is not installed.
@@ -182,10 +158,29 @@ class FirecrawlApp(APIApplication):
         Tags:
             scrape, important
         """
-        logger.info(f"Attempting to scrape URL: {url}")
+        logger.info(f"Attempting to scrape URL: {url} with schema: {schema is not None}, prompt: {prompt is not None}")
         try:
-            client = self._get_client()
-            response_data = client.scrape(url=url)
+            client = await self.get_firecrawl_client()
+            
+            # Construct formats if schema or prompt is provided (V2 structured output)
+            if schema or prompt:
+                formats = formats or []
+                json_format = {"type": "json"}
+                if schema:
+                    json_format["schema"] = schema
+                if prompt:
+                    json_format["prompt"] = prompt
+                formats.append(json_format)
+
+            response_data = await client.scrape(
+                url=url,
+                formats=formats,
+                only_main_content=only_main_content,
+                timeout=timeout,
+                wait_for=wait_for,
+                mobile=mobile,
+                skip_tls_verification=skip_tls_verification,
+            )
             logger.info(f"Successfully scraped URL: {url}")
             return self._to_serializable(response_data)
         except NotAuthorizedError:
@@ -196,7 +191,7 @@ class FirecrawlApp(APIApplication):
             error_msg = self._handle_firecrawl_exception(e, f"scraping URL {url}")
             return error_msg
 
-    def search(self, query: str) -> dict[str, Any] | str:
+    async def search(self, query: str) -> dict[str, Any] | str:
         """
         Executes a synchronous web search using the Firecrawl service for a given query. Unlike scrape_url which fetches a single page, this function discovers web content. It returns a dictionary of results on success or an error string on failure, raising exceptions for authorization or SDK issues.
 
@@ -216,8 +211,8 @@ class FirecrawlApp(APIApplication):
         """
         logger.info(f"Attempting Firecrawl search for query: {query}")
         try:
-            client = self._get_client()
-            response = client.search(query=query)
+            client = await self.get_firecrawl_client()
+            response = await client.search(query=query)
             logger.info(f"Successfully performed Firecrawl search for query: {query}")
             return self._to_serializable(response)
         except NotAuthorizedError:
@@ -227,15 +222,19 @@ class FirecrawlApp(APIApplication):
         except Exception as e:
             return self._handle_firecrawl_exception(e, f"search for '{query}'")
 
-    def start_crawl(
+    async def start_crawl(
         self,
         url: str,
+        limit: int = 10,
+        scrape_options: dict[str, Any] | None = None,
     ) -> dict[str, Any] | str:
         """
         Starts an asynchronous Firecrawl job to crawl a website from a given URL, returning a job ID. Unlike the synchronous `scrape_url` for single pages, this function initiates a comprehensive, link-following crawl. Progress can be monitored using the `check_crawl_status` function with the returned ID.
 
         Args:
             url: The starting URL for the crawl.
+            limit: The maximum number of pages to crawl.
+            scrape_options: Optional dictionary of scrape options (e.g., {'formats': ['markdown']}).
 
         Returns:
             A dictionary containing the job initiation response on success,
@@ -248,16 +247,12 @@ class FirecrawlApp(APIApplication):
         Tags:
             crawl, async_job, start
         """
-        logger.info(f"Attempting to start Firecrawl crawl for URL: {url}")
+        logger.info(f"Attempting to start Firecrawl crawl for URL: {url} with limit: {limit}")
         try:
-            client = self._get_client()
-            response = client.start_crawl(
-                url=url,
-            )
+            client = await self.get_firecrawl_client()
+            response = await client.start_crawl(url=url, limit=limit, scrape_options=scrape_options)
             job_id = response.id
-            logger.info(
-                f"Successfully started Firecrawl crawl for URL {url}, Job ID: {job_id}"
-            )
+            logger.info(f"Successfully started Firecrawl crawl for URL {url}, Job ID: {job_id}")
             return self._to_serializable(response)
         except NotAuthorizedError:
             raise
@@ -266,7 +261,7 @@ class FirecrawlApp(APIApplication):
         except Exception as e:
             return self._handle_firecrawl_exception(e, f"starting crawl for URL {url}")
 
-    def check_crawl_status(self, job_id: str) -> dict[str, Any] | str:
+    async def check_crawl_status(self, job_id: str) -> dict[str, Any] | str:
         """
         Retrieves the status of an asynchronous Firecrawl job using its unique ID. As the counterpart to `start_crawl`, this function exclusively monitors website crawl progress, distinct from status checkers for batch scraping or data extraction jobs. Returns job details on success or an error message on failure.
 
@@ -286,22 +281,18 @@ class FirecrawlApp(APIApplication):
         """
         logger.info(f"Attempting to check Firecrawl crawl status for job ID: {job_id}")
         try:
-            client = self._get_client()
-            status = client.get_crawl_status(job_id=job_id)
-            logger.info(
-                f"Successfully checked Firecrawl crawl status for job ID: {job_id}"
-            )
+            client = await self.get_firecrawl_client()
+            status = await client.get_crawl_status(job_id=job_id)
+            logger.info(f"Successfully checked Firecrawl crawl status for job ID: {job_id}")
             return self._to_serializable(status)
         except NotAuthorizedError:
             raise
         except ToolError:
             raise
         except Exception as e:
-            return self._handle_firecrawl_exception(
-                e, f"checking crawl status for job ID {job_id}"
-            )
+            return self._handle_firecrawl_exception(e, f"checking crawl status for job ID {job_id}")
 
-    def cancel_crawl(self, job_id: str) -> dict[str, Any] | str:
+    async def cancel_crawl(self, job_id: str) -> dict[str, Any] | str:
         """
         Cancels a running asynchronous Firecrawl crawl job using its unique ID. As a lifecycle management tool for jobs initiated by `start_crawl`, it returns a confirmation status upon success or an error message on failure, distinguishing it from controls for other job types.
 
@@ -322,25 +313,18 @@ class FirecrawlApp(APIApplication):
         """
         logger.info(f"Attempting to cancel Firecrawl crawl job ID: {job_id}")
         try:
-            client = self._get_client()
-            response = client.cancel_crawl(crawl_id=job_id)
-            logger.info(
-                f"Successfully issued cancel command for Firecrawl crawl job ID: {job_id}"
-            )
+            client = await self.get_firecrawl_client()
+            response = await client.cancel_crawl(crawl_id=job_id)
+            logger.info(f"Successfully issued cancel command for Firecrawl crawl job ID: {job_id}")
             return self._to_serializable(response)
         except NotAuthorizedError:
             raise
         except ToolError:
             raise
         except Exception as e:
-            return self._handle_firecrawl_exception(
-                e, f"cancelling crawl job ID {job_id}"
-            )
+            return self._handle_firecrawl_exception(e, f"cancelling crawl job ID {job_id}")
 
-    def start_batch_scrape(
-        self,
-        urls: list[str],
-    ) -> dict[str, Any] | str:
+    async def start_batch_scrape(self, urls: list[str]) -> dict[str, Any] | str:
         """
         Initiates an asynchronous Firecrawl job to scrape a list of URLs. It returns a job ID for tracking with `check_batch_scrape_status`. Unlike the synchronous `scrape_url` which processes a single URL, this function handles bulk scraping and doesn't wait for completion.
 
@@ -360,22 +344,18 @@ class FirecrawlApp(APIApplication):
         """
         logger.info(f"Attempting to start Firecrawl batch scrape for {len(urls)} URLs.")
         try:
-            client = self._get_client()
-            response = client.start_batch_scrape(urls=urls)
-            logger.info(
-                f"Successfully started Firecrawl batch scrape for {len(urls)} URLs."
-            )
+            client = await self.get_firecrawl_client()
+            response = await client.start_batch_scrape(urls=urls)
+            logger.info(f"Successfully started Firecrawl batch scrape for {len(urls)} URLs.")
             return self._to_serializable(response)
         except NotAuthorizedError:
             raise
         except ToolError:
             raise
         except Exception as e:
-            return self._handle_firecrawl_exception(
-                e, f"starting batch scrape for {len(urls)} URLs"
-            )
+            return self._handle_firecrawl_exception(e, f"starting batch scrape for {len(urls)} URLs")
 
-    def check_batch_scrape_status(self, job_id: str) -> dict[str, Any] | str:
+    async def check_batch_scrape_status(self, job_id: str) -> dict[str, Any] | str:
         """
         Checks the status of an asynchronous batch scrape job using its job ID. As the counterpart to `start_batch_scrape`, it specifically monitors multi-URL scraping tasks, distinct from checkers for site-wide crawls (`check_crawl_status`) or AI-driven extractions (`check_extract_status`). Returns detailed progress or an error message.
 
@@ -393,26 +373,20 @@ class FirecrawlApp(APIApplication):
         Tags:
             scrape, batch, async_job, status
         """
-        logger.info(
-            f"Attempting to check Firecrawl batch scrape status for job ID: {job_id}"
-        )
+        logger.info(f"Attempting to check Firecrawl batch scrape status for job ID: {job_id}")
         try:
-            client = self._get_client()
-            status = client.get_batch_scrape_status(job_id=job_id)
-            logger.info(
-                f"Successfully checked Firecrawl batch scrape status for job ID: {job_id}"
-            )
+            client = await self.get_firecrawl_client()
+            status = await client.get_batch_scrape_status(job_id=job_id)
+            logger.info(f"Successfully checked Firecrawl batch scrape status for job ID: {job_id}")
             return self._to_serializable(status)
         except NotAuthorizedError:
             raise
         except ToolError:
             raise
         except Exception as e:
-            return self._handle_firecrawl_exception(
-                e, f"checking batch scrape status for job ID {job_id}"
-            )
+            return self._handle_firecrawl_exception(e, f"checking batch scrape status for job ID {job_id}")
 
-    def quick_web_extract(
+    async def quick_web_extract(
         self,
         urls: list[str],
         prompt: str | None = None,
@@ -433,6 +407,35 @@ class FirecrawlApp(APIApplication):
         Returns:
             A dictionary containing the extracted data on success.
 
+        Examples:
+            Extraction with prompt:
+            >>> app.quick_web_extract(
+            ...     urls=["https://docs.firecrawl.dev"],
+            ...     prompt="Extract the page description"
+            ... )
+
+            Structured extraction with schema dictionary:
+            >>> schema = {
+            ...     "type": "object",
+            ...     "properties": {"description": {"type": "string"}},
+            ...     "required": ["description"],
+            ... }
+            >>> app.quick_web_extract(
+            ...     urls=["https://docs.firecrawl.dev"],
+            ...     schema=schema,
+            ...     prompt="Extract the page description"
+            ... )
+
+            Structured extraction with Pydantic model:
+            >>> from pydantic import BaseModel
+            >>> class PageInfo(BaseModel):
+            ...     description: str
+            >>> app.quick_web_extract(
+            ...     urls=["https://docs.firecrawl.dev"],
+            ...     schema=PageInfo.model_json_schema(),
+            ...     prompt="Extract the page description"
+            ... )
+
         Raises:
             NotAuthorizedError: If API key is missing or invalid.
             ToolError: If the Firecrawl SDK is not installed or extraction fails.
@@ -444,17 +447,11 @@ class FirecrawlApp(APIApplication):
             f"Attempting quick web extraction for {len(urls)} URLs with prompt: {prompt is not None}, schema: {schema is not None}."
         )
         try:
-            client = self._get_client()
-            response = client.extract(
-                urls=urls,
-                prompt=prompt,
-                schema=schema,
-                system_prompt=system_prompt,
-                allow_external_links=allow_external_links,
-            )
-            logger.info(
-                f"Successfully completed quick web extraction for {len(urls)} URLs."
+            client = await self.get_firecrawl_client()
+            response = await client.extract(
+                urls=urls, prompt=prompt, schema=schema, system_prompt=system_prompt, allow_external_links=allow_external_links
             )
+            logger.info(f"Successfully completed quick web extraction for {len(urls)} URLs.")
             return self._to_serializable(response)
         except NotAuthorizedError:
             logger.error("Firecrawl API key missing or invalid.")
@@ -463,18 +460,14 @@ class FirecrawlApp(APIApplication):
             logger.error("Firecrawl SDK not installed.")
             raise
         except Exception as e:
-            error_message = self._handle_firecrawl_exception(
-                e, f"quick web extraction for {len(urls)} URLs"
-            )
+            error_message = self._handle_firecrawl_exception(e, f"quick web extraction for {len(urls)} URLs")
             logger.error(f"Failed to perform quick web extraction: {error_message}")
             if error_message:
                 raise ToolError(error_message)
             else:
-                raise ToolError(
-                    f"Quick web extraction failed for {len(urls)} URLs: {e}"
-                )
+                raise ToolError(f"Quick web extraction failed for {len(urls)} URLs: {e}")
 
-    def check_extract_status(self, job_id: str) -> dict[str, Any] | str:
+    async def check_extract_status(self, job_id: str) -> dict[str, Any] | str:
         """
         Checks the status of an asynchronous, AI-powered Firecrawl data extraction job using its ID. Unlike `check_crawl_status` or `check_batch_scrape_status`, this function specifically monitors structured data extraction tasks, returning the job's progress or an error message on failure.
 
@@ -492,24 +485,52 @@ class FirecrawlApp(APIApplication):
         Tags:
             extract, ai, async_job, status
         """
-        logger.info(
-            f"Attempting to check Firecrawl extraction status for job ID: {job_id}"
-        )
+        logger.info(f"Attempting to check Firecrawl extraction status for job ID: {job_id}")
         try:
-            client = self._get_client()
-            status = client.get_extract_status(job_id=job_id)
-            logger.info(
-                f"Successfully checked Firecrawl extraction status for job ID: {job_id}"
-            )
+            client = await self.get_firecrawl_client()
+            status = await client.get_extract_status(job_id=job_id)
+            logger.info(f"Successfully checked Firecrawl extraction status for job ID: {job_id}")
             return self._to_serializable(status)
         except NotAuthorizedError:
             raise
         except ToolError:
             raise
         except Exception as e:
-            return self._handle_firecrawl_exception(
-                e, f"checking extraction status for job ID {job_id}"
-            )
+            return self._handle_firecrawl_exception(e, f"checking extraction status for job ID {job_id}")
+
+    async def map_site(self, url: str, limit: int | None = None) -> dict[str, Any] | str:
+        """
+        Maps a website to generate a list of all its URLs. This is useful for discovering content structure before crawling or scraping specific pages.
+
+        Args:
+            url: The starting URL to map.
+            limit: Optional limit on the number of URLs to return.
+
+        Returns:
+            A dictionary containing the list of URLs on success,
+            or a string containing an error message on failure.
+
+        Raises:
+            NotAuthorizedError: If API key is missing or invalid.
+            ToolError: If the Firecrawl SDK is not installed.
+
+        Tags:
+            map, discovery, links
+        """
+        logger.info(f"Attempting to map site: {url} with limit: {limit}")
+        try:
+            client = await self.get_firecrawl_client()
+            # client.map signature (async): (url, search=None, ignoreSitemap=None, includeSubdomains=None, limit=None)
+            # We expose url and limit for now, maybe more if needed later.
+            response = await client.map(url=url, limit=limit)
+            logger.info(f"Successfully mapped site: {url}")
+            return self._to_serializable(response)
+        except NotAuthorizedError:
+            raise
+        except ToolError:
+            raise
+        except Exception as e:
+            return self._handle_firecrawl_exception(e, f"mapping site {url}")
 
     def list_tools(self):
         return [
@@ -522,4 +543,5 @@ class FirecrawlApp(APIApplication):
             self.check_batch_scrape_status,
             self.quick_web_extract,
             self.check_extract_status,
+            self.map_site,
         ]