firecrawl-mcp 3.23.0 → 3.23.2

package/dist/index.js

@@ -8,7 +8,63 @@ import { readFile } from "fs/promises";
 import { createRequire } from "module";
 import { randomUUID } from "crypto";
 import path from "path";
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
+
+// src/developer.ts
+import { z } from "zod";
+var BASE = "/v2/developer/search";
+var ORIGIN_HEADERS = { "X-Origin": "mcp-fastmcp" };
+var MAX_PASSAGE_CHARS = 1200;
+function fmtDeveloper(results) {
+  if (!results || results.length === 0) return "(no results)";
+  return results.map((r) => {
+    const kind = r.type ? ` (${r.type})` : "";
+    const lines = [`## [${r.id ?? "?"}]${kind} ${r.title ?? "(untitled)"}`];
+    if (r.url) lines.push(r.url);
+    const body = (r.passages ?? []).map((p) => p.text ?? "").join("\n---\n").trim();
+    lines.push(body ? body.slice(0, MAX_PASSAGE_CHARS) : "(no content)");
+    return lines.join("\n");
+  }).join("\n\n");
+}
+function registerDeveloperTools(server2, getClient2) {
+  server2.addTool({
+    name: "firecrawl_developer_search",
+    annotations: {
+      title: "Search developer sources",
+      readOnlyHint: true,
+      // Semantic search over an indexed developer corpus; returns ranked results only.
+      openWorldHint: true,
+      // Searches the Firecrawl developer index of public GitHub and documentation content.
+      destructiveHint: false
+      // Query-only; no writes to external sources or the developer index.
+    },
+    description: `
+For a developer question \u2014 code behaviour, a library or framework, an API contract, an error message, or a known bug \u2014 search an index built for coding agents. The index covers GitHub issues, merged pull requests, repository READMEs, and curated documentation sites. Set skills to "only" to limit the search to agent-skill files.
+
+Returns ranked results with an ID, source type, URL, title, and the matched passages in markdown.
+`,
+    parameters: z.object({
+      query: z.string().min(1).describe(
+        "Natural-language developer question or search phrase, including the library, error message, or API involved when relevant."
+      ),
+      k: z.number().int().min(1).max(100).optional().describe("Number of ranked results to return (default 20)."),
+      skills: z.enum(["only"]).optional().describe('Set to "only" to search only agent-skill files.')
+    }),
+    execute: async (args2, { session }) => {
+      const { query, k, skills } = args2;
+      const params = new URLSearchParams();
+      params.append("query", query);
+      if (k != null) params.append("k", String(k));
+      if (skills != null) params.append("skills", skills);
+      const client = getClient2(session);
+      const res = await client.http.get(
+        `${BASE}?${params.toString()}`,
+        ORIGIN_HEADERS
+      );
+      return fmtDeveloper(res.data?.results);
+    }
+  });
+}
 
 // src/keyless-client-ip.ts
 import net from "net";
@@ -25,7 +81,7 @@ function extractSingleTrustedClientIp(rawForwardedFor) {
 }
 
 // src/monitor.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 
 // src/session-credential.ts
 import { createHmac } from "crypto";
