@browserless.io/mcp 1.6.0

package/build/src/lib/error-classifier.js

@@ -0,0 +1,125 @@
+const RECOVERY = {
+    SELECTOR_MISS: 'Re-snapshot — the element is not in the current DOM. If you have not tried it yet, retry with a deep selector "< selector" in case the element is inside a shadow root.',
+    SESSION_LOST: 'A fresh session was opened automatically. Re-run goto then snapshot — page state from before the failure is gone.',
+    UNAUTHORIZED: 'The server returned 401. Authentication is missing or invalid; the page is not reachable from this session. Do not retry the prior selector.',
+    FORBIDDEN: 'The server returned 403. Cookies/auth may be missing or invalid, or the resource is geo/IP-blocked. Do not retry the prior selector.',
+    NOT_FOUND: 'The server returned 404. The URL no longer exists; pick a different navigation target.',
+    SERVER_ERROR: 'The origin returned a 5xx error. Back off briefly, then retry once. If it persists, choose a different path.',
+    NAVIGATION_FAILED: 'A network/DNS error prevented navigation. Verify the URL is correct and reachable.',
+    TIMEOUT: 'The page or wait condition did not resolve in time. Try a longer waitFor, a different signal (waitForResponse with a known URL), or re-snapshot to confirm current state.',
+    INVALID_PARAMS: 'The parameters were rejected. The schema is authoritative — fix the params; do not blind-retry.',
+    UNKNOWN: 'Re-snapshot and re-plan from the current page state.',
+};
+const FATAL_SESSION_CODES = new Set(['BROWSER_CRASHED']);
+const NAVIGATION_FAIL_PATTERNS = [
+    /net::ERR_/i,
+    /\bECONNREFUSED\b/,
+    /\bENOTFOUND\b/,
+    /\bEAI_AGAIN\b/,
+    /\bECONNRESET\b/,
+    /navigation aborted/i,
+    /failed to navigate/i,
+];
+const WS_LOSS_PATTERNS = [
+    /WebSocket closed/i,
+    /WebSocket connection failed/i,
+    /Agent WebSocket connection failed/i,
+];
+const TIMEOUT_PATTERNS = [/timed out/i, /\btimeout\b/i];
+const extractStatus = (err) => {
+    if (typeof err.status === 'number') {
+        return err.status;
+    }
+    const match = err.message?.match(/\b(401|403|404|5\d\d)\b/);
+    if (match)
+        return Number(match[1]);
+    return undefined;
+};
+const fromStatus = (status) => {
+    if (status === 401)
+        return 'UNAUTHORIZED';
+    if (status === 403)
+        return 'FORBIDDEN';
+    if (status === 404)
+        return 'NOT_FOUND';
+    if (status >= 500 && status <= 599)
+        return 'SERVER_ERROR';
+    return undefined;
+};
+const INVALID_PARAMS_PATTERNS = [
+    /\bInvalid parameters?\b/i,
+    /\bFailed to deserialize\b/i,
+];
+export const classifyAgentError = (input) => {
+    const { err, cmd } = input;
+    const code = err.code;
+    const message = err.message ?? '';
+    // waitForSelector failures are timeouts in intent: the agent reports
+    // SELECTOR_NOT_FOUND, but the user asked to wait, so the actionable signal
+    // is "the wait expired", not "the element is missing right now".
+    if (cmd?.method === 'waitForSelector' && code === 'SELECTOR_NOT_FOUND') {
+        return { category: 'TIMEOUT', code, recovery: RECOVERY.TIMEOUT };
+    }
+    if (code === 'SELECTOR_NOT_FOUND') {
+        return {
+            category: 'SELECTOR_MISS',
+            code,
+            recovery: RECOVERY.SELECTOR_MISS,
+        };
+    }
+    // Authoritative upstream codes win first.
+    if (code === 'INVALID_PARAMS') {
+        return {
+            category: 'INVALID_PARAMS',
+            code,
+            recovery: RECOVERY.INVALID_PARAMS,
+        };
+    }
+    if (code && FATAL_SESSION_CODES.has(code)) {
+        return { category: 'SESSION_LOST', code, recovery: RECOVERY.SESSION_LOST };
+    }
+    // HTTP status before the INVALID_PARAMS *message-pattern* heuristic so a
+    // message that happens to mention 4xx/5xx isn't swallowed by it.
+    const status = extractStatus(err);
+    if (status !== undefined) {
+        const fromCode = fromStatus(status);
+        if (fromCode) {
+            return {
+                category: fromCode,
+                code,
+                status,
+                recovery: RECOVERY[fromCode],
+            };
+        }
+    }
+    if (INVALID_PARAMS_PATTERNS.some((re) => re.test(message))) {
+        return {
+            category: 'INVALID_PARAMS',
+            code,
+            recovery: RECOVERY.INVALID_PARAMS,
+        };
+    }
+    const isTimeout = TIMEOUT_PATTERNS.some((re) => re.test(message));
+    if (/Agent WebSocket connection timed out/i.test(message)) {
+        return { category: 'TIMEOUT', code, recovery: RECOVERY.TIMEOUT };
+    }
+    if (WS_LOSS_PATTERNS.some((re) => re.test(message))) {
+        return { category: 'SESSION_LOST', code, recovery: RECOVERY.SESSION_LOST };
+    }
+    if (NAVIGATION_FAIL_PATTERNS.some((re) => re.test(message))) {
+        return {
+            category: 'NAVIGATION_FAILED',
+            code,
+            recovery: RECOVERY.NAVIGATION_FAILED,
+        };
+    }
+    if (isTimeout) {
+        return { category: 'TIMEOUT', code, recovery: RECOVERY.TIMEOUT };
+    }
+    return { category: 'UNKNOWN', code, recovery: RECOVERY.UNKNOWN };
+};
+export const formatClassifiedError = (classified, bodyLines) => {
+    const parts = [`Category: ${classified.category}`, ...bodyLines];
+    parts.push(`Recovery: ${classified.recovery}`);
+    return parts.join('\n\n');
+};

