@browserless.io/mcp 1.6.0

package/build/src/lib/api-client.js

@@ -0,0 +1,357 @@
+import { compact, hashToken, isTextContentType } from './utils.js';
+import { retryWithBackoff } from './retry.js';
+import { ResponseCache } from './cache.js';
+/**
+ * Thrown when an API call references a profile that does not exist for the
+ * current API token. Tools catch this and re-throw as a UserError so the LLM
+ * sees a clean explanation instead of a downstream property-access crash on
+ * the 404 body shape `{ error: '...' }`.
+ */
+export class ProfileNotFoundError extends Error {
+    profile;
+    constructor(profile, serverMessage) {
+        super(serverMessage ??
+            `Profile "${profile}" was not found for the configured token.`);
+        this.profile = profile;
+        this.name = 'ProfileNotFoundError';
+    }
+}
+/**
+ * If the response is a 404 from a profile-aware endpoint with a profile set,
+ * throw a typed ProfileNotFoundError so the caller can surface it as a
+ * UserError. We treat any 404 + profile as profile-not-found regardless of
+ * body shape — the error body varies (`error` / `message` / `detail` /
+ * malformed JSON) and the downstream `await res.json()` would crash anyway.
+ */
+async function throwIfProfileMissing(res, profile) {
+    if (!profile || res.status !== 404)
+        return;
+    const body = await res
+        .clone()
+        .json()
+        .catch(() => null);
+    let serverMessage;
+    if (body && typeof body === 'object') {
+        const b = body;
+        const candidates = [
+            b.error,
+            b.message,
+            b.detail,
+            Array.isArray(b.errors) ? b.errors[0] : undefined,
+        ];
+        serverMessage = candidates.find((v) => typeof v === 'string');
+    }
+    throw new ProfileNotFoundError(profile, serverMessage);
+}
+const defaultShouldRetry = (error) => {
+    if (error instanceof ProfileNotFoundError)
+        return false;
+    return !error.message.startsWith('Server error 4');
+};
+async function defaultHandleResponse(res) {
+    if (!res.ok && res.status >= 500) {
+        throw new Error(`Server error ${res.status}: ${res.statusText}`);
+    }
+    if (!res.ok) {
+        const errorBody = await res.text().catch(() => res.statusText);
+        const message = errorBody.trim() || res.statusText;
+        throw new Error(`Server error ${res.status}: ${message}`);
+    }
+    return (await res.json());
+}
+function apiFetch(config, opts) {
+    const query = new URLSearchParams({ token: config.browserlessToken });
+    for (const [k, v] of Object.entries(opts.query ?? {})) {
+        if (v !== undefined)
+            query.set(k, String(v));
+    }
+    const url = `${config.browserlessApiUrl}${opts.path}?${query.toString()}`;
+    const method = opts.method ?? 'POST';
+    const init = { method };
+    if (opts.body !== undefined) {
+        init.headers = { 'Content-Type': opts.contentType ?? 'application/json' };
+        init.body = JSON.stringify(opts.body);
+    }
+    const handle = opts.handleResponse ?? (defaultHandleResponse);
+    return retryWithBackoff(async () => {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), opts.timeout + 5000);
+        try {
+            const res = await fetch(url, { ...init, signal: controller.signal });
+            await throwIfProfileMissing(res, opts.profile);
+            return await handle(res);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }, {
+        maxRetries: opts.maxRetries ?? config.maxRetries,
+        baseDelayMs: 1000,
+        shouldRetry: opts.shouldRetry ?? defaultShouldRetry,
+    });
+}
+/** Read a Response as text or base64-encoded binary based on its content type. */
+async function readGeneric(res) {
+    if (!res.ok && res.status >= 500) {
+        throw new Error(`Server error ${res.status}: ${res.statusText}`);
+    }
+    const respContentType = res.headers.get('content-type') ?? 'application/octet-stream';
+    const contentDisposition = res.headers.get('content-disposition') ?? null;
+    const isBinary = !isTextContentType(respContentType);
+    let data;
+    let size;
+    if (isBinary) {
+        const buf = Buffer.from(await res.arrayBuffer());
+        size = buf.byteLength;
+        data = buf.toString('base64');
+    }
+    else {
+        data = await res.text();
+        size = Buffer.byteLength(data, 'utf-8');
+    }
+    return {
+        data,
+        contentType: respContentType,
+        contentDisposition,
+        statusCode: res.status,
+        ok: res.ok,
+        size,
+        isBinary,
+    };
+}
+export function createApiClient(config, cache) {
+    const _cache = cache ?? new ResponseCache(config.cacheTtlMs);
+    return {
+        async smartScrape(params) {
+            const formats = params.formats ?? ['markdown'];
+            const tokenHash = hashToken(config.browserlessToken);
+            const cacheKey = JSON.stringify({
+                t: tokenHash,
+                // The api URL can be overridden per-session, so two backends sharing
+                // the same token must not share cache entries.
+                api: config.browserlessApiUrl,
+                url: params.url,
+                formats: [...formats].sort(),
+                // Profiles inject auth state — a cache hit across profiles would
+                // leak one user's session into another's response.
+                profile: params.profile ?? null,
+            });
+            const cached = _cache.get(cacheKey);
+            if (cached) {
+                return { ...cached, cacheHit: true };
+            }
+            const timeout = params.timeout ?? config.requestTimeout;
+            const result = await apiFetch(config, {
+                path: '/smart-scrape',
+                query: { timeout, profile: params.profile },
+                body: { url: params.url, formats },
+                timeout,
+                profile: params.profile,
+            });
+            _cache.set(cacheKey, result);
+            return { ...result, cacheHit: false };
+        },
+        async runFunction(params) {
+            const timeout = params.timeout ?? config.requestTimeout;
+            return apiFetch(config, {
+                path: '/function',
+                query: { timeout, profile: params.profile },
+                body: compact({ code: params.code, context: params.context }),
+                timeout,
+                profile: params.profile,
+                handleResponse: readGeneric,
+            });
+        },
+        async download(params) {
+            const timeout = params.timeout ?? config.requestTimeout;
+            return apiFetch(config, {
+                path: '/download',
+                query: { timeout, profile: params.profile },
+                body: compact({ code: params.code, context: params.context }),
+                timeout,
+                profile: params.profile,
+                handleResponse: readGeneric,
+            });
+        },
+        async exportPage(params) {
+            const timeout = params.timeout ?? config.requestTimeout;
+            return apiFetch(config, {
+                path: '/export',
+                query: { timeout, profile: params.profile },
+                body: compact({
+                    url: params.url,
+                    gotoOptions: params.gotoOptions,
+                    bestAttempt: params.bestAttempt,
+                    includeResources: params.includeResources,
+                    waitForTimeout: params.waitForTimeout,
+                }),
+                timeout,
+                profile: params.profile,
+                handleResponse: readGeneric,
+            });
+        },
+        async getStatus() {
+            try {
+                const queryParams = new URLSearchParams({
+                    token: config.browserlessToken,
+                });
+                const res = await fetch(`${config.browserlessApiUrl}/active?${queryParams.toString()}`);
+                if (res.ok) {
+                    return { ok: true, message: 'Browserless API is reachable' };
+                }
+                return { ok: false, message: `API returned status ${res.status}` };
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    message: `Cannot reach API: ${err.message}`,
+                };
+            }
+        },
+        async search(params) {
+            const timeout = params.timeout ?? config.requestTimeout;
+            return apiFetch(config, {
+                path: '/search',
+                query: { timeout },
+                body: compact({
+                    query: params.query,
+                    limit: params.limit,
+                    lang: params.lang,
+                    country: params.country,
+                    location: params.location,
+                    tbs: params.tbs,
+                    sources: params.sources,
+                    categories: params.categories,
+                    scrapeOptions: params.scrapeOptions,
+                }),
+                timeout,
+            });
+        },
+        async performance(params) {
+            const timeout = params.timeout ?? config.requestTimeout;
+            const body = { url: params.url };
+            if (params.categories) {
+                body.config = {
+                    extends: 'lighthouse:default',
+                    settings: { onlyCategories: params.categories },
+                };
+            }
+            if (params.budgets)
+                body.budgets = params.budgets;
+            return apiFetch(config, {
+                path: '/performance',
+                query: { timeout, profile: params.profile },
+                body,
+                timeout,
+                profile: params.profile,
+            });
+        },
+        async map(params) {
+            const timeout = params.timeout ?? config.requestTimeout;
+            return apiFetch(config, {
+                path: '/map',
+                query: { timeout },
+                body: compact({
+                    url: params.url,
+                    search: params.search,
+                    limit: params.limit,
+                    sitemap: params.sitemap,
+                    includeSubdomains: params.includeSubdomains,
+                    ignoreQueryParameters: params.ignoreQueryParameters,
+                }),
+                timeout,
+            });
+        },
+        async crawl(params) {
+            const timeout = params.timeout ?? config.requestTimeout;
+            return apiFetch(config, {
+                // /crawl accepts token + profile as query params; no `timeout` query.
+                path: '/crawl',
+                query: { profile: params.profile },
+                body: compact({
+                    url: params.url,
+                    limit: params.limit,
+                    maxDepth: params.maxDepth,
+                    maxRetries: params.maxRetries,
+                    allowExternalLinks: params.allowExternalLinks,
+                    allowSubdomains: params.allowSubdomains,
+                    sitemap: params.sitemap,
+                    includePaths: params.includePaths,
+                    excludePaths: params.excludePaths,
+                    delay: params.delay,
+                    scrapeOptions: params.scrapeOptions,
+                }),
+                timeout,
+                profile: params.profile,
+                handleResponse: async (res) => {
+                    if (!res.ok && res.status >= 500) {
+                        throw new Error(`Server error ${res.status}: ${res.statusText}`);
+                    }
+                    // The /crawl endpoint returns a structured
+                    // `{ success: false, error: string }` body on some 4xx responses
+                    // (e.g. 429 rate limit). Forward those so the tool can surface
+                    // them as a clean UserError. Non-JSON 4xx bodies surface as a
+                    // Server error so retry suppression catches them.
+                    if (!res.ok) {
+                        const text = await res.text().catch(() => '');
+                        try {
+                            const parsed = JSON.parse(text);
+                            if (parsed &&
+                                typeof parsed === 'object' &&
+                                parsed.success === false) {
+                                return parsed;
+                            }
+                        }
+                        catch {
+                            // Non-JSON body — fall through.
+                        }
+                        const message = text.trim() || res.statusText;
+                        throw new Error(`Server error ${res.status}: ${message}`);
+                    }
+                    return (await res.json());
+                },
+            });
+        },
+        async getCrawl(crawlId, skip) {
+            return apiFetch(config, {
+                path: `/crawl/${crawlId}`,
+                method: 'GET',
+                query: { skip: skip !== undefined && skip > 0 ? skip : undefined },
+                timeout: config.requestTimeout,
+                shouldRetry: (error) => !/^(Server|API) error 4/.test(error.message) &&
+                    !error.message.toLowerCase().includes('not found'),
+                handleResponse: async (res) => {
+                    if (res.status === 404)
+                        throw new Error('Crawl not found');
+                    if (!res.ok) {
+                        const errorBody = await res.text().catch(() => res.statusText);
+                        throw new Error(`API error ${res.status}: ${errorBody}`);
+                    }
+                    return (await res.json());
+                },
+            });
+        },
+        async cancelCrawl(crawlId) {
+            return apiFetch(config, {
+                path: `/crawl/${crawlId}`,
+                method: 'DELETE',
+                timeout: config.requestTimeout,
+                maxRetries: 0,
+                shouldRetry: () => false,
+                handleResponse: async (res) => {
+                    if (res.status === 404)
+                        throw new Error('Crawl not found');
+                    if (res.status === 409) {
+                        const body = (await res.json());
+                        throw new Error(body.message ?? 'Crawl is already in terminal state');
+                    }
+                    if (!res.ok) {
+                        const errorBody = await res.text().catch(() => res.statusText);
+                        throw new Error(`API error ${res.status}: ${errorBody}`);
+                    }
+                    return (await res.json());
+                },
+            });
+        },
+    };
+}

