firecrawl-mcp 3.23.0 → 3.23.1

package/dist/index.js

@@ -8,7 +8,61 @@ 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.
+
+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).")
+    }),
+    execute: async (args2, { session }) => {
+      const { query, k } = args2;
+      const params = new URLSearchParams();
+      params.append("query", query);
+      if (k != null) params.append("k", String(k));
+      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 +79,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 +178,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 +272,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 +313,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 +339,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 +365,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 +393,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 +419,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 +444,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 +476,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 +496,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 +620,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 +649,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 +669,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 +678,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 +700,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 +719,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 +746,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 +760,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 +781,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 +792,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 +1214,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 +1228,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 +1281,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 +1373,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 +1412,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 +1441,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 +1464,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 +1541,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 +1639,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 +1656,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 +1721,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 +1770,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 +2029,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 +2061,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 +2097,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 +2116,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 +2155,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 +2180,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 +2196,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 +2215,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 +2248,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 +2279,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 +2292,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 +2339,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 +2383,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 +2400,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 +2431,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 +2501,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 +2572,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 +2596,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 +2639,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 +2679,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 +2707,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 +2790,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 +2799,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 +2851,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 +2890,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 +2957,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 +2988,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.1",
   "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",