firecrawl-mcp 3.22.1 → 3.22.3

package/dist/index.js

@@ -3,1327 +3,14 @@
 // src/index.ts
 import FirecrawlApp from "@mendable/firecrawl-js";
 import dotenv from "dotenv";
+import { FastMCP } from "fastmcp";
 import { readFile } from "fs/promises";
 import { createRequire } from "module";
 import path from "path";
-import { z as z4 } from "zod";
-
-// src/fastmcp/FastMCP.ts
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  CallToolRequestSchema,
-  CompleteRequestSchema,
-  ErrorCode,
-  GetPromptRequestSchema,
-  ListPromptsRequestSchema,
-  ListResourcesRequestSchema,
-  ListResourceTemplatesRequestSchema,
-  ListToolsRequestSchema,
-  McpError,
-  ReadResourceRequestSchema,
-  RootsListChangedNotificationSchema,
-  SetLevelRequestSchema
-} from "@modelcontextprotocol/sdk/types.js";
-import { EventEmitter } from "events";
-import Fuse from "fuse.js";
-import { startHTTPServer } from "mcp-proxy";
-import { setTimeout as delay } from "timers/promises";
-import parseURITemplate from "uri-templates";
-import { toJsonSchema } from "xsschema";
-import { z } from "zod";
-var FastMCPError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = new.target.name;
-  }
-};
-var UnexpectedStateError = class extends FastMCPError {
-  extras;
-  constructor(message, extras) {
-    super(message);
-    this.name = new.target.name;
-    this.extras = extras;
-  }
-};
-var UserError = class extends UnexpectedStateError {
-};
-var TextContentZodSchema = z.object({
-  /**
-   * The text content of the message.
-   */
-  text: z.string(),
-  type: z.literal("text")
-}).strict();
-var ImageContentZodSchema = z.object({
-  /**
-   * The base64-encoded image data.
-   */
-  data: z.string().base64(),
-  /**
-   * The MIME type of the image. Different providers may support different image types.
-   */
-  mimeType: z.string(),
-  type: z.literal("image")
-}).strict();
-var AudioContentZodSchema = z.object({
-  /**
-   * The base64-encoded audio data.
-   */
-  data: z.string().base64(),
-  mimeType: z.string(),
-  type: z.literal("audio")
-}).strict();
-var ResourceContentZodSchema = z.object({
-  resource: z.object({
-    blob: z.string().optional(),
-    mimeType: z.string().optional(),
-    text: z.string().optional(),
-    uri: z.string()
-  }),
-  type: z.literal("resource")
-}).strict();
-var ResourceLinkZodSchema = z.object({
-  description: z.string().optional(),
-  mimeType: z.string().optional(),
-  name: z.string(),
-  title: z.string().optional(),
-  type: z.literal("resource_link"),
-  uri: z.string()
-});
-var ContentZodSchema = z.discriminatedUnion("type", [
-  TextContentZodSchema,
-  ImageContentZodSchema,
-  AudioContentZodSchema,
-  ResourceContentZodSchema,
-  ResourceLinkZodSchema
-]);
-var ContentResultZodSchema = z.object({
-  content: ContentZodSchema.array(),
-  isError: z.boolean().optional()
-}).strict();
-var CompletionZodSchema = z.object({
-  /**
-   * Indicates whether there are additional completion options beyond those provided in the current response, even if the exact total is unknown.
-   */
-  hasMore: z.optional(z.boolean()),
-  /**
-   * The total number of completion options available. This can exceed the number of values actually sent in the response.
-   */
-  total: z.optional(z.number().int()),
-  /**
-   * An array of completion values. Must not exceed 100 items.
-   */
-  values: z.array(z.string()).max(100)
-});
-var FastMCPSessionEventEmitterBase = EventEmitter;
-var escapeWWWAuthenticateValue = (value) => {
-  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-};
-var FastMCPSessionEventEmitter = class extends FastMCPSessionEventEmitterBase {
-};
-var FastMCPSession = class extends FastMCPSessionEventEmitter {
-  get clientCapabilities() {
-    return this.#clientCapabilities ?? null;
-  }
-  get isReady() {
-    return this.#connectionState === "ready";
-  }
-  get loggingLevel() {
-    return this.#loggingLevel;
-  }
-  get roots() {
-    return this.#roots;
-  }
-  get server() {
-    return this.#server;
-  }
-  #auth;
-  #capabilities = {};
-  #clientCapabilities;
-  #connectionState = "connecting";
-  #logger;
-  #loggingLevel = "info";
-  #needsEventLoopFlush = false;
-  #pingConfig;
-  #pingInterval = null;
-  #prompts = [];
-  #resources = [];
-  #resourceTemplates = [];
-  #roots = [];
-  #rootsConfig;
-  #server;
-  #utils;
-  constructor({
-    auth,
-    instructions,
-    logger,
-    name,
-    ping,
-    prompts,
-    resources,
-    resourcesTemplates,
-    roots,
-    tools,
-    transportType,
-    utils,
-    version
-  }) {
-    super();
-    this.#auth = auth;
-    this.#logger = logger;
-    this.#pingConfig = ping;
-    this.#rootsConfig = roots;
-    this.#needsEventLoopFlush = transportType === "httpStream";
-    if (tools.length) {
-      this.#capabilities.tools = {};
-    }
-    if (resources.length || resourcesTemplates.length) {
-      this.#capabilities.resources = {};
-    }
-    if (prompts.length) {
-      for (const prompt of prompts) {
-        this.addPrompt(prompt);
-      }
-      this.#capabilities.prompts = {};
-    }
-    this.#capabilities.logging = {};
-    this.#server = new Server(
-      { name, version },
-      { capabilities: this.#capabilities, instructions }
-    );
-    this.#utils = utils;
-    this.setupErrorHandling();
-    this.setupLoggingHandlers();
-    this.setupRootsHandlers();
-    this.setupCompleteHandlers();
-    if (tools.length) {
-      this.setupToolHandlers(tools);
-    }
-    if (resources.length || resourcesTemplates.length) {
-      for (const resource of resources) {
-        this.addResource(resource);
-      }
-      this.setupResourceHandlers(resources);
-      if (resourcesTemplates.length) {
-        for (const resourceTemplate of resourcesTemplates) {
-          this.addResourceTemplate(resourceTemplate);
-        }
-        this.setupResourceTemplateHandlers(resourcesTemplates);
-      }
-    }
-    if (prompts.length) {
-      this.setupPromptHandlers(prompts);
-    }
-  }
-  async close() {
-    this.#connectionState = "closed";
-    if (this.#pingInterval) {
-      clearInterval(this.#pingInterval);
-    }
-    try {
-      await this.#server.close();
-    } catch (error) {
-      this.#logger.error("[FastMCP error]", "could not close server", error);
-    }
-  }
-  async connect(transport) {
-    if (this.#server.transport) {
-      throw new UnexpectedStateError("Server is already connected");
-    }
-    this.#connectionState = "connecting";
-    try {
-      await this.#server.connect(transport);
-      let attempt = 0;
-      const maxAttempts = 10;
-      const retryDelay = 100;
-      while (attempt++ < maxAttempts) {
-        const capabilities = this.#server.getClientCapabilities();
-        if (capabilities) {
-          this.#clientCapabilities = capabilities;
-          break;
-        }
-        await delay(retryDelay);
-      }
-      if (!this.#clientCapabilities) {
-        this.#logger.warn(
-          `[FastMCP warning] could not infer client capabilities after ${maxAttempts} attempts. Connection may be unstable.`
-        );
-      }
-      if (this.#clientCapabilities?.roots?.listChanged && typeof this.#server.listRoots === "function") {
-        try {
-          const roots = await this.#server.listRoots();
-          this.#roots = roots?.roots || [];
-        } catch (e) {
-          if (e instanceof McpError && e.code === ErrorCode.MethodNotFound) {
-            this.#logger.debug(
-              "[FastMCP debug] listRoots method not supported by client"
-            );
-          } else {
-            this.#logger.error(
-              `[FastMCP error] received error listing roots.
-
-${e instanceof Error ? e.stack : JSON.stringify(e)}`
-            );
-          }
-        }
-      }
-      if (this.#clientCapabilities) {
-        const pingConfig = this.#getPingConfig(transport);
-        if (pingConfig.enabled) {
-          this.#pingInterval = setInterval(async () => {
-            try {
-              await this.#server.ping();
-            } catch {
-              const logLevel = pingConfig.logLevel;
-              if (logLevel === "debug") {
-                this.#logger.debug("[FastMCP debug] server ping failed");
-              } else if (logLevel === "warning") {
-                this.#logger.warn(
-                  "[FastMCP warning] server is not responding to ping"
-                );
-              } else if (logLevel === "error") {
-                this.#logger.error(
-                  "[FastMCP error] server is not responding to ping"
-                );
-              } else {
-                this.#logger.info("[FastMCP info] server ping failed");
-              }
-            }
-          }, pingConfig.intervalMs);
-        }
-      }
-      this.#connectionState = "ready";
-      this.emit("ready");
-    } catch (error) {
-      this.#connectionState = "error";
-      const errorEvent = {
-        error: error instanceof Error ? error : new Error(String(error))
-      };
-      this.emit("error", errorEvent);
-      throw error;
-    }
-  }
-  async requestSampling(message, options) {
-    return this.#server.createMessage(message, options);
-  }
-  waitForReady() {
-    if (this.isReady) {
-      return Promise.resolve();
-    }
-    if (this.#connectionState === "error" || this.#connectionState === "closed") {
-      return Promise.reject(
-        new Error(`Connection is in ${this.#connectionState} state`)
-      );
-    }
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        reject(
-          new Error(
-            "Connection timeout: Session failed to become ready within 5 seconds"
-          )
-        );
-      }, 5e3);
-      this.once("ready", () => {
-        clearTimeout(timeout);
-        resolve();
-      });
-      this.once("error", (event) => {
-        clearTimeout(timeout);
-        reject(event.error);
-      });
-    });
-  }
-  #getPingConfig(transport) {
-    const pingConfig = this.#pingConfig || {};
-    let defaultEnabled = false;
-    if ("type" in transport) {
-      if (transport.type === "httpStream") {
-        defaultEnabled = true;
-      }
-    }
-    return {
-      enabled: pingConfig.enabled !== void 0 ? pingConfig.enabled : defaultEnabled,
-      intervalMs: pingConfig.intervalMs || 5e3,
-      logLevel: pingConfig.logLevel || "debug"
-    };
-  }
-  addPrompt(inputPrompt) {
-    const completers = {};
-    const enums = {};
-    const fuseInstances = {};
-    for (const argument of inputPrompt.arguments ?? []) {
-      if (argument.complete) {
-        completers[argument.name] = argument.complete;
-      }
-      if (argument.enum) {
-        enums[argument.name] = argument.enum;
-        fuseInstances[argument.name] = new Fuse(argument.enum, {
-          includeScore: true,
-          threshold: 0.3
-          // More flexible matching!
-        });
-      }
-    }
-    const prompt = {
-      ...inputPrompt,
-      complete: async (name, value, auth) => {
-        if (completers[name]) {
-          return await completers[name](value, auth);
-        }
-        if (fuseInstances[name]) {
-          const result = fuseInstances[name].search(value);
-          return {
-            total: result.length,
-            values: result.map((item) => item.item)
-          };
-        }
-        return {
-          values: []
-        };
-      }
-    };
-    this.#prompts.push(prompt);
-  }
-  addResource(inputResource) {
-    this.#resources.push(inputResource);
-  }
-  addResourceTemplate(inputResourceTemplate) {
-    const completers = {};
-    for (const argument of inputResourceTemplate.arguments ?? []) {
-      if (argument.complete) {
-        completers[argument.name] = argument.complete;
-      }
-    }
-    const resourceTemplate = {
-      ...inputResourceTemplate,
-      complete: async (name, value, auth) => {
-        if (completers[name]) {
-          return await completers[name](value, auth);
-        }
-        return {
-          values: []
-        };
-      }
-    };
-    this.#resourceTemplates.push(resourceTemplate);
-  }
-  setupCompleteHandlers() {
-    this.#server.setRequestHandler(CompleteRequestSchema, async (request) => {
-      if (request.params.ref.type === "ref/prompt") {
-        const prompt = this.#prompts.find(
-          (prompt2) => prompt2.name === request.params.ref.name
-        );
-        if (!prompt) {
-          throw new UnexpectedStateError("Unknown prompt", {
-            request
-          });
-        }
-        if (!prompt.complete) {
-          throw new UnexpectedStateError("Prompt does not support completion", {
-            request
-          });
-        }
-        const completion = CompletionZodSchema.parse(
-          await prompt.complete(
-            request.params.argument.name,
-            request.params.argument.value,
-            this.#auth
-          )
-        );
-        return {
-          completion
-        };
-      }
-      if (request.params.ref.type === "ref/resource") {
-        const resource = this.#resourceTemplates.find(
-          (resource2) => resource2.uriTemplate === request.params.ref.uri
-        );
-        if (!resource) {
-          throw new UnexpectedStateError("Unknown resource", {
-            request
-          });
-        }
-        if (!("uriTemplate" in resource)) {
-          throw new UnexpectedStateError("Unexpected resource");
-        }
-        if (!resource.complete) {
-          throw new UnexpectedStateError(
-            "Resource does not support completion",
-            {
-              request
-            }
-          );
-        }
-        const completion = CompletionZodSchema.parse(
-          await resource.complete(
-            request.params.argument.name,
-            request.params.argument.value,
-            this.#auth
-          )
-        );
-        return {
-          completion
-        };
-      }
-      throw new UnexpectedStateError("Unexpected completion request", {
-        request
-      });
-    });
-  }
-  setupErrorHandling() {
-    this.#server.onerror = (error) => {
-      this.#logger.error("[FastMCP error]", error);
-    };
-  }
-  setupLoggingHandlers() {
-    this.#server.setRequestHandler(SetLevelRequestSchema, (request) => {
-      this.#loggingLevel = request.params.level;
-      return {};
-    });
-  }
-  setupPromptHandlers(prompts) {
-    this.#server.setRequestHandler(ListPromptsRequestSchema, async () => {
-      return {
-        prompts: prompts.map((prompt) => {
-          return {
-            arguments: prompt.arguments,
-            complete: prompt.complete,
-            description: prompt.description,
-            name: prompt.name
-          };
-        })
-      };
-    });
-    this.#server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-      const prompt = prompts.find(
-        (prompt2) => prompt2.name === request.params.name
-      );
-      if (!prompt) {
-        throw new McpError(
-          ErrorCode.MethodNotFound,
-          `Unknown prompt: ${request.params.name}`
-        );
-      }
-      const args2 = request.params.arguments;
-      for (const arg of prompt.arguments ?? []) {
-        if (arg.required && !(args2 && arg.name in args2)) {
-          throw new McpError(
-            ErrorCode.InvalidRequest,
-            `Prompt '${request.params.name}' requires argument '${arg.name}': ${arg.description || "No description provided"}`
-          );
-        }
-      }
-      let result;
-      try {
-        result = await prompt.load(
-          args2,
-          this.#auth
-        );
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new McpError(
-          ErrorCode.InternalError,
-          `Failed to load prompt '${request.params.name}': ${errorMessage}`
-        );
-      }
-      if (typeof result === "string") {
-        return {
-          description: prompt.description,
-          messages: [
-            {
-              content: { text: result, type: "text" },
-              role: "user"
-            }
-          ]
-        };
-      } else {
-        return {
-          description: prompt.description,
-          messages: result.messages
-        };
-      }
-    });
-  }
-  setupResourceHandlers(resources) {
-    this.#server.setRequestHandler(ListResourcesRequestSchema, async () => {
-      return {
-        resources: resources.map((resource) => ({
-          description: resource.description,
-          mimeType: resource.mimeType,
-          name: resource.name,
-          uri: resource.uri
-        }))
-      };
-    });
-    this.#server.setRequestHandler(
-      ReadResourceRequestSchema,
-      async (request) => {
-        if ("uri" in request.params) {
-          const resource = resources.find(
-            (resource2) => "uri" in resource2 && resource2.uri === request.params.uri
-          );
-          if (!resource) {
-            for (const resourceTemplate of this.#resourceTemplates) {
-              const uriTemplate = parseURITemplate(
-                resourceTemplate.uriTemplate
-              );
-              const match = uriTemplate.fromUri(request.params.uri);
-              if (!match) {
-                continue;
-              }
-              const uri = uriTemplate.fill(match);
-              const result = await resourceTemplate.load(match, this.#auth);
-              const resources2 = Array.isArray(result) ? result : [result];
-              return {
-                contents: resources2.map((resource2) => ({
-                  ...resource2,
-                  description: resourceTemplate.description,
-                  mimeType: resource2.mimeType ?? resourceTemplate.mimeType,
-                  name: resourceTemplate.name,
-                  uri: resource2.uri ?? uri
-                }))
-              };
-            }
-            throw new McpError(
-              ErrorCode.MethodNotFound,
-              `Resource not found: '${request.params.uri}'. Available resources: ${resources.map((r) => r.uri).join(", ") || "none"}`
-            );
-          }
-          if (!("uri" in resource)) {
-            throw new UnexpectedStateError("Resource does not support reading");
-          }
-          let maybeArrayResult;
-          try {
-            maybeArrayResult = await resource.load(this.#auth);
-          } catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            throw new McpError(
-              ErrorCode.InternalError,
-              `Failed to load resource '${resource.name}' (${resource.uri}): ${errorMessage}`,
-              {
-                uri: resource.uri
-              }
-            );
-          }
-          const resourceResults = Array.isArray(maybeArrayResult) ? maybeArrayResult : [maybeArrayResult];
-          return {
-            contents: resourceResults.map((result) => ({
-              ...result,
-              mimeType: result.mimeType ?? resource.mimeType,
-              name: resource.name,
-              uri: result.uri ?? resource.uri
-            }))
-          };
-        }
-        throw new UnexpectedStateError("Unknown resource request", {
-          request
-        });
-      }
-    );
-  }
-  setupResourceTemplateHandlers(resourceTemplates) {
-    this.#server.setRequestHandler(
-      ListResourceTemplatesRequestSchema,
-      async () => {
-        return {
-          resourceTemplates: resourceTemplates.map((resourceTemplate) => ({
-            description: resourceTemplate.description,
-            mimeType: resourceTemplate.mimeType,
-            name: resourceTemplate.name,
-            uriTemplate: resourceTemplate.uriTemplate
-          }))
-        };
-      }
-    );
-  }
-  setupRootsHandlers() {
-    if (this.#rootsConfig?.enabled === false) {
-      this.#logger.debug(
-        "[FastMCP debug] roots capability explicitly disabled via config"
-      );
-      return;
-    }
-    if (typeof this.#server.listRoots === "function") {
-      this.#server.setNotificationHandler(
-        RootsListChangedNotificationSchema,
-        () => {
-          this.#server.listRoots().then((roots) => {
-            this.#roots = roots.roots;
-            this.emit("rootsChanged", {
-              roots: roots.roots
-            });
-          }).catch((error) => {
-            if (error instanceof McpError && error.code === ErrorCode.MethodNotFound) {
-              this.#logger.debug(
-                "[FastMCP debug] listRoots method not supported by client"
-              );
-            } else {
-              this.#logger.error(
-                `[FastMCP error] received error listing roots.
-
-${error instanceof Error ? error.stack : JSON.stringify(error)}`
-              );
-            }
-          });
-        }
-      );
-    } else {
-      this.#logger.debug(
-        "[FastMCP debug] roots capability not available, not setting up notification handler"
-      );
-    }
-  }
-  setupToolHandlers(tools) {
-    this.#server.setRequestHandler(ListToolsRequestSchema, async () => {
-      return {
-        tools: await Promise.all(
-          tools.map(async (tool) => {
-            return {
-              annotations: tool.annotations,
-              description: tool.description,
-              inputSchema: tool.parameters ? await toJsonSchema(tool.parameters) : {
-                additionalProperties: false,
-                properties: {},
-                type: "object"
-              },
-              // More complete schema for Cursor compatibility
-              name: tool.name
-            };
-          })
-        )
-      };
-    });
-    this.#server.setRequestHandler(CallToolRequestSchema, async (request) => {
-      const tool = tools.find((tool2) => tool2.name === request.params.name);
-      if (!tool) {
-        throw new McpError(
-          ErrorCode.MethodNotFound,
-          `Unknown tool: ${request.params.name}`
-        );
-      }
-      let args2 = void 0;
-      if (tool.parameters) {
-        const parsed = await tool.parameters["~standard"].validate(
-          request.params.arguments
-        );
-        if (parsed.issues) {
-          const friendlyErrors = this.#utils?.formatInvalidParamsErrorMessage ? this.#utils.formatInvalidParamsErrorMessage(parsed.issues) : parsed.issues.map((issue) => {
-            const path2 = issue.path?.join(".") || "root";
-            return `${path2}: ${issue.message}`;
-          }).join(", ");
-          throw new McpError(
-            ErrorCode.InvalidParams,
-            `Tool '${request.params.name}' parameter validation failed: ${friendlyErrors}. Please check the parameter types and values according to the tool's schema.`
-          );
-        }
-        args2 = parsed.value;
-      }
-      const progressToken = request.params?._meta?.progressToken;
-      let result;
-      try {
-        const reportProgress = async (progress) => {
-          try {
-            await this.#server.notification({
-              method: "notifications/progress",
-              params: {
-                ...progress,
-                progressToken
-              }
-            });
-            if (this.#needsEventLoopFlush) {
-              await new Promise((resolve) => setImmediate(resolve));
-            }
-          } catch (progressError) {
-            this.#logger.warn(
-              `[FastMCP warning] Failed to report progress for tool '${request.params.name}':`,
-              progressError instanceof Error ? progressError.message : String(progressError)
-            );
-          }
-        };
-        const log = {
-          debug: (message, context) => {
-            this.#server.sendLoggingMessage({
-              data: {
-                context,
-                message
-              },
-              level: "debug"
-            });
-          },
-          error: (message, context) => {
-            this.#server.sendLoggingMessage({
-              data: {
-                context,
-                message
-              },
-              level: "error"
-            });
-          },
-          info: (message, context) => {
-            this.#server.sendLoggingMessage({
-              data: {
-                context,
-                message
-              },
-              level: "info"
-            });
-          },
-          warn: (message, context) => {
-            this.#server.sendLoggingMessage({
-              data: {
-                context,
-                message
-              },
-              level: "warning"
-            });
-          }
-        };
-        const streamContent = async (content) => {
-          const contentArray = Array.isArray(content) ? content : [content];
-          try {
-            await this.#server.notification({
-              method: "notifications/tool/streamContent",
-              params: {
-                content: contentArray,
-                toolName: request.params.name
-              }
-            });
-            if (this.#needsEventLoopFlush) {
-              await new Promise((resolve) => setImmediate(resolve));
-            }
-          } catch (streamError) {
-            this.#logger.warn(
-              `[FastMCP warning] Failed to stream content for tool '${request.params.name}':`,
-              streamError instanceof Error ? streamError.message : String(streamError)
-            );
-          }
-        };
-        const executeToolPromise = tool.execute(args2, {
-          client: {
-            version: this.#server.getClientVersion()
-          },
-          log,
-          reportProgress,
-          session: this.#auth,
-          streamContent
-        });
-        const maybeStringResult = await (tool.timeoutMs ? Promise.race([
-          executeToolPromise,
-          new Promise((_, reject) => {
-            const timeoutId = setTimeout(() => {
-              reject(
-                new UserError(
-                  `Tool '${request.params.name}' timed out after ${tool.timeoutMs}ms. Consider increasing timeoutMs or optimizing the tool implementation.`
-                )
-              );
-            }, tool.timeoutMs);
-            executeToolPromise.finally(() => clearTimeout(timeoutId));
-          })
-        ]) : executeToolPromise);
-        await delay(1);
-        if (maybeStringResult === void 0 || maybeStringResult === null) {
-          result = ContentResultZodSchema.parse({
-            content: []
-          });
-        } else if (typeof maybeStringResult === "string") {
-          result = ContentResultZodSchema.parse({
-            content: [{ text: maybeStringResult, type: "text" }]
-          });
-        } else if ("type" in maybeStringResult) {
-          result = ContentResultZodSchema.parse({
-            content: [maybeStringResult]
-          });
-        } else {
-          result = ContentResultZodSchema.parse(maybeStringResult);
-        }
-      } catch (error) {
-        if (error instanceof UserError) {
-          return {
-            content: [{ text: error.message, type: "text" }],
-            isError: true
-          };
-        }
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        return {
-          content: [
-            {
-              text: `Tool '${request.params.name}' execution failed: ${errorMessage}`,
-              type: "text"
-            }
-          ],
-          isError: true
-        };
-      }
-      return result;
-    });
-  }
-};
-function camelToSnakeCase(str) {
-  return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
-}
-function convertObjectToSnakeCase(obj) {
-  const result = {};
-  for (const [key, value] of Object.entries(obj)) {
-    const snakeKey = camelToSnakeCase(key);
-    result[snakeKey] = value;
-  }
-  return result;
-}
-var FastMCPEventEmitterBase = EventEmitter;
-var FastMCPEventEmitter = class extends FastMCPEventEmitterBase {
-};
-var FastMCP = class extends FastMCPEventEmitter {
-  constructor(options) {
-    super();
-    this.options = options;
-    this.#options = options;
-    this.#authenticate = options.authenticate;
-    this.#logger = options.logger || console;
-  }
-  options;
-  get sessions() {
-    return this.#sessions;
-  }
-  #authenticate;
-  #httpStreamServer = null;
-  #logger;
-  #options;
-  #prompts = [];
-  #resources = [];
-  #resourcesTemplates = [];
-  #sessions = [];
-  #tools = [];
-  /**
-   * Adds a prompt to the server.
-   */
-  addPrompt(prompt) {
-    this.#prompts.push(prompt);
-  }
-  /**
-   * Adds a resource to the server.
-   */
-  addResource(resource) {
-    this.#resources.push(resource);
-  }
-  /**
-   * Adds a resource template to the server.
-   */
-  addResourceTemplate(resource) {
-    this.#resourcesTemplates.push(resource);
-  }
-  /**
-   * Adds a tool to the server.
-   */
-  addTool(tool) {
-    this.#tools.push(tool);
-  }
-  /**
-   * Embeds a resource by URI, making it easy to include resources in tool responses.
-   *
-   * @param uri - The URI of the resource to embed
-   * @returns Promise<ResourceContent> - The embedded resource content
-   */
-  async embedded(uri) {
-    const directResource = this.#resources.find(
-      (resource) => resource.uri === uri
-    );
-    if (directResource) {
-      const result = await directResource.load();
-      const results = Array.isArray(result) ? result : [result];
-      const firstResult = results[0];
-      const resourceData = {
-        mimeType: directResource.mimeType,
-        uri
-      };
-      if ("text" in firstResult) {
-        resourceData.text = firstResult.text;
-      }
-      if ("blob" in firstResult) {
-        resourceData.blob = firstResult.blob;
-      }
-      return resourceData;
-    }
-    for (const template of this.#resourcesTemplates) {
-      const templateBase = template.uriTemplate.split("{")[0];
-      if (uri.startsWith(templateBase)) {
-        const params = {};
-        const templateParts = template.uriTemplate.split("/");
-        const uriParts = uri.split("/");
-        for (let i = 0; i < templateParts.length; i++) {
-          const templatePart = templateParts[i];
-          if (templatePart?.startsWith("{") && templatePart.endsWith("}")) {
-            const paramName = templatePart.slice(1, -1);
-            const paramValue = uriParts[i];
-            if (paramValue) {
-              params[paramName] = paramValue;
-            }
-          }
-        }
-        const result = await template.load(
-          params
-        );
-        const resourceData = {
-          mimeType: template.mimeType,
-          uri
-        };
-        if ("text" in result) {
-          resourceData.text = result.text;
-        }
-        if ("blob" in result) {
-          resourceData.blob = result.blob;
-        }
-        return resourceData;
-      }
-    }
-    throw new UnexpectedStateError(`Resource not found: ${uri}`, { uri });
-  }
-  /**
-   * Starts the server.
-   */
-  async start(options) {
-    const config = this.#parseRuntimeConfig(options);
-    if (config.transportType === "stdio") {
-      const transport = new StdioServerTransport();
-      let auth;
-      if (this.#authenticate) {
-        try {
-          auth = await this.#authenticate(
-            void 0
-          );
-        } catch (error) {
-          this.#logger.error(
-            "[FastMCP error] Authentication failed for stdio transport:",
-            error instanceof Error ? error.message : String(error)
-          );
-        }
-      }
-      const session = new FastMCPSession({
-        auth,
-        instructions: this.#options.instructions,
-        logger: this.#logger,
-        name: this.#options.name,
-        ping: this.#options.ping,
-        prompts: this.#prompts,
-        resources: this.#resources,
-        resourcesTemplates: this.#resourcesTemplates,
-        roots: this.#options.roots,
-        tools: this.#tools,
-        transportType: "stdio",
-        utils: this.#options.utils,
-        version: this.#options.version
-      });
-      await session.connect(transport);
-      this.#sessions.push(session);
-      session.once("error", () => {
-        this.#removeSession(session);
-      });
-      if (transport.onclose) {
-        const originalOnClose = transport.onclose;
-        transport.onclose = () => {
-          this.#removeSession(session);
-          if (originalOnClose) {
-            originalOnClose();
-          }
-        };
-      } else {
-        transport.onclose = () => {
-          this.#removeSession(session);
-        };
-      }
-      this.emit("connect", {
-        session
-      });
-    } else if (config.transportType === "httpStream") {
-      const httpConfig = config.httpStream;
-      if (httpConfig.stateless) {
-        this.#logger.info(
-          `[FastMCP info] Starting server in stateless mode on HTTP Stream at http://${httpConfig.host}:${httpConfig.port}${httpConfig.endpoint}`
-        );
-        this.#httpStreamServer = await startHTTPServer({
-          createServer: async (request) => {
-            const auth = await this.#authenticateRequest(request);
-            return this.#createSession(auth);
-          },
-          enableJsonResponse: httpConfig.enableJsonResponse,
-          eventStore: httpConfig.eventStore,
-          host: httpConfig.host,
-          oauth: this.#options.oauth,
-          // In stateless mode, we don't track sessions
-          onClose: async () => {
-          },
-          onConnect: async () => {
-            this.#logger.debug(
-              `[FastMCP debug] Stateless HTTP Stream request handled`
-            );
-          },
-          onUnhandledRequest: async (req, res) => {
-            await this.#handleUnhandledRequest(req, res, true, httpConfig.host);
-          },
-          port: httpConfig.port,
-          sseEndpoint: "/sse",
-          // Server-Sent Events endpoint for streaming events
-          stateless: true,
-          streamEndpoint: httpConfig.endpoint
-        });
-      } else {
-        this.#httpStreamServer = await startHTTPServer({
-          createServer: async (request) => {
-            const auth = await this.#authenticateRequest(request);
-            return this.#createSession(auth);
-          },
-          enableJsonResponse: httpConfig.enableJsonResponse,
-          eventStore: httpConfig.eventStore,
-          host: httpConfig.host,
-          oauth: this.#options.oauth,
-          onClose: async (session) => {
-            const sessionIndex = this.#sessions.indexOf(session);
-            if (sessionIndex !== -1) this.#sessions.splice(sessionIndex, 1);
-            this.emit("disconnect", {
-              session
-            });
-          },
-          onConnect: async (session) => {
-            this.#sessions.push(session);
-            this.#logger.info(`[FastMCP info] HTTP Stream session established`);
-            this.emit("connect", {
-              session
-            });
-          },
-          onUnhandledRequest: async (req, res) => {
-            await this.#handleUnhandledRequest(
-              req,
-              res,
-              false,
-              httpConfig.host
-            );
-          },
-          port: httpConfig.port,
-          sseEndpoint: "/sse",
-          streamEndpoint: httpConfig.endpoint
-        });
-        this.#logger.info(
-          `[FastMCP info] server is running on HTTP Stream at http://${httpConfig.host}:${httpConfig.port}${httpConfig.endpoint}`
-        );
-        this.#logger.info(
-          `[FastMCP info] Transport type: httpStream (Streamable HTTP, not SSE)`
-        );
-      }
-    } else {
-      throw new Error("Invalid transport type");
-    }
-  }
-  /**
-   * Stops the server.
-   */
-  async stop() {
-    if (this.#httpStreamServer) {
-      await this.#httpStreamServer.close();
-    }
-  }
-  async #authenticateRequest(request) {
-    if (!this.#authenticate) {
-      return void 0;
-    }
-    try {
-      return await this.#authenticate(request);
-    } catch (error) {
-      const response = this.#createOAuthChallengeResponse(error);
-      if (response) {
-        throw response;
-      }
-      throw error;
-    }
-  }
-  #createOAuthChallengeResponse(error) {
-    if (error instanceof Response) {
-      return void 0;
-    }
-    const resourceMetadataUrl = this.#options.oauth?.protectedResourceMetadataUrl;
-    if (!this.#options.oauth?.enabled || !resourceMetadataUrl) {
-      return void 0;
-    }
-    const errorMessage = error instanceof Error ? error.message : String(error || "Unauthorized");
-    const wwwAuthenticate = [
-      `resource_metadata="${escapeWWWAuthenticateValue(resourceMetadataUrl)}"`,
-      `error="invalid_token"`,
-      `error_description="${escapeWWWAuthenticateValue(errorMessage)}"`
-    ].join(", ");
-    return new Response(
-      JSON.stringify({
-        error: "invalid_token",
-        error_description: errorMessage
-      }),
-      {
-        headers: {
-          "Content-Type": "application/json",
-          "WWW-Authenticate": `Bearer ${wwwAuthenticate}`
-        },
-        status: 401
-      }
-    );
-  }
-  /**
-   * Creates a new FastMCPSession instance with the current configuration.
-   * Used both for regular sessions and stateless requests.
-   */
-  #createSession(auth) {
-    const allowedTools = auth ? this.#tools.filter(
-      (tool) => tool.canAccess ? tool.canAccess(auth) : true
-    ) : this.#tools;
-    return new FastMCPSession({
-      auth,
-      instructions: this.#options.instructions,
-      logger: this.#logger,
-      name: this.#options.name,
-      ping: this.#options.ping,
-      prompts: this.#prompts,
-      resources: this.#resources,
-      resourcesTemplates: this.#resourcesTemplates,
-      roots: this.#options.roots,
-      tools: allowedTools,
-      transportType: "httpStream",
-      utils: this.#options.utils,
-      version: this.#options.version
-    });
-  }
-  /**
-   * Handles unhandled HTTP requests with health, readiness, and OAuth endpoints
-   */
-  #handleUnhandledRequest = async (req, res, isStateless = false, host) => {
-    const url = new URL(req.url || "", `http://${host}`);
-    if (url.pathname === "/messages") {
-      return;
-    }
-    const healthConfig = this.#options.health ?? {};
-    const enabled = healthConfig.enabled === void 0 ? true : healthConfig.enabled;
-    if (enabled) {
-      const path2 = healthConfig.path ?? "/health";
-      try {
-        if (req.method === "GET" && url.pathname === path2) {
-          res.writeHead(healthConfig.status ?? 200, {
-            "Content-Type": "text/plain"
-          }).end(healthConfig.message ?? "\u2713 Ok");
-          return;
-        }
-        if (req.method === "GET" && url.pathname === "/ready") {
-          if (isStateless) {
-            const response = {
-              mode: "stateless",
-              ready: 1,
-              status: "ready",
-              total: 1
-            };
-            res.writeHead(200, {
-              "Content-Type": "application/json"
-            }).end(JSON.stringify(response));
-          } else {
-            const readySessions = this.#sessions.filter(
-              (s) => s.isReady
-            ).length;
-            const totalSessions = this.#sessions.length;
-            const allReady = readySessions === totalSessions && totalSessions > 0;
-            const response = {
-              ready: readySessions,
-              status: allReady ? "ready" : totalSessions === 0 ? "no_sessions" : "initializing",
-              total: totalSessions
-            };
-            res.writeHead(allReady ? 200 : 503, {
-              "Content-Type": "application/json"
-            }).end(JSON.stringify(response));
-          }
-          return;
-        }
-      } catch (error) {
-        this.#logger.error("[FastMCP error] health endpoint error", error);
-      }
-    }
-    const openaiAppsChallengeConfig = this.#options.openaiAppsChallenge;
-    const openaiAppsChallengeToken = openaiAppsChallengeConfig?.token?.trim();
-    const openaiAppsChallengeEnabled = openaiAppsChallengeConfig?.enabled !== false && !!openaiAppsChallengeToken;
-    if (openaiAppsChallengeEnabled && req.method === "GET") {
-      const path2 = openaiAppsChallengeConfig?.path ?? "/.well-known/openai-apps-challenge";
-      if (url.pathname === path2) {
-        res.writeHead(200, {
-          "Content-Type": "text/plain"
-        }).end(openaiAppsChallengeToken);
-        return;
-      }
-    }
-    const oauthConfig = this.#options.oauth;
-    if (oauthConfig?.enabled && req.method === "GET") {
-      if (url.pathname === "/.well-known/oauth-authorization-server" && oauthConfig.authorizationServer) {
-        const metadata = convertObjectToSnakeCase(
-          oauthConfig.authorizationServer
-        );
-        res.writeHead(200, {
-          "Content-Type": "application/json"
-        }).end(JSON.stringify(metadata));
-        return;
-      }
-      if (url.pathname === "/.well-known/oauth-protected-resource" && oauthConfig.protectedResource) {
-        const metadata = convertObjectToSnakeCase(
-          oauthConfig.protectedResource
-        );
-        res.writeHead(200, {
-          "Content-Type": "application/json"
-        }).end(JSON.stringify(metadata));
-        return;
-      }
-    }
-    res.writeHead(404).end();
-  };
-  #parseRuntimeConfig(overrides) {
-    const args2 = process.argv.slice(2);
-    const getArg = (name) => {
-      const index = args2.findIndex((arg) => arg === `--${name}`);
-      return index !== -1 && index + 1 < args2.length ? args2[index + 1] : void 0;
-    };
-    const transportArg = getArg("transport");
-    const portArg = getArg("port");
-    const endpointArg = getArg("endpoint");
-    const statelessArg = getArg("stateless");
-    const hostArg = getArg("host");
-    const envTransport = process.env.FASTMCP_TRANSPORT;
-    const envPort = process.env.FASTMCP_PORT;
-    const envEndpoint = process.env.FASTMCP_ENDPOINT;
-    const envStateless = process.env.FASTMCP_STATELESS;
-    const envHost = process.env.FASTMCP_HOST;
-    const transportType = overrides?.transportType || (transportArg === "http-stream" ? "httpStream" : transportArg) || envTransport || "stdio";
-    if (transportType === "httpStream") {
-      const port = parseInt(
-        overrides?.httpStream?.port?.toString() || portArg || envPort || "8080"
-      );
-      const host = overrides?.httpStream?.host || hostArg || envHost || "localhost";
-      const endpoint = overrides?.httpStream?.endpoint || endpointArg || envEndpoint || "/mcp";
-      const enableJsonResponse = overrides?.httpStream?.enableJsonResponse || false;
-      const stateless = overrides?.httpStream?.stateless || statelessArg === "true" || envStateless === "true" || false;
-      return {
-        httpStream: {
-          enableJsonResponse,
-          endpoint,
-          host,
-          port,
-          stateless
-        },
-        transportType: "httpStream"
-      };
-    }
-    return { transportType: "stdio" };
-  }
-  #removeSession(session) {
-    const sessionIndex = this.#sessions.indexOf(session);
-    if (sessionIndex !== -1) {
-      this.#sessions.splice(sessionIndex, 1);
-      this.emit("disconnect", {
-        session
-      });
-    }
-  }
-};
+import { z as z3 } from "zod";
 
 // src/monitor.ts