package/build/src/lib/bounded-event-store.d.ts

@@ -0,0 +1,22 @@
+import type { EventStore } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * A bounded in-memory EventStore that caps the number of stored events
+ * to prevent unbounded memory growth. Evicts oldest entries when full.
+ *
+ * The default InMemoryEventStore from mcp-proxy never evicts events,
+ * causing a steady memory leak in long-running servers.
+ */
+export declare class BoundedEventStore implements EventStore {
+    private events;
+    private lastTimestamp;
+    private lastTimestampCounter;
+    private readonly maxEvents;
+    constructor(maxEvents?: number);
+    storeEvent(streamId: string, message: JSONRPCMessage): Promise<string>;
+    replayEventsAfter(lastEventId: string, { send, }: {
+        send: (eventId: string, message: JSONRPCMessage) => Promise<void>;
+    }): Promise<string>;
+    private generateEventId;
+    private getStreamIdFromEventId;
+}

package/build/src/lib/bounded-event-store.js

@@ -0,0 +1,69 @@
+/**
+ * A bounded in-memory EventStore that caps the number of stored events
+ * to prevent unbounded memory growth. Evicts oldest entries when full.
+ *
+ * The default InMemoryEventStore from mcp-proxy never evicts events,
+ * causing a steady memory leak in long-running servers.
+ */
+export class BoundedEventStore {
+    events = new Map();
+    lastTimestamp = 0;
+    lastTimestampCounter = 0;
+    maxEvents;
+    constructor(maxEvents = 10_000) {
+        this.maxEvents = maxEvents;
+    }
+    async storeEvent(streamId, message) {
+        const eventId = this.generateEventId(streamId);
+        this.events.set(eventId, { message, streamId });
+        // Evict oldest entries when over capacity
+        if (this.events.size > this.maxEvents) {
+            const keysToDelete = [...this.events.keys()].slice(0, this.events.size - this.maxEvents);
+            for (const key of keysToDelete) {
+                this.events.delete(key);
+            }
+        }
+        return eventId;
+    }
+    async replayEventsAfter(lastEventId, { send, }) {
+        if (!lastEventId || !this.events.has(lastEventId)) {
+            return '';
+        }
+        const streamId = this.getStreamIdFromEventId(lastEventId);
+        if (!streamId) {
+            return '';
+        }
+        let foundLastEvent = false;
+        // Snapshot to avoid absorbing events added concurrently during async send()
+        const snapshot = [...this.events.entries()];
+        for (const [eventId, event] of snapshot) {
+            if (event.streamId !== streamId)
+                continue;
+            if (!foundLastEvent) {
+                if (eventId === lastEventId)
+                    foundLastEvent = true;
+                continue;
+            }
+            await send(eventId, event.message);
+        }
+        return streamId;
+    }
+    generateEventId(streamId) {
+        const now = Date.now();
+        if (now === this.lastTimestamp) {
+            this.lastTimestampCounter++;
+        }
+        else {
+            this.lastTimestamp = now;
+            this.lastTimestampCounter = 0;
+        }
+        const random = Math.random().toString(36).slice(2, 8);
+        return `${streamId}_${now}_${this.lastTimestampCounter}_${random}`;
+    }
+    getStreamIdFromEventId(eventId) {
+        // Event ID format: {streamId}_{timestamp}_{counter}_{random}
+        // streamId itself may contain underscores, so take everything except the last 3 segments
+        const parts = eventId.split('_');
+        return parts.length >= 4 ? parts.slice(0, -3).join('_') : undefined;
+    }
+}

