firecrawl-mcp 3.21.4 → 3.22.0

package/README.md

@@ -26,6 +26,24 @@ A Model Context Protocol (MCP) server that brings [Firecrawl](https://github.com
 
 ## Installation
 
+### Hosted MCP (keyless free tier)
+
+Connect to the remote hosted server with no setup:
+
+```
+https://mcp.firecrawl.dev/v2/mcp
+```
+
+On the keyless free tier, `scrape`, `search`, and `interact` work without an API key (rate-limited). Other tools such as `crawl`, `map`, `agent`, and `extract` still need a key.
+
+Prefer an API key or OAuth whenever the human can sign up. It unlocks the full tool set and higher limits. With a key, use:
+
+```
+https://mcp.firecrawl.dev/{FIRECRAWL_API_KEY}/v2/mcp
+```
+
+See the [MCP server docs](https://docs.firecrawl.dev/mcp-server) and the [agent onboarding guide](https://www.firecrawl.dev/agent-onboarding/SKILL.md) for setup details.
+
 ### Running with npx
 
 ```bash
@@ -326,14 +344,14 @@ Use this guide to select the right tool for your task:
 - **If you want to search the web for info:** use **search**
 - **If you need complex research across multiple unknown sources:** use **agent**
 - **If you want to analyze a whole site or section:** use **crawl** (with limits!)
-- **If you need interactive browser automation** (click, type, navigate): use **scrape** + **interact**
+- **If you need interactive browser automation** (click, type, navigate): use **interact** with a URL for a fresh page, or **scrape** + **interact** when you already scraped the page or need tighter scrape control
 
 ### Quick Reference Table
 
 | Tool         | Best for                                       | Returns                        |
 | ------------ | ---------------------------------------------- | ------------------------------ |
 | scrape       | Single page content                            | JSON (preferred) or markdown   |
-| interact     | Interact with a scraped page                   | Execution result               |
+| interact     | Interact with a URL or scraped page            | Execution result + scrapeId for URL mode |
 | batch_scrape | Multiple known URLs                            | JSON (preferred) or markdown[] |
 | map          | Discovering URLs on a site                     | URL[]                          |
 | crawl        | Multi-page extraction (with limits)            | markdown/html[]                |

package/dist/index.js

@@ -3846,24 +3846,28 @@ server.addTool({
     // Transient page interactions only; does not delete monitors, jobs, or external sites.
   },
   description: `
-Interact with a previously scraped page in a live browser session. Scrape a page first with firecrawl_scrape, then use the returned scrapeId to click buttons, fill forms, extract dynamic content, or navigate deeper.
+Interact with a page in a live browser session: click buttons, fill forms, extract dynamic content, or navigate deeper.
 
 **Best for:** Multi-step workflows on a single page \u2014 searching a site, clicking through results, filling forms, extracting data that requires interaction.
-**Requires:** A scrapeId from a previous firecrawl_scrape call (found in the metadata of the scrape response).
+**Two ways to target a page:**
+- Pass a \`url\` to interact directly. The session is opened for you in one call (use this for a fresh page).
+- Pass a \`scrapeId\` from a previous firecrawl_scrape to reuse that already-loaded page (cheaper when you just scraped it).
 
 **Arguments:**
-- scrapeId: The scrape job ID from a previous scrape (required)
+- url: Page to interact with; opens a session for you (use this OR scrapeId)
+- scrapeId: Scrape job ID from a previous scrape, found in its metadata (use this OR url)
 - prompt: Natural language instruction describing the action to take (use this OR code)
 - code: Code to execute in the browser session (use this OR prompt)
 - language: "bash", "python", or "node" (optional, defaults to "node", only used with code)
-- timeout: Execution timeout in seconds, 1-300 (optional, defaults to 30)
+- timeout: Interact execution timeout in seconds, 1-300 (optional, defaults to 30)
+- scrapeOptions: Optional scrape controls used only with url mode, such as waitFor, maxAge, proxy, or zeroDataRetention
 
-**Usage Example (prompt):**
+**Usage Example (prompt, direct via url):**
 \`\`\`json
 {
   "name": "firecrawl_interact",
   "arguments": {
-    "scrapeId": "scrape-id-from-previous-scrape",
+    "url": "https://example.com/products",
     "prompt": "Click on the first product and tell me its price"
   }
 }
@@ -3883,24 +3887,71 @@ Interact with a previously scraped page in a live browser session. Scrape a page
 **Returns:** Execution result including output, stdout, stderr, exit code, and live view URLs.
 `,
   parameters: z4.object({
-    scrapeId: z4.string(),
-    prompt: z4.string().optional(),
-    code: z4.string().optional(),
+    scrapeId: z4.string().trim().min(1).optional(),
+    url: z4.string().trim().url().optional(),
+    prompt: z4.string().trim().min(1).optional(),
+    code: z4.string().trim().min(1).optional(),
     language: z4.enum(["bash", "python", "node"]).optional(),
-    timeout: z4.number().min(1).max(300).optional()
+    timeout: z4.number().min(1).max(300).optional(),
+    scrapeOptions: scrapeParamsSchema.omit({ url: true }).partial().optional()
+  }).refine((data) => Boolean(data.scrapeId) !== Boolean(data.url), {
+    message: "Provide either 'url' (interact directly) or 'scrapeId' (reuse a previous scrape), not both."
+  }).refine((data) => !data.scrapeOptions || Boolean(data.url), {
+    message: "scrapeOptions can only be used with 'url' mode."
   }).refine((data) => data.code || data.prompt, {
     message: "Either 'code' or 'prompt' must be provided."
   }),
   execute: async (args2, { session, log }) => {
     const client = getClient(session);
-    const { scrapeId, prompt, code, language, timeout } = args2;
-    log.info("Interacting with scraped page", { scrapeId });
+    const {
+      scrapeId: providedScrapeId,
+      url,
+      prompt,
+      code,
+      language,
+      timeout,
+      scrapeOptions
+    } = args2;
+    let scrapeId = providedScrapeId;
+    const openedFromUrl = !scrapeId;
+    if (openedFromUrl) {
+      log.info("Opening interact session from url", { url });
+      const cleanedScrapeOptions = removeEmptyTopLevel(scrapeOptions ?? {});
+      const scraped = await client.scrape(String(url), {
+        ...cleanedScrapeOptions,
+        origin: ORIGIN
+      });
+      scrapeId = scraped?.metadata?.scrapeId;
+      if (!scrapeId) {
+        return asText2({
+          error: "Could not open an interact session: the scrape did not return a scrapeId. Try firecrawl_scrape first, then pass its scrapeId.",
+          url
+        });
+      }
+    }
+    if (!scrapeId) {
+      return asText2({
+        error: "Could not open an interact session: missing scrapeId.",
+        url
+      });
+    }
+    const activeScrapeId = scrapeId;
+    log.info("Interacting with page", { scrapeId: activeScrapeId });
     const interactArgs = { origin: ORIGIN };
     if (prompt) interactArgs.prompt = prompt;
     if (code) interactArgs.code = code;
     if (language) interactArgs.language = language;
     if (timeout != null) interactArgs.timeout = timeout;
-    const res = await client.interact(scrapeId, interactArgs);
+    const res = await client.interact(activeScrapeId, interactArgs);
+    if (openedFromUrl && res && typeof res === "object" && !Array.isArray(res)) {
+      return asText2({
+        ...res,
+        scrapeId: activeScrapeId
+      });
+    }
+    if (openedFromUrl) {
+      return asText2({ scrapeId: activeScrapeId, result: res });
+    }
     return asText2(res);
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl-mcp",
-  "version": "3.21.4",
+  "version": "3.22.0",
   "description": "MCP server for Firecrawl — search, scrape, and interact with the web. Supports both cloud and self-hosted instances. Features include web search, scraping, page interaction, batch processing, and LLM-powered content analysis.",
   "type": "module",
   "mcpName": "io.github.firecrawl/firecrawl-mcp-server",