Merge pull request #290 from firecrawl/search-monitor

feat(monitor): add search-target support to firecrawl_monitor_create

Author: developersdigest

package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl-mcp",
-  "version": "3.22.0",
+  "version": "3.22.1",
   "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",

server.json

@@ -12,7 +12,7 @@
     {
       "registryType": "npm",
       "identifier": "firecrawl-mcp",
-      "version": "3.20.2",
+      "version": "3.22.1",
       "transport": {
         "type": "stdio"
       },

src/monitor.ts

@@ -111,9 +111,17 @@ function buildMonitorCreateBody(
     args.page as string | undefined,
     args.pages as string[] | undefined
   );
-  if (urls.length === 0) {
+  const queries = Array.isArray(args.queries)
+    ? (args.queries as unknown[])
+        .filter((q): q is string => typeof q === 'string')
+        .map((q) => q.trim())
+        .filter(Boolean)
+    : [];
+  const isSearch = queries.length > 0;
+
+  if (urls.length === 0 && !isSearch) {
     throw new Error(
-      'firecrawl_monitor_create requires either `body`, `page`, or `pages`.'
+      'firecrawl_monitor_create requires either `body`, `page`/`pages`, or `queries`.'
     );
   }
 
@@ -124,6 +132,35 @@ function buildMonitorCreateBody(
     );
   }
 
+  // Build the target: search when `queries` are given, otherwise a scrape.
+  let target: Record<string, unknown>;
+  if (isSearch) {
+    const includeDomains = Array.isArray(args.includeDomains)
+      ? (args.includeDomains as unknown[]).filter(
+          (d): d is string => typeof d === 'string'
+        )
+      : undefined;
+    const excludeDomains = Array.isArray(args.excludeDomains)
+      ? (args.excludeDomains as unknown[]).filter(
+          (d): d is string => typeof d === 'string'
+        )
+      : undefined;
+    target = {
+      type: 'search',
+      queries,
+      ...(typeof args.searchWindow === 'string' && args.searchWindow.trim()
+        ? { searchWindow: args.searchWindow.trim() }
+        : {}),
+      ...(typeof args.maxResults === 'number'
+        ? { maxResults: args.maxResults }
+        : {}),
+      ...(includeDomains && includeDomains.length > 0 ? { includeDomains } : {}),
+      ...(excludeDomains && excludeDomains.length > 0 ? { excludeDomains } : {}),
+    };
+  } else {
+    target = { type: 'scrape', urls };
+  }
+
   const webhookUrl =
     typeof args.webhookUrl === 'string' ? args.webhookUrl.trim() : '';
   const email =
@@ -141,7 +178,9 @@ function buildMonitorCreateBody(
     name:
       typeof args.name === 'string' && args.name.trim()
         ? args.name.trim()
-        : `Monitor ${urls[0]}`,
+        : isSearch
+          ? `Monitor ${queries[0]}`
+          : `Monitor ${urls[0]}`,
     schedule: {
       text:
         typeof args.scheduleText === 'string' && args.scheduleText.trim()
@@ -153,7 +192,7 @@ function buildMonitorCreateBody(
           : 'UTC',
     },
     goal,
-    targets: [{ type: 'scrape', urls }],
+    targets: [target],
     ...(email ? { notification: email } : {}),
     ...(webhookUrl
       ? {
@@ -176,20 +215,38 @@ export function registerMonitorTools(server: FastMCP<SessionData>): void {
       destructiveHint: false, // Additive; creates a new monitor without deleting existing monitors or external content.
     },
     description: `
-Create a Firecrawl monitor — a recurring scrape or crawl that diffs each result against the last retained snapshot.
+Create a Firecrawl monitor — a recurring scrape, crawl, or search that diffs each result against the last retained snapshot.
 
-Prefer the simple path: pass \`page\` or \`pages\` plus \`goal\`. The tool will create a scrape monitor with a 30-minute schedule and meaningful-change judging enabled by the API. Use \`body\` only for advanced requests such as crawl targets, JSON change tracking, custom retention, or manual \`judgeEnabled\` control.
+Prefer the simple path: pass \`page\` or \`pages\` plus \`goal\` to monitor specific URLs, OR pass \`queries\` plus \`goal\` to monitor web search results for new/changed hits. The tool will create the monitor with a 30-minute schedule and meaningful-change judging enabled by the API. Use \`body\` only for advanced requests such as crawl targets, JSON change tracking, custom retention, or manual \`judgeEnabled\` control.
 
 Meaningful-change judge: set \`goal\` to a plain-language description of what the user actually cares about. \`judgeEnabled\` defaults to true when \`goal\` is set, so providing \`goal\` is enough. Page webhooks expose \`isMeaningful\` and \`judgment\` on \`monitor.page\` events.
 
 Simple fields:
 - \`page\`: one page URL to monitor.
 - \`pages\`: multiple page URLs to monitor.
-- \`goal\`: plain-English instruction for what changes matter. Required for the simple path.
+- \`queries\`: one or more search queries (1-12) to monitor instead of fixed URLs. Each check runs the searches and diffs the result set, so you get alerted when new or changed results appear. Mutually exclusive with \`page\`/\`pages\` in the simple path.
+- \`searchWindow\`: optional recency window for search targets — one of \`5m\`, \`15m\`, \`1h\`, \`6h\`, \`24h\`, \`7d\` (default \`24h\`).
+- \`maxResults\`: optional max results per search, 1-50 (default 10).
+- \`includeDomains\` / \`excludeDomains\`: optional domain allow/deny lists for search targets.
+- \`goal\`: plain-English instruction for what changes matter. Required for the simple path (and always required when \`queries\` are set — web monitors must have a goal).
 - \`scheduleText\`: optional natural-language schedule, default \`every 30 minutes\`.
 - \`email\`: optional email recipient for summaries.
 - \`webhookUrl\`: optional webhook URL. Configures \`monitor.page\` and \`monitor.check.completed\`.
 
+**Search-mode example:**
+
+\`\`\`json
+{
+  "name": "firecrawl_monitor_create",
+  "arguments": {
+    "queries": ["new LLM release", "frontier model launch"],
+    "goal": "Notify me about major new LLM model releases.",
+    "searchWindow": "24h",
+    "maxResults": 10
+  }
+}
+\`\`\`
+
 Goal guidance:
 - Expand the user's one-line monitoring intent into a concise 2-3 sentence monitor goal.
 - State what should trigger an alert, restate any scope the user gave, and include intent-specific exclusions only when obvious from the user's request.
@@ -198,7 +255,7 @@ Goal guidance:
 - If the user says they do not care about something, include that explicitly. It is okay to ask whether they want to ignore specific noise when it is likely to matter.
 - Do not invent page-specific sections, thresholds, entities, or business rules unless the user mentioned them.
 
-Full \`body\` requests require: \`name\`, \`schedule\` (with \`cron\` or \`text\`), and \`targets\` (one or more \`{ type: 'scrape', urls: [...] }\` or \`{ type: 'crawl', url: '...' }\`). Optional: \`goal\`, \`judgeEnabled\`, \`webhook\`, \`notification\`, \`retentionDays\`.
+Full \`body\` requests require: \`name\`, \`schedule\` (with \`cron\` or \`text\`), and \`targets\` (one or more \`{ type: 'scrape', urls: [...] }\`, \`{ type: 'crawl', url: '...' }\`, or \`{ type: 'search', queries: [...], searchWindow?, maxResults?, includeDomains?, excludeDomains? }\`). Optional: \`goal\` (required when any search target is present), \`judgeEnabled\`, \`webhook\`, \`notification\`, \`retentionDays\`.
 
 **Markdown-mode (default):** Each check produces a unified text diff of the page's markdown. No extra configuration needed.
 
@@ -274,6 +331,11 @@ Full \`body\` requests require: \`name\`, \`schedule\` (with \`cron\` or \`text\
       body: z.record(z.string(), z.any()).optional(),
       page: z.string().optional(),
       pages: z.array(z.string()).optional(),
+      queries: z.array(z.string()).optional(),
+      searchWindow: z.enum(['5m', '15m', '1h', '6h', '24h', '7d']).optional(),
+      maxResults: z.number().int().min(1).max(50).optional(),
+      includeDomains: z.array(z.string()).optional(),
+      excludeDomains: z.array(z.string()).optional(),
       goal: z.string().optional(),
       name: z.string().optional(),
       scheduleText: z.string().optional(),