@@ -124,8 +180,8 @@ async function monitorRequest(session, path2, init = {}) {
 function asText(data) {
   return JSON.stringify(data, null, 2);
 }
-var pageStatusSchema = z.enum(["same", "new", "changed", "removed", "error"]);
-var checkStatusSchema = z.enum([
+var pageStatusSchema = z2.enum(["same", "new", "changed", "removed", "error"]);
+var checkStatusSchema = z2.enum([
   "queued",
   "running",
   "completed",
@@ -218,22 +274,22 @@ Create a recurring scrape, crawl, or search monitor that compares each check wit
 
 In the simple form, a \`goal\` is required. If \`queries\` contains one or more non-empty values and is supplied with \`page\`/\`pages\`, \`queries\` create the search target and page targets are ignored. A monitor schedules future network checks and can send configured email or webhook notifications. Returns the created monitor.
 `,
-    parameters: z.object({
-      body: z.record(z.string(), z.any()).optional(),
-      page: z.string().optional(),
-      pages: z.array(z.string()).optional(),
-      queries: z.array(z.string()).optional(),
-      searchWindow: z.enum(["5m", "15m", "1h", "6h", "24h", "7d"]).optional(),
-      maxResults: z.number().int().min(1).max(50).optional(),
-      includeDomains: z.array(z.string()).optional(),
-      excludeDomains: z.array(z.string()).optional(),
-      goal: z.string().optional(),
-      name: z.string().optional(),
-      scheduleText: z.string().optional(),
-      timezone: z.string().optional(),
-      email: z.string().optional(),
-      includeDiffs: z.boolean().optional(),
-      webhookUrl: z.string().optional()
+    parameters: z2.object({
+      body: z2.record(z2.string(), z2.any()).optional(),
+      page: z2.string().optional(),
+      pages: z2.array(z2.string()).optional(),
+      queries: z2.array(z2.string()).optional(),
+      searchWindow: z2.enum(["5m", "15m", "1h", "6h", "24h", "7d"]).optional(),
+      maxResults: z2.number().int().min(1).max(50).optional(),
+      includeDomains: z2.array(z2.string()).optional(),
+      excludeDomains: z2.array(z2.string()).optional(),
+      goal: z2.string().optional(),
+      name: z2.string().optional(),
+      scheduleText: z2.string().optional(),
+      timezone: z2.string().optional(),
+      email: z2.string().optional(),
+      includeDiffs: z2.boolean().optional(),
+      webhookUrl: z2.string().optional()
     }),
     execute: async (args2, { session, log }) => {
       const body = buildMonitorCreateBody(args2);
@@ -259,9 +315,9 @@ In the simple form, a \`goal\` is required. If \`queries\` contains one or more
     description: `
 List monitors for the authenticated account with optional pagination controls. Returns one page of monitor records and pagination metadata.
 `,
-    parameters: z.object({
-      limit: z.number().int().positive().optional(),
-      offset: z.number().int().nonnegative().optional()
+    parameters: z2.object({
+      limit: z2.number().int().positive().optional(),
+      offset: z2.number().int().nonnegative().optional()
     }),
     execute: async (args2, { session }) => {
       const { limit, offset } = args2;
@@ -285,7 +341,7 @@ List monitors for the authenticated account with optional pagination controls. R
     description: `
 Retrieve one monitor by ID, including its configuration and current state. This does not run or modify the monitor.
 `,
-    parameters: z.object({ id: z.string() }),
+    parameters: z2.object({ id: z2.string() }),
     execute: async (args2, { session }) => {
       const { id } = args2;
       const res = await monitorRequest(
@@ -311,9 +367,9 @@ Patch an existing monitor by ID. The body can change its name, active/paused sta
 
 Returns the updated monitor.
 `,
-    parameters: z.object({
-      id: z.string(),
-      body: z.record(z.string(), z.any())
+    parameters: z2.object({
+      id: z2.string(),
+      body: z2.record(z2.string(), z2.any())
     }),
     execute: async (args2, { session }) => {
       const { id, body } = args2;
@@ -339,7 +395,7 @@ Returns the updated monitor.
     description: `
 Permanently delete a monitor by ID and stop its future schedule. This operation cannot be undone and returns deletion status.
 `,
-    parameters: z.object({ id: z.string() }),
+    parameters: z2.object({ id: z2.string() }),
     execute: async (args2, { session, log }) => {
       const { id } = args2;
       log.info("Deleting monitor", { id });
@@ -365,7 +421,7 @@ Permanently delete a monitor by ID and stop its future schedule. This operation
     description: `
 Queue an immediate check for a monitor outside its normal schedule. This starts network work for the monitor's configured targets and returns the queued check.
 `,
-    parameters: z.object({ id: z.string() }),
+    parameters: z2.object({ id: z2.string() }),
     execute: async (args2, { session }) => {
       const { id } = args2;
       const res = await monitorRequest(
@@ -390,10 +446,10 @@ Queue an immediate check for a monitor outside its normal schedule. This starts
     description: `
 List historical checks for a monitor, optionally filtered by status and bounded by a result limit. Returns one page of check summaries and pagination metadata.
 `,
-    parameters: z.object({
-      id: z.string(),
-      limit: z.number().int().positive().optional(),
-      offset: z.number().int().nonnegative().optional(),
+    parameters: z2.object({
+      id: z2.string(),
+      limit: z2.number().int().positive().optional(),
+      offset: z2.number().int().nonnegative().optional(),
       status: checkStatusSchema.optional()
     }),
     execute: async (args2, { session }) => {
@@ -422,11 +478,11 @@ Retrieve one monitor check and its page-level results, optionally filtered by pa
 
 Markdown tracking returns a unified text diff, JSON tracking returns field paths with previous/current values and a current snapshot, and mixed tracking returns both. Returns one page of results plus a \`next\` URL when more pages exist.
 `,
-    parameters: z.object({
-      id: z.string(),
-      checkId: z.string(),
-      limit: z.number().int().positive().optional(),
-      skip: z.number().int().nonnegative().optional(),
+    parameters: z2.object({
+      id: z2.string(),
+      checkId: z2.string(),
+      limit: z2.number().int().positive().optional(),
+      skip: z2.number().int().nonnegative().optional(),
       pageStatus: pageStatusSchema.optional()
     }),
     execute: async (args2, { session }) => {
@@ -442,9 +498,9 @@ Markdown tracking returns a unified text diff, JSON tracking returns field paths
 }
 
 // src/research.ts
-import { z as z2 } from "zod";
-var BASE = "/v2/search/research";
-var ORIGIN_HEADERS = { "X-Origin": "mcp-fastmcp" };
+import { z as z3 } from "zod";
+var BASE2 = "/v2/search/research";
+var ORIGIN_HEADERS2 = { "X-Origin": "mcp-fastmcp" };
 function appendParam(params, key, value) {
   if (value == null) return;
   if (Array.isArray(value)) {
@@ -566,21 +622,21 @@ For topics represented in the indexed corpus, search paper metadata and abstract
 
 Returns ranked papers with canonical IDs, titles, authors, and abstracts.
 `,
-    parameters: z2.object({
-      query: z2.string().min(1).describe(
+    parameters: z3.object({
+      query: z3.string().min(1).describe(
         "Natural-language research topic or question, including methods, systems, conditions, populations, interventions, or outcomes when relevant."
       ),
-      k: z2.number().int().min(1).max(500).optional().describe("Number of ranked papers to return (default 40)."),
-      authors: z2.array(z2.string()).optional().describe(
+      k: z3.number().int().min(1).max(500).optional().describe("Number of ranked papers to return (default 40)."),
+      authors: z3.array(z3.string()).optional().describe(
         "Author substring filter(s); ALL must match (case-insensitive)."
       ),
-      categories: z2.array(z2.string()).optional().describe(
+      categories: z3.array(z3.string()).optional().describe(
         "Paper category filter(s) (e.g. `cs.LG`); ALL provided values must match."
       ),
-      from: z2.string().optional().describe(
+      from: z3.string().optional().describe(
         "Inclusive lower bound on created/updated date (`YYYY-MM-DD`)."
       ),
-      to: z2.string().optional().describe(
+      to: z3.string().optional().describe(
         "Inclusive upper bound on created/updated date (`YYYY-MM-DD`)."
       )
     }),
@@ -595,8 +651,8 @@ Returns ranked papers with canonical IDs, titles, authors, and abstracts.
       appendParam(params, "to", to);
       const client = getClient2(session);
       const res = await client.http.get(
-        withQuery(`${BASE}/papers`, params),
-        ORIGIN_HEADERS
+        withQuery(`${BASE2}/papers`, params),
+        ORIGIN_HEADERS2
       );
       return fmtHits(res.data?.results);
     }
@@ -615,8 +671,8 @@ Returns ranked papers with canonical IDs, titles, authors, and abstracts.
     description: `
 Retrieve canonical metadata for one paper ID, such as an arXiv, PMC, PMID, or DOI identifier. Returns the title, abstract, authors, categories, source IDs, and dates as markdown.
 `,
-    parameters: z2.object({
-      paperId: z2.string().min(1).describe(
+    parameters: z3.object({
+      paperId: z3.string().min(1).describe(
         "Canonical paperId or primaryId such as `arxiv:1706.03762`, `pmcid:PMC12530322`, `pmid:40953549`, or `doi:10.1016/j.neunet.2025.108095`."
       )
     }),
@@ -624,8 +680,8 @@ Retrieve canonical metadata for one paper ID, such as an arXiv, PMC, PMID, or DO
       const { paperId } = args2;
       const client = getClient2(session);
       const res = await client.http.get(
-        `${BASE}/papers/${encodeURIComponent(paperId)}`,
-        ORIGIN_HEADERS
+        `${BASE2}/papers/${encodeURIComponent(paperId)}`,
+        ORIGIN_HEADERS2
       );
       return fmtPaperMetadata(res.data?.paper);
     }
@@ -646,12 +702,12 @@ Find citation-graph candidates from one to ten \`seed_ids\`; the first ID is the
 
 Returns ranked candidates and the evaluated pool size.
 `,
-    parameters: z2.object({
-      seed_ids: z2.array(z2.string()).min(1).max(10),
-      intent: z2.string().min(1),
-      mode: z2.enum(["similar", "citers", "references"]).optional(),
-      k: z2.number().int().min(1).max(500).optional(),
-      rerank: z2.boolean().optional().describe("Apply an additional rerank over the fused candidates.")
+    parameters: z3.object({
+      seed_ids: z3.array(z3.string()).min(1).max(10),
+      intent: z3.string().min(1),
+      mode: z3.enum(["similar", "citers", "references"]).optional(),
+      k: z3.number().int().min(1).max(500).optional(),
+      rerank: z3.boolean().optional().describe("Apply an additional rerank over the fused candidates.")
     }),
     execute: async (args2, { session }) => {
       const { seed_ids, intent, mode, k, rerank } = args2;
@@ -665,10 +721,10 @@ Returns ranked candidates and the evaluated pool size.
       const client = getClient2(session);
       const res = await client.http.get(
         withQuery(
-          `${BASE}/papers/${encodeURIComponent(primary)}/similar`,
+          `${BASE2}/papers/${encodeURIComponent(primary)}/similar`,
           params
         ),
-        ORIGIN_HEADERS
+        ORIGIN_HEADERS2
       );
       const note = res.data?.note ? `
 note: ${res.data.note}` : "";
@@ -692,12 +748,12 @@ Retrieve in-body passages from one paper that are relevant to a specific questio
 
 Returns matching passages or a notice when full text is unavailable.
 `,
-    parameters: z2.object({
-      paperId: z2.string().min(1).describe(
+    parameters: z3.object({
+      paperId: z3.string().min(1).describe(
         "Canonical paperId or primaryId such as `arxiv:1706.03762`, `pmcid:PMC12530322`, `pmid:40953549`, or `doi:10.1016/j.neunet.2025.108095`."
       ),
-      question: z2.string().min(1),
-      k: z2.number().int().min(1).max(50).optional().describe("Number of passages to return (default 4).")
+      question: z3.string().min(1),
+      k: z3.number().int().min(1).max(50).optional().describe("Number of passages to return (default 4).")
     }),
     execute: async (args2, { session }) => {
       const { paperId, question, k } = args2;
@@ -706,8 +762,8 @@ Returns matching passages or a notice when full text is unavailable.
       appendParam(params, "k", k);
       const client = getClient2(session);
       const res = await client.http.get(
-        withQuery(`${BASE}/papers/${encodeURIComponent(paperId)}`, params),
-        ORIGIN_HEADERS
+        withQuery(`${BASE2}/papers/${encodeURIComponent(paperId)}`, params),
+        ORIGIN_HEADERS2
       );
       const passages = res.data?.passages ?? [];
       return passages.length ? passages.map((p) => p.text).join("\n---\n") : "(no full-text passages available for this paper)";
@@ -727,9 +783,9 @@ Returns matching passages or a notice when full text is unavailable.
     description: `
 Search indexed public GitHub issue, pull-request, and README content. Returns ranked matches with repository, URL, snippet, and full matched markdown when available.
 `,
-    parameters: z2.object({
-      query: z2.string().min(1),
-      k: z2.number().int().min(1).max(100).optional()
+    parameters: z3.object({
+      query: z3.string().min(1),
+      k: z3.number().int().min(1).max(100).optional()
     }),
     execute: async (args2, { session }) => {
       const { query, k } = args2;
@@ -738,8 +794,8 @@ Search indexed public GitHub issue, pull-request, and README content. Returns ra
       appendParam(params, "k", k);
       const client = getClient2(session);
       const res = await client.http.get(
-        withQuery(`${BASE}/github`, params),
-        ORIGIN_HEADERS
+        withQuery(`${BASE2}/github`, params),
+        ORIGIN_HEADERS2
       );
       return fmtGithub(res.data?.results);
     }
@@ -1160,7 +1216,7 @@ function removeEmptyTopLevel(obj) {
   }
   return out;
 }
-var searchDomainSchema = z3.string().trim().toLowerCase().min(1).max(253).regex(
+var searchDomainSchema = z4.string().trim().toLowerCase().min(1).max(253).regex(
   /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$/,
   "Domain must be a valid hostname without protocol or path"
 );
@@ -1174,21 +1230,21 @@ function buildSearchQueryWithDomains(query, includeDomains, excludeDomains) {
   return query;
 }
 var searchToolBaseFields = {
-  query: z3.string().min(1),
-  highlights: z3.boolean().optional().describe(
+  query: z4.string().min(1),
+  highlights: z4.boolean().optional().describe(
     "Return query-relevant highlights for each search result. Set to false to keep the original search snippets."
   ),
-  limit: z3.number().optional(),
-  tbs: z3.string().optional(),
-  filter: z3.string().optional(),
-  location: z3.string().optional(),
-  includeDomains: z3.array(searchDomainSchema).optional(),
-  excludeDomains: z3.array(searchDomainSchema).optional(),
-  sources: z3.array(z3.object({ type: z3.enum(["web", "images", "news"]) })).optional(),
-  categories: z3.array(z3.enum(["github", "research", "pdf"])).optional().describe(
-    "Limit results to specific source types. `github` searches GitHub repositories, code, issues, and docs; `research` searches academic and research sources; `pdf` searches PDF results."
+  limit: z4.number().optional(),
+  tbs: z4.string().optional(),
+  filter: z4.string().optional(),
+  location: z4.string().optional(),
+  includeDomains: z4.array(searchDomainSchema).optional(),
+  excludeDomains: z4.array(searchDomainSchema).optional(),
+  sources: z4.array(z4.object({ type: z4.enum(["web", "images", "news"]) })).optional(),
+  categories: z4.array(z4.enum(["github", "research", "pdf", "developer"])).optional().describe(
+    "Limit results to specific source types. `github` searches GitHub repositories, code, issues, and docs; `research` searches academic and research sources; `pdf` searches PDF results; `developer` searches an index built for coding agents over GitHub issues, merged pull requests, repository READMEs, and curated documentation sites. `developer` adds a `data.developer` group of `{ url, title, description }` results, where `description` holds the matched passage; the other categories filter `data.web`."
   ),
-  enterprise: z3.array(z3.enum(["default", "anon", "zdr"])).optional()
+  enterprise: z4.array(z4.enum(["default", "anon", "zdr"])).optional()
 };
 function searchDomainsAreExclusive(args2) {
   return !(args2.includeDomains?.length && args2.excludeDomains?.length);
@@ -1227,9 +1283,10 @@ var openAiAppsChallengeToken = normalizeHeader(
 );
 var FULL_PROFILE_INSTRUCTIONS = `Firecrawl provides web search, page retrieval, site URL discovery, multi-page collection, structured extraction, monitoring, and asynchronous research. Match the requested operation to the tool boundary: firecrawl_scrape retrieves one supplied page, firecrawl_map enumerates URLs under a site without retrieving their content, and firecrawl_agent starts multi-source research whose result is read with firecrawl_agent_status. Provide only the required inputs and account for stated network or external side effects.`;
 var KEYLESS_PROFILE_INSTRUCTIONS = `Without authentication, this endpoint exposes Search, Scrape, and Parse with usage limits. An OAuth connection or Authorization bearer API key exposes account tools; unavailable tools return connection guidance. Firecrawl provides web search, page retrieval, site URL discovery, multi-page collection, structured extraction, monitoring, and asynchronous research. Match the requested operation to the tool boundary: firecrawl_scrape retrieves one supplied page, firecrawl_map enumerates URLs under a site without retrieving their content, and firecrawl_agent starts multi-source research whose result is read with firecrawl_agent_status. Provide only the required inputs.`;
-var SEARCH_PROFILE_INSTRUCTIONS = `Firecrawl provides web and research search. Use firecrawl_search to find relevant results across the web and specialized indexes. Use the firecrawl_research_* tools to search academic and research literature, expand from anchor papers via the citation graph, read full-text passages from a specific paper, and search public code repositories. All tools are read-only and return ranked results.`;
+var SEARCH_PROFILE_INSTRUCTIONS = `Firecrawl provides web, developer, and research search. Use firecrawl_search to find relevant results across the web and specialized indexes. For a programming question, call firecrawl_developer_search \u2014 or firecrawl_search with categories: ["developer"] \u2014 to search indexed GitHub issues, merged pull requests, READMEs, and documentation. Use the firecrawl_research_* tools to search academic and research literature, expand from anchor papers via the citation graph, read full-text passages from a specific paper, and search public code repositories. All tools are read-only and return ranked results.`;
 var SEARCH_PROFILE_TOOLS = /* @__PURE__ */ new Set([
   "firecrawl_search",
+  "firecrawl_developer_search",
   "firecrawl_research_search_papers",
   "firecrawl_research_inspect_paper",
   "firecrawl_research_related_papers",
@@ -1318,24 +1375,34 @@ var KEYLESS_TOOL_NAMES = /* @__PURE__ */ new Set([
 function isHostedKeylessSession(session) {
   return process.env.CLOUD_SERVICE === "true" && session?.authType === "keyless" && !session.firecrawlApiKey;
 }
-function recoveryPayload(code, requestId = randomUUID()) {
+function isLocalKeylessStartup() {
+  return process.env.CLOUD_SERVICE !== "true" && !isHttpStreamingTransport() && !resolveCredentialFromEnv() && !normalizeHeader(process.env.FIRECRAWL_API_URL);
+}
+function recoveryPayload(code, requestId = randomUUID(), options = {}) {
+  const retryAfterSeconds = options.retryAfterSeconds;
+  const isQuotaExhausted = code === "KEYLESS_QUOTA_EXHAUSTED" || code === "KEYLESS_LIMIT_REACHED";
+  const isToolUnavailable = code === "KEYLESS_TOOL_NOT_AVAILABLE";
+  const isKeylessAccessUnavailable = code === "KEYLESS_ACCESS_NOT_AVAILABLE";
+  const isKeylessEligibilityUnavailable = code === "KEYLESS_ELIGIBILITY_UNAVAILABLE";
+  const oauthUrl = "https://mcp.firecrawl.dev/v2/mcp-oauth";
   return {
     code,
     request_id: requestId,
     auth_mode: code === "CREDENTIAL_INVALID" ? "credential_error" : "keyless",
-    message: code === "CREDENTIAL_INVALID" ? "The supplied Firecrawl credential is invalid or revoked. Replace it or reconnect the account, then retry." : "This tool requires a Firecrawl account or API key. Connect an account or configure Authorization: Bearer <FIRECRAWL_API_KEY>, then retry.",
-    available_tools: [...KEYLESS_TOOL_NAMES],
+    message: code === "CREDENTIAL_INVALID" ? "The supplied Firecrawl credential is invalid or revoked. Replace it or reconnect the account, then retry." : isQuotaExhausted ? `The free daily limit for this network has been reached${retryAfterSeconds ? `; try again in about ${retryAfterSeconds} seconds` : ""}. To continue now, connect a Firecrawl account via OAuth or configure an API key.` : isToolUnavailable ? "The free tier includes Search, Scrape, and Parse. This tool needs a connected account; Search, Scrape, and Parse still work, so no action is required." : isKeylessAccessUnavailable ? "Anonymous keyless access is unavailable for this request. To continue, connect a Firecrawl account via OAuth or configure an API key." : isKeylessEligibilityUnavailable ? "The anonymous keyless eligibility check is temporarily unavailable. Retry shortly." : "This tool requires a Firecrawl account or API key. Connect an account or configure Authorization: Bearer <FIRECRAWL_API_KEY>, then retry.",
+    ...isKeylessAccessUnavailable ? {} : { available_tools: [...KEYLESS_TOOL_NAMES] },
     docs_url: "https://docs.firecrawl.dev/mcp-server",
-    next_actions: [
-      { kind: "connect_account", url: "https://firecrawl.dev/connect/mcp" },
-      {
-        kind: "configure_api_key",
-        header: "Authorization: Bearer <FIRECRAWL_API_KEY>"
-      }
+    ...retryAfterSeconds ? { retry_after_seconds: retryAfterSeconds } : {},
+    next_actions: isKeylessEligibilityUnavailable ? [{ kind: "retry_later", after_seconds: 30 }] : isQuotaExhausted || isKeylessAccessUnavailable ? [
+      { kind: "connect_oauth", url: oauthUrl, client_commands: [{ client: "claude-code", command: "claude mcp add --transport http firecrawl https://mcp.firecrawl.dev/v2/mcp-oauth" }] },
+      { kind: "configure_api_key", header: "Authorization: Bearer <FIRECRAWL_API_KEY>" }
+    ] : isToolUnavailable ? [{ kind: "continue_keyless", tools: [...KEYLESS_TOOL_NAMES] }] : [
+      { kind: "connect_oauth", url: oauthUrl },
+      { kind: "configure_api_key", header: "Authorization: Bearer <FIRECRAWL_API_KEY>" }
     ]
   };
 }
-function emitActionLog(toolName, status, session, error, requestId = randomUUID()) {
+function emitActionLog(toolName, status, session, error, requestId = randomUUID(), code) {
   if (process.env.CLOUD_SERVICE !== "true") return;
   const payload = {
     team_id: session?.teamId,
@@ -1347,20 +1414,23 @@ function emitActionLog(toolName, status, session, error, requestId = randomUUID(
     status,
     request_id: requestId,
     resource: primaryProfile.resourceUrl,
-    ...error ? { error_class: error instanceof Error ? error.name : typeof error } : {}
+    ...error ? { error_class: error instanceof Error ? error.name : typeof error } : {},
+    ...code ? { code } : {}
   };
   console.error("[MCP_ACTION]", JSON.stringify(payload));
   const secret = normalizeHeader(process.env.FIRECRAWL_MCP_ACTION_LOG_SECRET);
   const apiUrl = normalizeHeader(process.env.FIRECRAWL_API_URL);
   const endpoint = normalizeHeader(process.env.FIRECRAWL_MCP_ACTION_LOG_URL) ?? (apiUrl ? `${withoutTrailingSlash(apiUrl)}/v2/mcp/action-logs` : void 0);
   if (!secret || !endpoint || !payload.team_id || status === "started") return;
+  const actionLogPayload = { ...payload };
+  delete actionLogPayload.code;
   void fetch(endpoint, {
     method: "POST",
     headers: {
       Authorization: `Bearer ${secret}`,
       "Content-Type": "application/json"
     },
-    body: JSON.stringify(payload),
+    body: JSON.stringify(actionLogPayload),
     signal: AbortSignal.timeout(1500)
   }).catch(() => void 0);
 }
@@ -1373,7 +1443,11 @@ function guardHostedTool(tool, { logActions }) {
     beforeValidate: (_args, session) => {
       const code = session?.credentialError ? "CREDENTIAL_INVALID" : isHostedKeylessSession(session) && !keylessTool ? "KEYLESS_TOOL_NOT_AVAILABLE" : void 0;
       if (!code) return void 0;
-      const payload = recoveryPayload(code);
+      const requestId = randomUUID();
+      const payload = recoveryPayload(code, requestId);
+      if (logActions) {
+        emitActionLog(tool.name, "error", session, new UserError(String(payload.message), payload), requestId, code);
+      }
       return {
         content: [{ type: "text", text: String(payload.message) }],
         isError: true,
@@ -1392,11 +1466,15 @@ function guardHostedTool(tool, { logActions }) {
         session: invocationSession
       };
       if (invocationSession.credentialError) {
-        const payload = recoveryPayload("CREDENTIAL_INVALID", requestId);
+        const code = "CREDENTIAL_INVALID";
+        const payload = recoveryPayload(code, requestId);
+        if (logActions) emitActionLog(tool.name, "error", invocationSession, new UserError(String(payload.message), payload), requestId, code);
         throw new UserError(String(payload.message), payload);
       }
       if (isHostedKeylessSession(invocationSession) && !keylessTool) {
-        const payload = recoveryPayload("KEYLESS_TOOL_NOT_AVAILABLE", requestId);
+        const code = "KEYLESS_TOOL_NOT_AVAILABLE";
+        const payload = recoveryPayload(code, requestId);
+        if (logActions) emitActionLog(tool.name, "error", invocationSession, new UserError(String(payload.message), payload), requestId, code);
         throw new UserError(String(payload.message), payload);
       }
       if (!logActions) return execute(args2, invocationContext);
@@ -1465,7 +1543,7 @@ function createClient(apiKey) {
   return new FirecrawlApp(config);
 }
 var ORIGIN = "mcp-fastmcp";
-var ORIGIN_HEADERS2 = { "X-Origin": ORIGIN };
+var ORIGIN_HEADERS3 = { "X-Origin": ORIGIN };
 var SAFE_MODE = process.env.CLOUD_SERVICE === "true";
 function getClient(session) {
   if (process.env.CLOUD_SERVICE === "true" && !hasCredential(session)) {
@@ -1563,10 +1641,10 @@ function transformScrapeParams(args2) {
   delete out.pdfOptions;
   return out;
 }
-var scrapeParamsSchema = z3.object({
-  url: z3.string().url(),
-  formats: z3.array(
-    z3.enum([
+var scrapeParamsSchema = z4.object({
+  url: z4.string().url(),
+  formats: z4.array(
+    z4.enum([
       "markdown",
       "html",
       "rawHtml",
@@ -1580,62 +1658,62 @@ var scrapeParamsSchema = z3.object({
       "audio"
     ])
   ).optional(),
-  jsonOptions: z3.object({
-    prompt: z3.string().optional(),
-    schema: z3.record(z3.string(), z3.any()).optional()
+  jsonOptions: z4.object({
+    prompt: z4.string().optional(),
+    schema: z4.record(z4.string(), z4.any()).optional()
   }).optional(),
-  queryOptions: z3.object({
-    prompt: z3.string().max(1e4),
-    mode: z3.enum(["directQuote", "freeform"]).default("freeform")
+  queryOptions: z4.object({
+    prompt: z4.string().max(1e4),
+    mode: z4.enum(["directQuote", "freeform"]).default("freeform")
   }).optional(),
-  screenshotOptions: z3.object({
-    fullPage: z3.boolean().optional(),
-    quality: z3.number().optional(),
-    viewport: z3.object({ width: z3.number(), height: z3.number() }).optional()
+  screenshotOptions: z4.object({
+    fullPage: z4.boolean().optional(),
+    quality: z4.number().optional(),
+    viewport: z4.object({ width: z4.number(), height: z4.number() }).optional()
   }).optional(),
-  parsers: z3.array(z3.enum(["pdf"])).optional(),
-  pdfOptions: z3.object({
-    maxPages: z3.number().int().min(1).max(1e4).optional()
+  parsers: z4.array(z4.enum(["pdf"])).optional(),
+  pdfOptions: z4.object({
+    maxPages: z4.number().int().min(1).max(1e4).optional()
   }).optional(),
-  onlyMainContent: z3.boolean().optional(),
-  redactPII: z3.boolean().optional(),
-  includeTags: z3.array(z3.string()).optional(),
-  excludeTags: z3.array(z3.string()).optional(),
-  waitFor: z3.number().optional(),
+  onlyMainContent: z4.boolean().optional(),
+  redactPII: z4.boolean().optional(),
+  includeTags: z4.array(z4.string()).optional(),
+  excludeTags: z4.array(z4.string()).optional(),
+  waitFor: z4.number().optional(),
   ...SAFE_MODE ? {} : {
-    actions: z3.array(
-      z3.object({
-        type: z3.enum(allowedActionTypes),
-        selector: z3.string().optional(),
-        milliseconds: z3.number().optional(),
-        text: z3.string().optional(),
-        key: z3.string().optional(),
-        direction: z3.enum(["up", "down"]).optional(),
-        script: z3.string().optional(),
-        fullPage: z3.boolean().optional()
+    actions: z4.array(
+      z4.object({
+        type: z4.enum(allowedActionTypes),
+        selector: z4.string().optional(),
+        milliseconds: z4.number().optional(),
+        text: z4.string().optional(),
+        key: z4.string().optional(),
+        direction: z4.enum(["up", "down"]).optional(),
+        script: z4.string().optional(),
+        fullPage: z4.boolean().optional()
       })
     ).optional()
   },
-  mobile: z3.boolean().optional(),
-  skipTlsVerification: z3.boolean().optional(),
-  removeBase64Images: z3.boolean().optional(),
-  location: z3.object({
-    country: z3.string().optional(),
-    languages: z3.array(z3.string()).optional()
+  mobile: z4.boolean().optional(),
+  skipTlsVerification: z4.boolean().optional(),
+  removeBase64Images: z4.boolean().optional(),
+  location: z4.object({
+    country: z4.string().optional(),
+    languages: z4.array(z4.string()).optional()
   }).optional(),
-  storeInCache: z3.boolean().optional(),
-  zeroDataRetention: z3.boolean().optional(),
-  maxAge: z3.number().optional(),
-  lockdown: z3.boolean().optional(),
-  proxy: z3.enum(["basic", "stealth", "enhanced", "auto"]).optional(),
-  profile: z3.object({
-    name: z3.string(),
-    saveChanges: z3.boolean().optional()
+  storeInCache: z4.boolean().optional(),
+  zeroDataRetention: z4.boolean().optional(),
+  maxAge: z4.number().optional(),
+  lockdown: z4.boolean().optional(),
+  proxy: z4.enum(["basic", "stealth", "enhanced", "auto"]).optional(),
+  profile: z4.object({
+    name: z4.string(),
+    saveChanges: z4.boolean().optional()
   }).optional()
 });
-var parseOptionParamsSchema = z3.object({
-  formats: z3.array(
-    z3.enum([
+var parseOptionParamsSchema = z4.object({
+  formats: z4.array(
+    z4.enum([
       "markdown",
       "html",
       "rawHtml",
@@ -1645,48 +1723,48 @@ var parseOptionParamsSchema = z3.object({
       "query"
     ])
   ).optional(),
-  jsonOptions: z3.object({
-    prompt: z3.string().optional(),
-    schema: z3.record(z3.string(), z3.any()).optional()
+  jsonOptions: z4.object({
+    prompt: z4.string().optional(),
+    schema: z4.record(z4.string(), z4.any()).optional()
   }).optional(),
-  queryOptions: z3.object({
-    prompt: z3.string().max(1e4),
-    mode: z3.enum(["directQuote", "freeform"]).default("freeform")
+  queryOptions: z4.object({
+    prompt: z4.string().max(1e4),
+    mode: z4.enum(["directQuote", "freeform"]).default("freeform")
   }).optional(),
-  parsers: z3.array(z3.enum(["pdf"])).optional(),
-  pdfOptions: z3.object({
-    maxPages: z3.number().int().min(1).max(1e4).optional()
+  parsers: z4.array(z4.enum(["pdf"])).optional(),
+  pdfOptions: z4.object({
+    maxPages: z4.number().int().min(1).max(1e4).optional()
   }).optional(),
-  onlyMainContent: z3.boolean().optional(),
-  redactPII: z3.boolean().optional(),
-  includeTags: z3.array(z3.string()).optional(),
-  excludeTags: z3.array(z3.string()).optional(),
-  removeBase64Images: z3.boolean().optional(),
-  skipTlsVerification: z3.boolean().optional(),
-  storeInCache: z3.boolean().optional(),
-  zeroDataRetention: z3.boolean().optional(),
-  maxAge: z3.number().optional(),
-  proxy: z3.enum(["basic", "auto"]).optional()
+  onlyMainContent: z4.boolean().optional(),
+  redactPII: z4.boolean().optional(),
+  includeTags: z4.array(z4.string()).optional(),
+  excludeTags: z4.array(z4.string()).optional(),
+  removeBase64Images: z4.boolean().optional(),
+  skipTlsVerification: z4.boolean().optional(),
+  storeInCache: z4.boolean().optional(),
+  zeroDataRetention: z4.boolean().optional(),
+  maxAge: z4.number().optional(),
+  proxy: z4.enum(["basic", "auto"]).optional()
 });
 var localParseParamsSchema = parseOptionParamsSchema.extend({
-  filePath: z3.string().min(1).describe(
+  filePath: z4.string().min(1).describe(
     "Absolute or relative path to a local file to parse. Supported: .html, .htm, .pdf, .docx, .doc, .odt, .rtf, .xlsx, .xls"
   ),
-  contentType: z3.string().optional().describe(
+  contentType: z4.string().optional().describe(
     "Optional MIME type override. If omitted, the server infers the file kind from the extension."
   )
 });
 var hostedParseParamsSchema = parseOptionParamsSchema.extend({
-  filePath: z3.string().min(1).optional().describe(
+  filePath: z4.string().min(1).optional().describe(
     "Phase 1 only: path to the local file on the caller/harness machine. Hosted MCP will not read or stat this path; it is used only to produce upload instructions."
   ),
-  uploadRef: z3.string().min(1).optional().describe(
+  uploadRef: z4.string().min(1).optional().describe(
     "Phase 2 only: short-lived upload reference returned by phase 1 after the local PUT upload completes."
   ),
-  contentType: z3.string().optional().describe(
+  contentType: z4.string().optional().describe(
     "Phase 1 MIME type override. If omitted, the server infers it from the file extension without reading the file."
   ),
-  declaredSizeBytes: z3.number().int().positive().optional().describe(
+  declaredSizeBytes: z4.number().int().positive().optional().describe(
     "Optional phase 1 size declaration. Hosted MCP does not stat the file; provide this only if the caller already knows it."
   )
 }).superRefine((value, ctx) => {
@@ -1694,7 +1772,7 @@ var hostedParseParamsSchema = parseOptionParamsSchema.extend({
   const hasUploadRef = typeof value.uploadRef === "string" && value.uploadRef.length > 0;
   if (hasFilePath === hasUploadRef) {
     ctx.addIssue({
-      code: z3.ZodIssueCode.custom,
+      code: z4.ZodIssueCode.custom,
       message: "Hosted firecrawl_parse requires exactly one of filePath (phase 1) or uploadRef (phase 2).",
       path: hasFilePath && hasUploadRef ? ["uploadRef"] : ["filePath"]
     });
@@ -1953,13 +2031,13 @@ Enumerate URLs indexed under one website through Firecrawl without fetching each
 
 Returns matching URLs rather than page bodies. Retrieve one page with \`firecrawl_scrape\`; collect content across multiple pages with \`firecrawl_crawl\`.
 `,
-  parameters: z3.object({
-    url: z3.string().url(),
-    search: z3.string().optional(),
-    sitemap: z3.enum(["include", "skip", "only"]).optional(),
-    includeSubdomains: z3.boolean().optional(),
-    limit: z3.number().optional(),
-    ignoreQueryParameters: z3.boolean().optional()
+  parameters: z4.object({
+    url: z4.string().url(),
+    search: z4.string().optional(),
+    sitemap: z4.enum(["include", "skip", "only"]).optional(),
+    includeSubdomains: z4.boolean().optional(),
+    limit: z4.number().optional(),
+    ignoreQueryParameters: z4.boolean().optional()
   }),
   execute: async (args2, { session, log }) => {
     const { url, ...options } = args2;
@@ -1985,11 +2063,13 @@ server.addTool({
     // Query-only; no destructive side effects on external entities.
   },
   description: `
-Search web, news, or image sources and return ranked results. Operators include quoted phrases, \`-term\`, \`site:host\`, \`inurl:term\`, \`intitle:term\`, and \`related:host\`; the set is non-exhaustive. \`includeDomains\` and \`excludeDomains\` are mutually exclusive hostname filters; categories limit results to GitHub, research, or PDF sources.
+Search web, news, or image sources and return ranked results. Operators include quoted phrases, \`-term\`, \`site:host\`, \`inurl:term\`, \`intitle:term\`, and \`related:host\`; the set is non-exhaustive. \`includeDomains\` and \`excludeDomains\` are mutually exclusive hostname filters; categories limit results to GitHub, research, PDF, or developer sources.
 
-\`scrapeOptions\` can attach extracted page content. Returns source-type result groups, an \`id\` for optional search feedback, and usage metadata.
+For a programming question, add \`categories: ["developer"]\`. It searches an index of GitHub issues, merged pull requests, repository READMEs, and curated documentation sites, and returns the hits in \`data.developer\` beside the web results.
+
+\`scrapeOptions\` can attach extracted page content. Returns source-type result groups and usage metadata. Authenticated responses can include an \`id\` for optional search feedback.
 `,
-  parameters: z3.object({
+  parameters: z4.object({
     ...searchToolBaseFields,
     scrapeOptions: scrapeParamsSchema.omit({ url: true }).partial().optional()
   }).refine(searchDomainsAreExclusive, SEARCH_DOMAINS_CONFLICT_MESSAGE),
@@ -2019,7 +2099,9 @@ Search web, news, or image sources and return ranked results. Operators include
     };
     if (isKeylessMode(session)) {
       const json = await keylessPost("/v2/search", searchBody, session);
-      return asText2(json ?? {});
+      const keylessResponse = { ...json ?? {} };
+      delete keylessResponse.id;
+      return asText2(keylessResponse);
     }
     const client = getClient(session);
     const httpRes = await client.http.post("/v2/search", searchBody);
@@ -2036,25 +2118,35 @@ function resolveApiBaseUrl() {
 function extractClientIp(request) {
   return extractSingleTrustedClientIp(request?.headers?.["x-forwarded-for"]);
 }
+function keylessQuotaReason(reason) {
+  return reason === "requests" || reason === "credits";
+}
 async function keylessEligible(clientIp) {
   const secret = process.env.KEYLESS_PROXY_SECRET;
-  if (!secret) return false;
+  if (!secret) return { eligible: false, unavailable: true };
   try {
     const response = await fetch(
       `${resolveApiBaseUrl()}/v2/keyless/eligibility`,
       {
         headers: {
-          ...ORIGIN_HEADERS2,
+          ...ORIGIN_HEADERS3,
           "x-firecrawl-keyless-ip": clientIp,
           "x-firecrawl-keyless-secret": secret
         }
       }
     );
-    if (!response.ok) return false;
-    const json = await response.json().catch(() => ({}));
-    return json?.eligible === true;
+    if (!response.ok) return { eligible: false, unavailable: true };
+    const json = await response.json().catch(() => null);
+    if (typeof json?.eligible !== "boolean") {
+      return { eligible: false, unavailable: true };
+    }
+    return {
+      eligible: json?.eligible === true,
+      ...typeof json?.reason === "string" ? { reason: json.reason } : {},
+      ...Number.isFinite(json?.retryAfterSeconds) && json.retryAfterSeconds > 0 ? { retryAfterSeconds: json.retryAfterSeconds } : {}
+    };
   } catch {
-    return false;
+    return { eligible: false, unavailable: true };
   }
 }
 function isKeylessMode(session) {
@@ -2065,15 +2157,18 @@ function isKeylessMode(session) {
   return !process.env.FIRECRAWL_API_URL;
 }
 async function keylessPost(path2, body, session) {
-  if (isHostedKeylessSession(session) && (!session?.keylessClientIp || !await keylessEligible(session.keylessClientIp))) {
-    const payload = recoveryPayload(
-      "KEYLESS_ACCESS_NOT_AVAILABLE",
-      session?.requestId
-    );
-    throw new UserError(String(payload.message), payload);
+  if (isHostedKeylessSession(session)) {
+    const eligibility = session?.keylessClientIp ? await keylessEligible(session.keylessClientIp) : { eligible: false };
+    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
+      });
+      throw new UserError(String(payload.message), payload);
+    }
   }
   const headers = {
-    ...ORIGIN_HEADERS2,
+    ...ORIGIN_HEADERS3,
     "Content-Type": "application/json"
   };
   if (session?.keylessClientIp && process.env.KEYLESS_PROXY_SECRET) {
@@ -2087,11 +2182,11 @@ async function keylessPost(path2, body, session) {
   });
   const json = await response.json().catch(() => ({}));
   if (!response.ok) {
-    if (isHostedKeylessSession(session) && [401, 402, 429].includes(response.status)) {
-      const payload = recoveryPayload(
-        "KEYLESS_QUOTA_EXHAUSTED",
-        session?.requestId
-      );
+    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
+      });
       throw new UserError(String(payload.message), payload);
     }
     throw new Error(
@@ -2103,7 +2198,7 @@ async function keylessPost(path2, body, session) {
 async function getCrawlStatusWithOrigin(client, jobId) {
   const res = await client.http.get(
     `/v2/crawl/${encodeURIComponent(jobId)}`,
-    ORIGIN_HEADERS2
+    ORIGIN_HEADERS3
   );
   const body = res?.data ?? {};
   const initialDocs = Array.isArray(body.data) ? body.data : [];
@@ -2122,7 +2217,7 @@ async function getCrawlStatusWithOrigin(client, jobId) {
   const docs = initialDocs.slice();
   let current = body.next;
   while (current) {
-    const pageRes = await client.http.get(current, ORIGIN_HEADERS2);
+    const pageRes = await client.http.get(current, ORIGIN_HEADERS3);
     const payload = pageRes?.data ?? {};
     if (!payload.success) break;
     const pageData = Array.isArray(payload.data) ? payload.data : payload.data?.pages || [];
@@ -2155,17 +2250,17 @@ async function waitForCrawlCompletionWithOrigin(client, jobId, pollInterval = 2,
     );
   }
 }
-var feedbackIssueSchema = z3.string().trim().min(1).max(80).regex(
+var feedbackIssueSchema = z4.string().trim().min(1).max(80).regex(
   /^[a-z0-9][a-z0-9_-]*$/,
   "Issue codes must use lowercase letters, numbers, underscores, or hyphens"
 );
-var valuableSourceSchema = z3.object({
-  url: z3.string().url(),
-  reason: z3.string().max(1e3).optional()
+var valuableSourceSchema = z4.object({
+  url: z4.string().url(),
+  reason: z4.string().max(1e3).optional()
 });
-var missingContentSchema = z3.object({
-  topic: z3.string().min(1, "topic must not be empty").max(200, "topic must be 200 characters or fewer"),
-  description: z3.string().max(2e3).optional()
+var missingContentSchema = z4.object({
+  topic: z4.string().min(1, "topic must not be empty").max(200, "topic must be 200 characters or fewer"),
+  description: z4.string().max(2e3).optional()
 });
 var FEEDBACK_DISABLED_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
 function feedbackEnvEnabled(...keys) {
@@ -2186,7 +2281,7 @@ if (SEARCH_FEEDBACK_DISABLED) {
     "[firecrawl-mcp] Search feedback tool disabled by FIRECRAWL_NO_SEARCH_FEEDBACK; firecrawl_search_feedback will not be registered."
   );
 }
-if (!SEARCH_FEEDBACK_DISABLED) {
+if (!SEARCH_FEEDBACK_DISABLED && !isLocalKeylessStartup()) {
   server.addTool({
     name: "firecrawl_search_feedback",
     annotations: {
@@ -2199,28 +2294,28 @@ if (!SEARCH_FEEDBACK_DISABLED) {
       // Additive only; records feedback and may refund credits, does not delete data.
     },
     description: `
-Records schema-validated quality feedback for a prior \`firecrawl_search\` UUID \`searchId\`. A \`good\` rating requires a valuable source, \`partial\` a valuable source or missing topic, and \`bad\` a missing topic or query suggestion; caps are 50 \`valuableSources\` and 20 \`missingContent\` entries.
+Records schema-validated quality feedback for a prior \`firecrawl_search\` UUID \`searchId\`. A \`good\` rating requires a valuable source, \`partial\` a valuable source or at least one \`missingContent\` entry, and \`bad\` at least one \`missingContent\` entry or a query suggestion; caps are 50 \`valuableSources\` and 20 \`missingContent\` entries.
 
-Eligibility is limited to successful searches within the feedback age window. The record is idempotent per search ID. Returns submission and daily-cap status with accounting fields.
+Eligibility is limited to successful searches within the feedback age window. The record is idempotent per search ID. Eligible first feedback for a search can refund 1 credit; refunds are subject to the team's daily cap. The response reports whether a refund was applied, along with submission and daily-cap status.
 `,
-    parameters: z3.object({
-      searchId: z3.string().uuid("searchId must be the UUID returned by firecrawl_search"),
-      rating: z3.enum(["good", "bad", "partial"]),
-      valuableSources: z3.array(
-        z3.object({
-          url: z3.string().url(),
-          reason: z3.string().max(1e3).optional()
+    parameters: z4.object({
+      searchId: z4.string().uuid("searchId must be the UUID returned by firecrawl_search"),
+      rating: z4.enum(["good", "bad", "partial"]),
+      valuableSources: z4.array(
+        z4.object({
+          url: z4.string().url(),
+          reason: z4.string().max(1e3).optional()
         })
       ).max(50).optional(),
-      missingContent: z3.array(
-        z3.object({
-          topic: z3.string().min(1, "topic must not be empty").max(200, "topic must be 200 characters or fewer"),
-          description: z3.string().max(2e3).optional()
+      missingContent: z4.array(
+        z4.object({
+          topic: z4.string().min(1, "topic must not be empty").max(200, "topic must be 200 characters or fewer"),
+          description: z4.string().max(2e3).optional()
         })
       ).max(20).optional().describe(
         "Array of specific pieces of content the agent expected to find but did not. One entry per distinct topic. Each entry has a short `topic` and optional longer `description`."
       ),
-      querySuggestions: z3.string().max(2e3).optional()
+      querySuggestions: z4.string().max(2e3).optional()
     }),
     execute: async (args2, { session, log }) => {
       const {
@@ -2246,7 +2341,7 @@ Eligibility is limited to successful searches within the feedback age window. Th
       }
       if (querySuggestions) body.querySuggestions = querySuggestions;
       const headers = {
-        ...ORIGIN_HEADERS2,
+        ...ORIGIN_HEADERS3,
         "Content-Type": "application/json"
       };
       const credential = credentialForOutboundRequest(session);
@@ -2290,7 +2385,7 @@ if (ENDPOINT_FEEDBACK_DISABLED) {
     "[firecrawl-mcp] Endpoint feedback tool disabled by FIRECRAWL_NO_ENDPOINT_FEEDBACK; firecrawl_feedback will not be registered."
   );
 }
-if (!ENDPOINT_FEEDBACK_DISABLED) {
+if (!ENDPOINT_FEEDBACK_DISABLED && !isLocalKeylessStartup()) {
   server.addTool({
     name: "firecrawl_feedback",
     annotations: {
@@ -2307,19 +2402,19 @@ Submit concise quality feedback for a completed search, scrape, parse, or map jo
 
 Returns submission status, feedback ID, and accounting fields.
 `,
-    parameters: z3.object({
-      endpoint: z3.enum(["search", "scrape", "parse", "map"]),
-      jobId: z3.string().uuid("jobId must be the UUID returned by Firecrawl"),
-      rating: z3.enum(["good", "bad", "partial"]),
-      issues: z3.array(feedbackIssueSchema).max(20).optional(),
-      tags: z3.array(feedbackIssueSchema).max(20).optional(),
-      note: z3.string().max(4e3).optional(),
-      valuableSources: z3.array(valuableSourceSchema).max(50).optional(),
-      missingContent: z3.array(missingContentSchema).max(50).optional(),
-      querySuggestions: z3.string().max(2e3).optional(),
-      url: z3.string().url().optional(),
-      pageNumbers: z3.array(z3.number().int().positive()).max(100).optional(),
-      metadata: z3.record(z3.string(), z3.unknown()).optional()
+    parameters: z4.object({
+      endpoint: z4.enum(["search", "scrape", "parse", "map"]),
+      jobId: z4.string().uuid("jobId must be the UUID returned by Firecrawl"),
+      rating: z4.enum(["good", "bad", "partial"]),
+      issues: z4.array(feedbackIssueSchema).max(20).optional(),
+      tags: z4.array(feedbackIssueSchema).max(20).optional(),
+      note: z4.string().max(4e3).optional(),
+      valuableSources: z4.array(valuableSourceSchema).max(50).optional(),
+      missingContent: z4.array(missingContentSchema).max(50).optional(),
+      querySuggestions: z4.string().max(2e3).optional(),
+      url: z4.string().url().optional(),
+      pageNumbers: z4.array(z4.number().int().positive()).max(100).optional(),
+      metadata: z4.record(z4.string(), z4.unknown()).optional()
     }),
     execute: async (args2, { session, log }) => {
       const {
@@ -2338,7 +2433,7 @@ Returns submission status, feedback ID, and accounting fields.
       } = args2;
       const apiBase = resolveApiBaseUrl();
       const headers = {
-        ...ORIGIN_HEADERS2,
+        ...ORIGIN_HEADERS3,
         "Content-Type": "application/json"
       };
       const credential = credentialForOutboundRequest(session);
@@ -2408,25 +2503,25 @@ Start a multi-page crawl at a website URL, poll it to a terminal state, and retu
 
 Crawl results can be large; use conservative limits when full-site coverage is unnecessary. Webhooks and interactive scrape actions are unavailable in safe mode. Returns the crawl ID, status, and page data.
 `,
-  parameters: z3.object({
-    url: z3.string(),
-    prompt: z3.string().optional(),
-    excludePaths: z3.array(z3.string()).optional(),
-    includePaths: z3.array(z3.string()).optional(),
-    maxDiscoveryDepth: z3.number().optional(),
-    sitemap: z3.enum(["skip", "include", "only"]).optional(),
-    limit: z3.number().optional(),
-    allowExternalLinks: z3.boolean().optional(),
-    allowSubdomains: z3.boolean().optional(),
-    crawlEntireDomain: z3.boolean().optional(),
-    delay: z3.number().optional(),
-    maxConcurrency: z3.number().optional(),
+  parameters: z4.object({
+    url: z4.string(),
+    prompt: z4.string().optional(),
+    excludePaths: z4.array(z4.string()).optional(),
+    includePaths: z4.array(z4.string()).optional(),
+    maxDiscoveryDepth: z4.number().optional(),
+    sitemap: z4.enum(["skip", "include", "only"]).optional(),
+    limit: z4.number().optional(),
+    allowExternalLinks: z4.boolean().optional(),
+    allowSubdomains: z4.boolean().optional(),
+    crawlEntireDomain: z4.boolean().optional(),
+    delay: z4.number().optional(),
+    maxConcurrency: z4.number().optional(),
     ...SAFE_MODE ? {} : {
-      webhook: z3.string().optional(),
-      webhookHeaders: z3.record(z3.string(), z3.string()).optional()
+      webhook: z4.string().optional(),
+      webhookHeaders: z4.record(z4.string(), z4.string()).optional()
     },
-    deduplicateSimilarURLs: z3.boolean().optional(),
-    ignoreQueryParameters: z3.boolean().optional(),
+    deduplicateSimilarURLs: z4.boolean().optional(),
+    ignoreQueryParameters: z4.boolean().optional(),
     scrapeOptions: scrapeParamsSchema.omit({ url: true }).partial().optional()
   }),
   execute: async (args2, { session, log }) => {
@@ -2479,7 +2574,7 @@ server.addTool({
   description: `
 Retrieve the current status, progress, and available results for an existing crawl ID. This only reads Firecrawl job state and does not start or modify the crawl.
 `,
-  parameters: z3.object({ id: z3.string() }),
+  parameters: z4.object({ id: z4.string() }),
   execute: async (args2, { session }) => {
     const client = getClient(session);
     const id = args2.id;
@@ -2503,13 +2598,13 @@ Extract structured information from one or more URLs with an optional natural-la
 
 Use this for a defined structured result rather than full page content. Returns data shaped by the supplied schema or prompt.
 `,
-  parameters: z3.object({
-    urls: z3.array(z3.string()),
-    prompt: z3.string().optional(),
-    schema: z3.record(z3.string(), z3.any()).optional(),
-    allowExternalLinks: z3.boolean().optional(),
-    enableWebSearch: z3.boolean().optional(),
-    includeSubdomains: z3.boolean().optional()
+  parameters: z4.object({
+    urls: z4.array(z4.string()),
+    prompt: z4.string().optional(),
+    schema: z4.record(z4.string(), z4.any()).optional(),
+    allowExternalLinks: z4.boolean().optional(),
+    enableWebSearch: z4.boolean().optional(),
+    includeSubdomains: z4.boolean().optional()
   }),
   execute: async (args2, { session, log }) => {
     const client = getClient(session);
@@ -2546,10 +2641,10 @@ Start an asynchronous web research job from a prompt, optional seed URLs, and an
 
 This call returns only a job ID, not the research result. Read the job with \`firecrawl_agent_status\` until it reaches \`completed\` or \`failed\`; research commonly takes several minutes. If the job cannot finish within the task's available time, \`firecrawl_search\` and \`firecrawl_scrape\` can gather evidence synchronously.
 `,
-  parameters: z3.object({
-    prompt: z3.string().min(1).max(1e4),
-    urls: z3.array(z3.string().url()).optional(),
-    schema: z3.record(z3.string(), z3.any()).optional()
+  parameters: z4.object({
+    prompt: z4.string().min(1).max(1e4),
+    urls: z4.array(z4.string().url()).optional(),
+    schema: z4.record(z4.string(), z4.any()).optional()
   }),
   execute: async (args2, { session, log }) => {
     const client = getClient(session);
@@ -2586,14 +2681,14 @@ Retrieve progress or final results for a \`firecrawl_agent\` job ID. A \`process
 
 Returns job status, progress information, and result data when completed.
 `,
-  parameters: z3.object({ id: z3.string() }),
+  parameters: z4.object({ id: z4.string() }),
   execute: async (args2, { session, log }) => {
     const client = getClient(session);
     const { id } = args2;
     log.info("Checking agent status", { id });
     const res = await client.http.get(
       `/v2/agent/${encodeURIComponent(id)}`,
-      ORIGIN_HEADERS2
+      ORIGIN_HEADERS3
     );
     return asText2(res?.data ?? {});
   }
@@ -2614,13 +2709,13 @@ Open or reuse a live browser session to navigate a page, click controls, fill fi
 
 This acts on the live site, so actions such as form submission can create persistent external side effects. Returns execution output, stdout/stderr, exit status, and session viewing URLs.
 `,
-  parameters: z3.object({
-    scrapeId: z3.string().trim().min(1).optional(),
-    url: z3.string().trim().url().optional(),
-    prompt: z3.string().trim().min(1).optional(),
-    code: z3.string().trim().min(1).optional(),
-    language: z3.enum(["bash", "python", "node"]).optional(),
-    timeout: z3.number().min(1).max(300).optional(),
+  parameters: z4.object({
+    scrapeId: z4.string().trim().min(1).optional(),
+    url: z4.string().trim().url().optional(),
+    prompt: z4.string().trim().min(1).optional(),
+    code: z4.string().trim().min(1).optional(),
+    language: z4.enum(["bash", "python", "node"]).optional(),
+    timeout: z4.number().min(1).max(300).optional(),
     scrapeOptions: scrapeParamsSchema.omit({ url: true }).partial().optional()
   }).refine((data) => Boolean(data.scrapeId) !== Boolean(data.url), {
     message: "Provide either 'url' (interact directly) or 'scrapeId' (reuse a previous scrape), not both."
@@ -2697,8 +2792,8 @@ server.addTool({
   description: `
 Stop the live interact session associated with a \`scrapeId\` and release its resources. Returns a success confirmation.
 `,
-  parameters: z3.object({
-    scrapeId: z3.string()
+  parameters: z4.object({
+    scrapeId: z4.string()
   }),
   execute: async (args2, { session, log }) => {
     const client = getClient(session);
@@ -2706,7 +2801,7 @@ Stop the live interact session associated with a \`scrapeId\` and release its re
     log.info("Stopping interact session", { scrapeId });
     const res = await client.http.delete(
       `/v2/scrape/${encodeURIComponent(scrapeId)}/interact`,
-      ORIGIN_HEADERS2
+      ORIGIN_HEADERS3
     );
     return asText2(res?.data ?? {});
   }
@@ -2758,7 +2853,7 @@ Set \`redactPII\` to request redaction of personally identifiable information in
     });
     form.append("file", blob, filename);
     form.append("options", JSON.stringify(optionsPayload));
-    const headers = { ...ORIGIN_HEADERS2 };
+    const headers = { ...ORIGIN_HEADERS3 };
     const credential = credentialForOutboundRequest(session);
     if (credential) {
       headers["Authorization"] = `Bearer ${credential}`;
@@ -2797,11 +2892,13 @@ function registerMarketplaceSearchTool(registrar, getClientFn) {
       destructiveHint: false
     },
     description: `
-Search web and specialized indexes, returning ranked results. Operators include quoted phrases, \`-term\`, \`site:host\`, \`inurl:term\`, \`intitle:term\`, and \`related:host\`; the set is non-exhaustive. \`includeDomains\` and \`excludeDomains\` are mutually exclusive hostname filters; categories limit result types to \`github\`, \`research\`, or \`pdf\`.
+Search web and specialized indexes, returning ranked results. Operators include quoted phrases, \`-term\`, \`site:host\`, \`inurl:term\`, \`intitle:term\`, and \`related:host\`; the set is non-exhaustive. \`includeDomains\` and \`excludeDomains\` are mutually exclusive hostname filters; categories limit result types to \`github\`, \`research\`, \`pdf\`, or \`developer\`.
+
+For a programming question, add \`categories: ["developer"]\`. It searches an index of GitHub issues, merged pull requests, repository READMEs, and curated documentation sites, and returns the hits in \`data.developer\` beside the web results.
 
 Returns \`{ success, data, id, creditsUsed }\`, with source arrays in \`data\`.
 `,
-    parameters: z3.object({ ...searchToolBaseFields }).strict().refine(searchDomainsAreExclusive, SEARCH_DOMAINS_CONFLICT_MESSAGE),
+    parameters: z4.object({ ...searchToolBaseFields }).strict().refine(searchDomainsAreExclusive, SEARCH_DOMAINS_CONFLICT_MESSAGE),
     execute: async (args2, { session, log }) => {
       const {
         query,
@@ -2862,6 +2959,12 @@ if (process.env.CLOUD_SERVICE === "true" || process.env.SSE_LOCAL === "true" ||
 }
 registerMonitorTools(server);
 registerResearchTools(server, getClient);
+registerDeveloperTools(server, getClient);
+if (process.env.CLOUD_SERVICE === "true" && primaryProfile.allowKeyless && !normalizeHeader(process.env.KEYLESS_PROXY_SECRET)) {
+  console.warn(
+    "[firecrawl-mcp] KEYLESS_PROXY_SECRET is missing; keyless requests will be unavailable and /ready will fail."
+  );
+}
 if (primaryProfile.id === "search") {
   const primarySearchRegistrar = {
     addTool: ((tool) => {
@@ -2887,6 +2990,7 @@ if (searchProfileEnabled) {
     })
   };
   registerResearchTools(searchRegistrar, getClient);
+  registerDeveloperTools(searchRegistrar, getClient);
   registerMarketplaceSearchTool(searchRegistrar, getClient);
   try {
     await searchServer.start({

package/package.json

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