firecrawl-mcp 3.18.0 → 3.19.1

package/README.md

@@ -872,7 +872,75 @@ Check the status of an agent job and retrieve results when complete. Use this to
 - `completed`: Research finished - response includes the extracted data
 - `failed`: An error occurred
 
-### 11. Browser Create (`firecrawl_browser_create`) — Deprecated
+### 11. Monitor Tools (`firecrawl_monitor_*`)
+
+Create and manage recurring page monitors. Monitors run scheduled scrapes or crawls, diff each result against the last retained snapshot, and can notify by webhook or email.
+
+**Best for:**
+
+- Watching one page or a few pages over time
+- Alerting on meaningful changes using a plain-English goal
+- Tracking check history and page-level diffs
+
+**Recommended create pattern:**
+
+Use `page` or `pages` plus `goal`. The MCP server builds the monitor request with a 30-minute schedule and the API enables meaningful-change judging automatically.
+
+Meaningful-change judging runs automatically when `goal` is set. Page webhooks expose `isMeaningful` and `judgment` on `monitor.page` events.
+
+Write goals as concise 2-3 sentence monitor instructions. Say what should trigger an alert, preserve any scope the user gave, and include intent-specific exclusions only when obvious from the request. Generic noise such as whitespace, formatting-only changes, request IDs, tracking params, generic metadata, and unrelated page chrome is already handled by the judge, so do not repeat it in every goal. If the user is vague, keep the goal broad; if they ask for broad monitoring or "any change", preserve that. If the user says they do not care about something, include that explicitly.
+
+```json
+{
+  "name": "firecrawl_monitor_create",
+  "arguments": {
+    "page": "https://example.com/pricing",
+    "goal": "Alert when pricing, packaging, or launch messaging changes."
+  }
+}
+```
+
+**Multiple pages with webhooks:**
+
+```json
+{
+  "name": "firecrawl_monitor_create",
+  "arguments": {
+    "pages": ["https://example.com/pricing", "https://example.com/changelog"],
+    "goal": "Alert when pricing, packaging, or launch messaging changes.",
+    "webhookUrl": "https://example.com/webhooks/firecrawl"
+  }
+}
+```
+
+**Advanced create requests:**
+
+Pass `body` when you need crawl targets, JSON change tracking, custom retention, or explicit `judgeEnabled` control.
+
+```json
+{
+  "name": "firecrawl_monitor_create",
+  "arguments": {
+    "body": {
+      "name": "Docs monitor",
+      "schedule": { "text": "hourly", "timezone": "UTC" },
+      "goal": "Alert when docs pages add, remove, or materially change API behavior.",
+      "targets": [{ "type": "crawl", "url": "https://example.com/docs" }]
+    }
+  }
+}
+```
+
+**Other monitor tools:**
+
+- `firecrawl_monitor_list`: list monitors.
+- `firecrawl_monitor_get`: get one monitor.
+- `firecrawl_monitor_update`: update fields including `goal`, `judgeEnabled`, `webhook`, and `notification`.
+- `firecrawl_monitor_run`: trigger a check now.
+- `firecrawl_monitor_checks`: list checks, optionally filtered by status.
+- `firecrawl_monitor_check`: get page-level results, including `diff`, `snapshot`, `judgment.meaningful`, and `judgment.meaningfulChanges`.
+
+### 12. Browser Create (`firecrawl_browser_create`) — Deprecated
 
 > **Deprecated:** Prefer `firecrawl_scrape` + `firecrawl_interact` instead. Interact lets you scrape a page and then click, fill forms, and navigate without managing sessions manually.
 
@@ -903,7 +971,7 @@ Create a cloud browser session for interactive automation.
 
 - Session ID, CDP URL, and live view URL
 
-### 12. Browser Execute (`firecrawl_browser_execute`) — Deprecated
+### 13. Browser Execute (`firecrawl_browser_execute`) — Deprecated
 
 > **Deprecated:** Prefer `firecrawl_scrape` + `firecrawl_interact` instead.
 
