firecrawl-mcp 3.26.0 → 3.27.1

package/README.md

@@ -1283,10 +1283,13 @@ The existing `firecrawl_feedback` tool accepts `endpoint: "alexandria"`:
     "url": "https://example.com",
     "requestedFunctionality": "Find records and download their attachments"
   },
+  "objective": "Compare contract requirements across agencies before bidding",
   "rationale": "Found summaries but could not retrieve attachments"
 }
 ```
 
+`objective` is the underlying goal of the session: what the agent or its user was ultimately trying to accomplish, beyond the single website in `requestedWebsite`.
+
 This uses authenticated `POST /v2/feedback`, without a job ID, job-age deadline, or credit refund. Optional `providerFeedback` and `capabilityFeedback` arrays describe coverage gaps and execution issues; the tool schema lists supported issue values. A `new_capability_request` requires `requestedFunctionality`; `missing_capability` (the provider exists but lacks the capability) does not. Existing feedback opt-out and authentication controls apply.
 
 Eligible Alexandria execution and discovery results include a `feedbackTool` pointer with the tool name and a skeleton of the arguments. The pointer is omitted for Firecrawl-internal calls such as `bash` and when `firecrawl_feedback` is not registered (`FIRECRAWL_NO_ENDPOINT_FEEDBACK` or keyless startup).

package/dist/index.js

@@ -10,6 +10,7 @@ var alexandriaFeedbackFields = {
     requestedFunctionality: detail
   }).optional(),
   rationale: detail.optional(),
+  objective: detail.optional(),
   providerFeedback: z.array(
     z.strictObject({
       name,
@@ -55,6 +56,7 @@ var ALEXANDRIA_FEEDBACK_HINT = {
       url: "<website the user needed data from>",
       requestedFunctionality: "<what they needed from it>"
     },
+    objective: "<underlying goal of the task>",
     rationale: "<why this rating, from observed results>",
     providerFeedback: "<optional [{name, issue, why}]: providers that were missing, thin, or unavailable>",
     capabilityFeedback: "<optional [{name, provider, issue, why, requestedFunctionality?}]: capabilities that were missing, wrong, or failed>"
@@ -74,7 +76,8 @@ var alexandriaSessionFeedbackSchema = z.strictObject({
   rating: z.enum(["good", "bad", "partial"]),
   ...alexandriaFeedbackFields,
   requestedWebsite: alexandriaFeedbackFields.requestedWebsite.unwrap(),
-  rationale: detail
+  rationale: detail,
+  objective: detail
 });
 
 // src/index.ts
@@ -686,6 +689,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 +2481,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 +2567,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 +2577,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 +2586,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 +2687,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 +2733,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 +3640,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 +3662,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 +3692,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 +3717,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;
@@ -3882,7 +3955,7 @@ if (alexandriaFeedbackAvailable()) {
     description: `
 Submit concise quality feedback for a completed search, scrape, parse, or map job. Provide the endpoint, job ID, rating, and relevant issue codes or small contextual fields; omit large page contents and raw outputs.
 
-For an Alexandria session, set endpoint to \`alexandria\`, omit jobId, and provide requestedWebsite (url and requestedFunctionality), rationale, and rating. Optional providerFeedback and capabilityFeedback describe gaps or errors. Capability issues: new_capability_request (requires requestedFunctionality), missing_capability, insufficient_functionality, incorrect_result, execution_error, other. Alexandria feedback has no job-age deadline and no credit refund.
+For an Alexandria session, set endpoint to \`alexandria\`, omit jobId, and provide requestedWebsite (url and requestedFunctionality), objective, rationale, and rating. objective is the underlying goal behind the session: what you or your user were ultimately trying to accomplish (for example, "shortlist federal IT contracts to bid on this quarter"), not only what was needed from this website. Optional providerFeedback and capabilityFeedback describe gaps or errors. Capability issues: new_capability_request (requires requestedFunctionality), missing_capability, insufficient_functionality, incorrect_result, execution_error, other. Alexandria feedback has no job-age deadline and no credit refund.
 
 Returns submission status, feedback ID, and accounting fields.
 `,

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