-import { z as z2 } from "zod";
+import { z } from "zod";
 var DEFAULT_API_URL = "https://api.firecrawl.dev";
 function resolveAuth(session) {
   const apiKey = session?.firecrawlApiKey ?? process.env.FIRECRAWL_API_KEY;
@@ -1365,8 +52,8 @@ async function monitorRequest(session, path2, init = {}) {
 function asText(data) {
   return JSON.stringify(data, null, 2);
 }
-var pageStatusSchema = z2.enum(["same", "new", "changed", "removed", "error"]);
-var checkStatusSchema = z2.enum([
+var pageStatusSchema = z.enum(["same", "new", "changed", "removed", "error"]);
+var checkStatusSchema = z.enum([
   "queued",
   "running",
   "completed",
@@ -1495,6 +182,13 @@ Goal guidance:
 - If the user says they do not care about something, include that explicitly. It is okay to ask whether they want to ignore specific noise when it is likely to matter.
 - Do not invent page-specific sections, thresholds, entities, or business rules unless the user mentioned them.
 
+Query guidance (web monitors): \`queries\` control recall (what search retrieves) and \`goal\` controls precision (which results alert) \u2014 tune both.
+- Write keywords, not sentences: \`OpenAI new model release\`, not \`tell me when OpenAI releases a new model\`.
+- Quote multi-word entities (\`"Llama 4"\`); group synonyms with \`OR\` (\`launch OR release OR announcement\`).
+- Keep each query tight (~2-6 terms). One broad query usually beats several narrow ones \u2014 extra queries split the \`maxResults\` budget. Use one query per distinct entity; do not emit one per facet of a single subject.
+- Keep \`site:\` operators out of queries \u2014 use \`includeDomains\` / \`excludeDomains\`.
+- A healthy web monitor mostly returns \`new: 0\` and alerts only on genuinely new, on-goal results. Many \`ignored\` results \u21D2 queries too broad (tighten them); nothing for long stretches \u21D2 queries too narrow or window too tight (broaden); dismissed alerts \u21D2 goal too broad (add an intent-specific Ignore). Aim for high precision with enough recall.
+
 Full \`body\` requests require: \`name\`, \`schedule\` (with \`cron\` or \`text\`), and \`targets\` (one or more \`{ type: 'scrape', urls: [...] }\`, \`{ type: 'crawl', url: '...' }\`, or \`{ type: 'search', queries: [...], searchWindow?, maxResults?, includeDomains?, excludeDomains? }\`). Optional: \`goal\` (required when any search target is present), \`judgeEnabled\`, \`webhook\`, \`notification\`, \`retentionDays\`.
 
 **Markdown-mode (default):** Each check produces a unified text diff of the page's markdown. No extra configuration needed.
@@ -1567,22 +261,22 @@ Full \`body\` requests require: \`name\`, \`schedule\` (with \`cron\` or \`text\
 
 **Mixed mode (JSON + git-diff):** Use \`modes: ["json", "git-diff"]\` to get both per-field diffs and a markdown sidecar. The page is marked \`changed\` whenever either surface changed.
 `,
-    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()
+    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()
     }),
     execute: async (args2, { session, log }) => {
       const body = buildMonitorCreateBody(args2);
@@ -1613,11 +307,11 @@ List all Firecrawl monitors for the authenticated account.
 { "name": "firecrawl_monitor_list", "arguments": { "limit": 20 } }
 \`\`\`
 `,
-    parameters: z2.object({
-      limit: z2.number().int().positive().optional(),
-      offset: z2.number().int().nonnegative().optional()
+    parameters: z.object({
+      limit: z.number().int().positive().optional(),
+      offset: z.number().int().nonnegative().optional()
     }),
-    execute: async (args2, { session, log }) => {
+    execute: async (args2, { session }) => {
       const { limit, offset } = args2;
       const res = await monitorRequest(session, "/monitor", {
         query: { limit, offset }
@@ -1644,8 +338,8 @@ Get a single monitor by ID.
 { "name": "firecrawl_monitor_get", "arguments": { "id": "mon_abc123" } }
 \`\`\`
 `,
-    parameters: z2.object({ id: z2.string() }),
-    execute: async (args2, { session, log }) => {
+    parameters: z.object({ id: z.string() }),
+    execute: async (args2, { session }) => {
       const { id } = args2;
       const res = await monitorRequest(
         session,
@@ -1679,11 +373,11 @@ Update a monitor. Pass any subset of fields to patch: \`name\`, \`status\` ("act
 }
 \`\`\`
 `,
-    parameters: z2.object({
-      id: z2.string(),
-      body: z2.record(z2.string(), z2.any())
+    parameters: z.object({
+      id: z.string(),
+      body: z.record(z.string(), z.any())
     }),
-    execute: async (args2, { session, log }) => {
+    execute: async (args2, { session }) => {
       const { id, body } = args2;
       const res = await monitorRequest(
         session,
@@ -1712,7 +406,7 @@ Permanently delete a monitor and stop its schedule. This cannot be undone.
 { "name": "firecrawl_monitor_delete", "arguments": { "id": "mon_abc123" } }
 \`\`\`
 `,
-    parameters: z2.object({ id: z2.string() }),
+    parameters: z.object({ id: z.string() }),
     execute: async (args2, { session, log }) => {
       const { id } = args2;
       log.info("Deleting monitor", { id });
@@ -1743,8 +437,8 @@ Trigger a monitor check immediately, outside its normal schedule. Returns the qu
 { "name": "firecrawl_monitor_run", "arguments": { "id": "mon_abc123" } }
 \`\`\`
 `,
-    parameters: z2.object({ id: z2.string() }),
-    execute: async (args2, { session, log }) => {
+    parameters: z.object({ id: z.string() }),
+    execute: async (args2, { session }) => {
       const { id } = args2;
       const res = await monitorRequest(
         session,
@@ -1773,13 +467,13 @@ List historical checks for a monitor.
 { "name": "firecrawl_monitor_checks", "arguments": { "id": "mon_abc123", "limit": 10, "status": "completed" } }
 \`\`\`
 `,
-    parameters: z2.object({
-      id: z2.string(),
-      limit: z2.number().int().positive().optional(),
-      offset: z2.number().int().nonnegative().optional(),
+    parameters: z.object({
+      id: z.string(),
+      limit: z.number().int().positive().optional(),
+      offset: z.number().int().nonnegative().optional(),
       status: checkStatusSchema.optional()
     }),
-    execute: async (args2, { session, log }) => {
+    execute: async (args2, { session }) => {
       const { id, limit, offset, status } = args2;
       const res = await monitorRequest(
         session,
@@ -1856,14 +550,14 @@ The endpoint paginates via a top-level \`next\` URL; this tool returns one page
 }
 \`\`\`
 `,
-    parameters: z2.object({
-      id: z2.string(),
-      checkId: z2.string(),
-      limit: z2.number().int().positive().optional(),
-      skip: z2.number().int().nonnegative().optional(),
+    parameters: z.object({
+      id: z.string(),
+      checkId: z.string(),
+      limit: z.number().int().positive().optional(),
+      skip: z.number().int().nonnegative().optional(),
       pageStatus: pageStatusSchema.optional()
     }),
-    execute: async (args2, { session, log }) => {
+    execute: async (args2, { session }) => {
       const { id, checkId, limit, skip, pageStatus } = args2;
       const res = await monitorRequest(
         session,
@@ -1876,7 +570,7 @@ The endpoint paginates via a top-level \`next\` URL; this tool returns one page
 }
 
 // src/research.ts
-import { z as z3 } from "zod";
+import { z as z2 } from "zod";
 var BASE = "/v2/search/research";
 var ORIGIN_HEADERS = { "X-Origin": "mcp-fastmcp" };
 function appendParam(params, key, value) {
@@ -1987,26 +681,30 @@ function registerResearchTools(server2, getClient2) {
   server2.addTool({
     name: "firecrawl_research_search_papers",
     annotations: {
-      title: "Search arXiv papers",
+      title: "Search research papers",
       readOnlyHint: true,
-      // Semantic search over indexed arXiv metadata; returns ranked results only.
+      // Semantic search over indexed paper metadata; returns ranked results only.
       openWorldHint: true,
-      // Searches the public arXiv research corpus.
+      // Searches the Firecrawl research paper index.
       destructiveHint: false
-      // Query-only; no writes to arXiv or the research index.
+      // Query-only; no writes to external sources or the research index.
     },
-    description: "Primary entry point for finding arXiv papers by topic. Semantic (HyDE) search over arXiv abstracts; returns ranked papers with arXiv id, title, and abstract. The query should be a natural-language description of what you want. Run SEVERAL distinct framings of the question (sibling domains, rival methods, dataset/benchmark names) rather than one query \u2014 recall improves markedly with diverse framings. Returns up to `k` results (default 40).",
-    parameters: z3.object({
-      query: z3.string().min(1),
-      k: z3.number().int().min(1).max(500).optional(),
-      authors: z3.array(z3.string()).optional().describe(
+    description: "Primary entry point for finding research papers by topic across AI/ML, computer science, math, physics, biomedical, life sciences, and clinical literature. Semantic (HyDE) search over indexed paper metadata and abstracts; returns ranked papers with paper id, title, authors, and abstract. The query should be a natural-language research topic or question. Run SEVERAL distinct framings of the question (sibling domains, rival methods, dataset or benchmark names, conditions, populations, interventions, or outcomes) rather than one query \u2014 recall improves markedly with diverse framings.",
+    parameters: z2.object({
+      query: z2.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(
         "Author substring filter(s); ALL must match (case-insensitive)."
       ),
-      categories: z3.array(z3.string()).optional().describe("arXiv category filter(s) (e.g. `cs.LG`); ALL must match."),
-      from: z3.string().optional().describe(
+      categories: z2.array(z2.string()).optional().describe(
+        "Paper category filter(s) (e.g. `cs.LG`); ALL provided values must match."
+      ),
+      from: z2.string().optional().describe(
         "Inclusive lower bound on created/updated date (`YYYY-MM-DD`)."
       ),
-      to: z3.string().optional().describe(
+      to: z2.string().optional().describe(
         "Inclusive upper bound on created/updated date (`YYYY-MM-DD`)."
       )
     }),
@@ -2039,8 +737,8 @@ function registerResearchTools(server2, getClient2) {
       // Read-only metadata lookup.
     },
     description: "Fetch canonical metadata for one paper by primaryId or canonical paperId. Use this after search/related results when you need the full title, abstract, authors, categories, source ids, and dates rendered as markdown.",
-    parameters: z3.object({
-      paperId: z3.string().min(1).describe(
+    parameters: z2.object({
+      paperId: z2.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`."
       )
     }),
@@ -2066,12 +764,12 @@ function registerResearchTools(server2, getClient2) {
       // Read-only graph query; no modifications.
     },
     description: "Expand from anchor papers you have already found, via the citation graph, ranked and filtered to a natural-language `intent`. Pass arXiv ids of your strongest hits as `seed_ids`. Modes: `similar` (cocitation/coupling \u2014 papers in the same niche; the default), `citers` (papers that cite the anchors), `references` (papers the anchors cite). This reaches relevant papers that plain search misses, so use it on your best hits before finishing. A `similar` call already runs a DEEP multi-round expansion internally (re-seeding from each round\u2019s best finds), so one call reaches the wider neighborhood \u2014 no need to chain many. Returns the candidates plus the pool size.",
-    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.")
+    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.")
     }),
     execute: async (args2, { session }) => {
       const { seed_ids, intent, mode, k, rerank } = args2;
@@ -2108,12 +806,12 @@ note: ${res.data.note}` : "";
       // Read-only passage retrieval.
     },
     description: "Read the most relevant in-body (full-text) passages of ONE specific paper for a question. Use this to VERIFY whether a candidate actually satisfies a constraint before you include or reject it (e.g. 'does this paper actually use technique X / report a score on benchmark Y'). Returns the best-matching passages, or a notice if the paper's full text is unavailable.",
-    parameters: z3.object({
-      paperId: z3.string().min(1).describe(
+    parameters: z2.object({
+      paperId: z2.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: z3.string().min(1),
-      k: z3.number().int().min(1).max(50).optional().describe("Number of passages to return (default 4).")
+      question: z2.string().min(1),
+      k: z2.number().int().min(1).max(50).optional().describe("Number of passages to return (default 4).")
     }),
     execute: async (args2, { session }) => {
       const { paperId, question, k } = args2;
@@ -2141,9 +839,9 @@ note: ${res.data.note}` : "";
       // Query-only; does not create issues, PRs, or modify repositories.
     },
     description: "Search GitHub issue/PR history and repository readmes. Returns ranked matches with repo, url, a short snippet, and (when available) the full matched content in markdown.",
-    parameters: z3.object({
-      query: z3.string().min(1),
-      k: z3.number().int().min(1).max(100).optional()
+    parameters: z2.object({
+      query: z2.string().min(1),
+      k: z2.number().int().min(1).max(100).optional()
     }),
     execute: async (args2, { session }) => {
       const { query, k } = args2;
@@ -2164,6 +862,7 @@ note: ${res.data.note}` : "";
 dotenv.config({ debug: false, quiet: true });
 var require2 = createRequire(import.meta.url);
 var { version: packageVersion } = require2("../package.json");
+var authResultByRequest = /* @__PURE__ */ Symbol("firecrawlMcpAuthResult");
 function normalizeHeader(value) {
   if (value == null) return void 0;
   const v = Array.isArray(value) ? value[0] : value;
@@ -2201,6 +900,33 @@ function getMcpResourceUrl() {
 function getOAuthProtectedResourceMetadataUrl() {
   return `${new URL(getMcpResourceUrl()).origin}/.well-known/oauth-protected-resource`;
 }
+function escapeWWWAuthenticateValue(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function createOAuthChallengeResponse(error) {
+  if (!isMcpOAuthEnabled()) {
+    return void 0;
+  }
+  const errorMessage = error instanceof Error ? error.message : String(error || "Unauthorized");
+  const wwwAuthenticate = [
+    `resource_metadata="${escapeWWWAuthenticateValue(getOAuthProtectedResourceMetadataUrl())}"`,
+    'error="invalid_token"',
+    `error_description="${escapeWWWAuthenticateValue(errorMessage)}"`
+  ].join(", ");
+  return new Response(
+    JSON.stringify({
+      error: "invalid_token",
+      error_description: errorMessage
+    }),
+    {
+      headers: {
+        "Content-Type": "application/json",
+        "WWW-Authenticate": `Bearer ${wwwAuthenticate}`
+      },
+      status: 401
+    }
+  );
+}
 function getOAuthIntrospectionEndpoint() {
   return `${getOAuthIssuer()}/api/oauth/introspect`;
 }
@@ -2251,6 +977,52 @@ async function resolveCredentialFromHeaders(headers) {
   }
   return void 0;
 }
+async function authenticateRequest(request) {
+  const headerCred = request?.headers ? await resolveCredentialFromHeaders(request.headers) : void 0;
+  const envCred = resolveCredentialFromEnv();
+  if (process.env.CLOUD_SERVICE === "true") {
+    if (!headerCred) {
+      const clientIp = extractClientIp(request);
+      if (process.env.KEYLESS_PROXY_SECRET && clientIp && await keylessEligible(clientIp)) {
+        return { firecrawlApiKey: void 0, keylessClientIp: clientIp };
+      }
+      throw new Error(
+        "Firecrawl credentials required: OAuth access token (Authorization: Bearer fco_...) or API key (x-firecrawl-api-key)"
+      );
+    }
+    return { firecrawlApiKey: headerCred };
+  }
+  const credential = headerCred ?? envCred;
+  const httpStreaming = isHttpStreamingTransport();
+  if (!httpStreaming && !process.env.FIRECRAWL_API_KEY && !process.env.FIRECRAWL_API_URL) {
+    console.error(
+      "No FIRECRAWL_API_KEY or FIRECRAWL_API_URL set \u2014 running in keyless mode. firecrawl_scrape and firecrawl_search are free (rate-limited per IP) against the Firecrawl cloud; other tools require an API key (get one free at https://firecrawl.dev)."
+    );
+  }
+  if (httpStreaming && !credential && !process.env.FIRECRAWL_API_URL) {
+    console.error(
+      "HTTP MCP transport requires FIRECRAWL_API_URL and/or credentials (OAuth: Authorization Bearer fco_..., or FIRECRAWL_API_KEY / FIRECRAWL_OAUTH_TOKEN)"
+    );
+    process.exit(1);
+  }
+  return { firecrawlApiKey: credential };
+}
+async function authenticateWithOAuthChallenge(request) {
+  if (request?.[authResultByRequest]) {
+    return request[authResultByRequest];
+  }
+  const authResult = authenticateRequest(request).catch((error) => {
+    const oauthChallenge = createOAuthChallengeResponse(error);
+    if (oauthChallenge) {
+      throw oauthChallenge;
+    }
+    throw error;
+  });
+  if (request) {
+    request[authResultByRequest] = authResult;
+  }
+  return authResult;
+}
 function removeEmptyTopLevel(obj) {
   const out = {};
   for (const [k, v] of Object.entries(obj)) {
@@ -2263,7 +1035,7 @@ function removeEmptyTopLevel(obj) {
   }
   return out;
 }
-var searchDomainSchema = z4.string().trim().toLowerCase().min(1).max(253).regex(
+var searchDomainSchema = z3.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"
 );
@@ -2323,48 +1095,23 @@ var server = new FastMCP({
       resource: getMcpResourceUrl(),
       resourceName: "Firecrawl MCP",
       scopesSupported: ["firecrawl:global"]
-    },
-    protectedResourceMetadataUrl: getOAuthProtectedResourceMetadataUrl()
-  },
-  authenticate: async (request) => {
-    const headerCred = request?.headers ? await resolveCredentialFromHeaders(request.headers) : void 0;
-    const envCred = resolveCredentialFromEnv();
-    if (process.env.CLOUD_SERVICE === "true") {
-      if (!headerCred) {
-        const clientIp = extractClientIp(request);
-        if (process.env.KEYLESS_PROXY_SECRET && clientIp && await keylessEligible(clientIp)) {
-          return { firecrawlApiKey: void 0, keylessClientIp: clientIp };
-        }
-        throw new Error(
-          "Firecrawl credentials required: OAuth access token (Authorization: Bearer fco_...) or API key (x-firecrawl-api-key)"
-        );
-      }
-      return { firecrawlApiKey: headerCred };
     }
-    const credential = headerCred ?? envCred;
-    const httpStreaming = isHttpStreamingTransport();
-    if (!httpStreaming && !process.env.FIRECRAWL_API_KEY && !process.env.FIRECRAWL_API_URL) {
-      console.error(
-        "No FIRECRAWL_API_KEY or FIRECRAWL_API_URL set \u2014 running in keyless mode. firecrawl_scrape and firecrawl_search are free (rate-limited per IP) against the Firecrawl cloud; other tools require an API key (get one free at https://firecrawl.dev)."
-      );
-    }
-    if (httpStreaming && !credential && !process.env.FIRECRAWL_API_URL) {
-      console.error(
-        "HTTP MCP transport requires FIRECRAWL_API_URL and/or credentials (OAuth: Authorization Bearer fco_..., or FIRECRAWL_API_KEY / FIRECRAWL_OAUTH_TOKEN)"
-      );
-      process.exit(1);
-    }
-    return { firecrawlApiKey: credential };
   },
+  authenticate: authenticateWithOAuthChallenge,
   // Lightweight health endpoint for LB checks
   health: {
     enabled: true,
     message: "ok",
     path: "/health",
     status: 200
-  },
-  ...openAiAppsChallengeToken ? { openaiAppsChallenge: { token: openAiAppsChallengeToken } } : {}
+  }
 });
+if (openAiAppsChallengeToken) {
+  server.getApp().get(
+    "/.well-known/openai-apps-challenge",
+    (context) => context.text(openAiAppsChallengeToken)
+  );
+}
 function createClient(apiKey) {
   const config = {
     ...process.env.FIRECRAWL_API_URL && {
@@ -2461,10 +1208,10 @@ function transformScrapeParams(args2) {
   delete out.pdfOptions;
   return out;
 }
-var scrapeParamsSchema = z4.object({
-  url: z4.string().url(),
-  formats: z4.array(
-    z4.enum([
+var scrapeParamsSchema = z3.object({
+  url: z3.string().url(),
+  formats: z3.array(
+    z3.enum([
       "markdown",
       "html",
       "rawHtml",
@@ -2478,62 +1225,62 @@ var scrapeParamsSchema = z4.object({
       "audio"
     ])
   ).optional(),
-  jsonOptions: z4.object({
-    prompt: z4.string().optional(),
-    schema: z4.record(z4.string(), z4.any()).optional()
+  jsonOptions: z3.object({
+    prompt: z3.string().optional(),
+    schema: z3.record(z3.string(), z3.any()).optional()
   }).optional(),
-  queryOptions: z4.object({
-    prompt: z4.string().max(1e4),
-    mode: z4.enum(["directQuote", "freeform"]).default("freeform")
+  queryOptions: z3.object({
+    prompt: z3.string().max(1e4),
+    mode: z3.enum(["directQuote", "freeform"]).default("freeform")
   }).optional(),
-  screenshotOptions: z4.object({
-    fullPage: z4.boolean().optional(),
-    quality: z4.number().optional(),
-    viewport: z4.object({ width: z4.number(), height: z4.number() }).optional()
+  screenshotOptions: z3.object({
+    fullPage: z3.boolean().optional(),
+    quality: z3.number().optional(),
+    viewport: z3.object({ width: z3.number(), height: z3.number() }).optional()
   }).optional(),
-  parsers: z4.array(z4.enum(["pdf"])).optional(),
-  pdfOptions: z4.object({
-    maxPages: z4.number().int().min(1).max(1e4).optional()
+  parsers: z3.array(z3.enum(["pdf"])).optional(),
+  pdfOptions: z3.object({
+    maxPages: z3.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(),
-  waitFor: z4.number().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(),
   ...SAFE_MODE ? {} : {
-    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()
+    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()
       })
     ).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()
+  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()
   }).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()
+  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()
   }).optional()
 });
-var parseOptionParamsSchema = z4.object({
-  formats: z4.array(
-    z4.enum([
+var parseOptionParamsSchema = z3.object({
+  formats: z3.array(
+    z3.enum([
       "markdown",
       "html",
       "rawHtml",
@@ -2543,48 +1290,48 @@ var parseOptionParamsSchema = z4.object({
       "query"
     ])
   ).optional(),
-  jsonOptions: z4.object({
-    prompt: z4.string().optional(),
-    schema: z4.record(z4.string(), z4.any()).optional()
+  jsonOptions: z3.object({
+    prompt: z3.string().optional(),
+    schema: z3.record(z3.string(), z3.any()).optional()
   }).optional(),
-  queryOptions: z4.object({
-    prompt: z4.string().max(1e4),
-    mode: z4.enum(["directQuote", "freeform"]).default("freeform")
+  queryOptions: z3.object({
+    prompt: z3.string().max(1e4),
+    mode: z3.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()
+  parsers: z3.array(z3.enum(["pdf"])).optional(),
+  pdfOptions: z3.object({
+    maxPages: z3.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()
+  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()
 });
 var localParseParamsSchema = parseOptionParamsSchema.extend({
-  filePath: z4.string().min(1).describe(
+  filePath: z3.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(
+  contentType: z3.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(
+  filePath: z3.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(
+  uploadRef: z3.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(
+  contentType: z3.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(
+  declaredSizeBytes: z3.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) => {
@@ -2592,7 +1339,7 @@ var hostedParseParamsSchema = parseOptionParamsSchema.extend({
   const hasUploadRef = typeof value.uploadRef === "string" && value.uploadRef.length > 0;
   if (hasFilePath === hasUploadRef) {
     ctx.addIssue({
-      code: z4.ZodIssueCode.custom,
+      code: z3.ZodIssueCode.custom,
       message: "Hosted firecrawl_parse requires exactly one of filePath (phase 1) or uploadRef (phase 2).",
       path: hasFilePath && hasUploadRef ? ["uploadRef"] : ["filePath"]
     });
@@ -2616,7 +1363,11 @@ function inferContentType(filename) {
   return EXTENSION_CONTENT_TYPES[ext] ?? "application/octet-stream";
 }
 function extractParseOptions(args2) {
-  const { filePath, uploadRef, contentType, declaredSizeBytes, ...options } = args2;
+  const options = { ...args2 };
+  delete options.filePath;
+  delete options.uploadRef;
+  delete options.contentType;
+  delete options.declaredSizeBytes;
   return options;
 }
 function buildParseOptionsPayload(options) {
@@ -2959,13 +1710,13 @@ Map a website to discover all indexed URLs on the site.
 \`\`\`
 **Returns:** Array of URLs found on the site, filtered by search query if provided.
 `,
-  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()
+  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()
   }),
   execute: async (args2, { session, log }) => {
     const { url, ...options } = args2;
@@ -2996,7 +1747,7 @@ Search the web and optionally extract content from search results. This is the m
 The query also supports search operators, that you can use if needed to refine the search:
 | Operator | Functionality | Examples |
 ---|-|-|
-| \`""\` | Non-fuzzy matches a string of text | \`"Firecrawl"\`
+| \`"\` | Non-fuzzy matches a string of text | \`"Firecrawl"\`
 | \`-\` | Excludes certain keywords or negates other operators | \`-bad\`, \`-site:firecrawl.dev\`
 | \`site:\` | Only returns results from a specified website | \`site:firecrawl.dev\`
 | \`inurl:\` | Only returns results that include a word in the URL | \`inurl:firecrawl\`
@@ -3012,6 +1763,7 @@ The query also supports search operators, that you can use if needed to refine t
 **Common mistakes:** Using crawl or map for open-ended questions (use search instead).
 **Prompt Example:** "Find the latest research papers on AI published in 2023."
 **Sources:** web, images, news, default to web unless needed images or news.
+**Categories:** Optional filter to limit result types: \`github\` (GitHub repositories, code, issues, and docs), \`research\` (academic and research sources), \`pdf\` (PDF results). Example: \`categories: ["github", "research"]\`.
 **Domain filters:** Use includeDomains to restrict results to specific domains, or excludeDomains to remove domains. Do not use both in the same request. Domains must be hostnames only, without protocol or path.
 **Scrape Options:** Only use scrapeOptions when you think it is absolutely necessary. When you do so default to a lower limit to avoid timeouts, 5 or lower.
 **Optimal Workflow:** Search first using firecrawl_search without formats, then after fetching the results, use the scrape tool to get the content of the relevantpage(s) that you want to scrape
@@ -3038,6 +1790,7 @@ The query also supports search operators, that you can use if needed to refine t
   "arguments": {
     "query": "latest AI research papers 2023",
     "limit": 5,
+    "categories": ["github", "research"],
     "lang": "en",
     "country": "us",
     "sources": [
@@ -3054,17 +1807,20 @@ The query also supports search operators, that you can use if needed to refine t
 \`\`\`
 **Returns:** A JSON envelope of the form \`{ success, data: { web?, images?, news? }, id, creditsUsed }\`. Each result array contains the search results (with optional scraped content). Pass the top-level \`id\` to \`firecrawl_search_feedback\` after you've used the results.
 `,
-  parameters: z4.object({
-    query: z4.string().min(1),
-    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(),
+  parameters: z3.object({
+    query: z3.string().min(1),
+    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."
+    ),
     scrapeOptions: scrapeParamsSchema.omit({ url: true }).partial().optional(),
-    enterprise: z4.array(z4.enum(["default", "anon", "zdr"])).optional()
+    enterprise: z3.array(z3.enum(["default", "anon", "zdr"])).optional()
   }).refine(
     (args2) => !(args2.includeDomains?.length && args2.excludeDomains?.length),
     "includeDomains and excludeDomains cannot both be specified"
@@ -3207,7 +1963,7 @@ async function getCrawlStatusWithOrigin(client, jobId) {
 }
 async function waitForCrawlCompletionWithOrigin(client, jobId, pollInterval = 2, timeout) {
   const startedAt = Date.now();
-  while (true) {
+  for (; ; ) {
     const status = await getCrawlStatusWithOrigin(client, jobId);
     if (["completed", "failed", "cancelled"].includes(String(status.status ?? ""))) {
       return status;
@@ -3220,17 +1976,17 @@ async function waitForCrawlCompletionWithOrigin(client, jobId, pollInterval = 2,
     );
   }
 }
-var feedbackIssueSchema = z4.string().trim().min(1).max(80).regex(
+var feedbackIssueSchema = z3.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 = z4.object({
-  url: z4.string().url(),
-  reason: z4.string().max(1e3).optional()
+var valuableSourceSchema = z3.object({
+  url: z3.string().url(),
+  reason: z3.string().max(1e3).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 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 FEEDBACK_DISABLED_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
 function feedbackEnvEnabled(...keys) {
@@ -3324,24 +2080,24 @@ Pass the \`searchId\` returned by \`firecrawl_search\` (the \`id\` field on the
 
 **Returns:** \`{ success, feedbackId, creditsRefunded, creditsRefundedToday, dailyRefundCap, dailyCapReached?, alreadySubmitted?, warning? }\` JSON.
 `,
-    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()
+    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()
         })
       ).max(50).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()
+      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()
         })
       ).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: z4.string().max(2e3).optional()
+      querySuggestions: z3.string().max(2e3).optional()
     }),
     execute: async (args2, { session, log }) => {
       const {
@@ -3440,19 +2196,19 @@ Do not store multi-MB outputs in feedback. Use concise notes, issue codes, URLs,
 
 **Returns:** \`{ success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, alreadySubmitted?, warning? }\` JSON.
 `,
-    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()
+    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()
     }),
     execute: async (args2, { session, log }) => {
       const {
@@ -3561,25 +2317,25 @@ server.addTool({
  **Returns:** Final crawl status and data after internal polling, including the crawl id. Use firecrawl_check_crawl_status only when you need to re-check an existing crawl ID later.
  ${SAFE_MODE ? "**Safe Mode:** Read-only crawling. Webhooks and interactive actions are disabled for security." : ""}
  `,
-  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(),
+  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(),
     ...SAFE_MODE ? {} : {
-      webhook: z4.string().optional(),
-      webhookHeaders: z4.record(z4.string(), z4.string()).optional()
+      webhook: z3.string().optional(),
+      webhookHeaders: z3.record(z3.string(), z3.string()).optional()
     },
-    deduplicateSimilarURLs: z4.boolean().optional(),
-    ignoreQueryParameters: z4.boolean().optional(),
+    deduplicateSimilarURLs: z3.boolean().optional(),
+    ignoreQueryParameters: z3.boolean().optional(),
     scrapeOptions: scrapeParamsSchema.omit({ url: true }).partial().optional()
   }),
   execute: async (args2, { session, log }) => {
@@ -3643,7 +2399,7 @@ Check the status of a crawl job.
 \`\`\`
 **Returns:** Status and progress of the crawl job, including results if available.
 `,
-  parameters: z4.object({ id: z4.string() }),
+  parameters: z3.object({ id: z3.string() }),
   execute: async (args2, { session }) => {
     const client = getClient(session);
     const id = args2.id;
@@ -3699,13 +2455,13 @@ Extract structured information from web pages using LLM capabilities. Supports b
 \`\`\`
 **Returns:** Extracted structured data as defined by your schema.
 `,
-  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()
+  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()
   }),
   execute: async (args2, { session, log }) => {
     const client = getClient(session);
@@ -3806,10 +2562,10 @@ Then poll with \`firecrawl_agent_status\` every 15-30 seconds for at least 2-3 m
 \`\`\`
 **Returns:** Job ID for status checking. Use \`firecrawl_agent_status\` to poll for results.
 `,
-  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()
+  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()
   }),
   execute: async (args2, { session, log }) => {
     const client = getClient(session);
@@ -3866,7 +2622,7 @@ Check the status of an agent job and retrieve results when complete. Use this to
 
 **Returns:** Status, progress, and results (if completed) of the agent job.
 `,
-  parameters: z4.object({ id: z4.string() }),
+  parameters: z3.object({ id: z3.string() }),
   execute: async (args2, { session, log }) => {
     const client = getClient(session);
     const { id } = args2;
@@ -3930,13 +2686,13 @@ Interact with a page in a live browser session: click buttons, fill forms, extra
 \`\`\`
 **Returns:** Execution result including output, stdout, stderr, exit code, and live view URLs.
 `,
-  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(),
+  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(),
     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."
@@ -4024,8 +2780,8 @@ Stop an interact session for a scraped page. Call this when you are done interac
 \`\`\`
 **Returns:** Success confirmation.
 `,
-  parameters: z4.object({
-    scrapeId: z4.string()
+  parameters: z3.object({
+    scrapeId: z3.string()
   }),
   execute: async (args2, { session, log }) => {
     const client = getClient(session);