Concurrent Browser MCP

Instructions

Implementation Reference

• src/tools.ts:21-60 (schema)

  Tool schema definition for 'browser_create_instance' including name, description, and detailed inputSchema with properties like browserType, headless, viewport, userAgent, metadata.

    name: 'browser_create_instance',
    description: 'Create a new browser instance',
    inputSchema: {
      type: 'object',
      properties: {
        browserType: {
          type: 'string',
          enum: ['chromium', 'firefox', 'webkit'],
          description: 'Browser type',
          default: 'chromium'
        },
        headless: {
          type: 'boolean',
          description: 'Whether to run in headless mode',
          default: true
        },
        viewport: {
          type: 'object',
          properties: {
            width: { type: 'number', default: 1280 },
            height: { type: 'number', default: 720 }
          },
          description: 'Viewport size'
        },
        userAgent: {
          type: 'string',
          description: 'User agent string'
        },
        metadata: {
          type: 'object',
          properties: {
            name: { type: 'string', description: 'Instance name' },
            description: { type: 'string', description: 'Instance description' },
            tags: { type: 'array', items: { type: 'string' }, description: 'Tags' }
          },
          description: 'Instance metadata'
        }
      }
    }
  },

• src/tools.ts:498-507 (handler)

  Handler case in BrowserTools.executeTools method that processes 'browser_create_instance' tool call, extracts arguments, and delegates to browserManager.createInstance.

  case 'browser_create_instance':
    return await this.browserManager.createInstance(
      {
        browserType: args.browserType || 'chromium',
        headless: args.headless ?? true,
        viewport: args.viewport || { width: 1280, height: 720 },
        userAgent: args.userAgent
      },
      args.metadata
    );

• src/browser-manager.ts:162-227 (handler)

  Core implementation of createInstance in BrowserManager: launches Playwright browser based on config, handles proxy configuration, creates context and page, generates UUID, stores instance.

  async createInstance(
    browserConfig?: Partial<BrowserConfig>,
    metadata?: BrowserInstance['metadata']
  ): Promise<ToolResult> {
    try {
      if (this.instances.size >= this.config.maxInstances) {
        return {
          success: false,
          error: `Maximum number of instances (${this.config.maxInstances}) reached`
        };
      }
  
      const config = { ...this.config.defaultBrowserConfig, ...browserConfig };
      const browser = await this.launchBrowser(config);
      
      const contextOptions: any = {
        viewport: config.viewport,
        ...config.contextOptions
      };
      if (config.userAgent) {
        contextOptions.userAgent = config.userAgent;
      }
      
      // Add proxy configuration to context
      const effectiveProxy = this.getEffectiveProxy(browserConfig);
      if (effectiveProxy) {
        contextOptions.proxy = { server: effectiveProxy };
      }
      
      const context = await browser.newContext(contextOptions);
  
      const page = await context.newPage();
      
      const instanceId = uuidv4();
      const instance: BrowserInstance = {
        id: instanceId,
        browser,
        context,
        page,
        createdAt: new Date(),
        lastUsed: new Date(),
        isActive: true,
        ...(metadata && { metadata })
      };
  
      this.instances.set(instanceId, instance);
  
      return {
        success: true,
        data: {
          instanceId,
          browserType: config.browserType,
          headless: config.headless,
          viewport: config.viewport,
          proxy: effectiveProxy,
          metadata
        },
        instanceId
      };
    } catch (error) {
      return {
        success: false,
        error: `Failed to create browser instance: ${error instanceof Error ? error.message : error}`
      };
    }
  }

• src/server.ts:40-45 (registration)

  MCP Server listTools request handler that returns the list of all tools (including browser_create_instance schema) from BrowserTools.getTools().

  this.server.setRequestHandler(ListToolsRequestSchema, async () => {
    const tools = this.browserTools.getTools();
    return {
      tools: tools,
    };
  });

• src/server.ts:48-75 (registration)

  MCP Server callTool request handler that routes tool execution to BrowserTools.executeTools based on tool name, formats success/error responses.

  this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
  
    try {
      const result = await this.browserTools.executeTools(name, args || {});
      
      if (result.success) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(result.data, null, 2),
            },
          ],
        };
      } else {
        throw new McpError(ErrorCode.InternalError, result.error || 'Tool execution failed');
      }
    } catch (error) {
      if (error instanceof McpError) {
        throw error;
      }
      throw new McpError(
        ErrorCode.InternalError,
        `Tool execution failed: ${error instanceof Error ? error.message : error}`
      );
    }
  });