firecrawl-mcp 3.31.1 → 3.32.0

package/README.md

@@ -273,6 +273,9 @@ Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace
 - `FIRECRAWL_API_URL` (Optional): Custom API endpoint for self-hosted instances
   - Example: `https://firecrawl.your-domain.com`
   - If not provided, the cloud API will be used (requires API key)
+- `FIRECRAWL_INTEGRATION` (Optional): Integration tag for apps that launch this server, such as an editor extension
+  - Sent as the `integration` field of scrape, batch scrape, crawl, map, search, extract, agent, parse, interact and feedback requests
+  - Use a value that starts with `_`, for example `_zed`
 
 #### MCP OAuth (Bearer access tokens)
 

package/dist/index.js

@@ -3559,6 +3559,22 @@ The historical view returns periods sorted by start date with \`startDate\`, \`e
   });
 }
 
+// src/integration.ts
+var TAGGED_PATH = /^\/v2\/(scrape|batch\/scrape|crawl|map|search|extract|agent|parse|feedback|scrape\/[^/]+\/interact|search\/[^/]+\/feedback)$/;
+function integrationFrom(value) {
+  const tag = (value ?? "").trim();
+  return tag === "" ? void 0 : tag;
+}
+function pathOf(url) {
+  const path2 = url.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]+/i, "").split(/[?#]/)[0];
+  return path2.replace(/\/+$/, "");
+}
+function withIntegration(url, body, integration) {
+  if (!integration || body.integration != null) return body;
+  if (!TAGGED_PATH.test(pathOf(url))) return body;
+  return { ...body, integration };
+}
+
 // src/headers.ts
 function normalizeHeader(value) {
   if (value == null) return void 0;
@@ -3999,7 +4015,8 @@ function createFirecrawlMcpServer(options2 = {}) {
     fileAccess: options2.fileAccess ?? "local",
     requireCredential: options2.requireCredential ?? false,
     searchFeedback: options2.searchFeedback ?? true,
-    endpointFeedback: options2.endpointFeedback ?? true
+    endpointFeedback: options2.endpointFeedback ?? true,
+    integration: integrationFrom(options2.integration)
   };
   const logging = options2.logging ?? config.transport === "httpStream";
   const instructionDefaults = {
@@ -4127,7 +4144,22 @@ function createFirecrawlMcpServer(options2 = {}) {
     if (apiKey2) {
       clientConfig.apiKey = apiKey2;
     }
-    return new FirecrawlApp(clientConfig);
+    const client = new FirecrawlApp(clientConfig);
+    if (config.integration) {
+      client.http?.instance?.interceptors?.request?.use((request) => {
+        const isPost = String(request.method ?? "").toLowerCase() === "post";
+        const isPlainObject = request.data != null && typeof request.data === "object" && !Array.isArray(request.data) && !(request.data instanceof FormData);
+        if (isPost && isPlainObject) {
+          request.data = withIntegration(
+            request.url ?? "",
+            request.data,
+            config.integration
+          );
+        }
+        return request;
+      });
+    }
+    return client;
   }
   const SAFE_MODE = config.safeMode;
   function getClient(session) {
@@ -4461,7 +4493,7 @@ function createFirecrawlMcpServer(options2 = {}) {
   function buildParseOptionsPayload(options3, origin) {
     const transformed = transformScrapeParams(options3);
     const cleaned = removeEmptyTopLevel(transformed);
-    return { origin, ...cleaned };
+    return withIntegration("/v2/parse", { origin, ...cleaned }, config.integration);
   }
   function buildContinuationArguments(uploadRef, options3) {
     return {
@@ -4485,7 +4517,7 @@ function createFirecrawlMcpServer(options2 = {}) {
         Authorization: `Bearer ${apiKey2}`,
         ...origin ? originHeaders(origin) : {}
       },
-      body: JSON.stringify(body)
+      body: JSON.stringify(withIntegration(pathName, body, config.integration))
     });
     const responseText = await response.text();
     let parsed;
@@ -4928,7 +4960,7 @@ For a programming question, add \`categories: ["developer"]\`; its hits return i
     const response = await fetch(`${resolveApiBaseUrl()}${path2}`, {
       method: "POST",
       headers,
-      body: JSON.stringify(body)
+      body: JSON.stringify(withIntegration(path2, body, config.integration))
     });
     const json = await response.json().catch(() => ({}));
     if (!response.ok) {
@@ -5098,7 +5130,13 @@ Eligibility is limited to successful searches within the feedback age window. Th
         const response = await fetch(endpoint, {
           method: "POST",
           headers,
-          body: JSON.stringify(body)
+          body: JSON.stringify(
+            withIntegration(
+              `/v2/search/${encodeURIComponent(searchId)}/feedback`,
+              body,
+              config.integration
+            )
+          )
         });
         const responseText = await response.text();
         let parsed;
@@ -5237,7 +5275,7 @@ Returns submission status, feedback ID, and accounting fields.
         const response = await fetch(`${apiBase}/v2/feedback`, {
           method: "POST",
           headers,
-          body: JSON.stringify(body)
+          body: JSON.stringify(withIntegration("/v2/feedback", body, config.integration))
         });
         const responseText = await response.text();
         let parsed;
@@ -6718,7 +6756,8 @@ var options = {
   fileAccess: hosted ? "upload" : "local",
   requireCredential: hosted,
   searchFeedback: !searchFeedbackDisabled,
-  endpointFeedback: !endpointFeedbackDisabled
+  endpointFeedback: !endpointFeedbackDisabled,
+  integration: process.env.FIRECRAWL_INTEGRATION
 };
 var serviceSettings = { hosted, transport, apiKey, apiUrl };
 var primaryHooks = createServiceHooks(primaryProfile, serviceSettings);

package/dist/integration.js

@@ -0,0 +1,19 @@
+// src/integration.ts
+var TAGGED_PATH = /^\/v2\/(scrape|batch\/scrape|crawl|map|search|extract|agent|parse|feedback|scrape\/[^/]+\/interact|search\/[^/]+\/feedback)$/;
+function integrationFrom(value) {
+  const tag = (value ?? "").trim();
+  return tag === "" ? void 0 : tag;
+}
+function pathOf(url) {
+  const path = url.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]+/i, "").split(/[?#]/)[0];
+  return path.replace(/\/+$/, "");
+}
+function withIntegration(url, body, integration) {
+  if (!integration || body.integration != null) return body;
+  if (!TAGGED_PATH.test(pathOf(url))) return body;
+  return { ...body, integration };
+}
+export {
+  integrationFrom,
+  withIntegration
+};

package/dist/server.d.ts

@@ -420,6 +420,8 @@ interface FirecrawlMcpServerOptions {
     searchFeedback?: boolean;
     /** Register firecrawl_feedback. Defaults to true. */
     endpointFeedback?: boolean;
+    /** Tag sent as the `integration` field of API requests that accept one, such as `_zed`. */
+    integration?: string;
     /** Extension hooks. Unstable: may change in any release. */
     unstable_hooks?: FirecrawlMcpServerHooks;
 }

package/dist/server.js

@@ -3558,6 +3558,22 @@ The historical view returns periods sorted by start date with \`startDate\`, \`e
   });
 }
 
+// src/integration.ts
+var TAGGED_PATH = /^\/v2\/(scrape|batch\/scrape|crawl|map|search|extract|agent|parse|feedback|scrape\/[^/]+\/interact|search\/[^/]+\/feedback)$/;
+function integrationFrom(value) {
+  const tag = (value ?? "").trim();
+  return tag === "" ? void 0 : tag;
+}
+function pathOf(url) {
+  const path2 = url.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]+/i, "").split(/[?#]/)[0];
+  return path2.replace(/\/+$/, "");
+}
+function withIntegration(url, body, integration) {
+  if (!integration || body.integration != null) return body;
+  if (!TAGGED_PATH.test(pathOf(url))) return body;
+  return { ...body, integration };
+}
+
 // src/headers.ts
 function normalizeHeader(value) {
   if (value == null) return void 0;
@@ -3998,7 +4014,8 @@ function createFirecrawlMcpServer(options = {}) {
     fileAccess: options.fileAccess ?? "local",
     requireCredential: options.requireCredential ?? false,
     searchFeedback: options.searchFeedback ?? true,
-    endpointFeedback: options.endpointFeedback ?? true
+    endpointFeedback: options.endpointFeedback ?? true,
+    integration: integrationFrom(options.integration)
   };
   const logging = options.logging ?? config.transport === "httpStream";
   const instructionDefaults = {
@@ -4126,7 +4143,22 @@ function createFirecrawlMcpServer(options = {}) {
     if (apiKey) {
       clientConfig.apiKey = apiKey;
     }
-    return new FirecrawlApp(clientConfig);
+    const client = new FirecrawlApp(clientConfig);
+    if (config.integration) {
+      client.http?.instance?.interceptors?.request?.use((request) => {
+        const isPost = String(request.method ?? "").toLowerCase() === "post";
+        const isPlainObject = request.data != null && typeof request.data === "object" && !Array.isArray(request.data) && !(request.data instanceof FormData);
+        if (isPost && isPlainObject) {
+          request.data = withIntegration(
+            request.url ?? "",
+            request.data,
+            config.integration
+          );
+        }
+        return request;
+      });
+    }
+    return client;
   }
   const SAFE_MODE = config.safeMode;
   function getClient(session) {
@@ -4460,7 +4492,7 @@ function createFirecrawlMcpServer(options = {}) {
   function buildParseOptionsPayload(options2, origin) {
     const transformed = transformScrapeParams(options2);
     const cleaned = removeEmptyTopLevel(transformed);
-    return { origin, ...cleaned };
+    return withIntegration("/v2/parse", { origin, ...cleaned }, config.integration);
   }
   function buildContinuationArguments(uploadRef, options2) {
     return {
@@ -4484,7 +4516,7 @@ function createFirecrawlMcpServer(options = {}) {
         Authorization: `Bearer ${apiKey}`,
         ...origin ? originHeaders(origin) : {}
       },
-      body: JSON.stringify(body)
+      body: JSON.stringify(withIntegration(pathName, body, config.integration))
     });
     const responseText = await response.text();
     let parsed;
@@ -4927,7 +4959,7 @@ For a programming question, add \`categories: ["developer"]\`; its hits return i
     const response = await fetch(`${resolveApiBaseUrl()}${path2}`, {
       method: "POST",
       headers,
-      body: JSON.stringify(body)
+      body: JSON.stringify(withIntegration(path2, body, config.integration))
     });
     const json = await response.json().catch(() => ({}));
     if (!response.ok) {
@@ -5097,7 +5129,13 @@ Eligibility is limited to successful searches within the feedback age window. Th
         const response = await fetch(endpoint, {
           method: "POST",
           headers,
-          body: JSON.stringify(body)
+          body: JSON.stringify(
+            withIntegration(
+              `/v2/search/${encodeURIComponent(searchId)}/feedback`,
+              body,
+              config.integration
+            )
+          )
         });
         const responseText = await response.text();
         let parsed;
@@ -5236,7 +5274,7 @@ Returns submission status, feedback ID, and accounting fields.
         const response = await fetch(`${apiBase}/v2/feedback`, {
           method: "POST",
           headers,
-          body: JSON.stringify(body)
+          body: JSON.stringify(withIntegration("/v2/feedback", body, config.integration))
         });
         const responseText = await response.text();
         let parsed;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl-mcp",
-  "version": "3.31.1",
+  "version": "3.32.0",
   "description": "MCP server for Firecrawl — search, scrape, and interact with the web, and search scientific papers. Supports both cloud and self-hosted instances. Features include web search, scraping, page interaction, batch processing, LLM-powered content analysis, and research paper search over biomedical and arXiv literature (PubMed, bioRxiv, medRxiv, arXiv) with citation-graph expansion and full-text reading.",
   "type": "module",
   "mcpName": "io.github.firecrawl/firecrawl-mcp-server",