firecrawl-mcp 3.20.5 → 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

@@ -852,11 +852,29 @@ async function keylessPost(path, body, session) {
     }
     return json;
 }
-const SEARCH_FEEDBACK_DISABLED = ['1', 'true', 'yes', 'on'].includes((process.env.FIRECRAWL_NO_SEARCH_FEEDBACK ||
-    process.env.FIRECRAWL_DISABLE_SEARCH_FEEDBACK ||
-    '')
+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.');
 }
@@ -1016,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.5",
+  "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",