package/build/src/lib/cache.d.ts

@@ -0,0 +1,12 @@
+export declare class ResponseCache {
+    private store;
+    private readonly ttlMs;
+    private sweepTimer;
+    constructor(ttlMs: number);
+    private sweep;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T): void;
+    clear(): void;
+    dispose(): void;
+    get size(): number;
+}

package/build/src/lib/cache.js

@@ -0,0 +1,49 @@
+export class ResponseCache {
+    store = new Map();
+    ttlMs;
+    sweepTimer;
+    constructor(ttlMs) {
+        this.ttlMs = ttlMs;
+        if (ttlMs > 0) {
+            this.sweepTimer = setInterval(() => this.sweep(), ttlMs * 2);
+            this.sweepTimer.unref();
+        }
+    }
+    sweep() {
+        const now = Date.now();
+        for (const [key, entry] of this.store) {
+            if (now > entry.expiresAt) {
+                this.store.delete(key);
+            }
+        }
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value) {
+        this.store.set(key, {
+            value,
+            expiresAt: Date.now() + this.ttlMs,
+        });
+    }
+    clear() {
+        this.store.clear();
+    }
+    dispose() {
+        if (this.sweepTimer) {
+            clearInterval(this.sweepTimer);
+            this.sweepTimer = undefined;
+        }
+        this.store.clear();
+    }
+    get size() {
+        return this.store.size;
+    }
+}

