firecrawl-mcp 3.20.4 → 3.20.6

package/README.md

@@ -623,6 +623,43 @@ Sends structured feedback on a previous `firecrawl_search` result. The first fee
 
 - `{ success, feedbackId, creditsRefunded, alreadySubmitted? }` JSON.
 
+### 5c. Generic Feedback Tool (`firecrawl_feedback`)
+
+Sends structured feedback for a completed v2 endpoint job through `/v2/feedback`.
+Use this for endpoint-level feedback on `scrape`, `parse`, `map`, or `search`
+jobs. For search-result quality specifically, prefer
+`firecrawl_search_feedback` because it includes search-specific guidance.
+
+Keep feedback concise: use issue codes, tags, short notes, URLs, page numbers,
+and small metadata objects. Do not include raw scrape/parse outputs.
+
+**Opt out:** set `FIRECRAWL_NO_ENDPOINT_FEEDBACK=1` (or `FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1`) in the environment when starting the MCP server. The `firecrawl_feedback` tool will not be registered, so agents cannot call it.
+
+**Usage Example:**
+
+```json
+{
+  "name": "firecrawl_feedback",
+  "arguments": {
+    "endpoint": "scrape",
+    "jobId": "0193f6c5-1234-7890-abcd-1234567890ab",
+    "rating": "partial",
+    "issues": ["missing_markdown"],
+    "tags": ["docs"],
+    "note": "The pricing table was missing from the markdown output.",
+    "url": "https://example.com/pricing",
+    "pageNumbers": [1],
+    "metadata": {
+      "format": "markdown"
+    }
+  }
+}
+```
+
+**Returns:**
+
+- `{ success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, alreadySubmitted?, warning? }` JSON.
+
 ### 6. Crawl Tool (`firecrawl_crawl`)
 
 Starts an asynchronous crawl job on a website and extract content from all pages.

package/dist/index.js

