Merge pull request #291 from hmishra2250/feat/interact-standalone-url

feat(interact): allow firecrawl_interact to open a session from a url

Author: Max17190

README.md

@@ -344,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.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",

src/index.ts

@@ -2192,24 +2192,28 @@ server.addTool({
     destructiveHint: false, // 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 — 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"
   }
 }
@@ -2230,31 +2234,86 @@ Interact with a previously scraped page in a live browser session. Scrape a page
 `,
   parameters: z
     .object({
-      scrapeId: z.string(),
-      prompt: z.string().optional(),
-      code: z.string().optional(),
+      scrapeId: z.string().trim().min(1).optional(),
+      url: z.string().trim().url().optional(),
+      prompt: z.string().trim().min(1).optional(),
+      code: z.string().trim().min(1).optional(),
       language: z.enum(['bash', 'python', 'node']).optional(),
       timeout: z.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 (args: unknown, { session, log }): Promise<string> => {
     const client = getClient(session);
-    const { scrapeId, prompt, code, language, timeout } = args as {
-      scrapeId: string;
+    const {
+      scrapeId: providedScrapeId,
+      url,
+      prompt,
+      code,
+      language,
+      timeout,
+      scrapeOptions,
+    } = args as {
+      scrapeId?: string;
+      url?: string;
       prompt?: string;
       code?: string;
       language?: 'bash' | 'python' | 'node';
       timeout?: number;
+      scrapeOptions?: Record<string, unknown>;
     };
-    log.info('Interacting with scraped page', { scrapeId });
+    // No scrapeId means the caller passed a url: scrape it first to open the
+    // session, then interact. One tool call instead of scrape + interact.
+    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,
+      } as any);
+      scrapeId = (scraped as any)?.metadata?.scrapeId;
+      if (!scrapeId) {
+        return asText({
+          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 asText({
+        error: 'Could not open an interact session: missing scrapeId.',
+        url,
+      });
+    }
+    const activeScrapeId = scrapeId;
+    log.info('Interacting with page', { scrapeId: activeScrapeId });
     const interactArgs: Record<string, unknown> = { 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 as any);
+    const res = await client.interact(activeScrapeId, interactArgs as any);
+    if (openedFromUrl && res && typeof res === 'object' && !Array.isArray(res)) {
+      return asText({
+        ...(res as unknown as Record<string, unknown>),
+        scrapeId: activeScrapeId,
+      });
+    }
+    if (openedFromUrl) {
+      return asText({ scrapeId: activeScrapeId, result: res });
+    }
     return asText(res);
   },
 });