package/build/src/lib/define-tool.d.ts

@@ -0,0 +1,71 @@
+import { FastMCP } from 'fastmcp';
+import type { Content } from 'fastmcp';
+import { type ZodType } from 'zod';
+import { ResponseCache } from './cache.js';
+import { AnalyticsHelper } from './analytics.js';
+import type { ApiClient, McpConfig } from '../@types/types.js';
+/**
+ * Minimal log surface tools use. Tools only call the level methods with a
+ * string today, so the extra `data` param FastMCP's Logger accepts is just
+ * dropped here. Optional extra params on the source remain assignable.
+ */
+interface ToolLog {
+    debug(message: string): void;
+    error(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+}
+interface ToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+    streamingHint?: boolean;
+}
+export interface ToolRunContext<P> {
+    client: ApiClient;
+    params: P;
+    log: ToolLog;
+    /** For tools that fire analytics from inside their own logic (e.g. crawl polling). */
+    analytics?: AnalyticsHelper;
+    token: string;
+    apiUrl: string;
+    reportProgress: (progress: {
+        progress: number;
+        total: number;
+    }) => Promise<void>;
+    /** MCP session id (httpStream transport) or undefined for stdio — used by agent tool. */
+    sessionId: string | undefined;
+}
+export interface ToolDefinition<P, R> {
+    name: string;
+    description: string;
+    parameters: ZodType<P>;
+    annotations?: ToolAnnotations;
+    /** Throw UserError if any URL in params is invalid. Runs before progress 0. */
+    validateUrl?: (params: P) => void;
+    /** Override the default ProfileNotFoundError → UserError message. */
+    profileNotFoundMessage?: (profile: string) => string;
+    /**
+     * Persistent ResponseCache shared across executions of this tool. Pass
+     * a cache here if the tool relies on caching (e.g. smartScrape) — without
+     * it createApiClient builds a fresh per-execution cache.
+     */
+    cache?: ResponseCache;
+    /** Main tool logic. Returns the value `format` will render. */
+    run: (ctx: ToolRunContext<P>) => Promise<R>;
+    /** Render the result into MCP content blocks. May throw UserError. */
+    format: (result: R, params: P) => Content[];
+    /**
+     * Extra analytics properties beyond the base `{ token, tool, api_url }`.
+     * Fired AFTER `run` completes and BEFORE `format` runs — so analytics
+     * still fire if `format` throws (e.g. on `!response.ok`). Omit when the
+     * tool fires its own intra-execution events.
+     */
+    analyticsProps?: (params: P, result: R) => Record<string, unknown>;
+}
+/** Throw a UserError if `url` is not an http/https URL. */
+export declare function validateHttpUrl(url: string): void;
+export declare function defineTool<P, R>(server: FastMCP, config: McpConfig, analytics: AnalyticsHelper | undefined, def: ToolDefinition<P, R>): void;
+export {};

