feat(mcp): add generic feedback tool

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.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",

src/index.ts

@@ -1033,14 +1033,45 @@ async function keylessPost(
   return json;
 }
 
-const SEARCH_FEEDBACK_DISABLED = ['1', 'true', 'yes', 'on'].includes(
-  (
-    process.env.FIRECRAWL_NO_SEARCH_FEEDBACK ||
-    process.env.FIRECRAWL_DISABLE_SEARCH_FEEDBACK ||
-    ''
-  )
-    .trim()
-    .toLowerCase()
+const feedbackIssueSchema = z
+  .string()
+  .trim()
+  .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: string[]): boolean {
+  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) {
@@ -1233,6 +1264,144 @@ 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: unknown,
+      { session, log }: { session?: SessionData; log: Logger }
+    ): Promise<string> => {
+      const {
+        endpoint,
+        jobId,
+        rating,
+        issues,
+        tags,
+        note,
+        valuableSources,
+        missingContent,
+        querySuggestions,
+        url,
+        pageNumbers,
+        metadata,
+      } = args as {
+        endpoint: 'search' | 'scrape' | 'parse' | 'map';
+        jobId: string;
+        rating: 'good' | 'bad' | 'partial';
+        issues?: string[];
+        tags?: string[];
+        note?: string;
+        valuableSources?: { url: string; reason?: string }[];
+        missingContent?: { topic: string; description?: string }[];
+        querySuggestions?: string;
+        url?: string;
+        pageNumbers?: number[];
+        metadata?: Record<string, unknown>;
+      };
+
+      const apiBase = resolveApiBaseUrl();
+      const headers: Record<string, string> = {
+        '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: any;
+      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: {