# Browser Automation MCP Server

This TypeScript project spins up a Model Context Protocol (MCP) server that exposes three tooling primitives tailored for automation: browser-driven flows, API health checks, and visual comparisons. It listens on STDIO, so any MCP-aware agent (Claude, Cursor, LangChain, etc.) can start the Node process and negotiate `tools/list` + `tools/call` automatically.

## Setup
1. `npm install`
2. `npm run build`

## Running the server
Execute `npm run start` (or `node build/server.js` directly). The server already binds to STDIO, so configure your MCP client to launch the same command and keep the subprocess running while the agent is issuing tool requests.

## Tool catalogue
| Tool | Description | Inputs | Outputs |
| --- | --- | --- | --- |
| `run-browser-automation` | Navigates a Chromium tab, runs scripted actions (click/fill/assert), and optionally returns a final screenshot. | `url` (required), `actions` array (navigate/click/fill/type/press/assert/wait), viewport/device scale, `finalScreenshot` flag. | `steps` array, summary, optional screenshot (`data:image/png;base64,...`). |
| `run-api-check` | Hits any HTTP endpoint to verify status and capture response snippets. | `url` (required), HTTP `method`, `headers`, `body`, expected status. | HTTP `status`, comparison to `expectStatus`, response snippet, response headers. |
| `compare-page-screenshots` | Captures two pages at the same viewport and runs pixelmatch to flag visual regressions. | `baselineUrl`, `targetUrl`, optional `viewport`/`threshold`. | Pixel mismatch ratio, diff image (base64 PNG), baseline dimensions. |

## Example tool call payloads
*Browser automation*
```json
{
  "url": "https://example.com/login",
  "actions": [
    {"type": "fill", "selector": "#username", "value": "test"},
    {"type": "fill", "selector": "#password", "value": "secret"},
    {"type": "click", "selector": "#submit"},
    {"type": "waitForSelector", "selector": "#welcome"}
  ],
  "finalScreenshot": true
}
```

*Image comparison*
```json
{
  "baselineUrl": "https://example.com/home?baseline=1",
  "targetUrl": "https://example.com/home?baseline=2",
  "threshold": 0.04
}
```

## Debugging & exploration
Use the MCP Inspector to validate the server before wiring it to a client. Run `npx @modelcontextprotocol/inspector node build/server.js`, open the Inspector UI, and review the `tools` tab, send sample arguments, and inspect logs. The Inspector also proxies your server so you can replicate production-style connections locally.