package/build/src/lib/redis-oauth-proxy.d.ts

@@ -0,0 +1,13 @@
+import { Redis } from 'ioredis';
+import { OAuthProxy, type AuthorizationParams, type DCRRequest, type DCRResponse, type OAuthProxyConfig, type TokenRequest, type TokenResponse } from 'fastmcp/auth';
+export declare class RedisOAuthProxy extends OAuthProxy {
+    private redis;
+    constructor(config: OAuthProxyConfig, redis: Redis);
+    private get _internal();
+    registerClient(request: DCRRequest): Promise<DCRResponse>;
+    private isClientRegistered;
+    authorize(params: AuthorizationParams): Promise<Response>;
+    handleCallback(request: Request): Promise<Response>;
+    exchangeAuthorizationCode(request: TokenRequest): Promise<TokenResponse>;
+    destroy(): void;
+}

package/build/src/lib/redis-oauth-proxy.js

@@ -0,0 +1,214 @@
+import { OAuthProxy, OAuthProxyError, } from 'fastmcp/auth';
+/**
+ * Redis-backed OAuthProxy using Redis as the single source of truth for OAuth
+ * flow state (transactions, authorization codes, DCRs), so the steps of one
+ * flow can land on different instances behind a load balancer.
+ *
+ * fastmcp v4 (CWE-601 hardening) made DCR state load-bearing for authorize(),
+ * handleCallback(), and handleConsent(), all checking a process-local Map.
+ * That breaks multi-instance (DCR on A, authorize on B → B rejects a valid
+ * redirect_uri), so the overrides here validate against Redis instead and
+ * ignore the parent's Map (super.registerClient still fills it; we never read it).
+ *
+ * Consent is NOT supported — the parent's handleConsent uses a process-local
+ * Map; the constructor throws if it's enabled. Requires Redis 6.2+ / Valkey 7+
+ * for GETDEL (atomic one-time-use of authorization codes across instances).
+ */
+const KEY_PREFIX = 'mcp:oauth:';
+const TX_PREFIX = `${KEY_PREFIX}tx:`;
+const CODE_PREFIX = `${KEY_PREFIX}code:`;
+const CLIENT_PREFIX = `${KEY_PREFIX}client:`;
+const DEFAULT_TRANSACTION_TTL = 600;
+const DEFAULT_CODE_TTL = 300;
+const DEFAULT_CLIENT_TTL = 3600;
+const DATE_FIELDS = new Set(['createdAt', 'expiresAt', 'issuedAt']);
+function serialize(obj) {
+    return JSON.stringify(obj, (_key, value) => {
+        if (value instanceof Date)
+            return { __date: value.toISOString() };
+        return value;
+    });
+}
+function deserialize(json) {
+    return JSON.parse(json, (key, value) => {
+        if (value && typeof value === 'object' && '__date' in value) {
+            return new Date(value.__date);
+        }
+        if (DATE_FIELDS.has(key) && typeof value === 'string') {
+            return new Date(value);
+        }
+        return value;
+    });
+}
+export class RedisOAuthProxy extends OAuthProxy {
+    redis;
+    constructor(config, redis) {
+        super(config);
+        this.redis = redis;
+        // Our authorize() override short-circuits the parent's consent branch,
+        // and the parent's handleConsent reads transactions from a process-local
+        // Map which breaks in multi-instance. Fail fast if a caller opts in.
+        if (this.config.consentRequired) {
+            throw new Error('RedisOAuthProxy requires consentRequired: false — consent flow is not supported in multi-instance mode');
+        }
+    }
+    get _internal() {
+        return this;
+    }
+    async registerClient(request) {
+        // Delegate validation/response to the parent, then mirror the accepted
+        // URIs into Redis so every instance can honor the v4 redirect_uri check.
+        // (The parent's in-memory Map is also populated but we never read it.)
+        const response = await super.registerClient(request);
+        const ttl = this._internal.config.clientRegistrationTtl ?? DEFAULT_CLIENT_TTL;
+        // Snapshot pre-existence so rollback doesn't DEL a valid prior
+        // registration of the same URI (two DCR calls sharing a redirect_uri).
+        // allSettled → a probe failure is fail-fast with no writes attempted.
+        const probes = await Promise.allSettled(response.redirect_uris.map(async (uri) => ({
+            uri,
+            existed: (await this.redis.exists(`${CLIENT_PREFIX}${uri}`)) > 0,
+        })));
+        const probeFailed = probes.find((p) => p.status === 'rejected');
+        if (probeFailed) {
+            throw probeFailed.reason;
+        }
+        const redisPreExisting = new Set(probes
+            .filter((p) => p.status === 'fulfilled' && p.value.existed)
+            .map((p) => p.value.uri));
+        const writes = await Promise.allSettled(response.redirect_uris.map((uri) => this.redis.set(`${CLIENT_PREFIX}${uri}`, '1', 'EX', ttl)));
+        const writeFailed = writes.find((w) => w.status === 'rejected');
+        if (writeFailed) {
+            // Best-effort cleanup of Redis keys this call introduced; if these
+            // deletes also fail the originating error still wins.
+            await Promise.allSettled(response.redirect_uris
+                .filter((uri) => !redisPreExisting.has(uri))
+                .map((uri) => this.redis.del(`${CLIENT_PREFIX}${uri}`)));
+            throw writeFailed.reason;
+        }
+        return response;
+    }
+    async isClientRegistered(uri) {
+        return (await this.redis.exists(`${CLIENT_PREFIX}${uri}`)) === 1;
+    }
+    async authorize(params) {
+        if (!params.client_id || !params.redirect_uri || !params.response_type) {
+            throw new OAuthProxyError('invalid_request', 'Missing required parameters');
+        }
+        if (params.response_type !== 'code') {
+            throw new OAuthProxyError('unsupported_response_type', "Only 'code' response type is supported");
+        }
+        // RFC 6749 §5.2 — reject any client_id other than the single upstream
+        // identity this proxy fronts. Ported from fastmcp v4 OAuthProxy.authorize.
+        if (params.client_id !== this._internal.config.upstreamClientId) {
+            throw new OAuthProxyError('invalid_client', 'Unknown client_id');
+        }
+        // RFC 6749 §3.1.2.3 / RFC 6819 §4.1.5 — redirect_uri must be one
+        // previously registered via DCR; skipping this is CWE-601 (auth-code
+        // theft). We read the shared Redis registry so cross-instance DCR counts.
+        if (!(await this.isClientRegistered(params.redirect_uri))) {
+            throw new OAuthProxyError('invalid_request', 'redirect_uri is not registered for this client');
+        }
+        if (params.code_challenge && !params.code_challenge_method) {
+            throw new OAuthProxyError('invalid_request', 'code_challenge_method required when code_challenge is present');
+        }
+        const transaction = await this._internal.createTransaction(params);
+        const ttl = this._internal.config.transactionTtl || DEFAULT_TRANSACTION_TTL;
+        await this.redis.set(`${TX_PREFIX}${transaction.id}`, serialize(transaction), 'EX', ttl);
+        return this._internal.redirectToUpstream(transaction);
+    }
+    async handleCallback(request) {
+        const url = new URL(request.url);
+        const code = url.searchParams.get('code');
+        const state = url.searchParams.get('state');
+        const error = url.searchParams.get('error');
+        if (error) {
+            throw new OAuthProxyError(error, url.searchParams.get('error_description') || undefined);
+        }
+        if (!code || !state) {
+            throw new OAuthProxyError('invalid_request', 'Missing code or state parameter');
+        }
+        const txJson = await this.redis.get(`${TX_PREFIX}${state}`);
+        if (!txJson) {
+            throw new OAuthProxyError('invalid_request', 'Invalid or expired state');
+        }
+        const transaction = deserialize(txJson);
+        // Defense-in-depth: reject if the transaction's stored callback URL is no
+        // longer registered. Guards against DCR revocation mid-flow and any path
+        // that could have persisted an unvalidated URI.
+        if (!(await this.isClientRegistered(transaction.clientCallbackUrl))) {
+            await this.redis.del(`${TX_PREFIX}${state}`);
+            throw new OAuthProxyError('invalid_request', 'Transaction callback URL is not registered');
+        }
+        const upstreamTokens = await this._internal.exchangeUpstreamCode(code, transaction);
+        // generateAuthorizationCode writes to the in-memory clientCodes Map.
+        // We read from it, persist to Redis, then clean up the Map entry.
+        const clientCode = this._internal.generateAuthorizationCode(transaction, upstreamTokens);
+        const codeData = this._internal.clientCodes.get(clientCode);
+        if (codeData) {
+            const codeTtl = this._internal.config.authorizationCodeTtl || DEFAULT_CODE_TTL;
+            await this.redis.set(`${CODE_PREFIX}${clientCode}`, serialize(codeData), 'EX', codeTtl);
+            this._internal.clientCodes.delete(clientCode);
+        }
+        // Remove consumed transaction
+        await this.redis.del(`${TX_PREFIX}${state}`);
+        const redirectUrl = new URL(transaction.clientCallbackUrl);
+        redirectUrl.searchParams.set('code', clientCode);
+        redirectUrl.searchParams.set('state', transaction.state);
+        return new Response(null, {
+            headers: { Location: redirectUrl.toString() },
+            status: 302,
+        });
+    }
+    async exchangeAuthorizationCode(request) {
+        if (request.grant_type !== 'authorization_code') {
+            throw new OAuthProxyError('unsupported_grant_type', 'Only authorization_code grant type is supported');
+        }
+        // RFC 6749 §5.2 — reject unknown clients at token exchange too, so a
+        // stolen authorization code cannot be redeemed by an arbitrary caller.
+        // Ported from fastmcp v4 OAuthProxy.exchangeAuthorizationCode.
+        if (request.client_id !== this._internal.config.upstreamClientId) {
+            throw new OAuthProxyError('invalid_client', 'Unknown client_id');
+        }
+        // Atomically read-and-delete the code. The parent's in-memory `used` flag
+        // can't work across instances (two concurrent redemptions on different
+        // instances both see it valid); GETDEL makes the consume race-free.
+        const codeJson = await this.redis.getdel(`${CODE_PREFIX}${request.code}`);
+        if (!codeJson) {
+            throw new OAuthProxyError('invalid_grant', 'Invalid or expired authorization code');
+        }
+        const clientCode = deserialize(codeJson);
+        if (clientCode.clientId !== request.client_id) {
+            throw new OAuthProxyError('invalid_client', 'Client ID mismatch');
+        }
+        if (clientCode.codeChallenge && !request.code_verifier) {
+            throw new OAuthProxyError('invalid_request', 'code_verifier required for PKCE');
+        }
+        if (clientCode.codeChallenge && request.code_verifier) {
+            // Delegate PKCE validation to parent by placing code in Map temporarily.
+            // Redis key is already consumed by GETDEL above, so no additional del
+            // is needed in finally — only the local Map cleanup.
+            this._internal.clientCodes.set(request.code, clientCode);
+            try {
+                return await super.exchangeAuthorizationCode(request);
+            }
+            finally {
+                this._internal.clientCodes.delete(request.code);
+            }
+        }
+        const response = {
+            access_token: clientCode.upstreamTokens.accessToken,
+            expires_in: clientCode.upstreamTokens.expiresIn,
+            token_type: clientCode.upstreamTokens.tokenType,
+        };
+        if (clientCode.upstreamTokens.refreshToken) {
+            response.refresh_token = clientCode.upstreamTokens.refreshToken;
+        }
+        if (clientCode.upstreamTokens.scope?.length > 0) {
+            response.scope = clientCode.upstreamTokens.scope.join(' ');
+        }
+        return response;
+    }
+    destroy() {
+        super.destroy();
+    }
+}

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