@@ -223,6 +223,19 @@ const server = new FastMCP({
         const envCred = resolveCredentialFromEnv();
         if (process.env.CLOUD_SERVICE === 'true') {
             if (!headerCred) {
+                // Keyless free tier over the hosted MCP: serve it only when a forwarding
+                // secret is configured, we know the end-user's client IP (so the API can
+                // rate-limit per real IP, not the shared server IP), AND that IP still
+                // has free quota. If the IP is out of quota (or keyless is off), fall
+                // through to throw so FastMCP emits the OAuth 401 + WWW-Authenticate
+                // challenge — i.e. prompt the user to connect an account exactly when
+                // their free quota runs out.
+                const clientIp = extractClientIp(request);
+                if (process.env.KEYLESS_PROXY_SECRET &&
+                    clientIp &&
+                    (await keylessEligible(clientIp))) {
+                    return { firecrawlApiKey: undefined, research, keylessClientIp: clientIp };
+                }
                 throw new Error('Firecrawl credentials required: OAuth access token (Authorization: Bearer fco_...) or API key (x-firecrawl-api-key)');
             }
             return { firecrawlApiKey: headerCred, research };
@@ -233,8 +246,12 @@ const server = new FastMCP({
         if (!httpStreaming &&
             !process.env.FIRECRAWL_API_KEY &&
             !process.env.FIRECRAWL_API_URL) {
-            console.error('Either FIRECRAWL_API_KEY or FIRECRAWL_API_URL must be provided');
-            process.exit(1);
+            // No credential and no self-hosted URL: run in keyless mode. scrape and
+            // search work for free (rate-limited per IP) against the Firecrawl cloud;
+            // every other tool needs an API key and will return Unauthorized.
+            console.error('No FIRECRAWL_API_KEY or FIRECRAWL_API_URL set — running in keyless mode. ' +
+                'firecrawl_scrape and firecrawl_search are free (rate-limited per IP) against the Firecrawl cloud; ' +
+                'other tools require an API key (get one free at https://firecrawl.dev).');
         }
         if (httpStreaming && !credential && !process.env.FIRECRAWL_API_URL) {
             console.error('HTTP MCP transport requires FIRECRAWL_API_URL and/or credentials (OAuth: Authorization Bearer fco_..., or FIRECRAWL_API_KEY / FIRECRAWL_OAUTH_TOKEN)');
@@ -559,7 +576,6 @@ ${SAFE_MODE
     parameters: scrapeParamsSchema,
     execute: async (args, { session, log }) => {
         const { url, ...options } = args;
-        const client = getClient(session);
         const transformed = transformScrapeParams(options);
         const cleaned = removeEmptyTopLevel(transformed);
         if (cleaned.lockdown) {
@@ -568,6 +584,15 @@ ${SAFE_MODE
         else {
             log.info('Scraping URL', { url: String(url) });
         }
+        if (isKeylessMode(session)) {
+            const json = await keylessPost('/v2/scrape', {
+                url: String(url),
+                ...cleaned,
+                origin: ORIGIN,
+            }, session);
+            return asText(json?.data ?? json);
+        }
+        const client = getClient(session);
         const res = await client.scrape(String(url), {
             ...cleaned,
             origin: ORIGIN,
@@ -724,7 +749,6 @@ The query also supports search operators, that you can use if needed to refine t
     })
         .refine((args) => !(args.includeDomains?.length && args.excludeDomains?.length), 'includeDomains and excludeDomains cannot both be specified'),
     execute: async (args, { session, log }) => {
-        const client = getClient(session);
         const { query, ...opts } = args;
         const searchOpts = { ...opts };
         const includeDomains = searchOpts.includeDomains;
@@ -737,16 +761,22 @@ 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 searchBody = {
+            query: searchQuery,
+            ...cleaned,
+            origin: ORIGIN,
+        };
+        if (isKeylessMode(session)) {
+            const json = await keylessPost('/v2/search', searchBody, session);
+            return asText(json ?? {});
+        }
         // 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,
-        });
+        const client = getClient(session);
+        const httpRes = await client.http.post('/v2/search', searchBody);
         return asText(httpRes?.data ?? {});
     },
 });
@@ -754,11 +784,97 @@ 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 ||
-    '')
+// Keyless free tier: when no credential is configured and we're targeting the
+// Firecrawl cloud (not self-hosted via FIRECRAWL_API_URL, not the multi-tenant
+// CLOUD_SERVICE deployment), scrape and search are free, rate-limited per IP.
+// The cloud only grants this when NO Authorization header is sent, so we bypass
+// the SDK — which always attaches a Bearer header — and post directly.
+/** Best-effort end-user client IP from the incoming MCP request headers. */
+function extractClientIp(request) {
+    const xff = request?.headers?.['x-forwarded-for'];
+    const raw = Array.isArray(xff) ? xff[0] : xff;
+    const first = typeof raw === 'string' ? raw.split(',')[0].trim() : undefined;
+    return first || undefined;
+}
+/**
+ * Read-only check (no quota consumed) of whether a client IP can still use the
+ * keyless free tier, via the API's secret-gated eligibility endpoint. Fails
+ * closed: anything other than a clear "eligible: true" means fall through to the
+ * OAuth challenge rather than silently granting keyless.
+ */
+async function keylessEligible(clientIp) {
+    const secret = process.env.KEYLESS_PROXY_SECRET;
+    if (!secret)
+        return false;
+    try {
+        const response = await fetch(`${resolveApiBaseUrl()}/v2/keyless/eligibility`, {
+            headers: {
+                'x-firecrawl-keyless-ip': clientIp,
+                'x-firecrawl-keyless-secret': secret,
+            },
+        });
+        if (!response.ok)
+            return false;
+        const json = await response.json().catch(() => ({}));
+        return json?.eligible === true;
+    }
+    catch {
+        return false;
+    }
+}
+function isKeylessMode(session) {
+    if (session?.firecrawlApiKey)
+        return false;
+    if (process.env.CLOUD_SERVICE === 'true') {
+        // Hosted: keyless only for secret-gated sessions carrying the forwarded
+        // client IP (so the per-IP cap is meaningful, not the shared server IP).
+        return !!session?.keylessClientIp;
+    }
+    // Local/stdio against the cloud (not a self-hosted FIRECRAWL_API_URL).
+    return !process.env.FIRECRAWL_API_URL;
+}
+async function keylessPost(path, body, session) {
+    const headers = { 'Content-Type': 'application/json' };
+    // Forward the real client IP (secret-authenticated) when proxying keyless
+    // requests through the hosted MCP, so the API rate-limits per real IP.
+    if (session?.keylessClientIp && process.env.KEYLESS_PROXY_SECRET) {
+        headers['x-firecrawl-keyless-ip'] = session.keylessClientIp;
+        headers['x-firecrawl-keyless-secret'] = process.env.KEYLESS_PROXY_SECRET;
+    }
+    const response = await fetch(`${resolveApiBaseUrl()}${path}`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+    });
+    const json = await response.json().catch(() => ({}));
+    if (!response.ok) {
+        throw new Error(json?.error || `Firecrawl request failed (HTTP ${response.status})`);
+    }
+    return json;
+}
+const feedbackIssueSchema = z
+    .string()
     .trim()
-    .toLowerCase());
+    .min(1)
+    .max(80)
+    .regex(/^[a-z0-9][a-z0-9_-]*$/, 'Issue codes must use lowercase letters, numbers, underscores, or hyphens');
+const valuableSourceSchema = z.object({
+    url: z.string().url(),
+    reason: z.string().max(1000).optional(),
+});
+const missingContentSchema = 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(),
+});
+const FEEDBACK_DISABLED_VALUES = new Set(['1', 'true', 'yes', 'on']);
+function feedbackEnvEnabled(...keys) {
+    return keys.some((key) => FEEDBACK_DISABLED_VALUES.has((process.env[key] || '').trim().toLowerCase()));
+}
+const SEARCH_FEEDBACK_DISABLED = feedbackEnvEnabled('FIRECRAWL_NO_SEARCH_FEEDBACK', 'FIRECRAWL_DISABLE_SEARCH_FEEDBACK');
+const ENDPOINT_FEEDBACK_DISABLED = feedbackEnvEnabled('FIRECRAWL_NO_ENDPOINT_FEEDBACK', 'FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK');
 if (SEARCH_FEEDBACK_DISABLED) {
     console.error('[firecrawl-mcp] Search feedback tool disabled by FIRECRAWL_NO_SEARCH_FEEDBACK; firecrawl_search_feedback will not be registered.');
 }
@@ -918,6 +1034,107 @@ Pass the \`searchId\` returned by \`firecrawl_search\` (the \`id\` field on the
         },
     });
 }
+if (ENDPOINT_FEEDBACK_DISABLED) {
+    console.error('[firecrawl-mcp] Endpoint feedback tool disabled by FIRECRAWL_NO_ENDPOINT_FEEDBACK; firecrawl_feedback will not be registered.');
+}
+if (!ENDPOINT_FEEDBACK_DISABLED) {
+    server.addTool({
+        name: 'firecrawl_feedback',
+        annotations: {
+            title: 'Send feedback on a Firecrawl job',
+            readOnlyHint: false,
+            openWorldHint: true,
+        },
+        description: `
+Send structured feedback for a completed Firecrawl v2 job. Use this for endpoint-level feedback on \`scrape\`, \`parse\`, \`map\`, or \`search\` jobs when the job result was useful, partially useful, or failed to meet expectations.
+
+For search-result quality specifically, prefer \`firecrawl_search_feedback\` when available because it has search-focused guidance. This generic tool posts to \`/v2/feedback\` and accepts endpoint-wide signals:
+
+- **endpoint** — one of \`search\`, \`scrape\`, \`parse\`, or \`map\`.
+- **jobId** — the id returned by that endpoint.
+- **rating** — overall result quality: \`good\`, \`partial\`, or \`bad\`.
+- **issues** — stable lowercase issue codes such as \`missing_markdown\`, \`bad_pdf_parse\`, or \`wrong_links\`.
+- **tags** — optional lowercase tags for grouping feedback.
+- **note** — short human-readable context. Do not include huge page contents or raw scrape results.
+- **url**, **pageNumbers**, and **metadata** — small contextual fields that identify what the feedback refers to.
+
+Do not store multi-MB outputs in feedback. Use concise notes, issue codes, URLs, and page numbers.
+
+**Returns:** \`{ success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, alreadySubmitted?, warning? }\` JSON.
+`,
+        parameters: z.object({
+            endpoint: z.enum(['search', 'scrape', 'parse', 'map']),
+            jobId: z.string().uuid('jobId must be the UUID returned by Firecrawl'),
+            rating: z.enum(['good', 'bad', 'partial']),
+            issues: z.array(feedbackIssueSchema).max(20).optional(),
+            tags: z.array(feedbackIssueSchema).max(20).optional(),
+            note: z.string().max(4000).optional(),
+            valuableSources: z.array(valuableSourceSchema).max(50).optional(),
+            missingContent: z.array(missingContentSchema).max(50).optional(),
+            querySuggestions: z.string().max(2000).optional(),
+            url: z.string().url().optional(),
+            pageNumbers: z.array(z.number().int().positive()).max(100).optional(),
+            metadata: z.record(z.string(), z.unknown()).optional(),
+        }),
+        execute: async (args, { session, log }) => {
+            const { endpoint, jobId, rating, issues, tags, note, valuableSources, missingContent, querySuggestions, url, pageNumbers, metadata, } = args;
+            const apiBase = resolveApiBaseUrl();
+            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 feedback.');
+            }
+            const body = removeEmptyTopLevel({
+                endpoint,
+                jobId,
+                rating,
+                issues,
+                tags,
+                note,
+                valuableSources,
+                missingContent,
+                querySuggestions,
+                url,
+                pageNumbers,
+                metadata,
+                origin: ORIGIN,
+            });
+            log.info('Submitting endpoint feedback', { endpoint, jobId, rating });
+            const response = await fetch(`${apiBase}/v2/feedback`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+            });
+            const responseText = await response.text();
+            let parsed;
+            try {
+                parsed = JSON.parse(responseText);
+            }
+            catch {
+                parsed = { raw: responseText };
+            }
+            if (!response.ok) {
+                log.warn('Endpoint 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: {

package/package.json

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