# mcp-unified-automation

Custom MCP server — Playwright browser automation + system control, 25 tools, stdio transport.

Launched via `RUN_MCP_FAST.bat` on George's Desktop. Connects to Claude Code as a local MCP server.

---

## What it does

Runs a headed Chrome instance using George's actual Chrome profile (`User Data` dir), so the browser has real auth cookies — logged into Google, Search Console, Gmail, everything. Claude operates it through 25 registered MCP tools.

**Tool groups:**

| Group | Count | What it covers |
|---|---|---|
| `browser_*` | 7 | Backward-compatible Playwright tools (navigate, click, type, screenshot, etc.) |
| `system_*` | 6 | Shell commands, file read/write, process control |
| `session_*` | 2 | Named browser session management (multiple tabs/contexts) |
| `task_*` | 5 | Task DSL engine — plan, run, resume, pause, commit |
| `observe_*` | 1 | DOM observation / mutation watching |
| `network_*` | 2 | Request blocking + API endpoint discovery |
| `evidence_*` | 1 | Export + hash-chain verification of browser actions |
| `metrics_*` | 1 | Step-level timing and performance reporting |

---

## Setup

```bash
git clone https://github.com/gugosf114/mcp-unified-automation
cd mcp-unified-automation
npm install
cp .env.example .env
# Edit .env if your Chrome User Data path differs
npm run build
```

Then double-click `RUN_MCP_FAST.bat` (or right-click → Run as administrator if system tools need elevation).

---

## .env config

```
BROWSER_HEADED=true            # Show the browser window
BROWSER_BLOCK_MEDIA=false      # Block images/video to speed up crawls
HUMAN_DELAY_MIN=50             # ms — min delay between actions
HUMAN_DELAY_MAX=200            # ms — max delay (human-like pacing)
FAST_MODE=true                 # Skip networkidle waits + nav waits on click (10x faster)
CHROME_USER_DATA_DIR=C:\Users\georg\AppData\Local\mcp-unified-automation\chrome-profile
```

`CHROME_USER_DATA_DIR` points to a dedicated Chrome profile so sessions, cookies, and logins carry over. Must NOT be Chrome's default user-data-dir (Chrome blocks DevTools on it).

`FAST_MODE` skips Playwright's `networkidle` wait after every navigation and click. Modern sites (GA4, Gmail, etc.) never truly go network-idle due to analytics pings and websockets, so the default behavior just burns 10-30 seconds hitting the timeout. With FAST_MODE, pages are interactable as soon as the DOM loads.

---

## Claude Code config

Add to your Claude Code MCP config (`claude_desktop_config.json` or equivalent):

```json
{
  "mcpServers": {
    "unified-automation": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-unified-automation\\dist\\index.js"]
    }
  }
}
```

Or just run the BAT — it handles the node invocation.

---

## Architecture

```
src/
  index.ts        — server entry, registers all tool groups
  kernel.ts       — wires up shared managers (session, task, observer, network, evidence, metrics)
  tools/          — one file per tool group
  cdp/            — Chrome DevTools Protocol bridge
  session/        — named session + page slot management
  task/           — task DSL (plan/run/resume/pause/commit)
  observer/       — DOM mutation bus
  network/        — request interceptor + API discovery
  evidence/       — action ledger + hash chain
  metrics/        — step timing engine
  checkpoint/     — mid-task state snapshots
  recovery/       — resume after crash/disconnect
  policy/         — action policy enforcement
  types/          — shared TypeScript types
```

---

## Stack

- Node.js (ESM)
- TypeScript 5.7
- Playwright 1.52
- `@modelcontextprotocol/sdk` 1.12
- Zod (schema validation)

---

## What's New (March 2026)

### Features you can use

- **Domain readiness profiles** (`src/readiness.ts`) — The server now knows how to wait for LinkedIn, Gmail, Google Search, GitHub, Yelp, Facebook, and Instagram. Instead of waiting for `networkidle` (which times out on every modern site), it waits for the actual content selector that proves the page loaded. You don't call this directly — it fires automatically on every `navigate`, `goto`, and `warm` call. If you add a new site you automate frequently, add its selector to `readiness.ts`.

- **Selective evidence mode** — New `.env` setting `EVIDENCE_MODE=selective` records screenshots/DOM snapshots only on errors, approval gates, and the first/last step of a task. Set to `full` for audit trails, `none` to skip entirely. Controlled in `.env`, no code changes needed.

- **Semantic tool returns** — `browser_navigate`, `browser_click`, and `session_open` now return richer data: `readyState`, whether navigation occurred, whether the readiness selector matched, the domain profile used. This means Claude doesn't need a follow-up `getPageInfo` call after every action — the info comes back in the tool response. Fewer round trips = faster task execution.

- **Task management tools renamed** — `task.list` → `task_list`, `task.status` → `task_status`, `task.cancel` → `task_cancel`. Claude Desktop rejects dots in tool names. If you had prompts referencing the old names, update them.

### Performance & safety (automatic, no action needed)

- **FAST_MODE** — When `FAST_MODE=true` in `.env`: zero human delays, skip `networkidle` waits, sparse checkpoint writes (every 3rd step instead of every step), evidence recording follows `EVIDENCE_MODE` setting. Already enabled in your `.env`.

- **Stable path resolution** — Data directories (`data/checkpoints/`, `data/evidence/`) now resolve from the module's own location (`import.meta.url`), not `process.cwd()`. This fixed the crash when Claude Desktop spawned the server from `C:\WINDOWS\system32`. Centralized in `src/env.ts` as `DATA_ROOT`.

- **Retry with exponential backoff** (`src/action/retry.ts`) — Network-sensitive actions auto-retry on transient failures.

- **Conditional steps & parallel runner** — Task DSL now supports `condition` fields on steps and a parallel step executor for independent actions.

---

## Notes

- `browser_*` tools use a `”default”` page slot for backward compatibility — existing Claude prompts that call `browser_navigate` etc. still work unchanged.
- The task engine supports mid-run pause/resume — useful for long multi-step jobs that might hit context limits.
- Evidence ledger produces a hash-chained audit trail of every browser action. Useful for compliance work.
- Recovery module handles reconnect after Claude Code crashes or context resets.

---

## Execution Policy

This server runs in **operator-first mode**.

Reversible automation and read/write navigation steps are allowed by default — no approval gate required. Human approval is required only for:

- **Financial actions** (payments, subscriptions, transactions)
- **Destructive actions** (deletes, overwrites, sends that cannot be undone)
- **Explicit pproval_gate checkpoints** defined in the task DSL

The operator, not the client UI, is the final authority over execution policy. Approval prompts are task-level constructs, not UI-level guardrails.