@@ -0,0 +1,2 @@
+import type { RetryOptions } from '../@types/types.js';
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;

package/build/src/lib/retry.js

@@ -0,0 +1,19 @@
+export async function retryWithBackoff(fn, options) {
+    const { maxRetries, baseDelayMs, shouldRetry } = options;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt === maxRetries)
+                break;
+            if (shouldRetry && !shouldRetry(lastError))
+                break;
+            const delay = baseDelayMs * Math.pow(2, attempt) * (0.5 + Math.random() * 0.5);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+}

package/build/src/lib/schema-fields.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+/**
+ * Build the schema for an optional profile field. The NUL refinement protects
+ * the session-key separator used in agent-client.ts — a profile name
+ * containing NUL could otherwise collide with another key.
+ *
+ * Dependency-clean (zod only) so it can be shared by the server tools and the
+ * published `@browserless.io/mcp/schemas` surface without pulling in fastmcp.
+ */
+export declare function profileField(whenLoaded: string, extra?: string): z.ZodOptional<z.ZodString>;

package/build/src/lib/schema-fields.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+// NUL is the session-key separator (KEY_SEP) in agent-client.ts. Computed via
+// fromCharCode so the literal control character never appears in source.
+const NUL = String.fromCharCode(0);
+/**
+ * Build the schema for an optional profile field. The NUL refinement protects
+ * the session-key separator used in agent-client.ts — a profile name
+ * containing NUL could otherwise collide with another key.
+ *
+ * Dependency-clean (zod only) so it can be shared by the server tools and the
+ * published `@browserless.io/mcp/schemas` surface without pulling in fastmcp.
+ */
+export function profileField(whenLoaded, extra = '') {
+    const description = `Optional name of an authentication profile to hydrate into the browser ${whenLoaded}. ` +
+        "The profile's cookies, localStorage, and IndexedDB are restored into the session before the request runs. " +
+        'The profile must already exist for the API token in use — create one with Browserless.saveProfile in a live agent session first.' +
+        extra;
+    return z
+        .string()
+        .trim()
+        .min(1)
+        .refine((v) => !v.includes(NUL), {
+        message: 'profile must not contain NUL characters',
+    })
+        .optional()
+        .describe(description);
+}

