browser-control 0.2.1

CLI that manages browsers and exposes them over CDP/BiDi for agent-driven development. Includes an optional MCP server.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

> **Note:** This document describes the legacy TypeScript implementation. The
> current Rust CLI is described in the project README and ADR-001. See
> `docs/adrs/archive/` for the original ADRs.

# Tech Stack Specification

## Runtime

- **Node.js** >= 18 (ESM modules, `"type": "module"`)
- **TypeScript** 5.7+ (compiled via `tsc`, no bundler)

## Dependencies

### Production

| Package | Version | Purpose |
|---------|---------|---------|
| `@modelcontextprotocol/sdk` | ^1.12.0 | MCP server implementation |

### Development

| Package | Version | Purpose |
|---------|---------|---------|
| `typescript` | ^5.7.0 | TypeScript compiler |
| `@types/node` | ^22.0.0 | Node.js type definitions |

## Project Structure

```
browser-control-mcp/
  cli.ts                     # Entry point, arg parsing, wrap subcommand, stdio transport
  coordinator-server.ts      # Core MCP server, coordinator tools, CDP proxy integration
  cdp-proxy.ts               # TCP reverse proxy for CDP connections
  state.ts                   # State file management (proxy port discovery)
  browser-launcher.ts        # Port allocation, browser spawn, lifecycle
  browser-detector.ts        # Cross-platform browser detection
  vscode-integration.ts      # VS Code environment detection, CDP discovery
  extension.ts               # VS Code companion extension
  package.json
  README.md
  docs/
    adrs/                    # Architecture Decision Records
    specs/                   # Product and technical specifications
      features/              # Feature specifications
  CLAUDE.md                  # Agent instructions
```

## Commands

| Command | Description |
|---------|-------------|
| `bun run build` | Compile TypeScript (`tsc`) |
| `bun run dev` | Watch mode (`tsc --watch`) |
| `bun start` | Run compiled server (`node dist/cli.js`) |
| `bun run prepare` | Pre-install build hook (`tsc`) |

## CLI

```
npx @anthropic-community/browser-coordinator-mcp [options]
npx @anthropic-community/browser-coordinator-mcp wrap -- <command> [args...]

Modes:
  (default)               Start the coordinator MCP server
  wrap                    Read state file, inject CDP port, run child command

Options:
  --browser <type>        Preferred browser: chrome, edge, chromium, brave
  --browser-path <path>   Explicit browser executable path
  --no-headless           Show browser UI (default: headless)
  --no-vscode             Disable VS Code integration detection
  --help, -h              Show help

Wrap template variables:
  {cdp_port}              Replaced with the CDP proxy port number
  {cdp_endpoint}          Replaced with http://localhost:<port>
```

## Environment Variables

| Variable | Purpose |
|----------|---------|
| `BROWSER_COORDINATOR_DEBUG=1` | Enable debug logging to stderr |
| `VSCODE_CDP_PORT=<port>` | VS Code CDP port (set by companion extension) |

## Conventions

- All source files are in the project root (flat structure, no `src/` directory)
- Output compiles to `dist/`
- Tests use Bun's built-in test runner (`bun test`)
- No bundler — raw `tsc` compilation