@narumitw/pi-firecrawl 0.12.0 → 0.13.1

package/src/settings.ts

@@ -0,0 +1,188 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, link, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { FIRECRAWL_TOOL_NAMES, type FirecrawlToolName } from "./tools.js";
+
+const NEW_SETTINGS_FILE = "pi-firecrawl.json";
+const LEGACY_SETTINGS_FILE = "pi-firecrawl-settings.json";
+
+export interface FirecrawlSettings {
+	tools: FirecrawlToolName[];
+	updatedAt: number;
+}
+
+export type SettingsLoadResult =
+	| { kind: "missing"; notice?: string }
+	| { kind: "invalid"; reason: string; notice?: string }
+	| { kind: "loaded"; settings: FirecrawlSettings; notice?: string };
+
+type SettingsMigrationResult = {
+	kind: "migrated" | "failed";
+	notice: string;
+};
+
+export async function loadSettings(): Promise<SettingsLoadResult> {
+	const newPath = settingsFilePath();
+	const newSettings = await readSettingsFile(newPath);
+	if (newSettings.kind !== "missing") {
+		return withLegacyIgnoredNotice(newSettings);
+	}
+
+	const legacyPath = legacySettingsFilePath();
+	const legacySettings = await readSettingsFile(legacyPath);
+	const concurrentlyCreatedSettings = await readSettingsFile(newPath);
+	if (concurrentlyCreatedSettings.kind !== "missing") {
+		return withLegacyIgnoredNotice(concurrentlyCreatedSettings);
+	}
+	if (legacySettings.kind === "missing") return { kind: "missing" };
+	if (legacySettings.kind === "invalid") return legacySettings;
+
+	const migration = await migrateLegacySettings(legacyPath, legacySettings.settings);
+	if (migration.kind === "failed") {
+		const settingsCreatedDuringMigration = await readSettingsFile(newPath);
+		if (settingsCreatedDuringMigration.kind !== "missing") {
+			return withLegacyIgnoredNotice(settingsCreatedDuringMigration);
+		}
+	}
+
+	return { ...legacySettings, notice: migration.notice };
+}
+
+async function readSettingsFile(filePath: string): Promise<SettingsLoadResult> {
+	let text: string;
+	try {
+		text = await readFile(filePath, "utf8");
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return { kind: "missing" };
+		return { kind: "invalid", reason: `${filePath}: ${formatError(error)}` };
+	}
+
+	try {
+		const parsed = JSON.parse(text) as unknown;
+		const settings = normalizeFirecrawlSettings(parsed);
+		if (settings) return { kind: "loaded", settings };
+		return {
+			kind: "invalid",
+			reason: `${filePath}: expected tools to be an array of Firecrawl tool names`,
+		};
+	} catch (error) {
+		return { kind: "invalid", reason: `${filePath}: ${formatError(error)}` };
+	}
+}
+
+async function withLegacyIgnoredNotice(settings: SettingsLoadResult): Promise<SettingsLoadResult> {
+	if (!(await fileExists(legacySettingsFilePath()))) return settings;
+	return {
+		...settings,
+		notice: `Firecrawl legacy settings ignored: ${legacySettingsFilePath()} exists, but ${settingsFilePath()} takes precedence. Delete ${LEGACY_SETTINGS_FILE} after confirming your settings.`,
+	};
+}
+
+export async function installSettingsFileExclusively(filePath: string, contents: string) {
+	await mkdir(dirname(filePath), { recursive: true });
+	const tempFile = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+	try {
+		await writeFile(tempFile, contents, { encoding: "utf8", flag: "wx" });
+		await link(tempFile, filePath);
+	} finally {
+		await rm(tempFile, { force: true }).catch(() => undefined);
+	}
+}
+
+async function migrateLegacySettings(
+	legacyPath: string,
+	settings: FirecrawlSettings,
+): Promise<SettingsMigrationResult> {
+	const newPath = settingsFilePath();
+	try {
+		await installSettingsFileExclusively(
+			newPath,
+			`${JSON.stringify(settings, null, 2)}\n`,
+		);
+	} catch (error) {
+		return {
+			kind: "failed",
+			notice: `Firecrawl legacy settings migration failed: could not migrate ${legacyPath} to ${newPath}: ${formatError(error)}. The legacy file was used for this session; future saves will write ${NEW_SETTINGS_FILE}.`,
+		};
+	}
+
+	try {
+		await rm(legacyPath, { force: true });
+	} catch (error) {
+		return {
+			kind: "migrated",
+			notice: `Firecrawl settings migrated from ${legacyPath} to ${newPath}, but the legacy file could not be removed: ${formatError(error)}. Delete ${LEGACY_SETTINGS_FILE} after confirming your settings.`,
+		};
+	}
+
+	return {
+		kind: "migrated",
+		notice: `Firecrawl settings migrated from ${legacyPath} to ${newPath}. ${LEGACY_SETTINGS_FILE} is deprecated and will be removed in a future major release.`,
+	};
+}
+
+async function fileExists(filePath: string) {
+	try {
+		await access(filePath, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export function normalizeFirecrawlSettings(value: unknown): FirecrawlSettings | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const settings = value as { tools?: unknown; updatedAt?: unknown };
+	if (typeof settings.updatedAt !== "number") return undefined;
+	if (!Array.isArray(settings.tools)) return undefined;
+	if (!settings.tools.every(isFirecrawlToolName)) return undefined;
+	return { tools: orderedUniqueFirecrawlTools(settings.tools), updatedAt: settings.updatedAt };
+}
+
+function isFirecrawlToolName(value: unknown): value is FirecrawlToolName {
+	return typeof value === "string" && FIRECRAWL_TOOL_NAMES.includes(value as never);
+}
+
+function orderedUniqueFirecrawlTools(tools: readonly FirecrawlToolName[]) {
+	const selectedTools = new Set(tools);
+	return FIRECRAWL_TOOL_NAMES.filter((toolName) => selectedTools.has(toolName));
+}
+
+export async function saveSettings(settings: FirecrawlSettings) {
+	const filePath = settingsFilePath();
+	await mkdir(dirname(filePath), { recursive: true });
+	const tempFile = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+	try {
+		await writeFile(tempFile, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+		await rename(tempFile, filePath);
+	} catch (error) {
+		await rm(tempFile, { force: true }).catch(() => undefined);
+		throw error;
+	}
+}
+
+export function settingsFilePath() {
+	return join(agentDir(), NEW_SETTINGS_FILE);
+}
+
+function legacySettingsFilePath() {
+	return join(agentDir(), LEGACY_SETTINGS_FILE);
+}
+
+function agentDir() {
+	return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}
+
+function formatError(error: unknown) {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function unique<T>(values: T[]) {
+	return Array.from(new Set(values));
+}

package/src/tool-selector.ts

@@ -0,0 +1,330 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { configuredApiUrl, hasApiKey } from "./client.js";
+import { loadSettings, saveSettings, settingsFilePath, type SettingsLoadResult } from "./settings.js";
+import { FIRECRAWL_TOOL_NAMES, type FirecrawlToolName } from "./tools.js";
+
+type CommandContext = ExtensionCommandContext;
+
+const TOOL_SELECTOR_DONE = "Done";
+const TOOL_SELECTOR_ENABLE_ALL = "Enable all Firecrawl tools";
+const TOOL_SELECTOR_DISABLE_ALL = "Disable all Firecrawl tools";
+type ToolRuntimeStatus = "enabled" | "disabled" | "partial";
+type ToolSelectorAction = "enableAll" | "disableAll" | "done";
+type ToolSelectorRow =
+	| { kind: "tool"; toolName: FirecrawlToolName }
+	| { kind: "action"; action: ToolSelectorAction; label: string };
+interface ToolStatusSummary {
+	runtimeStatus: ToolRuntimeStatus;
+	activeFirecrawlToolCount: number;
+	activeNonFirecrawlToolCount: number;
+}
+
+let settingsNotice: string | undefined;
+
+export function clearSettingsNotice() {
+	settingsNotice = undefined;
+}
+
+export function recordSettingsNotice(settings: SettingsLoadResult) {
+	if (settings.notice) settingsNotice = settings.notice;
+}
+
+export async function showToolSelector(pi: ExtensionAPI, ctx: CommandContext) {
+	if (!ctx.hasUI) {
+		ctx.ui.notify(
+			`Firecrawl tool selection needs an interactive UI.\n\n${await buildStatusMessage(pi)}`,
+			hasApiKey() ? "info" : "warning",
+		);
+		return;
+	}
+
+	let selectedTools = new Set<FirecrawlToolName>(getActiveFirecrawlTools(pi));
+	let persistQueue = Promise.resolve();
+	const commitSelectedTools = () => {
+		const nextSelectedTools = orderedFirecrawlTools(selectedTools);
+		applyFirecrawlTools(pi, nextSelectedTools);
+		persistQueue = persistQueue.then(() => persistSettings(ctx, nextSelectedTools));
+	};
+
+	const customResult = await ctx.ui.custom<"closed" | undefined>(
+		(tui, theme, keybindings, done) => {
+			const rows = firecrawlToolSelectorRows();
+			let selectedIndex = 0;
+			const moveSelection = (delta: number) => {
+				selectedIndex = (selectedIndex + delta + rows.length) % rows.length;
+			};
+			const activateSelectedRow = () => {
+				const row = rows[selectedIndex];
+				if (!row) return;
+
+				if (row.kind === "tool") {
+					if (selectedTools.has(row.toolName)) selectedTools.delete(row.toolName);
+					else selectedTools.add(row.toolName);
+					commitSelectedTools();
+					return;
+				}
+
+				if (row.action === "enableAll") {
+					selectedTools = new Set(allFirecrawlTools());
+					commitSelectedTools();
+					return;
+				}
+				if (row.action === "disableAll") {
+					selectedTools = new Set();
+					commitSelectedTools();
+					return;
+				}
+
+				done("closed");
+			};
+
+			return {
+				invalidate() {},
+				render() {
+					return [
+						theme.fg("accent", theme.bold(toolSelectorTitle(selectedTools))),
+						"",
+						...rows.map((row, index) => {
+							const label = formatToolSelectorRow(row, selectedTools);
+							if (index === selectedIndex) {
+								return `${theme.fg("accent", "›")} ${theme.fg("accent", label)}`;
+							}
+							return `  ${label}`;
+						}),
+						"",
+						theme.fg("dim", "↑↓ navigate • Enter/Space toggle • Esc close"),
+					];
+				},
+				handleInput(data: string) {
+					if (keybindings.matches(data, "tui.select.up")) {
+						moveSelection(-1);
+						tui.requestRender();
+						return;
+					}
+					if (keybindings.matches(data, "tui.select.down")) {
+						moveSelection(1);
+						tui.requestRender();
+						return;
+					}
+					if (keybindings.matches(data, "tui.select.pageUp")) {
+						selectedIndex = 0;
+						tui.requestRender();
+						return;
+					}
+					if (keybindings.matches(data, "tui.select.pageDown")) {
+						selectedIndex = rows.length - 1;
+						tui.requestRender();
+						return;
+					}
+					if (keybindings.matches(data, "tui.select.confirm") || data === " ") {
+						activateSelectedRow();
+						tui.requestRender();
+						return;
+					}
+					if (keybindings.matches(data, "tui.select.cancel")) {
+						done("closed");
+					}
+				},
+			};
+		},
+	);
+
+	if (customResult !== "closed") {
+		await showDialogToolSelector(pi, ctx);
+		return;
+	}
+
+	await persistQueue;
+	ctx.ui.notify(await buildStatusMessage(pi), hasApiKey() ? "info" : "warning");
+}
+
+async function showDialogToolSelector(pi: ExtensionAPI, ctx: CommandContext) {
+	let selectedTools = new Set<FirecrawlToolName>(getActiveFirecrawlTools(pi));
+	while (true) {
+		const rows = firecrawlToolSelectorRows();
+		const choices = rows.map((row) => formatToolSelectorRow(row, selectedTools));
+		const choice = await ctx.ui.select(toolSelectorTitle(selectedTools), choices);
+		if (!choice) break;
+
+		const row = rows[choices.indexOf(choice)];
+		if (!row) continue;
+		if (row.kind === "action" && row.action === "done") break;
+
+		if (row.kind === "tool") {
+			if (selectedTools.has(row.toolName)) selectedTools.delete(row.toolName);
+			else selectedTools.add(row.toolName);
+		} else if (row.action === "enableAll") {
+			selectedTools = new Set(allFirecrawlTools());
+		} else if (row.action === "disableAll") {
+			selectedTools = new Set();
+		}
+
+		await setSelectedFirecrawlTools(pi, ctx, orderedFirecrawlTools(selectedTools));
+	}
+
+	ctx.ui.notify(await buildStatusMessage(pi), hasApiKey() ? "info" : "warning");
+}
+
+export async function updateFirecrawlTools(
+	pi: ExtensionAPI,
+	ctx: CommandContext,
+	selectedTools: readonly FirecrawlToolName[],
+	action: string,
+) {
+	await setSelectedFirecrawlTools(pi, ctx, selectedTools);
+	ctx.ui.notify(
+		`Firecrawl tools ${action}.\n\n${await buildStatusMessage(pi)}`,
+		hasApiKey() ? "info" : "warning",
+	);
+}
+
+export async function setSelectedFirecrawlTools(
+	pi: ExtensionAPI,
+	ctx: CommandContext,
+	selectedTools: readonly FirecrawlToolName[],
+) {
+	applyFirecrawlTools(pi, selectedTools);
+	await persistSettings(ctx, selectedTools);
+}
+
+export function applyFirecrawlTools(pi: ExtensionAPI, selectedTools: readonly FirecrawlToolName[]) {
+	const activeToolNames = pi.getActiveTools();
+	const firecrawlToolNames = new Set<string>(FIRECRAWL_TOOL_NAMES);
+	const activeNonFirecrawlToolNames = activeToolNames.filter(
+		(name) => !firecrawlToolNames.has(name),
+	);
+	pi.setActiveTools(unique([...activeNonFirecrawlToolNames, ...selectedTools]));
+}
+
+function getToolStatusSummary(pi: ExtensionAPI): ToolStatusSummary {
+	const firecrawlToolNames = new Set<string>(FIRECRAWL_TOOL_NAMES);
+	const activeToolNames = new Set(pi.getActiveTools());
+	const activeFirecrawlToolCount = FIRECRAWL_TOOL_NAMES.filter((name) =>
+		activeToolNames.has(name),
+	).length;
+	const activeNonFirecrawlToolCount = Array.from(activeToolNames).filter(
+		(name) => !firecrawlToolNames.has(name),
+	).length;
+	const runtimeStatus =
+		activeFirecrawlToolCount === FIRECRAWL_TOOL_NAMES.length
+			? "enabled"
+			: activeFirecrawlToolCount === 0
+				? "disabled"
+				: "partial";
+
+	return { runtimeStatus, activeFirecrawlToolCount, activeNonFirecrawlToolCount };
+}
+
+export async function buildStatusMessage(pi: ExtensionAPI) {
+	const summary = getToolStatusSummary(pi);
+	const persistedSetting = await persistedSettingLabel();
+	return [
+		`Firecrawl tools: ${formatRuntimeStatus(summary)}`,
+		`Persisted selection: ${persistedSetting}`,
+		`Settings file: ${settingsFilePath()}`,
+		...(settingsNotice ? [`Settings note: ${settingsNotice}`] : []),
+		`Other active tools preserved: ${summary.activeNonFirecrawlToolCount}`,
+		`API key: ${hasApiKey() ? "present" : "missing"} (FIRECRAWL_API_KEY)`,
+		`API URL: ${configuredApiUrl()}`,
+	].join("\n");
+}
+
+export function buildConfigMessage() {
+	return [
+		"Firecrawl configuration:",
+		`API key: ${hasApiKey() ? "present" : "missing"} (FIRECRAWL_API_KEY)`,
+		`API URL: ${configuredApiUrl()}`,
+		"Override API URL with FIRECRAWL_API_URL or FIRECRAWL_BASE_URL.",
+		"This extension never logs, displays, or stores your Firecrawl API key.",
+	].join("\n");
+}
+
+export function buildCommandGuide() {
+	return [
+		"Firecrawl commands:",
+		"/firecrawl — open this menu",
+		"/firecrawl help — show command usage",
+		"/firecrawl config — show API key presence and API URL",
+		"/firecrawl quickstart — alias for /firecrawl config",
+		"/firecrawl status — show tool and settings status",
+		"/firecrawl tools — select individual Firecrawl tools",
+		"/firecrawl toggle — alias for /firecrawl tools",
+		"/firecrawl enable — enable all Firecrawl tools",
+		"/firecrawl disable — disable all Firecrawl tools",
+	].join("\n");
+}
+
+function toolSelectorTitle(selectedTools: ReadonlySet<FirecrawlToolName>) {
+	return `Firecrawl tools (${selectedTools.size}/${FIRECRAWL_TOOL_NAMES.length}). Non-built-in tools run at user risk.`;
+}
+
+function firecrawlToolSelectorRows(): ToolSelectorRow[] {
+	return [
+		...FIRECRAWL_TOOL_NAMES.map((toolName) => ({ kind: "tool" as const, toolName })),
+		{ kind: "action", action: "enableAll", label: TOOL_SELECTOR_ENABLE_ALL },
+		{ kind: "action", action: "disableAll", label: TOOL_SELECTOR_DISABLE_ALL },
+		{ kind: "action", action: "done", label: TOOL_SELECTOR_DONE },
+	];
+}
+
+function formatToolSelectorRow(
+	row: ToolSelectorRow,
+	selectedTools: ReadonlySet<FirecrawlToolName>,
+) {
+	if (row.kind === "action") return row.label;
+	return `${selectedTools.has(row.toolName) ? "[x]" : "[ ]"} ${row.toolName}`;
+}
+
+function getActiveFirecrawlTools(pi: ExtensionAPI) {
+	const activeToolNames = new Set(pi.getActiveTools());
+	return FIRECRAWL_TOOL_NAMES.filter((toolName) => activeToolNames.has(toolName));
+}
+
+export function allFirecrawlTools() {
+	return [...FIRECRAWL_TOOL_NAMES];
+}
+
+function unique<T>(values: T[]) {
+	return Array.from(new Set(values));
+}
+
+export function orderedFirecrawlTools(selectedTools: ReadonlySet<FirecrawlToolName>) {
+	return FIRECRAWL_TOOL_NAMES.filter((toolName) => selectedTools.has(toolName));
+}
+
+function formatRuntimeStatus(summary: ToolStatusSummary) {
+	return `${summary.runtimeStatus} (${summary.activeFirecrawlToolCount}/${FIRECRAWL_TOOL_NAMES.length} active)`;
+}
+
+async function persistedSettingLabel() {
+	const settings = await loadSettings();
+	recordSettingsNotice(settings);
+	if (settings.kind === "loaded") return formatPersistedSelection(settings.settings.tools);
+	if (settings.kind === "invalid") {
+		return `none; current active-tool policy preserved (invalid settings ignored: ${settings.reason})`;
+	}
+	return "none; current active-tool policy preserved";
+}
+
+export function formatPersistedSelection(tools: readonly FirecrawlToolName[]) {
+	if (tools.length === FIRECRAWL_TOOL_NAMES.length) {
+		return `all enabled (${tools.length}/${FIRECRAWL_TOOL_NAMES.length} selected)`;
+	}
+	if (tools.length === 0) return `all disabled (0/${FIRECRAWL_TOOL_NAMES.length} selected)`;
+	return `${tools.length}/${FIRECRAWL_TOOL_NAMES.length} selected: ${tools.join(", ")}`;
+}
+
+function formatError(error: unknown) {
+	return error instanceof Error ? error.message : String(error);
+}
+
+async function persistSettings(
+	ctx: CommandContext,
+	selectedTools: readonly FirecrawlToolName[],
+) {
+	try {
+		await saveSettings({ tools: [...selectedTools], updatedAt: Date.now() });
+	} catch (error) {
+		ctx.ui.notify(`Firecrawl settings save failed: ${formatError(error)}`, "warning");
+	}
+}

package/src/tools.ts

@@ -0,0 +1,186 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { cleanObject, firecrawlRequest, jsonResult, withStatus } from "./client.js";
+
+export const FIRECRAWL_TOOL_NAMES = [
+	"firecrawl_scrape",
+	"firecrawl_crawl",
+	"firecrawl_crawl_status",
+	"firecrawl_map",
+	"firecrawl_search",
+] as const;
+export type FirecrawlToolName = (typeof FIRECRAWL_TOOL_NAMES)[number];
+
+const StringArray = Type.Array(Type.String());
+
+export const scrapeTool = defineTool({
+	name: FIRECRAWL_TOOL_NAMES[0],
+	label: "Firecrawl: Scrape",
+	description: "Scrape a single URL through Firecrawl and return requested formats.",
+	promptSnippet: "Scrape a URL through Firecrawl",
+	promptGuidelines: [
+		"Use firecrawl_scrape when you need clean markdown, HTML, links, screenshots, or structured extraction for one URL.",
+		"If FIRECRAWL_API_KEY is missing, report the configuration error instead of retrying repeatedly.",
+	],
+	parameters: Type.Object({
+		url: Type.String({ description: "URL to scrape." }),
+		formats: Type.Optional(
+			Type.Array(
+				Type.String({
+					description:
+						"Requested Firecrawl output format, such as markdown, html, rawHtml, links, screenshot, or json.",
+				}),
+				{ description: "Firecrawl output formats. Defaults to Firecrawl's API default." },
+			),
+		),
+		onlyMainContent: Type.Optional(
+			Type.Boolean({ description: "Return only the main page content when supported." }),
+		),
+		includeTags: Type.Optional(StringArray),
+		excludeTags: Type.Optional(StringArray),
+		waitFor: Type.Optional(Type.Number({ description: "Milliseconds to wait before scraping." })),
+		timeout: Type.Optional(
+			Type.Number({ description: "Firecrawl request timeout in milliseconds." }),
+		),
+		mobile: Type.Optional(Type.Boolean({ description: "Use a mobile user agent when supported." })),
+		skipTlsVerification: Type.Optional(
+			Type.Boolean({ description: "Skip TLS certificate verification when supported." }),
+		),
+		removeBase64Images: Type.Optional(
+			Type.Boolean({ description: "Remove base64 image data from the response when supported." }),
+		),
+		blockAds: Type.Optional(
+			Type.Boolean({ description: "Block ads while scraping when supported." }),
+		),
+		headers: Type.Optional(
+			Type.Record(Type.String(), Type.String(), {
+				description: "Additional HTTP headers Firecrawl should use while fetching the target URL.",
+			}),
+		),
+		jsonOptions: Type.Optional(
+			Type.Any({ description: "Firecrawl jsonOptions for structured extraction." }),
+		),
+		actions: Type.Optional(
+			Type.Array(Type.Any(), {
+				description: "Firecrawl browser actions to perform before scraping.",
+			}),
+		),
+		location: Type.Optional(Type.Any({ description: "Firecrawl location options." })),
+	}),
+	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		return withStatus(ctx, "scrape", async () => {
+			const payload = await firecrawlRequest("POST", "/scrape", cleanObject(params), signal);
+			return jsonResult(payload);
+		});
+	},
+});
+
+export const crawlTool = defineTool({
+	name: FIRECRAWL_TOOL_NAMES[1],
+	label: "Firecrawl: Crawl",
+	description: "Start a Firecrawl crawl job for a website.",
+	promptSnippet: "Start a Firecrawl site crawl job",
+	parameters: Type.Object({
+		url: Type.String({ description: "Starting URL for the crawl." }),
+		limit: Type.Optional(Type.Number({ description: "Maximum number of pages to crawl." })),
+		maxDepth: Type.Optional(Type.Number({ description: "Maximum crawl depth when supported." })),
+		includePaths: Type.Optional(
+			Type.Array(Type.String(), { description: "URL path patterns to include." }),
+		),
+		excludePaths: Type.Optional(
+			Type.Array(Type.String(), { description: "URL path patterns to exclude." }),
+		),
+		allowBackwardLinks: Type.Optional(
+			Type.Boolean({ description: "Allow crawling backward links when supported." }),
+		),
+		allowExternalLinks: Type.Optional(
+			Type.Boolean({ description: "Allow crawling external links when supported." }),
+		),
+		ignoreSitemap: Type.Optional(Type.Boolean({ description: "Ignore sitemap discovery." })),
+		deduplicateSimilarURLs: Type.Optional(
+			Type.Boolean({ description: "Deduplicate similar URLs when supported." }),
+		),
+		scrapeOptions: Type.Optional(
+			Type.Any({ description: "Firecrawl scrapeOptions applied to crawled pages." }),
+		),
+		webhook: Type.Optional(Type.Any({ description: "Firecrawl webhook configuration." })),
+	}),
+	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		return withStatus(ctx, "crawl", async () => {
+			const payload = await firecrawlRequest("POST", "/crawl", cleanObject(params), signal);
+			return jsonResult(payload);
+		});
+	},
+});
+
+export const crawlStatusTool = defineTool({
+	name: FIRECRAWL_TOOL_NAMES[2],
+	label: "Firecrawl: Crawl Status",
+	description: "Check a Firecrawl crawl job status and retrieve completed crawl data.",
+	promptSnippet: "Check a Firecrawl crawl job status",
+	parameters: Type.Object({
+		id: Type.String({ description: "Crawl job id returned by firecrawl_crawl." }),
+	}),
+	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		return withStatus(ctx, "crawl status", async () => {
+			const payload = await firecrawlRequest(
+				"GET",
+				`/crawl/${encodeURIComponent(params.id)}`,
+				undefined,
+				signal,
+			);
+			return jsonResult(payload);
+		});
+	},
+});
+
+export const mapTool = defineTool({
+	name: FIRECRAWL_TOOL_NAMES[3],
+	label: "Firecrawl: Map",
+	description: "Discover URLs for a site through Firecrawl's map endpoint.",
+	promptSnippet: "Map/discover URLs for a site through Firecrawl",
+	parameters: Type.Object({
+		url: Type.String({ description: "Website URL to map." }),
+		search: Type.Optional(
+			Type.String({ description: "Optional search term to filter discovered URLs." }),
+		),
+		ignoreSitemap: Type.Optional(Type.Boolean({ description: "Ignore sitemap discovery." })),
+		sitemapOnly: Type.Optional(
+			Type.Boolean({ description: "Only use sitemap URLs when supported." }),
+		),
+		includeSubdomains: Type.Optional(
+			Type.Boolean({ description: "Include subdomains when supported." }),
+		),
+		limit: Type.Optional(Type.Number({ description: "Maximum number of URLs to return." })),
+	}),
+	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		return withStatus(ctx, "map", async () => {
+			const payload = await firecrawlRequest("POST", "/map", cleanObject(params), signal);
+			return jsonResult(payload);
+		});
+	},
+});
+
+export const searchTool = defineTool({
+	name: FIRECRAWL_TOOL_NAMES[4],
+	label: "Firecrawl: Search",
+	description: "Search the web through Firecrawl and optionally scrape search results.",
+	promptSnippet: "Search the web through Firecrawl",
+	parameters: Type.Object({
+		query: Type.String({ description: "Search query." }),
+		limit: Type.Optional(Type.Number({ description: "Maximum number of search results." })),
+		tbs: Type.Optional(
+			Type.String({ description: "Google-style time based search filter when supported." }),
+		),
+		location: Type.Optional(Type.String({ description: "Search location when supported." })),
+		scrapeOptions: Type.Optional(
+			Type.Any({ description: "Firecrawl scrapeOptions for search result pages." }),
+		),
+	}),
+	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		return withStatus(ctx, "search", async () => {
+			const payload = await firecrawlRequest("POST", "/search", cleanObject(params), signal);
+			return jsonResult(payload);
+		});
+	},
+});