package/build/src/lib/supabase-token-patch.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Patch `globalThis.fetch` to extend `expires_in` on Supabase OAuth token
+ * responses so clients don't thrash refresh against the ~60s default. Global
+ * because FastMCP's OAuthProxy has no fetch hook; matched origin/path-exact.
+ */
+export declare function installSupabaseTokenTtlPatch(supabaseUrl: string, ttlSeconds: number): void;

package/build/src/lib/supabase-token-patch.js

@@ -0,0 +1,33 @@
+/**
+ * Patch `globalThis.fetch` to extend `expires_in` on Supabase OAuth token
+ * responses so clients don't thrash refresh against the ~60s default. Global
+ * because FastMCP's OAuthProxy has no fetch hook; matched origin/path-exact.
+ */
+export function installSupabaseTokenTtlPatch(supabaseUrl, ttlSeconds) {
+    const supabaseOrigin = new URL(supabaseUrl).origin;
+    const TOKEN_PATHNAME = '/auth/v1/oauth/token';
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async (...args) => {
+        const response = await originalFetch(...args);
+        const url = typeof args[0] === 'string'
+            ? args[0]
+            : args[0] instanceof URL
+                ? args[0].toString()
+                : args[0].url;
+        const reqUrl = new URL(url);
+        if (!response.ok ||
+            reqUrl.origin !== supabaseOrigin ||
+            reqUrl.pathname !== TOKEN_PATHNAME) {
+            return response;
+        }
+        const body = (await response.json());
+        if (typeof body.expires_in === 'number' && body.expires_in < ttlSeconds) {
+            body.expires_in = ttlSeconds;
+        }
+        return new Response(JSON.stringify(body), {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        });
+    };
+}

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

