firecrawl-mcp 3.30.2 → 3.31.0

package/README.md

@@ -73,6 +73,10 @@ Authorization: Bearer <FIRECRAWL_API_KEY>
 
 Never put an API key in the server URL. Never put an API key in an agent chat. Configure it directly in the client or secret manager. See the [hosted MCP setup guide](https://docs.firecrawl.dev/mcp-server) and the [agent onboarding guide](https://www.firecrawl.dev/agent-onboarding/SKILL.md) for client-specific instructions.
 
+#### Naming your integration
+
+An integration that connects over HTTP can name itself with an `X-Firecrawl-Origin` header, for example `X-Firecrawl-Origin: my-agent`. The server reports it to Firecrawl as the request origin `mcp-my-agent@<server version>`, in place of the client name or User-Agent it would otherwise report. Use letters, digits and dashes: each run of other characters becomes one dash, leading and trailing dashes are dropped, and the name is cut at 48 characters. Tool results are unaffected; only the origin sent to the Firecrawl API (and passed to an embedder's `beforeKeylessRequest`) changes.
+
 #### Search-only endpoint
 
 A fixed-scope search surface is also hosted at:
@@ -1246,7 +1250,7 @@ Options mirror the CLI's environment variables: `apiUrl`, `apiKey`, `transport`,
 
 FastMCP is bundled inside the package, so use the types exported from `firecrawl-mcp/server` (`Session`, `ToolDefinition`, `ToolRegistrar`, `FirecrawlMcpServerHooks` and others) rather than importing `fastmcp` yourself.
 
-The entry point also exports the helpers the built-in tools use, such as `recoveryPayload`, `normalizeHeader`, `requestOrigin`, `searchToolBaseFields`, `searchOutputSchema` and `structuredCompact`, so extra tools and hooks can match the built-in behaviour. They are unstable as well.
+The entry point also exports the helpers the built-in tools use, such as `recoveryPayload`, `normalizeHeader`, `requestOrigin`, `isRuntimeUserAgent`, `initializeClientSlug`, `searchToolBaseFields`, `searchOutputSchema` and `structuredCompact`, so extra tools and hooks can match the built-in behaviour. They are unstable as well.
 
 ## Logging System
 

package/dist/index.js

@@ -2401,6 +2401,14 @@ function defaultDomainTools(sources) {
     (source) => ["web", "news", "images"].includes(typeof source === "string" ? source : source?.type)
   );
 }
+function withAlexandriaSource(sources) {
+  if (!Array.isArray(sources) || sources.length === 0) return ["web", "alexandria"];
+  if (hasAlexandria(sources)) return sources;
+  return [...sources, typeof sources[0] === "string" ? "alexandria" : { type: "alexandria" }];
+}
+function enterpriseAllowsAlexandria(enterprise) {
+  return !(Array.isArray(enterprise) && enterprise.some((mode) => mode === "zdr" || mode === "anon"));
+}
 function normalizeSearchSources(sources) {
   if (!Array.isArray(sources)) return sources;
   return sources.map(
@@ -2427,8 +2435,8 @@ var findToolsSchema = z5.object({
 }).strict();
 var ALEXANDRIA_CATALOGUE_VERTICALS = "companies, people, jobs, finance and filings, public records and government spending, real estate, places and restaurants, retail and prices, package registries and developer data, news, research, and more";
 var ALEXANDRIA_CATALOGUE_SENTENCE = "Alexandria is Firecrawl's catalogue of data providers and workflows across " + ALEXANDRIA_CATALOGUE_VERTICALS + "; providers return typed, sourced records through published contracts.";
-var ALEXANDRIA_SOURCES_OPT_OUT = 'A search with sources: ["web"] omits semantic provider discovery; domainTools: true can still return website-matched tools. Web-only results use domainTools: false.';
-var ALEXANDRIA_SEARCH_LEAD = "Authenticated search also returns matching Alexandria data providers in data.tools (" + ALEXANDRIA_CATALOGUE_VERTICALS + "). Prefer a provider over scraping pages when the task needs the same fields across several entities, exact figures or timestamps, provenance, or many records; use web results when they already answer the question. " + ALEXANDRIA_SOURCES_OPT_OUT;
+var ALEXANDRIA_SOURCES_ALWAYS_ON = 'Authenticated searches always add alexandria to the sources, so sources: ["web"] also returns providers; domainTools: false turns off website-matched tools only.';
+var ALEXANDRIA_SEARCH_LEAD = "Authenticated search also returns matching Alexandria data providers in data.tools (" + ALEXANDRIA_CATALOGUE_VERTICALS + "). Prefer a provider over scraping pages when the task needs the same fields across several entities, exact figures or timestamps, provenance, or many records; use web results when they already answer the question. " + ALEXANDRIA_SOURCES_ALWAYS_ON;
 var ALEXANDRIA_CONTRACT_GUIDANCE = "The selected contract marks required inputs and any requiresOneOf groups (at least one member per group); it may include example.request/example.response and response.key (which may differ from records). Where pagination is declared, its fields govern paging with the same filters; catalogue next is separate from provider pagination.";
 function findToolsOptions(args2) {
   const level = args2.level ?? (args2.query || args2.capabilities?.length || args2.providers?.length || args2.groups?.length || args2.urls?.length ? "tools" : args2.categories?.length ? "providers" : "categories");
@@ -2460,7 +2468,7 @@ function withFindToolsNavigation(envelope, carry = {}) {
   if (link(page.next)) page.nextTool = link(page.next);
   return envelope;
 }
-var ALEXANDRIA_SEARCH_INSTRUCTIONS = 'Authenticated search combines web results, semantic tool summaries and domain matches. Use sources: ["alexandria"] for semantic tools only. ' + ALEXANDRIA_SOURCES_OPT_OUT + ' Tool matches describe available structured-data capabilities, not executed data. toolDetail: "compact" (default) returns only provider, capability and description; "summary" adds metadata; "full" includes their input and output contracts. firecrawl_scrape with an alexandria body executes a selected capability; firecrawl_find_tools provides catalogue browsing and full contracts.';
+var ALEXANDRIA_SEARCH_INSTRUCTIONS = 'Authenticated search combines web results, semantic tool summaries and domain matches. Use sources: ["alexandria"] for semantic tools only. ' + ALEXANDRIA_SOURCES_ALWAYS_ON + ' Tool matches describe available structured-data capabilities, not executed data. toolDetail: "compact" (default) returns only provider, capability and description; "summary" adds metadata; "full" includes their input and output contracts. firecrawl_scrape with an alexandria body executes a selected capability; firecrawl_find_tools provides catalogue browsing and full contracts.';
 var TOOL_PRICE_KEYS = ["creditsCost", "perRecord", "billing", "recordsPerUnit", "zeroDataRetentionCreditsCost"];
 function withoutToolPrice(tool) {
   if (!tool || typeof tool !== "object" || Array.isArray(tool)) return tool;
@@ -2575,19 +2583,79 @@ import { z as z6 } from "zod";
 // src/origin.ts
 import { createRequire } from "module";
 var ORIGIN_SERVER = "mcp-fastmcp";
+var DECLARED_ORIGIN_HEADER = "x-firecrawl-origin";
 var NAME_MAX = 48;
+var RUNTIME_PRODUCTS = /* @__PURE__ */ new Set([
+  "apache-httpasyncclient",
+  "apache-httpclient",
+  "aiohttp",
+  "axios",
+  "bun",
+  "curl",
+  "dart",
+  "deno",
+  "faraday",
+  "go-http-client",
+  "got",
+  "guzzlehttp",
+  "java-http-client",
+  "ktor-client",
+  "libcurl-agent",
+  "mozilla",
+  "node",
+  "node-fetch",
+  "okhttp",
+  "python",
+  "python-httpx",
+  "python-httpx2",
+  "python-requests",
+  "python-urllib",
+  "reqwest",
+  "ruby",
+  "undici",
+  "wget"
+]);
+var GENERIC_CLIENT_NAMES = /* @__PURE__ */ new Set([
+  "client",
+  "example-client",
+  "mcp",
+  "mcp-client",
+  "test",
+  "test-client"
+]);
 function slugOf(name2) {
   return (name2 ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, NAME_MAX).replace(/-+$/, "");
 }
+function isOwnSlug(slug) {
+  return slug === "" || slug === "fastmcp" || slug === "firecrawl-fastmcp";
+}
 function userAgentProduct(userAgent) {
   const first = (userAgent ?? "").trim().split(/\s+/)[0] ?? "";
   return slugOf(first.split("/")[0]);
 }
-function originForClient(client, serverVersion2, userAgent) {
+function initializeClientSlug(name2) {
+  const slug = slugOf(name2);
+  return isOwnSlug(slug) || GENERIC_CLIENT_NAMES.has(slug) ? "" : slug;
+}
+function referrerSlug(referrer) {
+  let host;
+  try {
+    host = new URL(referrer ?? "").hostname.toLowerCase().replace(/\.$/, "");
+  } catch {
+    return "";
+  }
+  if (!host.includes(".") || host.endsWith(".localhost") || host.endsWith(".local") || /^[\d.]+$/.test(host) || host.startsWith("[")) {
+    return "";
+  }
+  return slugOf(host.replace(/^www\./, ""));
+}
+function originForClient(client, serverVersion2, userAgent, signals = {}) {
+  const declared = slugOf(signals.declaredOrigin);
   const slug = slugOf(client?.name);
-  const own = slug === "" || slug === "fastmcp" || slug === "firecrawl-fastmcp";
-  const product = own ? userAgentProduct(userAgent) : "";
-  const base = !own ? `mcp-${slug}` : product ? `mcp-ua-${product}` : ORIGIN_SERVER;
+  const product = userAgentProduct(userAgent);
+  const remembered = initializeClientSlug(signals.initializeClient?.name);
+  const referrer = referrerSlug(signals.referrer);
+  const base = !isOwnSlug(declared) ? `mcp-${declared}` : !isOwnSlug(slug) ? `mcp-${slug}` : product && !RUNTIME_PRODUCTS.has(product) ? `mcp-ua-${product}` : remembered ? `mcp-${remembered}` : referrer ? `mcp-ref-${referrer}` : product ? `mcp-ua-${product}` : ORIGIN_SERVER;
   return serverVersion2 ? `${base}@${serverVersion2}` : base;
 }
 function originHeaders(origin) {
@@ -2600,7 +2668,12 @@ function requestOrigin(client, session) {
   return originForClient(
     client?.version ?? null,
     serverVersion,
-    session?.clientUserAgent
+    session?.clientUserAgent,
+    {
+      declaredOrigin: session?.clientOrigin,
+      initializeClient: session?.initializeClient,
+      referrer: session?.clientReferrer
+    }
   );
 }
 
@@ -3677,7 +3750,7 @@ var searchToolBaseFields = {
   location: z11.string().optional(),
   includeDomains: z11.array(searchDomainSchema).optional().describe("Hostnames to restrict results to. Mutually exclusive with excludeDomains."),
   excludeDomains: z11.array(searchDomainSchema).optional().describe("Hostnames to leave out of results. Mutually exclusive with includeDomains."),
-  sources: z11.array(searchSourceSchema).optional().describe("Search sources; authenticated sessions default to web + alexandria, keyless sessions to web only. " + ALEXANDRIA_SOURCES_OPT_OUT + ' Use ["alexandria"] alone for provider discovery without web results.'),
+  sources: z11.array(searchSourceSchema).optional().describe("Search sources; authenticated sessions default to web + alexandria, keyless sessions to web only. " + ALEXANDRIA_SOURCES_ALWAYS_ON + ' enterprise zdr or anon searches do not add it. Use ["alexandria"] alone for provider discovery without web results.'),
   categories: z11.array(z11.enum(["research", "pdf", "developer", "gov"])).optional().describe(
     "Limit results to specific source types. `research` restricts ordinary web results to research-affiliated websites and returns page snippets, which is separate from the `firecrawl_research_*` tools that search paper abstracts and full text across biomedical (PubMed, bioRxiv, medRxiv) and arXiv literature; `pdf` searches PDF results; `developer` searches an index built for coding agents over public repositories, GitHub issues, merged pull requests, repository READMEs, and code documentation; `gov` searches the Government Index of US federal, state, and local legal and regulatory sources, the index behind firecrawl_gov_search, and cannot be combined with other categories; gov hits can include historical versions, bill text, agency guidance, and third-party reproductions, so verify the issuer, jurisdiction, enacted/effective status, and version before citing current governing law, clarify a missing jurisdiction or ambiguous as-of date, and use general search for non-US questions or missing coverage (no hits does not establish that no applicable law exists). `developer` and `gov` return hits in `data.web` with `category` set to their name; the other categories also filter `data.web`."
   ),
@@ -3819,7 +3892,7 @@ async function relayExchangeError(run, context) {
     });
   }
 }
-async function postSearchWithFallback(client, body, implicitTools) {
+async function postSearchWithFallback(client, body, implicitTools, fallbackSources = ["web"]) {
   try {
     return await client.http.post("/v2/search", body);
   } catch (error2) {
@@ -3832,7 +3905,7 @@ async function postSearchWithFallback(client, body, implicitTools) {
     if (!implicitTools || response?.status !== 403 || !unavailable) throw error2;
     return client.http.post("/v2/search", {
       ...body,
-      sources: ["web"],
+      sources: fallbackSources,
       domainTools: false
     });
   }
@@ -3892,7 +3965,7 @@ var ConsoleLogger = class {
     }
   }
 };
-var FULL_PROFILE_INSTRUCTIONS = `Firecrawl provides web search, page retrieval, site URL discovery, multi-page collection, structured page data, monitoring, and multi-source research that returns structured data. Match the requested operation to the tool boundary: firecrawl_scrape retrieves one supplied page and can return JSON matching a supplied schema, firecrawl_map enumerates URLs under a site without retrieving their content, and firecrawl_agent runs multi-source research and returns structured data when the URLs are not known or the answer spans several sites (an entity plus its fields, a list, a dataset); its result is read with firecrawl_agent_status. Authenticated firecrawl_search returns web results together with matching Alexandria providers in data.tools. ${ALEXANDRIA_CATALOGUE_SENTENCE} A matching provider can return the same fields across several entities, provenance, exact figures or timestamps, or a large set of records through firecrawl_scrape with its published contract. If web results already answer the question, use them. For the same fields across multiple pages, firecrawl_find_tools offers free provider discovery. Use firecrawl_find_tools to read a contract that was not returned in full or to browse the catalogue by category. ${ALEXANDRIA_SOURCES_OPT_OUT} If no provider fits, continue with web search or firecrawl_agent. For biomedical, life-science, clinical, or arXiv literature, the firecrawl_research_* tools search a paper index of abstracts and full text; firecrawl_search with categories: ["research"] is a website filter over ordinary web results and reaches different sources. For a programming question (code behaviour, a library or framework, an API contract, an error message, or a known bug), firecrawl_developer_search (or firecrawl_search with categories: ["developer"]) searches an index of public repositories, GitHub issues, merged pull requests, READMEs, and code documentation. For a legal or regulatory question, firecrawl_gov_search searches primary law and regulatory material from US federal, state, and local government sources: statutes, regulations, codes, court opinions, and other government publications; firecrawl_search with categories: ["gov"] reaches the same sources and cannot be combined with other categories. firecrawl_search with sources: [{type: "alexandria"}] returns compact tool summaries in data.tools; toolDetail: "full" includes contracts, firecrawl_find_tools starts with categories, lists providers, then compact tools, and expands the selected full contract, and firecrawl_scrape with alexandria: [{provider, capability, options}] executes up to ten capabilities and returns their results. Alexandria access needs an API key on a team with it enabled. Provide only the required inputs and account for stated network or external side effects.`;
+var FULL_PROFILE_INSTRUCTIONS = `Firecrawl provides web search, page retrieval, site URL discovery, multi-page collection, structured page data, monitoring, and multi-source research that returns structured data. Match the requested operation to the tool boundary: firecrawl_scrape retrieves one supplied page and can return JSON matching a supplied schema, firecrawl_map enumerates URLs under a site without retrieving their content, and firecrawl_agent runs multi-source research and returns structured data when the URLs are not known or the answer spans several sites (an entity plus its fields, a list, a dataset); its result is read with firecrawl_agent_status. Authenticated firecrawl_search returns web results together with matching Alexandria providers in data.tools. ${ALEXANDRIA_CATALOGUE_SENTENCE} A matching provider can return the same fields across several entities, provenance, exact figures or timestamps, or a large set of records through firecrawl_scrape with its published contract. If web results already answer the question, use them. For the same fields across multiple pages, firecrawl_find_tools offers free provider discovery. Use firecrawl_find_tools to read a contract that was not returned in full or to browse the catalogue by category. ${ALEXANDRIA_SOURCES_ALWAYS_ON} If no provider fits, continue with web search or firecrawl_agent. For biomedical, life-science, clinical, or arXiv literature, the firecrawl_research_* tools search a paper index of abstracts and full text; firecrawl_search with categories: ["research"] is a website filter over ordinary web results and reaches different sources. For a programming question (code behaviour, a library or framework, an API contract, an error message, or a known bug), firecrawl_developer_search (or firecrawl_search with categories: ["developer"]) searches an index of public repositories, GitHub issues, merged pull requests, READMEs, and code documentation. For a legal or regulatory question, firecrawl_gov_search searches primary law and regulatory material from US federal, state, and local government sources: statutes, regulations, codes, court opinions, and other government publications; firecrawl_search with categories: ["gov"] reaches the same sources and cannot be combined with other categories. firecrawl_search with sources: [{type: "alexandria"}] returns compact tool summaries in data.tools; toolDetail: "full" includes contracts, firecrawl_find_tools starts with categories, lists providers, then compact tools, and expands the selected full contract, and firecrawl_scrape with alexandria: [{provider, capability, options}] executes up to ten capabilities and returns their results. Alexandria access needs an API key on a team with it enabled. Provide only the required inputs and account for stated network or external side effects.`;
 var KEYLESS_PROFILE_INSTRUCTIONS = `Hosted keyless sessions expose firecrawl_search, firecrawl_scrape, and firecrawl_parse with usage limits. firecrawl_search searches the web. For programming questions, firecrawl_search with categories: ["developer"] searches indexed public repositories, GitHub issues, merged pull requests, repository READMEs, and code documentation. For legal or regulatory questions, firecrawl_search with categories: ["gov"] searches US government legal and regulatory sources and cannot be combined with other categories. For biomedical, life-science, clinical, or arXiv literature, firecrawl_search with categories: ["research"] filters ordinary web results to research-affiliated websites. firecrawl_scrape retrieves one supplied page and can return JSON matching a supplied schema. firecrawl_parse processes supported local files through its two-phase upload flow. An Authorization bearer API key can provide higher usage limits and expose additional tools, subject to plan, deployment, and team policy, including firecrawl_map for site URL discovery, firecrawl_agent and firecrawl_agent_status for multi-source research that returns structured data when the URLs are not known, firecrawl_research_* for paper-index and repository research, and firecrawl_find_tools as the progressive Alexandria catalogue lookup alongside the Alexandria options of firecrawl_search and firecrawl_scrape for catalogued data providers.`;
 function deprecatedExtractPayload() {
   return {
@@ -3953,10 +4026,18 @@ function createFirecrawlMcpServer(options2 = {}) {
     const cached = request?.[authResultByRequest];
     if (cached) return cached;
     const authResult = authenticateSession(request).then((session) => {
-      const userAgent = request?.headers?.["user-agent"];
+      const headers = request?.headers;
+      const userAgent = headers?.["user-agent"];
       if (typeof userAgent === "string" && userAgent !== "") {
         session.clientUserAgent = userAgent;
       }
+      const declaredOrigin = normalizeHeader(headers?.[DECLARED_ORIGIN_HEADER]);
+      if (declaredOrigin) session.clientOrigin = declaredOrigin;
+      const referrer = [
+        normalizeHeader(headers?.["origin"]),
+        normalizeHeader(headers?.["referer"])
+      ].find((value) => value && value !== "null");
+      if (referrer) session.clientReferrer = referrer;
       return session;
     });
     if (request) request[authResultByRequest] = authResult;
@@ -4561,7 +4642,7 @@ Scrape one URL and return its content: markdown by default, or HTML, links, scre
 
 Firecrawl may serve recently indexed content; set \`maxAge: 0\` for a live fetch or a smaller \`maxAge\` to bound staleness. A successful response does not by itself confirm the page is still current. ${SAFE_MODE ? "A named browser profile loads saved session data without saving changes to it." : "Browser actions can change the live page when interactive actions are enabled."} Authenticated responses can include a \`metadata.scrapeId\` for optional scrape feedback.
 
-On an authenticated session with Alexandria access, \`firecrawl_search\` with \`sources\` unset and \`firecrawl_find_tools\` can discover providers for the same fields across several pages; a matching provider returns typed records in one call. Keyless sessions have no provider matches.
+On an authenticated session with Alexandria access, \`firecrawl_search\` and \`firecrawl_find_tools\` can discover providers for the same fields across several pages; a matching provider returns typed records in one call. Keyless sessions have no provider matches.
 
 Alexandria mode, on an authenticated session with Alexandria access: \`alexandria\` selects catalogued capability execution and is mutually exclusive with \`url\`.
 `,
@@ -4691,11 +4772,13 @@ For a programming question, add \`categories: ["developer"]\`; its hits return i
     ),
     execute: async (args2, { session, log, client: mcpClient }) => {
       const { query, ...opts } = args2;
+      const requestedSources = normalizeSearchSources(
+        Array.isArray(opts.sources) && opts.sources.length ? opts.sources : ["web"]
+      );
+      const addsAlexandria = hasCredential(session) && enterpriseAllowsAlexandria(opts.enterprise) && !hasAlexandria(requestedSources);
       const searchOpts = {
         ...opts,
-        sources: normalizeSearchSources(
-          opts.sources ?? (hasCredential(session) ? ["web", "alexandria"] : ["web"])
-        )
+        sources: addsAlexandria ? withAlexandriaSource(requestedSources) : requestedSources
       };
       searchOpts.domainTools ??= defaultDomainTools(searchOpts.sources);
       searchOpts.toolDetail ??= "compact";
@@ -4725,7 +4808,8 @@ For a programming question, add \`categories: ["developer"]\`; its hits return i
       const postSearch = () => postSearchWithFallback(
         client,
         searchBody,
-        opts.sources === void 0 && opts.domainTools !== true
+        addsAlexandria && opts.domainTools !== true,
+        requestedSources
       );
       const httpRes = await relayExchangeError(postSearch, { tool: "firecrawl_search" });
       return structuredCompact(withoutDiscoveredToolPrices(httpRes?.data ?? {}));
@@ -6384,7 +6468,7 @@ function searchSurfaceScrapeDescription(safeMode) {
   return `
 Scrape one URL and return its content, or execute catalogued Alexandria capabilities. URL mode returns markdown by default, or HTML, links, screenshots, branding data, a targeted answer, or JSON matching a supplied schema, plus page metadata. Firecrawl may serve recently indexed content; set \`maxAge: 0\` for a live fetch. A successful response does not by itself confirm the page is still current. ${safeMode ? "A named browser profile loads saved session data without saving changes to it." : "Browser actions can change the live page, and a named browser profile can load saved session data and overwrite its stored state."}
 
-\`firecrawl_search\` with \`sources\` unset and \`firecrawl_find_tools\` can discover providers for the same fields across several pages; a matching Alexandria provider returns typed records in one call.
+\`firecrawl_search\` and \`firecrawl_find_tools\` can discover providers for the same fields across several pages; a matching Alexandria provider returns typed records in one call.
 
 Alexandria mode: \`alexandria\` selects catalogued capability execution and is mutually exclusive with \`url\`. Alexandria execution is billed per capability (pass includeCosts to firecrawl_find_tools to see prices if you need) and needs a team with Alexandria enabled.
 `;
@@ -6440,6 +6524,11 @@ Returns result groups in \`data\` and an operation \`id\`.
         toolDetail
       } = args2;
       const searchQuery = query ?? "";
+      const requestedSources = normalizeSearchSources(
+        sources?.length ? sources : ["web"]
+      );
+      const addsAlexandria = hasCredential(session) && enterpriseAllowsAlexandria(enterprise) && !hasAlexandria(requestedSources);
+      const searchSources = addsAlexandria ? withAlexandriaSource(requestedSources) : requestedSources;
       const searchBody = {
         query: searchQuery,
         ...removeEmptyTopLevel({
@@ -6449,12 +6538,12 @@ Returns result groups in \`data\` and an operation \`id\`.
           tbs,
           filter,
           location,
-          sources: normalizeSearchSources(sources ?? ["web", "alexandria"]),
+          sources: searchSources,
           categories,
           highlights,
           enterprise,
           toolDetail: toolDetail ?? "compact",
-          domainTools: domainTools ?? defaultDomainTools(sources ?? ["web", "alexandria"])
+          domainTools: domainTools ?? defaultDomainTools(searchSources)
         }),
         origin: requestOrigin(mcpClient, session)
       };
@@ -6466,7 +6555,8 @@ Returns result groups in \`data\` and an operation \`id\`.
       const postSearch = () => postSearchWithFallback(
         client,
         searchBody,
-        sources === void 0 && domainTools !== true
+        addsAlexandria && domainTools !== true,
+        requestedSources
       );
       const httpRes = await relayExchangeError(postSearch, { tool: "firecrawl_search" });
       return structuredCompactResult(httpRes?.data ?? {});

package/dist/origin.js

@@ -1,19 +1,83 @@
 // src/origin.ts
 import { createRequire } from "module";
 var ORIGIN_SERVER = "mcp-fastmcp";
+var DECLARED_ORIGIN_HEADER = "x-firecrawl-origin";
 var NAME_MAX = 48;
+var RUNTIME_PRODUCTS = /* @__PURE__ */ new Set([
+  "apache-httpasyncclient",
+  "apache-httpclient",
+  "aiohttp",
+  "axios",
+  "bun",
+  "curl",
+  "dart",
+  "deno",
+  "faraday",
+  "go-http-client",
+  "got",
+  "guzzlehttp",
+  "java-http-client",
+  "ktor-client",
+  "libcurl-agent",
+  "mozilla",
+  "node",
+  "node-fetch",
+  "okhttp",
+  "python",
+  "python-httpx",
+  "python-httpx2",
+  "python-requests",
+  "python-urllib",
+  "reqwest",
+  "ruby",
+  "undici",
+  "wget"
+]);
+var GENERIC_CLIENT_NAMES = /* @__PURE__ */ new Set([
+  "client",
+  "example-client",
+  "mcp",
+  "mcp-client",
+  "test",
+  "test-client"
+]);
 function slugOf(name) {
   return (name ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, NAME_MAX).replace(/-+$/, "");
 }
+function isOwnSlug(slug) {
+  return slug === "" || slug === "fastmcp" || slug === "firecrawl-fastmcp";
+}
 function userAgentProduct(userAgent) {
   const first = (userAgent ?? "").trim().split(/\s+/)[0] ?? "";
   return slugOf(first.split("/")[0]);
 }
-function originForClient(client, serverVersion2, userAgent) {
+function isRuntimeUserAgent(userAgent) {
+  const product = userAgentProduct(userAgent);
+  return product === "" || RUNTIME_PRODUCTS.has(product);
+}
+function initializeClientSlug(name) {
+  const slug = slugOf(name);
+  return isOwnSlug(slug) || GENERIC_CLIENT_NAMES.has(slug) ? "" : slug;
+}
+function referrerSlug(referrer) {
+  let host;
+  try {
+    host = new URL(referrer ?? "").hostname.toLowerCase().replace(/\.$/, "");
+  } catch {
+    return "";
+  }
+  if (!host.includes(".") || host.endsWith(".localhost") || host.endsWith(".local") || /^[\d.]+$/.test(host) || host.startsWith("[")) {
+    return "";
+  }
+  return slugOf(host.replace(/^www\./, ""));
+}
+function originForClient(client, serverVersion2, userAgent, signals = {}) {
+  const declared = slugOf(signals.declaredOrigin);
   const slug = slugOf(client?.name);
-  const own = slug === "" || slug === "fastmcp" || slug === "firecrawl-fastmcp";
-  const product = own ? userAgentProduct(userAgent) : "";
-  const base = !own ? `mcp-${slug}` : product ? `mcp-ua-${product}` : ORIGIN_SERVER;
+  const product = userAgentProduct(userAgent);
+  const remembered = initializeClientSlug(signals.initializeClient?.name);
+  const referrer = referrerSlug(signals.referrer);
+  const base = !isOwnSlug(declared) ? `mcp-${declared}` : !isOwnSlug(slug) ? `mcp-${slug}` : product && !RUNTIME_PRODUCTS.has(product) ? `mcp-ua-${product}` : remembered ? `mcp-${remembered}` : referrer ? `mcp-ref-${referrer}` : product ? `mcp-ua-${product}` : ORIGIN_SERVER;
   return serverVersion2 ? `${base}@${serverVersion2}` : base;
 }
 function originHeaders(origin) {
@@ -26,11 +90,19 @@ function requestOrigin(client, session) {
   return originForClient(
     client?.version ?? null,
     serverVersion,
-    session?.clientUserAgent
+    session?.clientUserAgent,
+    {
+      declaredOrigin: session?.clientOrigin,
+      initializeClient: session?.initializeClient,
+      referrer: session?.clientReferrer
+    }
   );
 }
 export {
+  DECLARED_ORIGIN_HEADER,
   ORIGIN_SERVER,
+  initializeClientSlug,
+  isRuntimeUserAgent,
   originForClient,
   originHeaders,
   requestOrigin,

package/dist/server.d.ts

@@ -6,10 +6,20 @@ import { z } from 'zod';
 declare function normalizeHeader(value: string | string[] | undefined): string | undefined;
 declare function withoutTrailingSlash(value: string): string;
 
+/** The header a connection sets to name the integration it comes from. */
+declare const DECLARED_ORIGIN_HEADER = "x-firecrawl-origin";
 type ClientImplementation = {
     name?: string;
     version?: string;
 };
+/** Whether a User-Agent is absent or names an HTTP runtime rather than an MCP client. */
+declare function isRuntimeUserAgent(userAgent: string | null | undefined): boolean;
+/**
+ * The token an initialize client name stamps when it reaches a call only
+ * through `ClientSignals.initializeClient`; empty for the server's own names
+ * and the defaults SDKs send when the integration sets none.
+ */
+declare function initializeClientSlug(name: string | null | undefined): string;
 /** The header form of an origin, for the requests that reach the API without a body. */
 declare function originHeaders(origin: string): Record<string, string>;
 /**
@@ -19,14 +29,19 @@ declare function originHeaders(origin: string): Record<string, string>;
 type McpClient = {
     version?: ClientImplementation | undefined;
 } | undefined;
+/** The client signals the authenticated session carries (see SessionData). */
+type OriginSession = {
+    clientUserAgent?: string;
+    clientOrigin?: string;
+    clientReferrer?: string;
+    initializeClient?: ClientImplementation;
+};
 /**
  * The origin of every request a tool call makes: the call's client, the
- * User-Agent the session was authenticated with (stateless HTTP calls carry
- * no client name), and this server's version.
+ * client signals of the request the session was authenticated with
+ * (stateless HTTP calls carry no client name), and this server's version.
  */
-declare function requestOrigin(client: McpClient, session?: {
-    clientUserAgent?: string;
-} | undefined): string;
+declare function requestOrigin(client: McpClient, session?: OriginSession | undefined): string;
 
 /** An API-issued keyless signup link, or undefined for anything else. */
 declare function keylessSignupUrlFrom(value: unknown): string | undefined;
@@ -44,6 +59,10 @@ declare function keylessQuotaReason(reason: unknown): reason is 'requests' | 'cr
 
 declare function hasAlexandria(sources: unknown): boolean;
 declare function defaultDomainTools(sources: unknown): boolean;
+/** Adds alexandria to the requested sources, keeping the caller's entries and their string or object form. */
+declare function withAlexandriaSource(sources: unknown): unknown[];
+/** Zero data retention and anonymous searches cannot run provider discovery. */
+declare function enterpriseAllowsAlexandria(enterprise: unknown): boolean;
 declare function normalizeSearchSources(sources: unknown): unknown;
 declare function searchQueryIsValid(args: {
     query?: string;
@@ -146,7 +165,8 @@ type ExchangeErrorContext = {
 };
 declare function relayTermsRequired<T>(run: () => Promise<T>, context: ExchangeErrorContext): Promise<T>;
 declare function relayExchangeError(run: () => Promise<any>, context: ExchangeErrorContext): Promise<any>;
-declare function postSearchWithFallback(client: any, body: Record<string, unknown>, implicitTools: boolean): Promise<any>;
+/** Retries without Alexandria, on fallbackSources, when tools the caller did not ask for are refused. */
+declare function postSearchWithFallback(client: any, body: Record<string, unknown>, implicitTools: boolean, fallbackSources?: unknown[]): Promise<any>;
 
 /**
  * Library entry point: `import { createFirecrawlMcpServer } from 'firecrawl-mcp/server'`.
@@ -204,10 +224,23 @@ interface SessionData {
      */
     firecrawlApiKey?: string;
     /**
-     * The User-Agent of the HTTP request that opened the session, the only
-     * client signal a stateless HTTP tool call carries (see src/origin.ts).
+     * The User-Agent of the HTTP request that opened the session, one of the
+     * client signals a stateless HTTP tool call carries (see src/origin.ts).
      */
     clientUserAgent?: string;
+    /** The `X-Firecrawl-Origin` header: the integration the connection names. */
+    clientOrigin?: string;
+    /** The `Origin` or `Referer` header of that request. */
+    clientReferrer?: string;
+    /**
+     * The client an earlier initialize named, for stateless HTTP calls that do
+     * not carry it. Set by an embedder that can recover it; read only when the
+     * User-Agent names a runtime rather than a client.
+     */
+    initializeClient?: {
+        name?: string;
+        version?: string;
+    };
     authType?: 'api-key' | 'oauth' | 'env' | 'keyless' | 'none';
     /** Admitted, but the supplied credential cannot be used. */
     credentialError?: 'CREDENTIAL_INVALID';
@@ -423,4 +456,4 @@ declare const structuredCompactResult: (data: unknown) => ToolResult;
 
 declare function createFirecrawlMcpServer(options?: FirecrawlMcpServerOptions): FirecrawlMcpServer;
 
-export { ALEXANDRIA_CATALOGUE_VERTICALS, ALEXANDRIA_SEARCH_INSTRUCTIONS, type AuthenticationRequest, type ExtraToolsContext, type FirecrawlMcpServer, type FirecrawlMcpServerHooks, type FirecrawlMcpServerOptions, type FirecrawlMcpServerStartArgs, type HttpApp, type InstructionDefaults, keylessToolNames as KEYLESS_TOOL_NAMES, type OutboundRequest, type ProtectedResourceMetadata, type ResourceContent, type ResourceDefinition, type ResourceRegistrar, SEARCH_DOMAINS_CONFLICT_MESSAGE, type Session, type SessionData, type ToolCallEvent, type ToolContext, type ToolDefinition, type ToolIcon, type ToolLogger, type ToolRegistrar, type ToolResult, UserError, assertExchangeCredential, createFirecrawlMcpServer, defaultDomainTools, hasAlexandria, invalidApiKeyRecoveryPayload, invalidOAuthRecoveryPayload, keylessQuotaReason, keylessSignupUrlFrom, normalizeHeader, normalizeSearchSources, originHeaders, postSearchWithFallback, recoveryPayload, relayExchangeError, relayTermsRequired, removeEmptyTopLevel, requestOrigin, searchDomainsAreExclusive, searchOutputSchema, searchQueryIsValid, searchToolBaseFields, structuredCompactResult as structuredCompact, withoutTrailingSlash };
+export { ALEXANDRIA_CATALOGUE_VERTICALS, ALEXANDRIA_SEARCH_INSTRUCTIONS, type AuthenticationRequest, DECLARED_ORIGIN_HEADER, type ExtraToolsContext, type FirecrawlMcpServer, type FirecrawlMcpServerHooks, type FirecrawlMcpServerOptions, type FirecrawlMcpServerStartArgs, type HttpApp, type InstructionDefaults, keylessToolNames as KEYLESS_TOOL_NAMES, type OutboundRequest, type ProtectedResourceMetadata, type ResourceContent, type ResourceDefinition, type ResourceRegistrar, SEARCH_DOMAINS_CONFLICT_MESSAGE, type Session, type SessionData, type ToolCallEvent, type ToolContext, type ToolDefinition, type ToolIcon, type ToolLogger, type ToolRegistrar, type ToolResult, UserError, assertExchangeCredential, createFirecrawlMcpServer, defaultDomainTools, enterpriseAllowsAlexandria, hasAlexandria, initializeClientSlug, invalidApiKeyRecoveryPayload, invalidOAuthRecoveryPayload, isRuntimeUserAgent, keylessQuotaReason, keylessSignupUrlFrom, normalizeHeader, normalizeSearchSources, originHeaders, postSearchWithFallback, recoveryPayload, relayExchangeError, relayTermsRequired, removeEmptyTopLevel, requestOrigin, searchDomainsAreExclusive, searchOutputSchema, searchQueryIsValid, searchToolBaseFields, structuredCompactResult as structuredCompact, withAlexandriaSource, withoutTrailingSlash };

package/dist/server.js

@@ -2396,6 +2396,14 @@ function defaultDomainTools(sources) {
     (source) => ["web", "news", "images"].includes(typeof source === "string" ? source : source?.type)
   );
 }
+function withAlexandriaSource(sources) {
+  if (!Array.isArray(sources) || sources.length === 0) return ["web", "alexandria"];
+  if (hasAlexandria(sources)) return sources;
+  return [...sources, typeof sources[0] === "string" ? "alexandria" : { type: "alexandria" }];
+}
+function enterpriseAllowsAlexandria(enterprise) {
+  return !(Array.isArray(enterprise) && enterprise.some((mode) => mode === "zdr" || mode === "anon"));
+}
 function normalizeSearchSources(sources) {
   if (!Array.isArray(sources)) return sources;
   return sources.map(
@@ -2422,8 +2430,8 @@ var findToolsSchema = z5.object({
 }).strict();
 var ALEXANDRIA_CATALOGUE_VERTICALS = "companies, people, jobs, finance and filings, public records and government spending, real estate, places and restaurants, retail and prices, package registries and developer data, news, research, and more";
 var ALEXANDRIA_CATALOGUE_SENTENCE = "Alexandria is Firecrawl's catalogue of data providers and workflows across " + ALEXANDRIA_CATALOGUE_VERTICALS + "; providers return typed, sourced records through published contracts.";
-var ALEXANDRIA_SOURCES_OPT_OUT = 'A search with sources: ["web"] omits semantic provider discovery; domainTools: true can still return website-matched tools. Web-only results use domainTools: false.';
-var ALEXANDRIA_SEARCH_LEAD = "Authenticated search also returns matching Alexandria data providers in data.tools (" + ALEXANDRIA_CATALOGUE_VERTICALS + "). Prefer a provider over scraping pages when the task needs the same fields across several entities, exact figures or timestamps, provenance, or many records; use web results when they already answer the question. " + ALEXANDRIA_SOURCES_OPT_OUT;
+var ALEXANDRIA_SOURCES_ALWAYS_ON = 'Authenticated searches always add alexandria to the sources, so sources: ["web"] also returns providers; domainTools: false turns off website-matched tools only.';
+var ALEXANDRIA_SEARCH_LEAD = "Authenticated search also returns matching Alexandria data providers in data.tools (" + ALEXANDRIA_CATALOGUE_VERTICALS + "). Prefer a provider over scraping pages when the task needs the same fields across several entities, exact figures or timestamps, provenance, or many records; use web results when they already answer the question. " + ALEXANDRIA_SOURCES_ALWAYS_ON;
 var ALEXANDRIA_CONTRACT_GUIDANCE = "The selected contract marks required inputs and any requiresOneOf groups (at least one member per group); it may include example.request/example.response and response.key (which may differ from records). Where pagination is declared, its fields govern paging with the same filters; catalogue next is separate from provider pagination.";
 function findToolsOptions(args) {
   const level = args.level ?? (args.query || args.capabilities?.length || args.providers?.length || args.groups?.length || args.urls?.length ? "tools" : args.categories?.length ? "providers" : "categories");
@@ -2455,7 +2463,7 @@ function withFindToolsNavigation(envelope, carry = {}) {
   if (link(page.next)) page.nextTool = link(page.next);
   return envelope;
 }
-var ALEXANDRIA_SEARCH_INSTRUCTIONS = 'Authenticated search combines web results, semantic tool summaries and domain matches. Use sources: ["alexandria"] for semantic tools only. ' + ALEXANDRIA_SOURCES_OPT_OUT + ' Tool matches describe available structured-data capabilities, not executed data. toolDetail: "compact" (default) returns only provider, capability and description; "summary" adds metadata; "full" includes their input and output contracts. firecrawl_scrape with an alexandria body executes a selected capability; firecrawl_find_tools provides catalogue browsing and full contracts.';
+var ALEXANDRIA_SEARCH_INSTRUCTIONS = 'Authenticated search combines web results, semantic tool summaries and domain matches. Use sources: ["alexandria"] for semantic tools only. ' + ALEXANDRIA_SOURCES_ALWAYS_ON + ' Tool matches describe available structured-data capabilities, not executed data. toolDetail: "compact" (default) returns only provider, capability and description; "summary" adds metadata; "full" includes their input and output contracts. firecrawl_scrape with an alexandria body executes a selected capability; firecrawl_find_tools provides catalogue browsing and full contracts.';
 var TOOL_PRICE_KEYS = ["creditsCost", "perRecord", "billing", "recordsPerUnit", "zeroDataRetentionCreditsCost"];
 function withoutToolPrice(tool) {
   if (!tool || typeof tool !== "object" || Array.isArray(tool)) return tool;
@@ -2570,19 +2578,83 @@ import { z as z6 } from "zod";
 // src/origin.ts
 import { createRequire } from "module";
 var ORIGIN_SERVER = "mcp-fastmcp";
+var DECLARED_ORIGIN_HEADER = "x-firecrawl-origin";
 var NAME_MAX = 48;
+var RUNTIME_PRODUCTS = /* @__PURE__ */ new Set([
+  "apache-httpasyncclient",
+  "apache-httpclient",
+  "aiohttp",
+  "axios",
+  "bun",
+  "curl",
+  "dart",
+  "deno",
+  "faraday",
+  "go-http-client",
+  "got",
+  "guzzlehttp",
+  "java-http-client",
+  "ktor-client",
+  "libcurl-agent",
+  "mozilla",
+  "node",
+  "node-fetch",
+  "okhttp",
+  "python",
+  "python-httpx",
+  "python-httpx2",
+  "python-requests",
+  "python-urllib",
+  "reqwest",
+  "ruby",
+  "undici",
+  "wget"
+]);
+var GENERIC_CLIENT_NAMES = /* @__PURE__ */ new Set([
+  "client",
+  "example-client",
+  "mcp",
+  "mcp-client",
+  "test",
+  "test-client"
+]);
 function slugOf(name2) {
   return (name2 ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, NAME_MAX).replace(/-+$/, "");
 }
+function isOwnSlug(slug) {
+  return slug === "" || slug === "fastmcp" || slug === "firecrawl-fastmcp";
+}
 function userAgentProduct(userAgent) {
   const first = (userAgent ?? "").trim().split(/\s+/)[0] ?? "";
   return slugOf(first.split("/")[0]);
 }
-function originForClient(client, serverVersion2, userAgent) {
+function isRuntimeUserAgent(userAgent) {
+  const product = userAgentProduct(userAgent);
+  return product === "" || RUNTIME_PRODUCTS.has(product);
+}
+function initializeClientSlug(name2) {
+  const slug = slugOf(name2);
+  return isOwnSlug(slug) || GENERIC_CLIENT_NAMES.has(slug) ? "" : slug;
+}
+function referrerSlug(referrer) {
+  let host;
+  try {
+    host = new URL(referrer ?? "").hostname.toLowerCase().replace(/\.$/, "");
+  } catch {
+    return "";
+  }
+  if (!host.includes(".") || host.endsWith(".localhost") || host.endsWith(".local") || /^[\d.]+$/.test(host) || host.startsWith("[")) {
+    return "";
+  }
+  return slugOf(host.replace(/^www\./, ""));
+}
+function originForClient(client, serverVersion2, userAgent, signals = {}) {
+  const declared = slugOf(signals.declaredOrigin);
   const slug = slugOf(client?.name);
-  const own = slug === "" || slug === "fastmcp" || slug === "firecrawl-fastmcp";
-  const product = own ? userAgentProduct(userAgent) : "";
-  const base = !own ? `mcp-${slug}` : product ? `mcp-ua-${product}` : ORIGIN_SERVER;
+  const product = userAgentProduct(userAgent);
+  const remembered = initializeClientSlug(signals.initializeClient?.name);
+  const referrer = referrerSlug(signals.referrer);
+  const base = !isOwnSlug(declared) ? `mcp-${declared}` : !isOwnSlug(slug) ? `mcp-${slug}` : product && !RUNTIME_PRODUCTS.has(product) ? `mcp-ua-${product}` : remembered ? `mcp-${remembered}` : referrer ? `mcp-ref-${referrer}` : product ? `mcp-ua-${product}` : ORIGIN_SERVER;
   return serverVersion2 ? `${base}@${serverVersion2}` : base;
 }
 function originHeaders(origin) {
@@ -2595,7 +2667,12 @@ function requestOrigin(client, session) {
   return originForClient(
     client?.version ?? null,
     serverVersion,
-    session?.clientUserAgent
+    session?.clientUserAgent,
+    {
+      declaredOrigin: session?.clientOrigin,
+      initializeClient: session?.initializeClient,
+      referrer: session?.clientReferrer
+    }
   );
 }
 
@@ -3672,7 +3749,7 @@ var searchToolBaseFields = {
   location: z11.string().optional(),
   includeDomains: z11.array(searchDomainSchema).optional().describe("Hostnames to restrict results to. Mutually exclusive with excludeDomains."),
   excludeDomains: z11.array(searchDomainSchema).optional().describe("Hostnames to leave out of results. Mutually exclusive with includeDomains."),
-  sources: z11.array(searchSourceSchema).optional().describe("Search sources; authenticated sessions default to web + alexandria, keyless sessions to web only. " + ALEXANDRIA_SOURCES_OPT_OUT + ' Use ["alexandria"] alone for provider discovery without web results.'),
+  sources: z11.array(searchSourceSchema).optional().describe("Search sources; authenticated sessions default to web + alexandria, keyless sessions to web only. " + ALEXANDRIA_SOURCES_ALWAYS_ON + ' enterprise zdr or anon searches do not add it. Use ["alexandria"] alone for provider discovery without web results.'),
   categories: z11.array(z11.enum(["research", "pdf", "developer", "gov"])).optional().describe(
     "Limit results to specific source types. `research` restricts ordinary web results to research-affiliated websites and returns page snippets, which is separate from the `firecrawl_research_*` tools that search paper abstracts and full text across biomedical (PubMed, bioRxiv, medRxiv) and arXiv literature; `pdf` searches PDF results; `developer` searches an index built for coding agents over public repositories, GitHub issues, merged pull requests, repository READMEs, and code documentation; `gov` searches the Government Index of US federal, state, and local legal and regulatory sources, the index behind firecrawl_gov_search, and cannot be combined with other categories; gov hits can include historical versions, bill text, agency guidance, and third-party reproductions, so verify the issuer, jurisdiction, enacted/effective status, and version before citing current governing law, clarify a missing jurisdiction or ambiguous as-of date, and use general search for non-US questions or missing coverage (no hits does not establish that no applicable law exists). `developer` and `gov` return hits in `data.web` with `category` set to their name; the other categories also filter `data.web`."
   ),
@@ -3814,7 +3891,7 @@ async function relayExchangeError(run, context) {
     });
   }
 }
-async function postSearchWithFallback(client, body, implicitTools) {
+async function postSearchWithFallback(client, body, implicitTools, fallbackSources = ["web"]) {
   try {
     return await client.http.post("/v2/search", body);
   } catch (error2) {
@@ -3827,7 +3904,7 @@ async function postSearchWithFallback(client, body, implicitTools) {
     if (!implicitTools || response?.status !== 403 || !unavailable) throw error2;
     return client.http.post("/v2/search", {
       ...body,
-      sources: ["web"],
+      sources: fallbackSources,
       domainTools: false
     });
   }
@@ -3887,7 +3964,7 @@ var ConsoleLogger = class {
     }
   }
 };
-var FULL_PROFILE_INSTRUCTIONS = `Firecrawl provides web search, page retrieval, site URL discovery, multi-page collection, structured page data, monitoring, and multi-source research that returns structured data. Match the requested operation to the tool boundary: firecrawl_scrape retrieves one supplied page and can return JSON matching a supplied schema, firecrawl_map enumerates URLs under a site without retrieving their content, and firecrawl_agent runs multi-source research and returns structured data when the URLs are not known or the answer spans several sites (an entity plus its fields, a list, a dataset); its result is read with firecrawl_agent_status. Authenticated firecrawl_search returns web results together with matching Alexandria providers in data.tools. ${ALEXANDRIA_CATALOGUE_SENTENCE} A matching provider can return the same fields across several entities, provenance, exact figures or timestamps, or a large set of records through firecrawl_scrape with its published contract. If web results already answer the question, use them. For the same fields across multiple pages, firecrawl_find_tools offers free provider discovery. Use firecrawl_find_tools to read a contract that was not returned in full or to browse the catalogue by category. ${ALEXANDRIA_SOURCES_OPT_OUT} If no provider fits, continue with web search or firecrawl_agent. For biomedical, life-science, clinical, or arXiv literature, the firecrawl_research_* tools search a paper index of abstracts and full text; firecrawl_search with categories: ["research"] is a website filter over ordinary web results and reaches different sources. For a programming question (code behaviour, a library or framework, an API contract, an error message, or a known bug), firecrawl_developer_search (or firecrawl_search with categories: ["developer"]) searches an index of public repositories, GitHub issues, merged pull requests, READMEs, and code documentation. For a legal or regulatory question, firecrawl_gov_search searches primary law and regulatory material from US federal, state, and local government sources: statutes, regulations, codes, court opinions, and other government publications; firecrawl_search with categories: ["gov"] reaches the same sources and cannot be combined with other categories. firecrawl_search with sources: [{type: "alexandria"}] returns compact tool summaries in data.tools; toolDetail: "full" includes contracts, firecrawl_find_tools starts with categories, lists providers, then compact tools, and expands the selected full contract, and firecrawl_scrape with alexandria: [{provider, capability, options}] executes up to ten capabilities and returns their results. Alexandria access needs an API key on a team with it enabled. Provide only the required inputs and account for stated network or external side effects.`;
+var FULL_PROFILE_INSTRUCTIONS = `Firecrawl provides web search, page retrieval, site URL discovery, multi-page collection, structured page data, monitoring, and multi-source research that returns structured data. Match the requested operation to the tool boundary: firecrawl_scrape retrieves one supplied page and can return JSON matching a supplied schema, firecrawl_map enumerates URLs under a site without retrieving their content, and firecrawl_agent runs multi-source research and returns structured data when the URLs are not known or the answer spans several sites (an entity plus its fields, a list, a dataset); its result is read with firecrawl_agent_status. Authenticated firecrawl_search returns web results together with matching Alexandria providers in data.tools. ${ALEXANDRIA_CATALOGUE_SENTENCE} A matching provider can return the same fields across several entities, provenance, exact figures or timestamps, or a large set of records through firecrawl_scrape with its published contract. If web results already answer the question, use them. For the same fields across multiple pages, firecrawl_find_tools offers free provider discovery. Use firecrawl_find_tools to read a contract that was not returned in full or to browse the catalogue by category. ${ALEXANDRIA_SOURCES_ALWAYS_ON} If no provider fits, continue with web search or firecrawl_agent. For biomedical, life-science, clinical, or arXiv literature, the firecrawl_research_* tools search a paper index of abstracts and full text; firecrawl_search with categories: ["research"] is a website filter over ordinary web results and reaches different sources. For a programming question (code behaviour, a library or framework, an API contract, an error message, or a known bug), firecrawl_developer_search (or firecrawl_search with categories: ["developer"]) searches an index of public repositories, GitHub issues, merged pull requests, READMEs, and code documentation. For a legal or regulatory question, firecrawl_gov_search searches primary law and regulatory material from US federal, state, and local government sources: statutes, regulations, codes, court opinions, and other government publications; firecrawl_search with categories: ["gov"] reaches the same sources and cannot be combined with other categories. firecrawl_search with sources: [{type: "alexandria"}] returns compact tool summaries in data.tools; toolDetail: "full" includes contracts, firecrawl_find_tools starts with categories, lists providers, then compact tools, and expands the selected full contract, and firecrawl_scrape with alexandria: [{provider, capability, options}] executes up to ten capabilities and returns their results. Alexandria access needs an API key on a team with it enabled. Provide only the required inputs and account for stated network or external side effects.`;
 var KEYLESS_PROFILE_INSTRUCTIONS = `Hosted keyless sessions expose firecrawl_search, firecrawl_scrape, and firecrawl_parse with usage limits. firecrawl_search searches the web. For programming questions, firecrawl_search with categories: ["developer"] searches indexed public repositories, GitHub issues, merged pull requests, repository READMEs, and code documentation. For legal or regulatory questions, firecrawl_search with categories: ["gov"] searches US government legal and regulatory sources and cannot be combined with other categories. For biomedical, life-science, clinical, or arXiv literature, firecrawl_search with categories: ["research"] filters ordinary web results to research-affiliated websites. firecrawl_scrape retrieves one supplied page and can return JSON matching a supplied schema. firecrawl_parse processes supported local files through its two-phase upload flow. An Authorization bearer API key can provide higher usage limits and expose additional tools, subject to plan, deployment, and team policy, including firecrawl_map for site URL discovery, firecrawl_agent and firecrawl_agent_status for multi-source research that returns structured data when the URLs are not known, firecrawl_research_* for paper-index and repository research, and firecrawl_find_tools as the progressive Alexandria catalogue lookup alongside the Alexandria options of firecrawl_search and firecrawl_scrape for catalogued data providers.`;
 function deprecatedExtractPayload() {
   return {
@@ -3948,10 +4025,18 @@ function createFirecrawlMcpServer(options = {}) {
     const cached = request?.[authResultByRequest];
     if (cached) return cached;
     const authResult = authenticateSession(request).then((session) => {
-      const userAgent = request?.headers?.["user-agent"];
+      const headers = request?.headers;
+      const userAgent = headers?.["user-agent"];
       if (typeof userAgent === "string" && userAgent !== "") {
         session.clientUserAgent = userAgent;
       }
+      const declaredOrigin = normalizeHeader(headers?.[DECLARED_ORIGIN_HEADER]);
+      if (declaredOrigin) session.clientOrigin = declaredOrigin;
+      const referrer = [
+        normalizeHeader(headers?.["origin"]),
+        normalizeHeader(headers?.["referer"])
+      ].find((value) => value && value !== "null");
+      if (referrer) session.clientReferrer = referrer;
       return session;
     });
     if (request) request[authResultByRequest] = authResult;
@@ -4556,7 +4641,7 @@ Scrape one URL and return its content: markdown by default, or HTML, links, scre
 
 Firecrawl may serve recently indexed content; set \`maxAge: 0\` for a live fetch or a smaller \`maxAge\` to bound staleness. A successful response does not by itself confirm the page is still current. ${SAFE_MODE ? "A named browser profile loads saved session data without saving changes to it." : "Browser actions can change the live page when interactive actions are enabled."} Authenticated responses can include a \`metadata.scrapeId\` for optional scrape feedback.
 
-On an authenticated session with Alexandria access, \`firecrawl_search\` with \`sources\` unset and \`firecrawl_find_tools\` can discover providers for the same fields across several pages; a matching provider returns typed records in one call. Keyless sessions have no provider matches.
+On an authenticated session with Alexandria access, \`firecrawl_search\` and \`firecrawl_find_tools\` can discover providers for the same fields across several pages; a matching provider returns typed records in one call. Keyless sessions have no provider matches.
 
 Alexandria mode, on an authenticated session with Alexandria access: \`alexandria\` selects catalogued capability execution and is mutually exclusive with \`url\`.
 `,
@@ -4686,11 +4771,13 @@ For a programming question, add \`categories: ["developer"]\`; its hits return i
     ),
     execute: async (args, { session, log, client: mcpClient }) => {
       const { query, ...opts } = args;
+      const requestedSources = normalizeSearchSources(
+        Array.isArray(opts.sources) && opts.sources.length ? opts.sources : ["web"]
+      );
+      const addsAlexandria = hasCredential(session) && enterpriseAllowsAlexandria(opts.enterprise) && !hasAlexandria(requestedSources);
       const searchOpts = {
         ...opts,
-        sources: normalizeSearchSources(
-          opts.sources ?? (hasCredential(session) ? ["web", "alexandria"] : ["web"])
-        )
+        sources: addsAlexandria ? withAlexandriaSource(requestedSources) : requestedSources
       };
       searchOpts.domainTools ??= defaultDomainTools(searchOpts.sources);
       searchOpts.toolDetail ??= "compact";
@@ -4720,7 +4807,8 @@ For a programming question, add \`categories: ["developer"]\`; its hits return i
       const postSearch = () => postSearchWithFallback(
         client,
         searchBody,
-        opts.sources === void 0 && opts.domainTools !== true
+        addsAlexandria && opts.domainTools !== true,
+        requestedSources
       );
       const httpRes = await relayExchangeError(postSearch, { tool: "firecrawl_search" });
       return structuredCompact(withoutDiscoveredToolPrices(httpRes?.data ?? {}));
@@ -5723,15 +5811,19 @@ Set \`redactPII\` to request redaction of personally identifiable information in
 export {
   ALEXANDRIA_CATALOGUE_VERTICALS,
   ALEXANDRIA_SEARCH_INSTRUCTIONS,
+  DECLARED_ORIGIN_HEADER,
   keylessToolNames as KEYLESS_TOOL_NAMES,
   SEARCH_DOMAINS_CONFLICT_MESSAGE,
   UserError2 as UserError,
   assertExchangeCredential,
   createFirecrawlMcpServer,
   defaultDomainTools,
+  enterpriseAllowsAlexandria,
   hasAlexandria,
+  initializeClientSlug,
   invalidApiKeyRecoveryPayload,
   invalidOAuthRecoveryPayload,
+  isRuntimeUserAgent,
   keylessQuotaReason,
   keylessSignupUrlFrom,
   normalizeHeader,
@@ -5748,5 +5840,6 @@ export {
   searchQueryIsValid,
   searchToolBaseFields,
   structuredCompactResult as structuredCompact,
+  withAlexandriaSource,
   withoutTrailingSlash
 };

package/package.json

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