# Browser AI Debate MCP

A Model Context Protocol (MCP) server that runs a structured multi-round debate between ChatGPT Web and Gemini Web by operating both in Chrome via CDP (Chrome DevTools Protocol). It uses browser automation rather than provider APIs.

## What It Does

1. Opens ChatGPT Web and Gemini Web in the same Chrome session
2. Sends the same question to both models independently
3. Makes each model critique the other response
4. Requests revised answers
5. Produces a final conclusion and an independent audit
6. Returns structured results with confidence, rationale, risks, and provider status

## Important

- Requires logged-in ChatGPT and Gemini browser sessions
- Uses browser UI automation, so provider UI changes can break selectors
- Does not require OpenAI or Gemini API keys
- Stores the dedicated profile only in `.browser-ai-profile/`, which is gitignored
- Does not terminate a user-owned Chrome process

## Prerequisites

- Node.js 20 or newer
- Google Chrome desktop

## Setup

```bash
git clone https://github.com/kaenozu/browser-ai-debate-mcp.git
cd browser-ai-debate-mcp
npm install
npm run build
```

## Chrome Preparation

### Auto-launch

When `BROWSER_AI_CDP_URL` is not set, the server attempts to launch a dedicated Chrome profile automatically.

```bash
npm start
```

### Connect to an existing logged-in Chrome

1. Log into ChatGPT and Gemini in Chrome.
2. Enable remote debugging at `chrome://inspect/#remote-debugging`.
3. Configure the CDP endpoint before starting the server.

Windows Command Prompt:

```cmd
set BROWSER_AI_CDP_URL=http://127.0.0.1:9222
npm start
```

PowerShell:

```powershell
$env:BROWSER_AI_CDP_URL = "http://127.0.0.1:9222"
npm start
```

### Pre-launch a dedicated profile

```bash
npm run login
```

Log into both services, close Chrome, then run:

```bash
npm run chrome:debug
```

Start the MCP server in another terminal:

```bash
npm start
```

## MCP Client Configuration

The public server identifier remains `browser-ai-debate`, and the public tool name remains `browser_ai_debate` for compatibility.

Auto-launch configuration:

```json
{
  "mcpServers": {
    "browser-ai-debate": {
      "command": "node",
      "args": ["dist/index.js"]
    }
  }
}
```

Existing Chrome via CDP:

```json
{
  "mcpServers": {
    "browser-ai-debate": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "BROWSER_AI_CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}
```

## `browser_ai_debate` Tool

Example input:

```json
{
  "question": "Why is not swallowing exceptions important in TypeScript?",
  "context": "We have 70 source files and 23 try-catch blocks that swallow errors",
  "decisionCriteria": ["reliability", "debuggability", "user experience", "maintainability"],
  "maxRounds": 3,
  "timeoutMs": 900000
}
```

| Field | Required | Default | Description |
|---|---|---|---|
| `question` | Yes | — | Debate question, up to 100,000 characters |
| `context` | No | — | Additional context |
| `decisionCriteria` | No | — | Evaluation criteria |
| `maxRounds` | No | 3 | Maximum 1–5 rounds |
| `timeoutMs` | No | 900000 | Total timeout, minimum 30,000 ms |
| `providerTimeoutMs` | No | derived | Per-provider timeout |
| `includeTranscript` | No | true | Include the transcript |
| `finalizer` | No | `chatgpt` | Provider that produces the final decision |

## Timeout and Partial Results

- `timeoutMs` covers queue wait time and all debate phases
- Provider failures are returned explicitly
- If only one provider completes, the result is marked `partial`
- Partial output is never presented as a complete result

## Security Notes

- Browser profiles and credentials are not committed to Git
- Conversation content is not sent to an additional external service by this MCP server
- User-owned Chrome is not terminated by the server
- Dedicated Chrome processes started by the server are cleaned up on shutdown

## Troubleshooting

### CDP connection fails

1. Confirm Chrome remote debugging is enabled.
2. Confirm `BROWSER_AI_CDP_URL` points to the active endpoint.
3. Check that port 9222 is available and reachable.
4. Run `npm run chrome:debug` to start the dedicated profile explicitly.
5. Open `http://127.0.0.1:9222/json/version` locally to confirm the endpoint responds.

### `AUTH_REQUIRED`

The stored browser session has expired or is not logged into one of the providers.

1. Run `npm run login`.
2. Log into ChatGPT and Gemini.
3. Close the profile window and retry.

### Provider UI or DOM selectors changed

Authentication succeeds, but the provider page no longer matches the expected UI.

1. Retry with a fresh dedicated profile.
2. Confirm the provider page works manually.
3. Report the provider, page state, and observed error without including credentials or private conversation content.
4. Update only the provider selector module (`src/providers/<provider>/selectors.ts`) and its sanitized fixture test (`tests/provider-selector-smoke.test.ts`). Keep fixtures free of real conversation content.
5. Run `npm test` and `npm run check` before opening a PR.

The normal CI suite runs the sanitized DOM fixture and fallback-order tests. The opt-in `.github/workflows/live-smoke.yml` is manual-only, checks out `master`, requires the protected `provider-live-smoke` environment, and reads only `BROWSER_AI_CDP_URL` from secrets. It must never be enabled for pull requests or execute untrusted PR code. Live smoke requires logged-in ChatGPT and Gemini tabs in the operator's CDP session; those checks are intentionally an external gate.

### Auto-launch cannot find Chrome

Confirm Chrome is installed in a standard location, or use an explicit CDP connection with `BROWSER_AI_CDP_URL`.

## Windows Quick Start

```cmd
start.bat
```

Manual start:

```cmd
npm run build
npm start
```

Interactive MCP inspection:

```cmd
npm run inspector
```

## OpenCode MCP Registration

Existing logged-in Chrome:

```json
{
  "mcpServers": {
    "browser-ai-debate": {
      "command": "cmd",
      "args": ["/c", "node", "C:/path/to/browser-ai-debate-mcp/dist/index.js"],
      "env": {
        "BROWSER_AI_CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}
```

For dedicated auto-launch mode, omit the `env` block.