@@ -0,0 +1,27 @@
+import type { SupabaseJwtPayload } from '../@types/types.js';
+/**
+ * 64-bit truncation of SHA-256 — wide enough to make accidental collisions
+ * astronomically unlikely, unlike a 32-bit djb2. Used to fingerprint tokens,
+ * proxy configs, and other identifiers we want stable but unguessable.
+ */
+export declare function hashToken(input: string): string;
+/**
+ * djb2 string hash. Matches the Browserless backend's session ID hashing —
+ * kept compatible so analytics `user_id` values stay consistent across services.
+ */
+export declare function djb2(str: string): number;
+/** Content-Types that should be treated as text (not base64-encoded). */
+export declare const TEXT_CONTENT_TYPES: string[];
+export declare function isTextContentType(ct: string): boolean;
+/** Strip undefined entries so JSON.stringify omits them from the wire body. */
+export declare function compact<T extends Record<string, unknown>>(obj: T): Partial<T>;
+/** Split a comma-separated env-var value into a trimmed, non-empty list. */
+export declare function parseCsv(raw: string | undefined): string[];
+/** Decode the payload segment of a JWT. Throws on malformed input. */
+export declare function decodeJwtPayload(jwt: string): SupabaseJwtPayload;
+/**
+ * Reject server bodies that are obviously not a real message — empty, just
+ * whitespace, or a literal `null`/`undefined` from a misbehaving JSON layer.
+ * Callers usually fall back to a canned message when this returns false.
+ */
+export declare function isMeaningfulBody(s: string): boolean;

