@browserless.io/mcp 1.6.0

package/build/src/index.js

@@ -0,0 +1,153 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FastMCP, OAuthProvider } from 'fastmcp';
+import { OAuthProxy } from 'fastmcp/auth';
+import { getConfig } from './config.js';
+import { registerSmartScraperTool } from './tools/smartscraper.js';
+import { registerFunctionTool } from './tools/function.js';
+import { registerDownloadTool } from './tools/download.js';
+import { registerExportTool } from './tools/export.js';
+import { registerAgentTools } from './tools/agent.js';
+import { registerSearchTool } from './tools/search.js';
+import { registerMapTool } from './tools/map.js';
+import { registerCrawlTool } from './tools/crawl.js';
+import { registerPerformanceTool } from './tools/performance.js';
+import { registerApiDocsResource } from './resources/api-docs.js';
+import { registerStatusResource } from './resources/status.js';
+import { registerScrapeUrlPrompt } from './prompts/scrape-url.js';
+import { registerExtractContentPrompt } from './prompts/extract-content.js';
+import { AnalyticsHelper } from './lib/analytics.js';
+import { resolveApiKey, installSupabaseTokenTtlPatch, } from './lib/account-resolver.js';
+import { BoundedEventStore } from './lib/bounded-event-store.js';
+import { RedisOAuthProxy } from './lib/redis-oauth-proxy.js';
+import { Redis } from 'ioredis';
+const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json'), 'utf-8'));
+const config = getConfig();
+// Override Supabase's short-lived (~60s) OAuth token TTL so MCP clients don't
+// thrash refresh. Narrowly scoped to the Supabase token endpoint; see
+// installSupabaseTokenTtlPatch in account-resolver.ts for the full rationale.
+if (config.oauthEnabled && config.supabaseUrl) {
+    installSupabaseTokenTtlPatch(config.supabaseUrl, 3600);
+}
+const analytics = new AnalyticsHelper(config.analyticsEnabled, config.sqsQueueUrl, config.sqsRegion);
+// Passthrough OAuth provider: disables FastMCP's token-swap mode so the MCP client
+// receives the raw Supabase JWT directly.
+const redisClient = config.redisUrl ? new Redis(config.redisUrl) : undefined;
+if (redisClient) {
+    redisClient.on('error', (err) => console.error('[browserless-mcp] Redis error:', err.message));
+    // Redis is only configured for the hosted httpStream deployment (REDIS_URL is
+    // not set in stdio mode), so writing the "connected" line to stdout doesn't
+    // interfere with MCP-over-stdio protocol framing.
+    redisClient.on('ready', () => console.log('[browserless-mcp] Redis connected for OAuth state storage'));
+}
+class PassthroughOAuthProvider extends OAuthProvider {
+    createProxy() {
+        const proxyConfig = {
+            allowedRedirectUriPatterns: config.oauthAllowedRedirectUriPatterns,
+            baseUrl: this.config.baseUrl,
+            consentRequired: false,
+            enableTokenSwap: false,
+            scopes: this.config.scopes ?? [],
+            upstreamAuthorizationEndpoint: this.genericConfig.authorizationEndpoint,
+            upstreamClientId: this.config.clientId,
+            upstreamClientSecret: this.config.clientSecret,
+            upstreamTokenEndpoint: this.genericConfig.tokenEndpoint,
+            upstreamTokenEndpointAuthMethod: this.genericConfig.tokenEndpointAuthMethod ?? 'client_secret_basic',
+        };
+        if (redisClient) {
+            return new RedisOAuthProxy(proxyConfig, redisClient);
+        }
+        return new OAuthProxy(proxyConfig);
+    }
+}
+const oauthProvider = config.oauthEnabled && config.transport === 'httpStream'
+    ? new PassthroughOAuthProvider({
+        baseUrl: config.mcpBaseUrl,
+        clientId: config.supabaseOAuthClientId,
+        clientSecret: config.supabaseOAuthClientSecret,
+        authorizationEndpoint: `${config.supabaseUrl}/auth/v1/oauth/authorize`,
+        tokenEndpoint: `${config.supabaseUrl}/auth/v1/oauth/token`,
+        scopes: ['email'],
+        consentRequired: false,
+    })
+    : undefined;
+// Hybrid authenticate, in order: (1) Authorization header with a plain API
+// key or (2) ?token= query param → direct token session; (3) Authorization
+// header with a Supabase JWT → resolve the Browserless API key via PostgREST.
+const hybridAuthenticate = config.transport === 'httpStream'
+    ? async (request) => {
+        const params = new URLSearchParams(request.url?.split('?')[1] ?? '');
+        const authHeader = request.headers.authorization;
+        const headerToken = authHeader?.startsWith('Bearer ')
+            ? authHeader.slice(7)
+            : authHeader;
+        const apiUrl = request.headers['x-browserless-api-url'] ??
+            params.get('browserlessUrl') ??
+            config.browserlessApiUrl;
+        // JWTs have 3 dot-separated base64url segments; plain API keys do not.
+        const isJwt = headerToken ? headerToken.split('.').length === 3 : false;
+        // 1. Authorization header with plain API key
+        if (headerToken && !isJwt) {
+            return { token: headerToken, apiUrl };
+        }
+        // 2. ?token= query param
+        const directToken = params.get('token') || undefined;
+        if (directToken) {
+            return { token: directToken, apiUrl };
+        }
+        // 3. Authorization header with JWT → decode Supabase token directly
+        if (isJwt && headerToken) {
+            const { apiKey } = await resolveApiKey(config.supabaseUrl, config.supabaseServiceRoleKey, headerToken);
+            return { token: apiKey, apiUrl };
+        }
+        throw new Error('No Browserless API token provided. ' +
+            'Pass it as Authorization: Bearer <token> header, ' +
+            '?token= query parameter, or authenticate via OAuth.');
+    }
+    : undefined;
+const server = new FastMCP({
+    name: 'browserless-mcp',
+    version: pkg.version,
+    ...(oauthProvider ? { auth: oauthProvider } : {}),
+    authenticate: hybridAuthenticate,
+});
+registerSmartScraperTool(server, config, analytics);
+registerFunctionTool(server, config, analytics);
+registerDownloadTool(server, config, analytics);
+registerExportTool(server, config, analytics);
+registerAgentTools(server, config, analytics);
+registerSearchTool(server, config, analytics);
+registerMapTool(server, config, analytics);
+registerCrawlTool(server, config, analytics);
+registerPerformanceTool(server, config, analytics);
+registerApiDocsResource(server, config);
+registerStatusResource(server, config);
+registerScrapeUrlPrompt(server);
+registerExtractContentPrompt(server);
+server.on('connect', (event) => {
+    const id = event.session.sessionId ?? 'stdio';
+    console.error(`[browserless-mcp] Client connected: ${id}`);
+});
+server.on('disconnect', (event) => {
+    const id = event.session.sessionId ?? 'stdio';
+    console.error(`[browserless-mcp] Client disconnected: ${id}`);
+});
+if (config.transport === 'httpStream') {
+    server.start({
+        transportType: 'httpStream',
+        httpStream: {
+            port: config.port,
+            host: '0.0.0.0',
+            eventStore: new BoundedEventStore(10_000),
+            stateless: false,
+        },
+    });
+    console.error(`[browserless-mcp] HTTP Streamable server listening on port ${config.port}`);
+}
+else {
+    server.start({
+        transportType: 'stdio',
+    });
+}
+export { server };