@@ -947,7 +1015,7 @@ Execute code in a browser session. Supports agent-browser commands (bash), Pytho
 }
 ```
 
-### 13. Browser List (`firecrawl_browser_list`) — Deprecated
+### 14. Browser List (`firecrawl_browser_list`) — Deprecated
 
 > **Deprecated:** Prefer `firecrawl_scrape` + `firecrawl_interact` instead.
 
@@ -962,7 +1030,7 @@ List browser sessions, optionally filtered by status.
 }
 ```
 
-### 14. Browser Delete (`firecrawl_browser_delete`) — Deprecated
+### 15. Browser Delete (`firecrawl_browser_delete`) — Deprecated
 
 > **Deprecated:** Prefer `firecrawl_scrape` + `firecrawl_interact` instead.
 

package/dist/monitor.js

@@ -53,6 +53,67 @@ function asText(data) {
     return JSON.stringify(data, null, 2);
 }
 const pageStatusSchema = z.enum(['same', 'new', 'changed', 'removed', 'error']);
+const checkStatusSchema = z.enum([
+    'queued',
+    'running',
+    'completed',
+    'failed',
+    'partial',
+    'skipped_overlap',
+]);
+function splitPages(page, pages) {
+    return [page, ...(pages ?? [])]
+        .filter((url) => typeof url === 'string')
+        .map(url => url.trim())
+        .filter(Boolean);
+}
+function buildMonitorCreateBody(args) {
+    if (args.body && typeof args.body === 'object' && !Array.isArray(args.body)) {
+        return args.body;
+    }
+    const urls = splitPages(args.page, args.pages);
+    if (urls.length === 0) {
+        throw new Error('firecrawl_monitor_create requires either `body`, `page`, or `pages`.');
+    }
+    const goal = typeof args.goal === 'string' ? args.goal.trim() : '';
+    if (!goal) {
+        throw new Error('firecrawl_monitor_create shorthand requires `goal`. Use `body` for advanced requests without a goal.');
+    }
+    const webhookUrl = typeof args.webhookUrl === 'string' ? args.webhookUrl.trim() : '';
+    const email = typeof args.email === 'string' && args.email.trim()
+        ? {
+            email: {
+                enabled: true,
+                recipients: [args.email.trim()],
+                includeDiffs: Boolean(args.includeDiffs),
+            },
+        }
+        : undefined;
+    return {
+        name: typeof args.name === 'string' && args.name.trim()
+            ? args.name.trim()
+            : `Monitor ${urls[0]}`,
+        schedule: {
+            text: typeof args.scheduleText === 'string' && args.scheduleText.trim()
+                ? args.scheduleText.trim()
+                : 'every 30 minutes',
+            timezone: typeof args.timezone === 'string' && args.timezone.trim()
+                ? args.timezone.trim()
+                : 'UTC',
+        },
+        goal,
+        targets: [{ type: 'scrape', urls }],
+        ...(email ? { notification: email } : {}),
+        ...(webhookUrl
+            ? {
+                webhook: {
+                    url: webhookUrl,
+                    events: ['monitor.page', 'monitor.check.completed'],
+                },
+            }
+            : {}),
+    };
+}
 export function registerMonitorTools(server) {
     server.addTool({
         name: 'firecrawl_monitor_create',
@@ -64,7 +125,27 @@ export function registerMonitorTools(server) {
         description: `
 Create a Firecrawl monitor — a recurring scrape or crawl that diffs each result against the last retained snapshot.
 
-Pass the full request body. Required fields: \`name\`, \`schedule\` (with \`cron\` or \`text\`), and \`targets\` (one or more \`{ type: 'scrape', urls: [...] }\` or \`{ type: 'crawl', url: '...' }\`). Optional: \`webhook\`, \`notification\`, \`retentionDays\`.
+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.
+
+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.
+- \`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\`.
+
+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.
+- Generic noise such as whitespace, formatting-only changes, request IDs, tracking params, generic metadata, and unrelated page chrome is already handled by the judge; do not repeat it in every goal.
+- If the user is vague, keep the goal broad rather than guessing exclusions. If the user asks for broad monitoring or "any change", preserve that and do not add exclusions that hide changes.
+- 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\`.
 
 **Markdown-mode (default):** Each check produces a unified text diff of the page's markdown. No extra configuration needed.
 
@@ -72,12 +153,22 @@ Pass the full request body. Required fields: \`name\`, \`schedule\` (with \`cron
 {
   "name": "firecrawl_monitor_create",
   "arguments": {
-    "body": {
-      "name": "Blog watch",
-      "schedule": { "text": "every 30 minutes", "timezone": "UTC" },
-      "targets": [{ "type": "scrape", "urls": ["https://example.com/blog"] }],
-      "notification": { "email": { "enabled": true, "recipients": ["a@b.com"] } }
-    }
+    "page": "https://example.com/blog",
+    "goal": "Alert when a new blog post is published or an existing headline changes.",
+    "email": "alerts@example.com"
+  }
+}
+\`\`\`
+
+**Multiple pages:**
+
+\`\`\`json
+{
+  "name": "firecrawl_monitor_create",
+  "arguments": {
+    "pages": ["https://example.com/pricing", "https://example.com/changelog"],
+    "goal": "Alert when pricing, packaging, or launch messaging changes.",
+    "webhookUrl": "https://example.com/webhooks/firecrawl"
   }
 }
 \`\`\`
@@ -91,6 +182,7 @@ Pass the full request body. Required fields: \`name\`, \`schedule\` (with \`cron
     "body": {
       "name": "Pricing watch",
       "schedule": { "text": "hourly", "timezone": "UTC" },
+      "goal": "Alert when a pricing tier, price, billing period, limit, or headline feature changes. Ignore unrelated marketing copy unless it changes the pricing offer.",
       "targets": [{
         "type": "scrape",
         "urls": ["https://example.com/pricing"],
@@ -126,10 +218,19 @@ Pass the full request body. Required fields: \`name\`, \`schedule\` (with \`cron
 **Mixed mode (JSON + git-diff):** Use \`modes: ["json", "git-diff"]\` to get both per-field diffs and a markdown sidecar. The page is marked \`changed\` whenever either surface changed.
 `,
         parameters: z.object({
-            body: z.record(z.string(), z.any()),
+            body: z.record(z.string(), z.any()).optional(),
+            page: z.string().optional(),
+            pages: z.array(z.string()).optional(),
+            goal: z.string().optional(),
+            name: z.string().optional(),
+            scheduleText: z.string().optional(),
+            timezone: z.string().optional(),
+            email: z.string().optional(),
+            includeDiffs: z.boolean().optional(),
+            webhookUrl: z.string().optional(),
         }),
         execute: async (args, { session, log }) => {
-            const { body } = args;
+            const body = buildMonitorCreateBody(args);
             log.info('Creating monitor', { name: body.name });
             const res = await monitorRequest(session, '/monitor', {
                 method: 'POST',
@@ -195,7 +296,7 @@ Get a single monitor by ID.
             openWorldHint: true,
         },
         description: `
-Update a monitor. Pass any subset of fields to patch: \`name\`, \`status\` ("active" | "paused"), \`schedule\`, \`targets\`, \`webhook\`, \`notification\`, \`retentionDays\`.
+Update a monitor. Pass any subset of fields to patch: \`name\`, \`status\` ("active" | "paused"), \`schedule\`, \`targets\`, \`goal\`, \`judgeEnabled\`, \`webhook\`, \`notification\`, \`retentionDays\`.
 
 **Usage Example:**
 \`\`\`json
@@ -276,17 +377,18 @@ List historical checks for a monitor.
 
 **Usage Example:**
 \`\`\`json
-{ "name": "firecrawl_monitor_checks", "arguments": { "id": "mon_abc123", "limit": 10 } }
+{ "name": "firecrawl_monitor_checks", "arguments": { "id": "mon_abc123", "limit": 10, "status": "completed" } }
 \`\`\`
 `,
         parameters: z.object({
             id: z.string(),
             limit: z.number().int().positive().optional(),
             offset: z.number().int().nonnegative().optional(),
+            status: checkStatusSchema.optional(),
         }),
         execute: async (args, { session }) => {
-            const { id, limit, offset } = args;
-            const res = await monitorRequest(session, `/monitor/${encodeURIComponent(id)}/checks`, { query: { limit, offset } });
+            const { id, limit, offset, status } = args;
+            const res = await monitorRequest(session, `/monitor/${encodeURIComponent(id)}/checks`, { query: { limit, offset, status } });
             return asText(res);
         },
     });
@@ -300,7 +402,7 @@ List historical checks for a monitor.
         description: `
 Get a single check with page-level diff results. Filter \`pageStatus\` to surface only the pages that changed (or were new, removed, etc.).
 
-Each entry in \`data.pages[]\` has \`url\`, \`status\` (\`same\` | \`new\` | \`changed\` | \`removed\` | \`error\`), and — when changed — a \`diff\` and possibly a \`snapshot\`. The shape of \`diff\` depends on the monitor's \`formats\` configuration:
+Each entry in \`data.pages[]\` has \`url\`, \`status\` (\`same\` | \`new\` | \`changed\` | \`removed\` | \`error\`), optional \`judgment\` when goal-based judging ran, and — when changed — a \`diff\` and possibly a \`snapshot\`. The shape of \`diff\` depends on the monitor's \`formats\` configuration:
 
 - **Markdown mode (default).** \`diff.text\` is the unified markdown diff; \`diff.json\` is a parse-diff AST (\`{ files: [...] }\`). No \`snapshot\`.
 - **JSON mode** (\`changeTracking\` with \`modes: ["json"]\`). \`diff.json\` is a per-field map keyed by JSON path into the extraction, e.g. \`plans[0].price\`, with each value being \`{ previous, current }\`. \`snapshot.json\` is the full current extraction. No \`diff.text\`.
@@ -318,12 +420,27 @@ Each entry in \`data.pages[]\` has \`url\`, \`status\` (\`same\` | \`new\` | \`c
       "plans[1].features[2]": { "previous": "10 GB storage", "current": "25 GB storage" }
     }
   },
-  "snapshot": { "json": { "plans": [/* current full extraction matching the monitor's schema */] } }
+  "snapshot": { "json": { "plans": [/* current full extraction matching the monitor's schema */] } },
+  "judgment": {
+    "meaningful": true,
+    "confidence": "high",
+    "reason": "The pricing changed, which matches the monitor goal.",
+    "meaningfulChanges": [
+      {
+        "type": "changed",
+        "before": "$19/mo",
+        "after": "$24/mo",
+        "reason": "The tracked plan price changed."
+      }
+    ]
+  }
 }
 \`\`\`
 
 When summarizing a check for the user, prefer \`diff.json\` paths (e.g. "plans[0].price changed from $19/mo to $24/mo") over re-printing the markdown diff — it's more concise and grounded in the schema fields they asked for.
 
+When \`judgment\` is present, use it to decide what to surface. \`judgment.meaningful: false\` means the change was classified as noise for the monitor's goal. When \`judgment.meaningfulChanges\` is present, prefer those goal-relevant changes over raw diff hunks; each item includes \`type\`, \`before\`, \`after\`, and \`reason\`.
+
 The endpoint paginates via a top-level \`next\` URL; this tool returns one page at a time. Increase \`limit\` (max 100) to fetch fewer pages.
 
 **Usage Example:**

package/package.json

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