# fast-browser-mcp

`fast-browser-mcp` is a lightweight MCP server that adds persistent QA state on top of [`agent-browser`](https://github.com/vercel-labs/agent-browser).

It does not rebuild browser automation. Instead, it shells out to `agent-browser` commands and stores compact session state on disk so AI agents can reason over changes across multiple steps.

## Features

- session-scoped storage (`sessionId`) instead of environment-scoped state
- persistent snapshots, diffs, errors, timeline, and QA report
- simple line-based diff optimized for AI readability
- file-based architecture only (no database, no workers, no polling)
- MCP-first tool interface for Cursor and other MCP clients

## Why this project exists

AI-driven QA workflows lose context quickly between actions. This server keeps state per browser session so agents can:

- compare state before/after each action
- inspect recent console/network failures
- generate concise QA reports from deterministic stored artifacts

## Requirements

- Node.js `>=24` (required by `agent-browser`)
- npm

`agent-browser` does not need to be installed globally. This package will use a local/global `agent-browser` if available, and falls back to `npx agent-browser@latest` when needed.

## Installation

### Option A: Run from npm (after publish)

```bash
npx fast-browser-mcp
```

### Option B: Install globally from GitHub (no npm registry publish required)

Direct `npm i -g github:...` can leave a broken symlink in global `node_modules` on some npm setups. Use the pack-then-install flow instead:

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/donleqt/fast-browser-mcp/main/scripts/install-global.sh)
```

Or manually:

```bash
tmpdir=$(mktemp -d) && \
tarball=$(npm pack github:donleqt/fast-browser-mcp --pack-destination "$tmpdir" --silent) && \
npm i -g "$tmpdir/$tarball" && \
rm -rf "$tmpdir"
```

Then run:

```bash
fast-browser-mcp
```

### Option C: Build from source

```bash
git clone https://github.com/donleqt/fast-browser-mcp.git
cd fast-browser-mcp
npm install
npm run build
node dist/index.js
```

## Cursor MCP configuration

Add a stdio MCP server entry:

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

If installed globally:

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

## Session model

- every browser flow is keyed by `sessionId`
- default `sessionId` is slug-safe and derived from URL
- duplicate derived session IDs are reused by default
- custom `sessionId` is supported

Examples:

- `http://localhost:3000` -> `localhost-3000`
- `https://app.example.com/dashboard` -> `app-example-com-dashboard`

## Storage layout

All artifacts are written under:

```txt
.fast-browser/
  sessions/
    {sessionId}/
      latest.md
      previous.md
      diff.md
      errors.md
      timeline.jsonl
      meta.json
      screenshot.png
      report.md
```

## MCP tools

- `fast_browser_open({ url, sessionId? })`
- `fast_browser_snapshot({ sessionId })`
- `fast_browser_diff({ sessionId })`
- `fast_browser_errors({ sessionId })`
- `fast_browser_act({ sessionId, action, ref?, value? })`
- `fast_browser_state({ sessionId })`
- `fast_browser_report({ sessionId })`
- `fast_browser_sessions({})`

## Quick example workflow

```txt
fast_browser_open({ url: "http://localhost:3000" })
fast_browser_state({ sessionId: "localhost-3000" })
fast_browser_act({ sessionId: "localhost-3000", action: "click", ref: "@e1" })
fast_browser_report({ sessionId: "localhost-3000" })
```

## Architecture

- `src/agentBrowser.ts`: centralized CLI mapping and execution wrapper
- `src/storage.ts`: file-based session persistence
- `src/tools.ts`: MCP tool handlers and orchestration
- `src/diff.ts`: readable line-based diff
- `src/report.ts`: report generation

## Scope and non-goals (MVP)

This project intentionally does not include:

- environment concepts (`local/staging/prod`)
- database or cloud sync
- authentication or multi-user orchestration
- web UI, React/Redux hooks, polling loops, background workers

## Troubleshooting

- `ENOTDIR` or `git dep preparation failed` during global GitHub install
  - remove any broken global install: `rm -f "$(npm root -g)/fast-browser-mcp"`
  - reinstall using Option B above (pack-then-install), not `npm i -g github:...` directly
- `agent-browser CLI not found...`
  - ensure `npx` can run in your environment
  - optionally install `agent-browser` globally for faster startup (`npm i -g agent-browser`)
  - verify Node.js version is `>=24`
- session not found errors
  - run `fast_browser_open` first to create/reuse a session