Browserless MCP Server

Instructions

Implementation Reference

• src/client.ts:233-270 (handler)

  Core implementation of createWebSocketConnection: constructs WS endpoint based on options, tests connection with WebSocket, returns endpoint and session ID or error.

  async createWebSocketConnection(options: WebSocketOptions = { browser: 'chromium', library: 'puppeteer' }): Promise<BrowserlessResponse<WebSocketResponse>> {
    try {
      const { browser, library } = options;
      
      let endpoint: string;
      if (library === 'puppeteer') {
        endpoint = `ws://${this.config.host}:${this.config.port}?token=${this.config.token}`;
      } else {
        // Playwright
        endpoint = `ws://${this.config.host}:${this.config.port}/${browser}/playwright?token=${this.config.token}`;
      }
  
      // Test the connection
      const ws = new WebSocket(endpoint);
      
      return new Promise((resolve) => {
        ws.on('open', () => {
          ws.close();
          resolve({
            success: true,
            data: {
              browserWSEndpoint: endpoint,
              sessionId: `session-${Date.now()}`,
            },
          });
        });
  
        ws.on('error', (error) => {
          resolve({
            success: false,
            error: `WebSocket connection failed: ${error.message}`,
          });
        });
      });
    } catch (error) {
      return this.handleError(error);
    }
  }

• src/index.ts:219-242 (registration)

  Registers the tool in the MCP server's tool list with name, description, and input schema.

    name: 'create_websocket_connection',
    description: 'Create WebSocket connection for Puppeteer/Playwright',
    inputSchema: {
      type: 'object',
      properties: {
        browser: { type: 'string', enum: ['chromium', 'firefox', 'webkit'] },
        library: { type: 'string', enum: ['puppeteer', 'playwright'] },
        stealth: { type: 'boolean' },
        blockAds: { type: 'boolean' },
        viewport: {
          type: 'object',
          properties: {
            width: { type: 'number' },
            height: { type: 'number' },
            deviceScaleFactor: { type: 'number' },
            isMobile: { type: 'boolean' },
            hasTouch: { type: 'boolean' },
          },
        },
        userAgent: { type: 'string' },
        extraHTTPHeaders: { type: 'object' },
      },
    },
  },

• src/index.ts:511-530 (handler)

  MCP server handler for the tool: delegates to BrowserlessClient.createWebSocketConnection and formats response.

  case 'create_websocket_connection': {
    if (!args) throw new Error('Arguments are required');
    const result = await this.client!.createWebSocketConnection(args as any);
    if (result.success && result.data) {
      return {
        content: [
          {
            type: 'text',
            text: `WebSocket connection created successfully. Session ID: ${result.data.sessionId}`,
          },
          {
            type: 'text',
            text: `Browser WebSocket endpoint: ${result.data.browserWSEndpoint}`,
          },
        ],
      };
    } else {
      throw new Error(result.error || 'Failed to create WebSocket connection');
    }
  }

• src/types.ts:234-244 (schema)

  Zod schema and TypeScript type definition for WebSocketOptions input.

  export const WebSocketOptionsSchema = z.object({
    browser: z.enum(['chromium', 'firefox', 'webkit']).default('chromium'),
    library: z.enum(['puppeteer', 'playwright']).default('puppeteer'),
    stealth: z.boolean().optional(),
    blockAds: z.boolean().optional(),
    viewport: ViewportSchema.optional(),
    userAgent: z.string().optional(),
    extraHTTPHeaders: z.record(z.string()).optional(),
  });
  
  export type WebSocketOptions = z.infer<typeof WebSocketOptionsSchema>;

• src/types.ts:310-313 (schema)

  TypeScript interface for the WebSocketResponse output.

  export interface WebSocketResponse {
    browserWSEndpoint: string;
    sessionId: string;
  }