firecrawl-mcp 3.26.0 → 3.27.0

package/dist/index.js

@@ -686,6 +686,38 @@ function extractSingleTrustedClientIp(rawForwardedFor) {
   return net.isIP(candidate) ? candidate : void 0;
 }
 
+// src/keyless-signup-link.ts
+var SIGNUP_HOSTS = /* @__PURE__ */ new Set(["firecrawl.dev", "www.firecrawl.dev"]);
+var TOKEN_PATH = /^\/k\/[0-9abcdefghjkmnpqrstvwxyz]{12}$/;
+var SURFACES = /* @__PURE__ */ new Set(["api", "mcp", "cli"]);
+var SIGNIN_PARAMS = /* @__PURE__ */ new Set(["utm_source", "utm_medium", "redirect"]);
+var SIGNIN_REDIRECT = "/app/api-keys";
+function checkKeylessSignupUrl(value) {
+  if (typeof value !== "string") return { ok: false, firecrawlHost: false };
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return { ok: false, firecrawlHost: false };
+  }
+  const firecrawlHost = SIGNUP_HOSTS.has(url.hostname);
+  if (url.protocol !== "https:" || !firecrawlHost || url.port || url.username || url.password || url.hash) {
+    return { ok: false, firecrawlHost };
+  }
+  if (TOKEN_PATH.test(url.pathname) && !url.search) {
+    return { ok: true, url: value };
+  }
+  if (url.pathname === "/signin") {
+    const params = url.searchParams;
+    const keys = [...params.keys()];
+    const known = keys.every((key) => SIGNIN_PARAMS.has(key)) && new Set(keys).size === keys.length;
+    if (known && params.get("utm_source") === "keyless" && SURFACES.has(params.get("utm_medium") ?? "") && (!params.has("redirect") || params.get("redirect") === SIGNIN_REDIRECT)) {
+      return { ok: true, url: value };
+    }
+  }
+  return { ok: false, firecrawlHost };
+}
+
 // src/monitor.ts
 import { z as z5 } from "zod";
 