package/build/src/lib/utils.js

@@ -0,0 +1,67 @@
+import { createHash } from 'node:crypto';
+/**
+ * 64-bit truncation of SHA-256 — wide enough to make accidental collisions
+ * astronomically unlikely, unlike a 32-bit djb2. Used to fingerprint tokens,
+ * proxy configs, and other identifiers we want stable but unguessable.
+ */
+export function hashToken(input) {
+    return createHash('sha256').update(input).digest('hex').slice(0, 16);
+}
+/**
+ * djb2 string hash. Matches the Browserless backend's session ID hashing —
+ * kept compatible so analytics `user_id` values stay consistent across services.
+ */
+export function djb2(str) {
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+        hash = (hash * 33) ^ str.charCodeAt(i);
+    }
+    return hash >>> 0;
+}
+/** Content-Types that should be treated as text (not base64-encoded). */
+export const TEXT_CONTENT_TYPES = [
+    'text/',
+    'application/json',
+    'application/javascript',
+    'application/xml',
+    'application/xhtml+xml',
+    'application/ld+json',
+];
+export function isTextContentType(ct) {
+    const lower = ct.toLowerCase();
+    return TEXT_CONTENT_TYPES.some((prefix) => lower.includes(prefix));
+}
+/** Strip undefined entries so JSON.stringify omits them from the wire body. */
+export function compact(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+/** Split a comma-separated env-var value into a trimmed, non-empty list. */
+export function parseCsv(raw) {
+    return (raw ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/** Decode the payload segment of a JWT. Throws on malformed input. */
+export function decodeJwtPayload(jwt) {
+    const parts = jwt.split('.');
+    if (parts.length !== 3) {
+        throw new Error('Invalid JWT format');
+    }
+    const payload = Buffer.from(parts[1], 'base64url').toString('utf-8');
+    return JSON.parse(payload);
+}
+/**
+ * Reject server bodies that are obviously not a real message — empty, just
+ * whitespace, or a literal `null`/`undefined` from a misbehaving JSON layer.
+ * Callers usually fall back to a canned message when this returns false.
+ */
+export function isMeaningfulBody(s) {
+    const normalized = s.trim();
+    return normalized.length > 0 && !/^(?:null|undefined)$/i.test(normalized);
+}

package/build/src/prompts/extract-content.d.ts

@@ -0,0 +1,2 @@
+import type { FastMCP } from 'fastmcp';
+export declare function registerExtractContentPrompt(server: FastMCP): void;

package/build/src/prompts/extract-content.js

@@ -0,0 +1,33 @@
+export function registerExtractContentPrompt(server) {
+    server.addPrompt({
+        name: 'extract-content',
+        description: 'Extract specific information from a webpage using the smart scraper',
+        arguments: [
+            {
+                name: 'url',
+                description: 'The URL to extract content from',
+                required: true,
+            },
+            {
+                name: 'instructions',
+                description: 'What information to extract from the page',
+                required: true,
+            },
+        ],
+        load: async ({ url, instructions }) => {
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Use the browserless_smartscraper tool to scrape: ${url}\n` +
+                                `Then extract the following information: ${instructions}\n` +
+                                'Return the extracted information in a structured format.',
+                        },
+                    },
+                ],
+            };
+        },
+    });
+}

package/build/src/prompts/scrape-url.d.ts

@@ -0,0 +1,2 @@
+import type { FastMCP } from 'fastmcp';
+export declare function registerScrapeUrlPrompt(server: FastMCP): void;

package/build/src/prompts/scrape-url.js

@@ -0,0 +1,36 @@
+export function registerScrapeUrlPrompt(server) {
+    server.addPrompt({
+        name: 'scrape-url',
+        description: 'Scrape a webpage and return its content as markdown with metadata',
+        arguments: [
+            {
+                name: 'url',
+                description: 'The URL to scrape',
+                required: true,
+            },
+            {
+                name: 'includeScreenshot',
+                description: 'Whether to capture a screenshot (true/false)',
+                required: false,
+            },
+        ],
+        load: async ({ url, includeScreenshot }) => {
+            const formats = includeScreenshot === 'true'
+                ? '["markdown", "screenshot"]'
+                : '["markdown"]';
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Use the browserless_smartscraper tool to scrape the following URL: ${url}\n` +
+                                `Options: formats=${formats}\n` +
+                                'Return the markdown content and summarize the key information found on the page.',
+                        },
+                    },
+                ],
+            };
+        },
+    });
+}

package/build/src/resources/api-docs.d.ts

@@ -0,0 +1,3 @@
+import type { FastMCP } from 'fastmcp';
+import type { McpConfig } from '../@types/types.js';
+export declare function registerApiDocsResource(server: FastMCP, config: McpConfig): void;