package/build/src/lib/account-resolver.d.ts

@@ -0,0 +1,17 @@
+interface ResolvedAccount {
+    apiKey: string;
+    email: string;
+}
+/**
+ * Resolves a Browserless API key from a Supabase access token (JWT)
+ * by extracting app_metadata.accountId and querying Supabase PostgREST.
+ */
+export declare function resolveApiKey(supabaseUrl: string, serviceRoleKey: string, accessToken: string): Promise<ResolvedAccount>;
+export declare function clearResolverCache(): void;
+/**
+ * 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;
+export {};

package/build/src/lib/account-resolver.js

@@ -0,0 +1,78 @@
+import { ResponseCache } from './cache.js';
+import { decodeJwtPayload } from './utils.js';
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const cache = new ResponseCache(CACHE_TTL_MS);
+/**
+ * Resolves a Browserless API key from a Supabase access token (JWT)
+ * by extracting app_metadata.accountId and querying Supabase PostgREST.
+ */
+export async function resolveApiKey(supabaseUrl, serviceRoleKey, accessToken) {
+    const payload = decodeJwtPayload(accessToken);
+    const accountId = payload.app_metadata?.accountId;
+    if (!accountId) {
+        throw new Error('Supabase JWT does not contain app_metadata.accountId. ' +
+            'The user may not have a Browserless account.');
+    }
+    const cached = cache.get(`account:${accountId}`);
+    if (cached) {
+        return cached;
+    }
+    const url = `${supabaseUrl}/rest/v1/accounts?account_id=eq.${encodeURIComponent(accountId)}&select=api_key,email`;
+    const response = await fetch(url, {
+        headers: {
+            apikey: serviceRoleKey,
+            Authorization: `Bearer ${serviceRoleKey}`,
+            Accept: 'application/json',
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Supabase REST API returned ${response.status}: ${response.statusText}`);
+    }
+    const rows = (await response.json());
+    const account = rows[0];
+    if (!account?.api_key || !account?.email) {
+        throw new Error('Account not found or missing api_key/email.');
+    }
+    const resolved = {
+        apiKey: account.api_key,
+        email: account.email,
+    };
+    cache.set(`account:${accountId}`, resolved);
+    return resolved;
+}
+export function clearResolverCache() {
+    cache.clear();
+}
+/**
+ * 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/agent-client.d.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import type { ActiveSession, AgentResponse, ProxyOptions } from '../@types/types.js';
+export type { ProxyOptions, ActiveSession, AgentMessage, AgentResponse, AgentError, } from '../@types/types.js';
+export declare const ProxyOptionsSchema: z.ZodObject<{
+    proxy: z.ZodOptional<z.ZodEnum<{
+        residential: "residential";
+    }>>;
+    proxyCountry: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    proxyState: z.ZodOptional<z.ZodString>;
+    proxyCity: z.ZodOptional<z.ZodString>;
+    proxySticky: z.ZodOptional<z.ZodBoolean>;
+    proxyLocaleMatch: z.ZodOptional<z.ZodBoolean>;
+    proxyPreset: z.ZodOptional<z.ZodString>;
+    externalProxyServer: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const PROXY_FIELDS: Array<keyof ProxyOptions>;
+/**
+ * Thrown when the agent WebSocket upgrade is rejected with a non-101 HTTP
+ * response. Carries the status code and body so the tool layer can render a
+ * status-specific UserError.
+ */
+export declare class UpgradeError extends Error {
+    readonly statusCode: number;
+    readonly statusMessage: string;
+    readonly body: string;
+    constructor(statusCode: number, statusMessage: string, body: string);
+}
+/**
+ * UpgradeError specialization for the profile-not-found case (404 on the WS
+ * upgrade when `?profile=` was supplied). Mirrors api-client.ts so all tools
+ * surface profile errors through the same UserError pattern.
+ */
+export declare class ProfileNotFoundError extends UpgradeError {
+    readonly profile: string;
+    constructor(profile: string, statusMessage: string, body: string);
+}
+export declare const isRetryableUpgradeError: (err: unknown) => boolean;
+/**
+ * Build a stable, credential-free key segment for a proxy config — identical
+ * configs fingerprint the same regardless of key order. `externalProxyServer`
+ * is SHA-256 hashed so credentials never land in the eviction log.
+ */
+export declare const proxyFingerprint: (proxy?: ProxyOptions) => string;
+/**
+ * Build the WebSocket URL for `/chromium/agent`: normalize trailing slashes,
+ * swap http(s)→ws(s), and append `token` plus proxy params. Boolean proxy
+ * flags follow the API's presence-only contract (set only when truthy).
+ */
+export declare const buildAgentWsUrl: (apiUrl: string, token: string, proxy?: ProxyOptions, profile?: string) => string;
+export declare const getOrCreateSession: (mcpSessionId: string | undefined, apiUrl: string, token: string, proxy?: ProxyOptions, profile?: string) => Promise<ActiveSession>;
+export declare const send: (session: ActiveSession, method: string, params?: Record<string, unknown>, timeoutMs?: number) => Promise<AgentResponse>;
+export declare const closeSession: (mcpSessionId: string | undefined, token: string, proxy?: ProxyOptions, profile?: string) => void;
+/**
+ * Force-destroy a session after a browser crash or unrecoverable state, so
+ * the next call reconnects fresh. Unlike `closeSession`, it also drops any
+ * in-flight connect for the key so a concurrent caller can't reuse a dead WS.
+ */
+export declare const destroySession: (mcpSessionId: string | undefined, token: string, proxy?: ProxyOptions, profile?: string) => void;