@@ -2446,16 +2478,36 @@ function isHostedKeylessSession(session) {
 function isLocalKeylessStartup() {
   return process.env.CLOUD_SERVICE !== "true" && !isHttpStreamingTransport() && !resolveCredentialFromEnv() && !normalizeHeader(process.env.FIRECRAWL_API_URL);
 }
-var KEYLESS_ACCOUNT_FIX = "Fix: Create an API key at https://www.firecrawl.dev/app/api-keys, then:\n- Set the header: Authorization: Bearer YOUR_API_KEY on https://mcp.firecrawl.dev/v2/mcp\nThen start a new session.";
-var KEYLESS_QUOTA_MESSAGE = `You've hit Firecrawl's free MCP rate limit. To continue using without limits, create a Firecrawl API key.
+var KEYLESS_SIGNUP_FALLBACK_URL = "https://www.firecrawl.dev/signin?utm_source=keyless&utm_medium=mcp&redirect=%2Fapp%2Fapi-keys";
+var droppedKeylessSignupUrls = /* @__PURE__ */ new Set();
+function keylessSignupUrlFrom(value) {
+  const check = checkKeylessSignupUrl(value);
+  if (check.ok) return check.url;
+  if (check.firecrawlHost && typeof value === "string" && droppedKeylessSignupUrls.size < 50 && !droppedKeylessSignupUrls.has(value)) {
+    droppedKeylessSignupUrls.add(value);
+    console.warn(
+      "[WARN]",
+      (/* @__PURE__ */ new Date()).toISOString(),
+      "Ignoring an unrecognized Firecrawl keyless signup link from the API; using the fallback",
+      { signupUrl: value }
+    );
+  }
+  return void 0;
+}
+function keylessAccountFix(signupUrl) {
+  return `Fix: Create an API key at ${signupUrl} and then:
+- Set the header: Authorization: Bearer YOUR_API_KEY on https://mcp.firecrawl.dev/v2/mcp
+Then start a new session.`;
+}
+var keylessQuotaMessage = (signupUrl) => `You've hit Firecrawl's free MCP rate limit. To continue using without limits, create a Firecrawl API key.
 
-${KEYLESS_ACCOUNT_FIX}`;
-var KEYLESS_TOOL_MESSAGE = `This tool needs a Firecrawl account.
+${keylessAccountFix(signupUrl)}`;
+var keylessToolMessage = (signupUrl) => `This tool needs a Firecrawl account.
 
-${KEYLESS_ACCOUNT_FIX}`;
-var KEYLESS_ACCESS_MESSAGE = `Anonymous keyless access is unavailable for this request.
+${keylessAccountFix(signupUrl)}`;
+var keylessAccessMessage = (signupUrl) => `Anonymous keyless access is unavailable for this request.
 
-${KEYLESS_ACCOUNT_FIX}`;
+${keylessAccountFix(signupUrl)}`;
 var INVALID_API_KEY_MESSAGE = "The Firecrawl API key is invalid or revoked.\nFix: Replace the key on the existing Firecrawl MCP server, then start a new session. Get an API key at https://www.firecrawl.dev/app/api-keys";
 var INVALID_OAUTH_MESSAGE = "This Firecrawl account connection is no longer valid.\nFix: Reconnect the existing Firecrawl server in the client, or set that existing server URL to https://mcp.firecrawl.dev/v2/mcp-oauth, then start a new session.";
 function connectionRecoveryPayload(params) {
@@ -2512,6 +2564,7 @@ ${agentHintsText(hints)}` : message,
 }
 function recoveryPayload(code, requestId = randomUUID(), options = {}) {
   const retryAfterSeconds = options.retryAfterSeconds;
+  const signupUrl = options.signupUrl ?? KEYLESS_SIGNUP_FALLBACK_URL;
   const isQuotaExhausted = code === "KEYLESS_QUOTA_EXHAUSTED" || code === "KEYLESS_LIMIT_REACHED";
   const isToolUnavailable = code === "KEYLESS_TOOL_NOT_AVAILABLE";
   const isKeylessAccessUnavailable = code === "KEYLESS_ACCESS_NOT_AVAILABLE";
@@ -2521,7 +2574,7 @@ function recoveryPayload(code, requestId = randomUUID(), options = {}) {
     code,
     request_id: requestId,
     auth_mode: code === "CREDENTIAL_INVALID" ? "credential_error" : "keyless",
-    message: code === "CREDENTIAL_INVALID" ? INVALID_API_KEY_MESSAGE : isQuotaExhausted ? KEYLESS_QUOTA_MESSAGE : isToolUnavailable ? KEYLESS_TOOL_MESSAGE : isKeylessAccessUnavailable ? KEYLESS_ACCESS_MESSAGE : isKeylessEligibilityUnavailable ? "The anonymous keyless eligibility check is temporarily unavailable. Retry shortly." : "This tool requires a Firecrawl account or API key.",
+    message: code === "CREDENTIAL_INVALID" ? INVALID_API_KEY_MESSAGE : isQuotaExhausted ? keylessQuotaMessage(signupUrl) : isToolUnavailable ? keylessToolMessage(signupUrl) : isKeylessAccessUnavailable ? keylessAccessMessage(signupUrl) : isKeylessEligibilityUnavailable ? "The anonymous keyless eligibility check is temporarily unavailable. Retry shortly." : "This tool requires a Firecrawl account or API key.",
     // CREDENTIAL_INVALID sessions gate every tool call (including keyless
     // tools) on the credentialError check before the keyless branch ever
     // runs, so none of KEYLESS_TOOL_NAMES are actually callable here. Listing
@@ -2530,6 +2583,7 @@ function recoveryPayload(code, requestId = randomUUID(), options = {}) {
     // tools, and ineligible access omit available_tools and next_actions for
     // the same reason: those fields retry tools that cannot clear the error.
     ...isKeylessConversion || code === "CREDENTIAL_INVALID" ? {} : { available_tools: [...KEYLESS_TOOL_NAMES] },
+    ...isKeylessConversion ? { signup_url: signupUrl } : {},
     docs_url: MCP_CONNECTION_GUIDE_URL,
     ...retryAfterSeconds ? { retry_after_seconds: retryAfterSeconds } : {},
     ...isKeylessEligibilityUnavailable ? { next_actions: [{ kind: "retry_later", after_seconds: 30 }] } : {}
@@ -2630,7 +2684,9 @@ function guardHostedTool(tool, { logActions }) {
       const code = session?.credentialError ? "CREDENTIAL_INVALID" : isHostedKeylessSession(session) && !keylessTool ? "KEYLESS_TOOL_NOT_AVAILABLE" : void 0;
       if (code) {
         const requestId = randomUUID();
-        const payload2 = recoveryPayload(code, requestId);
+        const payload2 = recoveryPayload(code, requestId, {
+          signupUrl: code === "KEYLESS_TOOL_NOT_AVAILABLE" ? await hostedKeylessSignupUrl(session) : void 0
+        });
         if (logActions) {
           emitActionLog(tool.name, "error", session, new UserError2(String(payload2.message), payload2), requestId, code);
         }
@@ -2674,7 +2730,9 @@ function guardHostedTool(tool, { logActions }) {
       }
       if (isHostedKeylessSession(invocationSession) && !keylessTool) {
         const code = "KEYLESS_TOOL_NOT_AVAILABLE";
-        const payload = recoveryPayload(code, requestId);
+        const payload = recoveryPayload(code, requestId, {
+          signupUrl: await hostedKeylessSignupUrl(invocationSession)
+        });
         if (logActions) emitActionLog(tool.name, "error", invocationSession, new UserError2(String(payload.message), payload), requestId, code);
         throw new UserError2(String(payload.message), payload);
       }
@@ -3579,12 +3637,12 @@ function extractClientIp(request) {
 function keylessQuotaReason(reason) {
   return reason === "requests" || reason === "credits";
 }
-async function keylessEligible(clientIp, origin) {
+async function keylessEligible(clientIp, origin, { signupLink = false } = {}) {
   const secret = process.env.KEYLESS_PROXY_SECRET;
   if (!secret) return { eligible: false, unavailable: true };
   try {
     const response = await fetch(
-      `${resolveApiBaseUrl()}/v2/keyless/eligibility`,
+      `${resolveApiBaseUrl()}/v2/keyless/eligibility${signupLink ? "?signup_link=1" : ""}`,
       {
         headers: {
           ...originHeaders(origin),
@@ -3601,12 +3659,22 @@ async function keylessEligible(clientIp, origin) {
     return {
       eligible: json?.eligible === true,
       ...typeof json?.reason === "string" ? { reason: json.reason } : {},
-      ...Number.isFinite(json?.retryAfterSeconds) && json.retryAfterSeconds > 0 ? { retryAfterSeconds: json.retryAfterSeconds } : {}
+      ...Number.isFinite(json?.retryAfterSeconds) && json.retryAfterSeconds > 0 ? { retryAfterSeconds: json.retryAfterSeconds } : {},
+      ...keylessSignupUrlFrom(json?.signupUrl) ? { signupUrl: json.signupUrl } : {}
     };
   } catch {
     return { eligible: false, unavailable: true };
   }
 }
+async function hostedKeylessSignupUrl(session) {
+  if (!session?.keylessClientIp) return void 0;
+  const eligibility = await keylessEligible(
+    session.keylessClientIp,
+    requestOrigin(void 0, session),
+    { signupLink: true }
+  );
+  return eligibility.signupUrl;
+}
 function isKeylessMode(session) {
   if (hasCredential(session) || session?.credentialError) return false;
   if (process.env.CLOUD_SERVICE === "true") {
@@ -3621,7 +3689,8 @@ async function keylessPost(path2, body, session, originOverride) {
     if (!eligibility.eligible) {
       const code = eligibility.unavailable ? "KEYLESS_ELIGIBILITY_UNAVAILABLE" : keylessQuotaReason(eligibility.reason) ? "KEYLESS_QUOTA_EXHAUSTED" : "KEYLESS_ACCESS_NOT_AVAILABLE";
       const payload = recoveryPayload(code, session?.requestId, {
-        retryAfterSeconds: eligibility.retryAfterSeconds
+        retryAfterSeconds: eligibility.retryAfterSeconds,
+        signupUrl: eligibility.signupUrl
       });
       throw new UserError2(String(payload.message), payload);
     }
@@ -3645,7 +3714,8 @@ async function keylessPost(path2, body, session, originOverride) {
     if (isKeylessMode(session) && response.status === 429) {
       const code = keylessQuotaReason(json?.reason) ? "KEYLESS_QUOTA_EXHAUSTED" : "KEYLESS_LIMIT_REACHED";
       const payload = recoveryPayload(code, session?.requestId, {
-        retryAfterSeconds: Number.isFinite(json?.retry_after_seconds) && json.retry_after_seconds > 0 ? json.retry_after_seconds : void 0
+        retryAfterSeconds: Number.isFinite(json?.retry_after_seconds) && json.retry_after_seconds > 0 ? json.retry_after_seconds : void 0,
+        signupUrl: keylessSignupUrlFrom(json?.signup_url)
       });
       const hints = readAgentHints(json);
       if (hints) payload.agent_hints = hints;

package/dist/keyless-signup-link.js

@@ -0,0 +1,34 @@
+// src/keyless-signup-link.ts
+var SIGNUP_HOSTS = /* @__PURE__ */ new Set(["firecrawl.dev", "www.firecrawl.dev"]);
+var TOKEN_PATH = /^\/k\/[0-9abcdefghjkmnpqrstvwxyz]{12}$/;
+var SURFACES = /* @__PURE__ */ new Set(["api", "mcp", "cli"]);
+var SIGNIN_PARAMS = /* @__PURE__ */ new Set(["utm_source", "utm_medium", "redirect"]);
+var SIGNIN_REDIRECT = "/app/api-keys";
+function checkKeylessSignupUrl(value) {
+  if (typeof value !== "string") return { ok: false, firecrawlHost: false };
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return { ok: false, firecrawlHost: false };
+  }
+  const firecrawlHost = SIGNUP_HOSTS.has(url.hostname);
+  if (url.protocol !== "https:" || !firecrawlHost || url.port || url.username || url.password || url.hash) {
+    return { ok: false, firecrawlHost };
+  }
+  if (TOKEN_PATH.test(url.pathname) && !url.search) {
+    return { ok: true, url: value };
+  }
+  if (url.pathname === "/signin") {
+    const params = url.searchParams;
+    const keys = [...params.keys()];
+    const known = keys.every((key) => SIGNIN_PARAMS.has(key)) && new Set(keys).size === keys.length;
+    if (known && params.get("utm_source") === "keyless" && SURFACES.has(params.get("utm_medium") ?? "") && (!params.has("redirect") || params.get("redirect") === SIGNIN_REDIRECT)) {
+      return { ok: true, url: value };
+    }
+  }
+  return { ok: false, firecrawlHost };
+}
+export {
+  checkKeylessSignupUrl
+};

package/package.json

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