# Browser MCP Server

A Model Context Protocol (MCP) server that provides browser automation capabilities, specifically for capturing console output from web pages.

## Features

- **browser-console**: Navigate to a URL and capture console output from the browser
- **browser-server-console**: Spawn a local Express static server for a directory and capture console output from the served content
- Built with Puppeteer for reliable browser automation
- Supports custom timeouts and wait conditions
- Static file serving for local development and testing
- Automatic port detection (finds next available port if requested port is busy)

## Installation

```bash
npm install
```

## Usage

### As an MCP Server

This server is designed to be used with MCP-compatible clients. Add it to your MCP client configuration:

```json
{
  "mcpServers": {
    "browser-mcp-server": {
      "command": "npx",
      "args": ["browser-mcp-server"]
    }
  }
}
```

### Direct Usage

You can also run the server directly:

```bash
npm start
```

Or in development mode with auto-reload:

```bash
npm run dev
```

## Tools

### browser-console

Navigate to a URL and capture console output from the browser.

**Parameters:**
- `url` (required): The URL to navigate to
- `timeout` (optional): Timeout in milliseconds (default: 30000)
- `waitFor` (optional): CSS selector to wait for before capturing console
- `commands` (optional): Browser commands to execute (e.g., "click .button wait 2s")
- `stream` (optional): Whether to stream output in real-time (default: true)

**Commands syntax:**
- `wait <time>`: Wait for specified time (e.g., "5s", "1000ms")
- `click <selector>`: Click on element matching CSS selector

**Example:**
```json
{
  "name": "browser-console",
  "arguments": {
    "url": "https://example.com",
    "timeout": 10000,
    "waitFor": "#main-content",
    "commands": "click .load-more-btn wait 2s click .submit",
    "stream": true
  }
}
```

### browser-server-console

Spawn an Express static server for a directory and capture console output from the served content.

**Parameters:**
- `directory` (required): The directory to serve statically
- `port` (optional): Preferred port to run the server on (will automatically find next available if busy, default: 3000)
- `path` (optional): Path to navigate to after starting server (default: "/")
- `timeout` (optional): Timeout in milliseconds (default: 30000)
- `waitFor` (optional): CSS selector to wait for before capturing console
- `commands` (optional): Browser commands to execute (e.g., "click .button wait 2s")
- `stream` (optional): Whether to stream output in real-time (default: true)

**Commands syntax:**
- `wait <time>`: Wait for specified time (e.g., "5s", "1000ms")
- `click <selector>`: Click on element matching CSS selector

**Example:**
```json
{
  "name": "browser-server-console",
  "arguments": {
    "directory": "./public",
    "port": 3001,
    "path": "/index.html",
    "timeout": 10000,
    "waitFor": "#app",
    "commands": "click #start-btn wait 3s",
    "stream": false
  }
}
```

## Implementation Status

- [x] Basic MCP server structure
- [x] Tool schema definition
- [x] Browser navigation with Puppeteer
- [x] Console output capture
- [x] Real-time console message streaming
- [x] Browser command execution (click, wait)
- [x] Error handling for browser issues
- [x] Support for custom timeouts and wait conditions
- [x] True streaming output (currently batched)
- [ ] Support for different browser types

## Development

The main server implementation is in `src/index.js`. The current implementation includes:

- MCP server setup with proper tool registration
- Input validation for the browser-console tool
- Error handling and graceful shutdown
- Placeholder implementation for browser functionality

## Dependencies

- `@modelcontextprotocol/sdk`: MCP SDK for server implementation
- `puppeteer`: Browser automation library for console capture
- `express`: Web framework for static file serving
- `@types/node`: TypeScript definitions for Node.js

## License

MIT