package/build/src/lib/define-tool.js

@@ -0,0 +1,71 @@
+import { UserError } from 'fastmcp';
+import { createApiClient, ProfileNotFoundError } from './api-client.js';
+const defaultProfileMessage = (profile) => `Profile "${profile}" was not found for the configured API token. ` +
+    `Create the profile with Browserless.saveProfile in a live session first, ` +
+    `or omit the profile parameter.`;
+/** Throw a UserError if `url` is not an http/https URL. */
+export function validateHttpUrl(url) {
+    const urlObj = new URL(url);
+    if (!['http:', 'https:'].includes(urlObj.protocol)) {
+        throw new UserError(`Invalid URL protocol "${urlObj.protocol}". Only http and https are supported.`);
+    }
+}
+export function defineTool(server, config, analytics, def) {
+    server.addTool({
+        name: def.name,
+        description: def.description,
+        parameters: def.parameters,
+        annotations: def.annotations,
+        execute: async (args, { reportProgress, session, sessionId, log }) => {
+            const params = args;
+            // Single localized cast — FastMCP types session as Record<string, unknown>
+            // for the unconstrained generic. Tools see the typed session via this helper
+            // and never cast token/apiUrl themselves.
+            const s = session;
+            const token = s?.token ?? config.browserlessToken;
+            if (!token) {
+                throw new UserError('No Browserless API token provided. ' +
+                    'For stdio: set the BROWSERLESS_TOKEN environment variable. ' +
+                    'For HTTP: pass Authorization: Bearer <token> header.');
+            }
+            const apiUrl = s?.apiUrl ?? config.browserlessApiUrl;
+            def.validateUrl?.(params);
+            await reportProgress({ progress: 0, total: 100 });
+            const client = createApiClient({
+                ...config,
+                browserlessToken: token,
+                browserlessApiUrl: apiUrl,
+            }, def.cache);
+            let result;
+            try {
+                result = await def.run({
+                    client,
+                    params,
+                    log,
+                    analytics,
+                    token,
+                    apiUrl,
+                    reportProgress,
+                    sessionId,
+                });
+            }
+            catch (err) {
+                if (err instanceof ProfileNotFoundError) {
+                    const msg = def.profileNotFoundMessage
+                        ? def.profileNotFoundMessage(err.profile)
+                        : defaultProfileMessage(err.profile);
+                    throw new UserError(msg);
+                }
+                throw err;
+            }
+            await reportProgress({ progress: 100, total: 100 });
+            if (analytics && def.analyticsProps) {
+                analytics.fireToolRequest(token, def.name, {
+                    api_url: apiUrl,
+                    ...def.analyticsProps(params, result),
+                });
+            }
+            return { content: def.format(result, params) };
+        },
+    });
+}

package/build/src/lib/error-classifier.d.ts

@@ -0,0 +1,4 @@
+import type { ClassifiedError, ClassifyInput } from '../@types/types.js';
+export type { ErrorCategory, ClassifiedError, ClassifyInput, } from '../@types/types.js';
+export declare const classifyAgentError: (input: ClassifyInput) => ClassifiedError;
+export declare const formatClassifiedError: (classified: ClassifiedError, bodyLines: string[]) => string;