firecrawl-mcp 3.15.0 → 3.17.0

package/README.md

@@ -8,7 +8,7 @@
 
 # Firecrawl MCP Server
 
-A Model Context Protocol (MCP) server implementation that integrates with [Firecrawl](https://github.com/firecrawl/firecrawl) for searching, scraping, and interacting with the web.
+A Model Context Protocol (MCP) server that brings [Firecrawl](https://github.com/firecrawl/firecrawl) to MCP-compatible AI agents — search, scrape, and interact with the live web for clean, agent-ready context.
 
 > Big thanks to [@vrknetha](https://github.com/vrknetha), [@knacklabs](https://www.knacklabs.ai) for the initial implementation!
 
@@ -565,12 +565,51 @@ Search the web and optionally extract content from search results.
 
 **Returns:**
 
-- Array of search results (with optional scraped content)
+- Array of search results (with optional scraped content), plus an `id` field. Pass that `id` to `firecrawl_search_feedback` after you've used the results to refund 1 credit (search costs 2) and improve search quality.
 
 **Prompt Example:**
 
 > "Find the latest research papers on AI published in 2023."
 
+### 5b. Search Feedback Tool (`firecrawl_search_feedback`)
+
+Sends structured feedback on a previous `firecrawl_search` result. The first feedback per search id refunds 1 credit and improves Firecrawl's search quality. Idempotent per search id.
+
+**Call this after every search you actually use** (or that didn't help). Bad/partial feedback with `missingContent` is just as valuable as good feedback.
+
+**Opt out:** set `FIRECRAWL_NO_SEARCH_FEEDBACK=1` (or `FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1`) in the environment when starting the MCP server. The `firecrawl_search_feedback` tool will not be registered, so agents can't call it. Team admins can also disable feedback server-side; in that case the tool is registered but always returns `feedbackErrorCode: "TEAM_OPTED_OUT"`.
+
+**Most important field:** `missingContent`. It's an array of specific pieces of content the agent expected to find but did not. One entry per missing topic — these aggregate across teams and tell us what to index next.
+
+**Daily refund cap (per team, per UTC day, default 100 credits).** Once a team's `creditsRefundedToday` reaches `dailyRefundCap`, further submissions still record feedback but no longer refund credits. The response sets `dailyCapReached: true`. Agents should stop calling this tool for the rest of the UTC day when they see that flag.
+
+**Usage Example:**
+
+```json
+{
+  "name": "firecrawl_search_feedback",
+  "arguments": {
+    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
+    "rating": "good",
+    "valuableSources": [
+      {
+        "url": "https://docs.firecrawl.dev/features/search",
+        "reason": "Most up-to-date description of /search."
+      }
+    ],
+    "missingContent": [
+      { "topic": "Pricing for the search endpoint", "description": "No pricing tier table for /search specifically." },
+      { "topic": "Per-team rate limits" }
+    ],
+    "querySuggestions": "Boost docs.firecrawl.dev for queries that mention 'firecrawl'"
+  }
+}
+```
+
+**Returns:**
+
+- `{ success, feedbackId, creditsRefunded, alreadySubmitted? }` JSON.
+
 ### 6. Crawl Tool (`firecrawl_crawl`)
 
 Starts an asynchronous crawl job on a website and extract content from all pages.

package/dist/index.js

@@ -5,6 +5,7 @@ import { z } from 'zod';
 import FirecrawlApp from '@mendable/firecrawl-js';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { registerMonitorTools } from './monitor.js';
 dotenv.config({ debug: false, quiet: true });
 function extractApiKey(headers) {
     const headerAuth = headers['authorization'];
@@ -530,6 +531,7 @@ The query also supports search operators, that you can use if needed to refine t
 **Domain filters:** Use includeDomains to restrict results to specific domains, or excludeDomains to remove domains. Do not use both in the same request. Domains must be hostnames only, without protocol or path.
 **Scrape Options:** Only use scrapeOptions when you think it is absolutely necessary. When you do so default to a lower limit to avoid timeouts, 5 or lower.
 **Optimal Workflow:** Search first using firecrawl_search without formats, then after fetching the results, use the scrape tool to get the content of the relevantpage(s) that you want to scrape
+**After the search:** Once you have processed the results (or decided they were not useful), call \`firecrawl_search_feedback\` with the \`id\` from this response. The first feedback per search refunds 1 credit and helps Firecrawl improve search quality.
 
 **Usage Example without formats (Preferred):**
 \`\`\`json
@@ -566,7 +568,7 @@ The query also supports search operators, that you can use if needed to refine t
   }
 }
 \`\`\`
-**Returns:** Array of search results (with optional scraped content).
+**Returns:** A JSON envelope of the form \`{ success, data: { web?, images?, news? }, id, creditsUsed }\`. Each result array contains the search results (with optional scraped content). Pass the top-level \`id\` to \`firecrawl_search_feedback\` after you've used the results.
 `,
     parameters: z
         .object({
@@ -601,13 +603,187 @@ The query also supports search operators, that you can use if needed to refine t
         const cleaned = removeEmptyTopLevel(searchOpts);
         const searchQuery = buildSearchQueryWithDomains(query, includeDomains, excludeDomains);
         log.info('Searching', { query: searchQuery });
-        const res = await client.search(searchQuery, {
+        // Call /v2/search through the SDK's HTTP layer (auth + retries) instead
+        // of `client.search()` so we preserve the full response envelope. The
+        // high-level `search()` helper strips `id` and `creditsUsed`, which
+        // breaks the `firecrawl_search_feedback` workflow that this server
+        // explicitly tells the LLM to use after every search.
+        const httpRes = await client.http.post('/v2/search', {
+            query: searchQuery,
             ...cleaned,
             origin: ORIGIN,
         });
-        return asText(res);
+        return asText(httpRes?.data ?? {});
     },
 });
+const DEFAULT_CLOUD_API_URL = 'https://api.firecrawl.dev';
+function resolveApiBaseUrl() {
+    return (process.env.FIRECRAWL_API_URL || DEFAULT_CLOUD_API_URL).replace(/\/$/, '');
+}
+const SEARCH_FEEDBACK_DISABLED = ['1', 'true', 'yes', 'on'].includes((process.env.FIRECRAWL_NO_SEARCH_FEEDBACK ||
+    process.env.FIRECRAWL_DISABLE_SEARCH_FEEDBACK ||
+    '')
+    .trim()
+    .toLowerCase());
+if (SEARCH_FEEDBACK_DISABLED) {
+    console.error('[firecrawl-mcp] Search feedback tool disabled by FIRECRAWL_NO_SEARCH_FEEDBACK; firecrawl_search_feedback will not be registered.');
+}
+if (!SEARCH_FEEDBACK_DISABLED) {
+    server.addTool({
+        name: 'firecrawl_search_feedback',
+        annotations: {
+            title: 'Send feedback on a search result',
+            readOnlyHint: false,
+            openWorldHint: true,
+        },
+        description: `
+Send structured feedback on a previous \`firecrawl_search\` result. **Call this immediately after a search where you used the results** so we can improve search quality and refund 1 credit (search costs 2).
+
+Pass the \`searchId\` returned by \`firecrawl_search\` (the \`id\` field on the response) and tell us:
+
+- **rating** — overall result quality: \`good\`, \`partial\`, or \`bad\`.
+- **valuableSources** — which result URLs were actually useful, and a short reason why.
+- **missingContent** — **the most important field.** An ARRAY of specific pieces of content you expected to find but didn't. One entry per missing piece, each with a short \`topic\` and an optional longer \`description\`. Examples: \`{"topic":"enterprise pricing","description":"no pricing tier table for the Enterprise plan was returned"}\`, \`{"topic":"API rate limits"}\`, \`{"topic":"comparison vs competitors"}\`. **Be specific** — these aggregate across teams and tell us what to index next. Do not pack multiple topics into one entry.
+- **querySuggestions** — how the query or response shape could be improved (e.g. "would have liked official docs first", "should boost github.com").
+
+**Substantive-feedback requirement** (zero-effort feedback is rejected with HTTP 400):
+- \`good\` — must include at least one \`valuableSources\` entry
+- \`partial\` — must include \`valuableSources\` or at least one \`missingContent\` entry
+- \`bad\` — must include at least one \`missingContent\` entry or \`querySuggestions\`
+
+**Time window:** Feedback must be submitted within ~2 minutes of the search. Beyond that, the call returns HTTP 409 with \`feedbackErrorCode: "FEEDBACK_WINDOW_EXPIRED"\` — do not retry, just move on. Same goes for any 4xx response: do not retry-loop.
+
+**Behaviors:**
+- Idempotent per \`searchId\`. Re-submitting for the same id returns \`alreadySubmitted: true\` with \`creditsRefunded: 0\`.
+- Refund only applies to billable searches; preview teams are blocked.
+- Failed searches cannot receive feedback (the search itself already returned an error you can act on).
+- **Daily refund cap (per team, per UTC day, default 100 credits).** Once a team's \`creditsRefundedToday\` reaches \`dailyRefundCap\`, the response returns \`dailyCapReached: true\` with \`creditsRefunded: 0\`. The feedback is still recorded for search-quality improvement — only the credit refund is gated. **Stop calling this tool for the rest of the UTC day** when you see \`dailyCapReached: true\`.
+
+**When to call:** Right after processing a search result. If the result didn't help, send rating \`bad\` with a clear \`missingContent\` — that is just as valuable as a \`good\` rating.
+
+**Usage Example (good rating with valuable sources + missing content):**
+\`\`\`json
+{
+  "name": "firecrawl_search_feedback",
+  "arguments": {
+    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
+    "rating": "good",
+    "valuableSources": [
+      { "url": "https://docs.firecrawl.dev/features/search", "reason": "Most up-to-date description of /search." }
+    ],
+    "missingContent": [
+      { "topic": "Pricing for the search endpoint", "description": "No pricing tier table for /search specifically." },
+      { "topic": "Rate limits", "description": "Per-team RPS for /search not documented." }
+    ],
+    "querySuggestions": "Boost docs.firecrawl.dev for queries that mention 'firecrawl'"
+  }
+}
+\`\`\`
+
+**Usage Example (bad rating, what was missing):**
+\`\`\`json
+{
+  "name": "firecrawl_search_feedback",
+  "arguments": {
+    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
+    "rating": "bad",
+    "missingContent": [
+      { "topic": "Recent benchmarks", "description": "All results were >12 months old." },
+      { "topic": "Comparison vs Algolia" }
+    ]
+  }
+}
+\`\`\`
+
+**Returns:** \`{ success, feedbackId, creditsRefunded, creditsRefundedToday, dailyRefundCap, dailyCapReached?, alreadySubmitted?, warning? }\` JSON.
+`,
+        parameters: z.object({
+            searchId: z
+                .string()
+                .uuid('searchId must be the UUID returned by firecrawl_search'),
+            rating: z.enum(['good', 'bad', 'partial']),
+            valuableSources: z
+                .array(z.object({
+                url: z.string().url(),
+                reason: z.string().max(1000).optional(),
+            }))
+                .max(50)
+                .optional(),
+            missingContent: z
+                .array(z.object({
+                topic: z
+                    .string()
+                    .min(1, 'topic must not be empty')
+                    .max(200, 'topic must be 200 characters or fewer'),
+                description: z.string().max(2000).optional(),
+            }))
+                .max(20)
+                .optional()
+                .describe('Array of specific pieces of content the agent expected to find but did not. ' +
+                'One entry per distinct topic. Each entry has a short `topic` and optional ' +
+                'longer `description`.'),
+            querySuggestions: z.string().max(2000).optional(),
+        }),
+        execute: async (args, { session, log }) => {
+            const { searchId, rating, valuableSources, missingContent, querySuggestions, } = args;
+            const apiBase = resolveApiBaseUrl();
+            const endpoint = `${apiBase}/v2/search/${encodeURIComponent(searchId)}/feedback`;
+            const body = {
+                rating,
+                origin: ORIGIN,
+            };
+            if (valuableSources && valuableSources.length > 0) {
+                body.valuableSources = valuableSources;
+            }
+            if (missingContent && missingContent.length > 0) {
+                body.missingContent = missingContent;
+            }
+            if (querySuggestions)
+                body.querySuggestions = querySuggestions;
+            const headers = {
+                'Content-Type': 'application/json',
+            };
+            const apiKey = session?.firecrawlApiKey;
+            if (apiKey) {
+                headers['Authorization'] = `Bearer ${apiKey}`;
+            }
+            else if (process.env.CLOUD_SERVICE === 'true') {
+                throw new Error('Unauthorized: missing API key for search feedback.');
+            }
+            log.info('Submitting search feedback', { searchId, rating });
+            const response = await fetch(endpoint, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+            });
+            const responseText = await response.text();
+            let parsed;
+            try {
+                parsed = JSON.parse(responseText);
+            }
+            catch {
+                parsed = { raw: responseText };
+            }
+            // 4xx is terminal; surface a structured payload (with retryable=false)
+            // so agents do not retry-loop on substantive-feedback rejections,
+            // expired windows, etc.
+            if (!response.ok) {
+                log.warn('Search feedback rejected', {
+                    status: response.status,
+                    feedbackErrorCode: parsed?.feedbackErrorCode,
+                });
+                return asText({
+                    success: false,
+                    status: response.status,
+                    feedbackErrorCode: parsed?.feedbackErrorCode,
+                    error: parsed?.error ?? `HTTP ${response.status}`,
+                    retryable: response.status >= 500,
+                });
+            }
+            return asText(parsed);
+        },
+    });
+}
 server.addTool({
     name: 'firecrawl_crawl',
     annotations: {
@@ -1445,4 +1621,5 @@ else {
         transportType: 'stdio',
     };
 }
+registerMonitorTools(server);
 await server.start(args);

package/dist/monitor.js

@@ -0,0 +1,354 @@
+/**
+ * Firecrawl Monitor tools.
+ *
+ * Monitors run recurring scrapes/crawls and diff each result against the last
+ * retained snapshot. The SDK exposes monitor methods, but its HttpClient
+ * injects a top-level `origin` field into every POST/PATCH body and
+ * /v2/monitor rejects that with "Unrecognized key in body". Until the SDK
+ * strips `origin` for monitor requests, we hit /v2/monitor directly via fetch
+ * — same pattern the CLI uses.
+ */
+import { z } from 'zod';
+const DEFAULT_API_URL = 'https://api.firecrawl.dev';
+function resolveAuth(session) {
+    const apiKey = session?.firecrawlApiKey ?? process.env.FIRECRAWL_API_KEY;
+    const baseUrl = (process.env.FIRECRAWL_API_URL ?? DEFAULT_API_URL).replace(/\/$/, '');
+    return { apiKey, baseUrl };
+}
+async function monitorRequest(session, path, init = {}) {
+    const { apiKey, baseUrl } = resolveAuth(session);
+    if (!apiKey && !process.env.FIRECRAWL_API_URL) {
+        throw new Error('Unauthorized: API key is required for monitor requests');
+    }
+    let url = `${baseUrl}/v2${path}`;
+    if (init.query) {
+        const qs = new URLSearchParams();
+        for (const [k, v] of Object.entries(init.query)) {
+            if (v !== undefined && v !== null && v !== '')
+                qs.set(k, String(v));
+        }
+        const s = qs.toString();
+        if (s)
+            url += `?${s}`;
+    }
+    const headers = { 'X-Origin': 'mcp' };
+    if (apiKey)
+        headers.Authorization = `Bearer ${apiKey}`;
+    if (init.body !== undefined)
+        headers['Content-Type'] = 'application/json';
+    const response = await fetch(url, {
+        method: init.method ?? 'GET',
+        headers,
+        body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+    });
+    const payload = (await response.json().catch(() => ({})));
+    if (!response.ok || payload?.success === false) {
+        const message = payload?.error ||
+            `HTTP ${response.status}: ${response.statusText || 'Request failed'}`;
+        throw new Error(message);
+    }
+    return payload;
+}
+function asText(data) {
+    return JSON.stringify(data, null, 2);
+}
+const pageStatusSchema = z.enum(['same', 'new', 'changed', 'removed', 'error']);
+export function registerMonitorTools(server) {
+    server.addTool({
+        name: 'firecrawl_monitor_create',
+        annotations: {
+            title: 'Create monitor',
+            readOnlyHint: false,
+            openWorldHint: true,
+        },
+        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\`.
+
+**Markdown-mode (default):** Each check produces a unified text diff of the page's markdown. No extra configuration needed.
+
+\`\`\`json
+{
+  "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"] } }
+    }
+  }
+}
+\`\`\`
+
+**JSON-mode change tracking:** To detect changes in **specific structured fields** (price, headline, in-stock flag, list items) instead of the whole page, add a \`changeTracking\` format with \`modes: ["json"]\` and a JSON schema to the target's \`scrapeOptions.formats\`. The check response will then carry a per-field diff (keyed by JSON path, e.g. \`plans[0].price\`) and a \`snapshot.json\` with the full current extraction. See \`firecrawl_monitor_check\` for the response shape.
+
+\`\`\`json
+{
+  "name": "firecrawl_monitor_create",
+  "arguments": {
+    "body": {
+      "name": "Pricing watch",
+      "schedule": { "text": "hourly", "timezone": "UTC" },
+      "targets": [{
+        "type": "scrape",
+        "urls": ["https://example.com/pricing"],
+        "scrapeOptions": {
+          "formats": [{
+            "type": "changeTracking",
+            "modes": ["json"],
+            "prompt": "Extract pricing tiers and headline features for each plan.",
+            "schema": {
+              "type": "object",
+              "properties": {
+                "plans": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "name":     { "type": "string" },
+                      "price":    { "type": "string" },
+                      "features": { "type": "array", "items": { "type": "string" } }
+                    }
+                  }
+                }
+              }
+            }
+          }]
+        }
+      }]
+    }
+  }
+}
+\`\`\`
+
+**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()),
+        }),
+        execute: async (args, { session, log }) => {
+            const { body } = args;
+            log.info('Creating monitor', { name: body.name });
+            const res = await monitorRequest(session, '/monitor', {
+                method: 'POST',
+                body,
+            });
+            return asText(res);
+        },
+    });
+    server.addTool({
+        name: 'firecrawl_monitor_list',
+        annotations: {
+            title: 'List monitors',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
+        description: `
+List all Firecrawl monitors for the authenticated account.
+
+**Usage Example:**
+\`\`\`json
+{ "name": "firecrawl_monitor_list", "arguments": { "limit": 20 } }
+\`\`\`
+`,
+        parameters: z.object({
+            limit: z.number().int().positive().optional(),
+            offset: z.number().int().nonnegative().optional(),
+        }),
+        execute: async (args, { session }) => {
+            const { limit, offset } = args;
+            const res = await monitorRequest(session, '/monitor', {
+                query: { limit, offset },
+            });
+            return asText(res);
+        },
+    });
+    server.addTool({
+        name: 'firecrawl_monitor_get',
+        annotations: {
+            title: 'Get monitor',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
+        description: `
+Get a single monitor by ID.
+
+**Usage Example:**
+\`\`\`json
+{ "name": "firecrawl_monitor_get", "arguments": { "id": "mon_abc123" } }
+\`\`\`
+`,
+        parameters: z.object({ id: z.string() }),
+        execute: async (args, { session }) => {
+            const { id } = args;
+            const res = await monitorRequest(session, `/monitor/${encodeURIComponent(id)}`);
+            return asText(res);
+        },
+    });
+    server.addTool({
+        name: 'firecrawl_monitor_update',
+        annotations: {
+            title: 'Update monitor',
+            readOnlyHint: false,
+            openWorldHint: true,
+        },
+        description: `
+Update a monitor. Pass any subset of fields to patch: \`name\`, \`status\` ("active" | "paused"), \`schedule\`, \`targets\`, \`webhook\`, \`notification\`, \`retentionDays\`.
+
+**Usage Example:**
+\`\`\`json
+{
+  "name": "firecrawl_monitor_update",
+  "arguments": {
+    "id": "mon_abc123",
+    "body": { "status": "paused" }
+  }
+}
+\`\`\`
+`,
+        parameters: z.object({
+            id: z.string(),
+            body: z.record(z.string(), z.any()),
+        }),
+        execute: async (args, { session }) => {
+            const { id, body } = args;
+            const res = await monitorRequest(session, `/monitor/${encodeURIComponent(id)}`, { method: 'PATCH', body });
+            return asText(res);
+        },
+    });
+    server.addTool({
+        name: 'firecrawl_monitor_delete',
+        annotations: {
+            title: 'Delete monitor',
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: true,
+        },
+        description: `
+Permanently delete a monitor and stop its schedule. This cannot be undone.
+
+**Usage Example:**
+\`\`\`json
+{ "name": "firecrawl_monitor_delete", "arguments": { "id": "mon_abc123" } }
+\`\`\`
+`,
+        parameters: z.object({ id: z.string() }),
+        execute: async (args, { session, log }) => {
+            const { id } = args;
+            log.info('Deleting monitor', { id });
+            const res = await monitorRequest(session, `/monitor/${encodeURIComponent(id)}`, { method: 'DELETE' });
+            return asText(res);
+        },
+    });
+    server.addTool({
+        name: 'firecrawl_monitor_run',
+        annotations: {
+            title: 'Run monitor now',
+            readOnlyHint: false,
+            openWorldHint: true,
+        },
+        description: `
+Trigger a monitor check immediately, outside its normal schedule. Returns the queued check.
+
+**Usage Example:**
+\`\`\`json
+{ "name": "firecrawl_monitor_run", "arguments": { "id": "mon_abc123" } }
+\`\`\`
+`,
+        parameters: z.object({ id: z.string() }),
+        execute: async (args, { session }) => {
+            const { id } = args;
+            const res = await monitorRequest(session, `/monitor/${encodeURIComponent(id)}/run`, { method: 'POST' });
+            return asText(res);
+        },
+    });
+    server.addTool({
+        name: 'firecrawl_monitor_checks',
+        annotations: {
+            title: 'List monitor checks',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
+        description: `
+List historical checks for a monitor.
+
+**Usage Example:**
+\`\`\`json
+{ "name": "firecrawl_monitor_checks", "arguments": { "id": "mon_abc123", "limit": 10 } }
+\`\`\`
+`,
+        parameters: z.object({
+            id: z.string(),
+            limit: z.number().int().positive().optional(),
+            offset: z.number().int().nonnegative().optional(),
+        }),
+        execute: async (args, { session }) => {
+            const { id, limit, offset } = args;
+            const res = await monitorRequest(session, `/monitor/${encodeURIComponent(id)}/checks`, { query: { limit, offset } });
+            return asText(res);
+        },
+    });
+    server.addTool({
+        name: 'firecrawl_monitor_check',
+        annotations: {
+            title: 'Get monitor check',
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
+        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:
+
+- **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\`.
+- **Mixed mode** (\`modes: ["json", "git-diff"]\`). Both \`diff.text\` (markdown sidecar) AND \`diff.json\` (per-field map) are present, plus \`snapshot.json\`.
+
+**Example JSON-mode response \`pages[]\` entry:**
+
+\`\`\`json
+{
+  "url": "https://example.com/pricing",
+  "status": "changed",
+  "diff": {
+    "json": {
+      "plans[0].price":       { "previous": "$19/mo",        "current": "$24/mo" },
+      "plans[1].features[2]": { "previous": "10 GB storage", "current": "25 GB storage" }
+    }
+  },
+  "snapshot": { "json": { "plans": [/* current full extraction matching the monitor's schema */] } }
+}
+\`\`\`
+
+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.
+
+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:**
+\`\`\`json
+{
+  "name": "firecrawl_monitor_check",
+  "arguments": {
+    "id": "mon_abc123",
+    "checkId": "chk_xyz",
+    "pageStatus": "changed"
+  }
+}
+\`\`\`
+`,
+        parameters: z.object({
+            id: z.string(),
+            checkId: z.string(),
+            limit: z.number().int().positive().optional(),
+            skip: z.number().int().nonnegative().optional(),
+            pageStatus: pageStatusSchema.optional(),
+        }),
+        execute: async (args, { session }) => {
+            const { id, checkId, limit, skip, pageStatus } = args;
+            const res = await monitorRequest(session, `/monitor/${encodeURIComponent(id)}/checks/${encodeURIComponent(checkId)}`, { query: { limit, skip, status: pageStatus } });
+            return asText(res);
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl-mcp",
-  "version": "3.15.0",
+  "version": "3.17.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",
@@ -15,7 +15,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@mendable/firecrawl-js": "4.21.0",
+    "@mendable/firecrawl-js": "4.24.0",
     "dotenv": "^17.2.2",
     "firecrawl-fastmcp": "^1.0.4",
     "typescript": "^5.9.2",