firecrawl-mcp 3.21.3 → 3.21.4

package/dist/index.js

@@ -2487,6 +2487,247 @@ var scrapeParamsSchema = z4.object({
     saveChanges: z4.boolean().optional()
   }).optional()
 });
+var parseOptionParamsSchema = z4.object({
+  formats: z4.array(
+    z4.enum([
+      "markdown",
+      "html",
+      "rawHtml",
+      "links",
+      "summary",
+      "json",
+      "query"
+    ])
+  ).optional(),
+  jsonOptions: z4.object({
+    prompt: z4.string().optional(),
+    schema: z4.record(z4.string(), z4.any()).optional()
+  }).optional(),
+  queryOptions: z4.object({
+    prompt: z4.string().max(1e4),
+    mode: z4.enum(["directQuote", "freeform"]).default("freeform")
+  }).optional(),
+  parsers: z4.array(z4.enum(["pdf"])).optional(),
+  pdfOptions: z4.object({
+    maxPages: z4.number().int().min(1).max(1e4).optional()
+  }).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: 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: z4.string().optional().describe(
+    "Optional MIME type override. If omitted, the server infers the file kind from the extension."
+  )
+});
+var hostedParseParamsSchema = parseOptionParamsSchema.extend({
+  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: z4.string().min(1).optional().describe(
+    "Phase 2 only: short-lived upload reference returned by phase 1 after the local PUT upload completes."
+  ),
+  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: 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) => {
+  const hasFilePath = typeof value.filePath === "string" && value.filePath.length > 0;
+  const hasUploadRef = typeof value.uploadRef === "string" && value.uploadRef.length > 0;
+  if (hasFilePath === hasUploadRef) {
+    ctx.addIssue({
+      code: z4.ZodIssueCode.custom,
+      message: "Hosted firecrawl_parse requires exactly one of filePath (phase 1) or uploadRef (phase 2).",
+      path: hasFilePath && hasUploadRef ? ["uploadRef"] : ["filePath"]
+    });
+  }
+});
+var parseParamsSchema = process.env.CLOUD_SERVICE === "true" ? hostedParseParamsSchema : localParseParamsSchema;
+var EXTENSION_CONTENT_TYPES = {
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".xhtml": "application/xhtml+xml",
+  ".pdf": "application/pdf",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".doc": "application/msword",
+  ".odt": "application/vnd.oasis.opendocument.text",
+  ".rtf": "application/rtf",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".xls": "application/vnd.ms-excel"
+};
+function inferContentType(filename) {
+  const ext = path.extname(filename).toLowerCase();
+  return EXTENSION_CONTENT_TYPES[ext] ?? "application/octet-stream";
+}
+function extractParseOptions(args2) {
+  const { filePath, uploadRef, contentType, declaredSizeBytes, ...options } = args2;
+  return options;
+}
+function buildParseOptionsPayload(options) {
+  const transformed = transformScrapeParams(options);
+  const cleaned = removeEmptyTopLevel(transformed);
+  return { origin: ORIGIN, ...cleaned };
+}
+function buildContinuationArguments(uploadRef, options) {
+  return {
+    uploadRef,
+    ...removeEmptyTopLevel(options)
+  };
+}
+function shellQuote(value) {
+  if (value.length === 0) return "''";
+  return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+function parseApiData(json) {
+  return json && typeof json === "object" && "data" in json ? json.data : json;
+}
+async function apiPostJson(pathName, body, apiKey) {
+  const response = await fetch(`${resolveApiBaseUrl()}${pathName}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: JSON.stringify(body)
+  });
+  const responseText = await response.text();
+  let parsed;
+  try {
+    parsed = responseText ? JSON.parse(responseText) : {};
+  } catch {
+    parsed = { raw: responseText };
+  }
+  if (!response.ok) {
+    throw new Error(
+      parsed?.error || parsed?.message || `Firecrawl request failed (HTTP ${response.status})`
+    );
+  }
+  return parsed;
+}
+async function apiPostJsonForSession(pathName, body, session) {
+  if (session?.firecrawlApiKey) {
+    return apiPostJson(pathName, body, session.firecrawlApiKey);
+  }
+  if (isKeylessMode(session)) {
+    return keylessPost(pathName, body, session);
+  }
+  throw new Error(
+    "Firecrawl credentials or keyless eligibility required for hosted parse."
+  );
+}
+function buildCurlUploadCommand(filePath, upload) {
+  const method = upload.method ?? "PUT";
+  const headerArgs = Object.entries(upload.headers ?? {}).sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => `-H ${shellQuote(`${key}: ${value}`)}`);
+  if (method.toUpperCase() === "POST" && upload.fields) {
+    const fieldArgs = Object.entries(upload.fields).sort(([a], [b]) => a.localeCompare(b)).flatMap(([key, value]) => ["-F", shellQuote(`${key}=${value}`)]);
+    return [
+      "curl",
+      "-X",
+      shellQuote("POST"),
+      ...headerArgs,
+      ...fieldArgs,
+      "-F",
+      shellQuote(`file=@${filePath}`),
+      shellQuote(upload.uploadUrl)
+    ].join(" ");
+  }
+  return [
+    "curl",
+    "-X",
+    shellQuote(method),
+    ...headerArgs,
+    "--upload-file",
+    shellQuote(filePath),
+    shellQuote(upload.uploadUrl)
+  ].join(" ");
+}
+async function executeHostedParse(args2, session, log) {
+  const hasFilePath = typeof args2.filePath === "string" && args2.filePath.length > 0;
+  const hasUploadRef = typeof args2.uploadRef === "string" && args2.uploadRef.length > 0;
+  if (hasFilePath === hasUploadRef) {
+    throw new Error(
+      "Hosted firecrawl_parse requires exactly one of filePath or uploadRef."
+    );
+  }
+  if (!session?.firecrawlApiKey && !isKeylessMode(session)) {
+    return asText2({
+      success: false,
+      mode: "hosted-upload-ref-auth-required",
+      message: "Hosted firecrawl_parse requires an authenticated Firecrawl session or keyless eligibility before a local file upload URL can be minted. Connect a Firecrawl account, provide an API key, or use keyless hosted MCP while eligible, then call firecrawl_parse again."
+    });
+  }
+  const options = extractParseOptions(args2);
+  if (hasFilePath && args2.filePath) {
+    const filename = path.basename(args2.filePath);
+    const contentType = typeof args2.contentType === "string" && args2.contentType.length > 0 ? args2.contentType : inferContentType(filename);
+    const uploadRequest = removeEmptyTopLevel({
+      filename,
+      contentType,
+      declaredSizeBytes: args2.declaredSizeBytes
+    });
+    log.info("Creating hosted parse upload URL", { filename, contentType });
+    const uploadJson = await apiPostJsonForSession(
+      "/v2/parse/upload-url",
+      uploadRequest,
+      session
+    );
+    const upload = parseApiData(uploadJson);
+    if (!upload?.uploadUrl || !upload?.uploadRef) {
+      throw new Error(
+        "Firecrawl upload-url response did not include uploadUrl and uploadRef"
+      );
+    }
+    const uploadHeaders = upload.headers && Object.keys(upload.headers).length > 0 ? upload.headers : (upload.method ?? "PUT").toUpperCase() === "POST" ? {} : { "Content-Type": contentType };
+    const uploadForCommand = { ...upload, headers: uploadHeaders };
+    return asText2({
+      success: true,
+      mode: "hosted-upload-ref-awaiting-upload",
+      message: "Hosted MCP cannot read local files. Run the local upload command, then call firecrawl_parse again with uploadRef. No Firecrawl API key is included in this command.",
+      upload: {
+        command: buildCurlUploadCommand(args2.filePath, uploadForCommand),
+        method: upload.method ?? "PUT",
+        headers: uploadHeaders,
+        fields: upload.fields,
+        uploadUrl: upload.uploadUrl,
+        uploadRef: upload.uploadRef,
+        expiresAt: upload.expiresAt,
+        maxSizeBytes: upload.maxSizeBytes
+      },
+      nextToolCall: {
+        name: "firecrawl_parse",
+        arguments: buildContinuationArguments(upload.uploadRef, options)
+      },
+      notes: [
+        "Run the curl command on the machine that can read filePath.",
+        "After the PUT succeeds, use nextToolCall as the second MCP tool call.",
+        "Clients without a local upload mechanism cannot complete hosted parse for local files."
+      ]
+    });
+  }
+  const parsePayload = {
+    uploadRef: args2.uploadRef,
+    ...buildParseOptionsPayload(options)
+  };
+  log.info("Parsing hosted upload reference");
+  const parseJson = await apiPostJsonForSession(
+    "/v2/parse",
+    parsePayload,
+    session
+  );
+  return asText2(parseJson);
+}
 server.addTool({
   name: "firecrawl_scrape",
   annotations: {
@@ -3702,82 +3943,29 @@ Stop an interact session for a scraped page. Call this when you are done interac
     return asText2(res?.data ?? {});
   }
 });
-if (process.env.CLOUD_SERVICE !== "true") {
-  let inferContentType = function(filename) {
-    const ext = path.extname(filename).toLowerCase();
-    return EXTENSION_CONTENT_TYPES[ext] ?? "application/octet-stream";
-  };
-  inferContentType2 = inferContentType;
-  const parseParamsSchema = z4.object({
-    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: z4.string().optional().describe(
-      "Optional MIME type override. If omitted, the server infers the file kind from the extension."
-    ),
-    formats: z4.array(
-      z4.enum([
-        "markdown",
-        "html",
-        "rawHtml",
-        "links",
-        "summary",
-        "json",
-        "query"
-      ])
-    ).optional(),
-    jsonOptions: z4.object({
-      prompt: z4.string().optional(),
-      schema: z4.record(z4.string(), z4.any()).optional()
-    }).optional(),
-    queryOptions: z4.object({
-      prompt: z4.string().max(1e4),
-      mode: z4.enum(["directQuote", "freeform"]).default("freeform")
-    }).optional(),
-    parsers: z4.array(z4.enum(["pdf"])).optional(),
-    pdfOptions: z4.object({
-      maxPages: z4.number().int().min(1).max(1e4).optional()
-    }).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()
-  });
-  const EXTENSION_CONTENT_TYPES = {
-    ".html": "text/html",
-    ".htm": "text/html",
-    ".pdf": "application/pdf",
-    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-    ".doc": "application/msword",
-    ".odt": "application/vnd.oasis.opendocument.text",
-    ".rtf": "application/rtf",
-    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-    ".xls": "application/vnd.ms-excel"
-  };
-  server.addTool({
-    name: "firecrawl_parse",
-    annotations: {
-      title: "Parse a local file",
-      readOnlyHint: true,
-      // Reads and parses a local file; does not modify the file on disk.
-      openWorldHint: false,
-      // Operates on a local filesystem path, not the open web.
-      destructiveHint: false
-      // Read-only parsing; no deletion or writes to the source file.
-    },
-    description: `
-Parse a file from the local filesystem using a self-hosted Firecrawl API's /v2/parse endpoint.
-This is the fastest and most reliable way to extract content from a document on disk \u2014 if the file lives locally and the MCP is pointed at a self-hosted Firecrawl instance, you should always prefer this tool over uploading the file elsewhere and then scraping it.
+server.addTool({
+  name: "firecrawl_parse",
+  annotations: {
+    title: "Parse a local file",
+    readOnlyHint: true,
+    // Local mode reads a file; hosted mode only returns upload instructions or parses an uploadRef.
+    openWorldHint: false,
+    // Operates on a local filesystem path/upload reference, not an arbitrary web URL.
+    destructiveHint: false
+    // Read-only parsing; no deletion or writes to the source file.
+  },
+  description: `
+Parse a file using Firecrawl's /v2/parse endpoint.
+
+In local/non-cloud MCP mode, this tool reads filePath from the MCP server filesystem and posts multipart data to the configured self-hosted FIRECRAWL_API_URL, preserving the existing direct-read behavior.
+
+In hosted CLOUD_SERVICE mode, this tool is a two-call flow because hosted MCP cannot read your local filesystem:
+1. Call with filePath, contentType, parse options, and optional declaredSizeBytes. The hosted server mints a short-lived upload URL and returns a safe local curl PUT command plus nextToolCall.
+2. Run the returned curl command locally, then call firecrawl_parse again with uploadRef and the desired parse options. The hosted server calls /v2/parse server-side with your session credential.
 
-**Best for:** Extracting content from a local document (PDF, Word, Excel, HTML, etc.) when you don't want to host it on the public web first; pulling structured data out of a file with JSON format; converting binary documents into markdown for downstream reasoning.
+**Best for:** Extracting content from a local document (PDF, Word, Excel, HTML, etc.); pulling structured data out of a file with JSON format; converting binary documents into markdown for downstream reasoning.
 **Not recommended for:** Remote URLs (use firecrawl_scrape); multiple files at once (call parse multiple times); documents that require interactive actions, screenshots, or change tracking \u2014 those aren't supported by the parse endpoint.
-**Common mistakes:** Passing a URL instead of a local file path; requesting an unsupported format (screenshot, branding, changeTracking); setting waitFor, location, mobile, or a non-basic/auto proxy \u2014 parse uploads reject all of those.
+**Common mistakes:** In hosted mode, do not pass both filePath and uploadRef. Phase 1 uses filePath only to generate upload instructions; phase 2 uses uploadRef only to parse server-side.
 
 **Supported file types:** .html, .htm, .xhtml, .pdf, .docx, .doc, .odt, .rtf, .xlsx, .xls
 **Unsupported options:** actions, screenshot/branding/changeTracking formats, waitFor > 0, location, mobile, proxy values other than "auto" or "basic".
@@ -3786,122 +3974,96 @@ This is the fastest and most reliable way to extract content from a document on
 **CRITICAL - Format Selection (same rules as firecrawl_scrape):**
 When the user asks for SPECIFIC data points from a document, you MUST use JSON format with a schema. Only use markdown when the user needs the ENTIRE document content.
 
-**Use JSON format when the user asks for:**
-- Specific fields, parameters, or values from a form / PDF / spreadsheet
-- Prices, numbers, or other structured data
-- Lists of items or properties
-
-**Use markdown format when:**
-- User wants to read, summarize, or analyze the full document
-- User explicitly asks for the complete content
-
 **Handling PDFs:**
 Add \`"parsers": ["pdf"]\` (optionally with \`pdfOptions.maxPages\`) when parsing a PDF so the PDF engine is invoked explicitly. For very long documents, cap \`maxPages\` to keep the response within token limits.
 
-**Usage Example (markdown from a local PDF):**
+**Hosted phase 1 example:**
 \`\`\`json
 {
   "name": "firecrawl_parse",
   "arguments": {
     "filePath": "/absolute/path/to/document.pdf",
+    "contentType": "application/pdf",
     "formats": ["markdown"],
     "parsers": ["pdf"],
-    "onlyMainContent": true
+    "zeroDataRetention": true
   }
 }
 \`\`\`
 
-**Usage Example (structured JSON extraction from a local HTML file):**
+**Hosted phase 2 example:**
 \`\`\`json
 {
   "name": "firecrawl_parse",
   "arguments": {
-    "filePath": "./invoice.html",
-    "formats": ["json"],
-    "jsonOptions": {
-      "prompt": "Extract the invoice number, total, and line items",
-      "schema": {
-        "type": "object",
-        "properties": {
-          "invoiceNumber": { "type": "string" },
-          "total": { "type": "number" },
-          "lineItems": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "properties": {
-                "description": { "type": "string" },
-                "amount": { "type": "number" }
-              }
-            }
-          }
-        }
-      }
-    }
+    "uploadRef": "upload-ref-from-phase-1",
+    "formats": ["markdown"],
+    "parsers": ["pdf"],
+    "zeroDataRetention": true
   }
 }
 \`\`\`
-**Returns:** A parsed document with markdown, html, links, summary, json, or query results depending on the requested formats.
+
+**Returns:** Phase 1 hosted upload instructions or a parsed document with markdown, html, links, summary, json, or query results depending on the requested formats.
 `,
-    parameters: parseParamsSchema,
-    execute: async (args2, { session, log }) => {
-      const apiUrl = process.env.FIRECRAWL_API_URL;
-      if (!apiUrl) {
-        throw new Error(
-          "firecrawl_parse requires FIRECRAWL_API_URL to be set to a self-hosted Firecrawl API instance."
-        );
-      }
-      const {
-        filePath,
-        contentType: overrideContentType,
-        ...options
-      } = args2;
-      const absPath = path.resolve(filePath);
-      const buffer = await readFile(absPath);
-      const filename = path.basename(absPath);
-      const fileContentType = overrideContentType && overrideContentType.length > 0 ? overrideContentType : inferContentType(filename);
-      const transformed = transformScrapeParams(
-        options
+  parameters: parseParamsSchema,
+  execute: async (args2, { session, log }) => {
+    if (process.env.CLOUD_SERVICE === "true") {
+      return executeHostedParse(args2, session, log);
+    }
+    const apiUrl = process.env.FIRECRAWL_API_URL;
+    if (!apiUrl) {
+      throw new Error(
+        "firecrawl_parse requires FIRECRAWL_API_URL to be set to a self-hosted Firecrawl API instance."
       );
-      const cleaned = removeEmptyTopLevel(transformed);
-      const optionsPayload = { origin: ORIGIN, ...cleaned };
-      const form = new FormData();
-      const blob = new Blob([new Uint8Array(buffer)], {
-        type: fileContentType
-      });
-      form.append("file", blob, filename);
-      form.append("options", JSON.stringify(optionsPayload));
-      const headers = { ...ORIGIN_HEADERS2 };
-      const apiKey = session?.firecrawlApiKey;
-      if (apiKey) {
-        headers["Authorization"] = `Bearer ${apiKey}`;
-      }
-      const endpoint = `${apiUrl.replace(/\/$/, "")}/v2/parse`;
-      log.info("Parsing local file", {
-        endpoint,
-        filename,
-        size: buffer.length
-      });
-      const response = await fetch(endpoint, {
-        method: "POST",
-        headers,
-        body: form
-      });
-      const responseText = await response.text();
-      if (!response.ok) {
-        throw new Error(
-          `Parse request failed with status ${response.status}: ${responseText}`
-        );
-      }
-      try {
-        return asText2(JSON.parse(responseText));
-      } catch {
-        return responseText;
-      }
     }
-  });
-}
-var inferContentType2;
+    const {
+      filePath,
+      contentType: overrideContentType,
+      ...options
+    } = args2;
+    const absPath = path.resolve(filePath);
+    const buffer = await readFile(absPath);
+    const filename = path.basename(absPath);
+    const fileContentType = overrideContentType && overrideContentType.length > 0 ? overrideContentType : inferContentType(filename);
+    const optionsPayload = buildParseOptionsPayload(
+      options
+    );
+    const form = new FormData();
+    const blob = new Blob([new Uint8Array(buffer)], {
+      type: fileContentType
+    });
+    form.append("file", blob, filename);
+    form.append("options", JSON.stringify(optionsPayload));
+    const headers = { ...ORIGIN_HEADERS2 };
+    const apiKey = session?.firecrawlApiKey;
+    if (apiKey) {
+      headers["Authorization"] = `Bearer ${apiKey}`;
+    }
+    const endpoint = `${apiUrl.replace(/\/$/, "")}/v2/parse`;
+    log.info("Parsing local file", {
+      endpoint,
+      filename,
+      size: buffer.length
+    });
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers,
+      body: form
+    });
+    const responseText = await response.text();
+    if (!response.ok) {
+      throw new Error(
+        `Parse request failed with status ${response.status}: ${responseText}`
+      );
+    }
+    try {
+      return asText2(JSON.parse(responseText));
+    } catch {
+      return responseText;
+    }
+  }
+});
 var PORT = Number(process.env.PORT || 3e3);
 var HOST = process.env.CLOUD_SERVICE === "true" ? "0.0.0.0" : process.env.HOST || "localhost";
 var args;

package/package.json

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