# WAT-AI-Broker #

**a small MCP server that lets an LLM build, inspect and drive a running [WebApp Tinkerer](https://github.com/rozek/webapp-tinkerer) applet live in the browser**

WAT-AI-Broker (abbreviation: **the broker**) is the bridge between an AI assistant and a running [WebApp Tinkerer](https://github.com/rozek/webapp-tinkerer) (WAT) instance.

WAT applets usually live entirely in the browser — there is no server and no way for an external process to reach the applet directly. The broker closes the gap between the AI assistant and the WebApp Tinkerer: it speaks the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) towards the LLM on one side, and a tiny JSON-RPC-style protocol over WebSocket towards WAT on the other, forwarding every tool call to the connected tab and returning its result.

With it, an MCP-capable assistant can list pages and widgets, read and edit their properties, add or delete elements, change geometry, manage behaviours, get and set scripts, configure and observe values, evaluate live expressions, open overlays and dialogs, visit pages and even capture a screenshot of the current applet — all against the applet the user is looking at, in real time (and, with a little bit of care, while the user is also actively working with that applet).

## How it works

The broker is a single Node.js process that opens two ports:

| Port (default) | Protocol | Who connects | Path |
|---|---|---|---|
| `3460` | MCP over Streamable HTTP | the LLM / MCP client | `POST/GET/DELETE /mcp`, `GET /health` |
| `3461` | WebSocket | the WAT tab | `/wat` |

```
   ┌────────────┐   MCP / HTTP    ┌───────────────────────┐   WebSocket    ┌──────────────────┐
   │ LLM client │ ◄────────────►  │     WAT-AI-Broker     │ ◄───────────►  │ WebApp Tinkerer  │
   │  (Claude…) │   :3460 /mcp    │   (this process)      │   :3461 /wat   │    (browser)     │
   └────────────┘                 └───────────────────────┘                └──────────────────┘
```

### Connection handshake

When WAT connects to `ws://localhost:3461/wat`, its first message must be a `hello` carrying the shared access token plus the current applet name and visited page. The broker replies with `welcome` and, from then on, relays requests. A wrong token is rejected (close code `4001`), a second simultaneous connection is refused (`4002`), and the wrong path is closed (`4004`). WAT also sends `notify` events (e.g. `page_visited`) so the broker's status stays current.

## Installation

```bash
git clone https://github.com/rozek/wat-ai-broker.git
cd wat-ai-broker
npm install
```

## Configuration

The broker is configured entirely through environment variables:

| Variable | Required | Default | Purpose |
|---|---|---|---|
| `WAT_ACCESS_TOKEN` | **yes** | — | shared secret; must match the token configured in the WebApp Tinkerer. The process exits immediately if it is unset. |
| `WAT_MCP_PORT` | no | `3460` | port the MCP client connects to (`/mcp`) |
| `WAT_MCP_HOST` | no | `127.0.0.1` | interface the MCP HTTP server binds to |
| `WAT_BROKER_PORT` | no | `3461` | WebSocket port the WAT instance connects to (`/wat`) |

## Running

Build once, then start:

```bash
npm run build
WAT_ACCESS_TOKEN='your-secret-token' npm start
```

`GET /health` returns `200` with the current status when a WAT instance is connected, and `503` otherwise — handy for readiness checks without an MCP session.

Here is a [cURL](https://curl.se/) command you may use for that purpose:

```bash
curl -i http://127.0.0.1:3460/health
```

It prints `HTTP/1.1 200 OK` followed by a JSON status snapshot while a WAT instance is connected, and `HTTP/1.1 503 Service Unavailable` otherwise:

```json
{
  "connected": true,
  "applet_name": "My Applet",
  "current_page": "Home",
  "connected_at": "2026-07-12T07:24:44.000Z"
}
```

## Configuring an MCP client

Point your MCP client at the Streamable-HTTP endpoint:

```
http://127.0.0.1:3460/mcp
```

A typical configuration looks as follows:

```json
{
  "mcpServers": {
    "wat-ai-broker": {
      "type": "http",
      "url": "http://127.0.0.1:3460/mcp"
    }
  }
}
```

If your AI assistant supports MCP stdio transport only, you can bridge it to the broker's HTTP endpoint with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```json
{
  "mcpServers": {
    "wat-ai-broker": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:3460/mcp"]
    }
  }
}
```

## Configuring the WebApp Tinkerer

In the WebApp Tinkerer, configure its MCP connector to reach `ws://localhost:3461/wat` using the same `WAT_ACCESS_TOKEN`. Once the tab is open and connected, every tool call from the LLM operates on that applet.

## Available tools

44 tools in 9 groups. Every tool except `connection_status` requires a connected WAT instance.

- **connection** — `connection_status` (works even without a connected tab)
- **applet** — `applet_info`, `applet_get`, `applet_patch`, `applet_save`, `applet_export`, `applet_import`
- **navigation** — `list_pages`, `list_widgets`, `find`, `page_visit`
- **pages** — `page_get`, `page_patch`, `page_add`, `page_duplicate`, `page_delete`, `page_reorder`
- **widgets** — `widget_get`, `widget_patch`, `widget_add`, `widget_duplicate`, `widget_delete`, `widget_reorder`, `widget_transfer`
- **geometry** — `widget_get_rect`, `widget_set_rect` (pixel rects, abstracting WAT's anchor/offset model)
- **behaviours** — `list_behaviors`, `behavior_get`, `behavior_set`, `behavior_rename`, `behavior_delete`, `behavior_usage`
- **scripts & configuration** — `script_get`, `script_set`, `error_report`, `configure`, `value_get`, `value_set`
- **live interaction** — `live_eval`, `overlay_open`, `overlay_close`, `dialog_open`, `dialog_close`, `live_screenshot`

Each tool's inputs are validated with [Zod](https://zod.dev) before being forwarded, and results are returned as MCP text content (`live_screenshot` returns image content).

**Addressing.** Pages and widgets are addressed either by their name or by their 0-based index (widgets within their page, in z-order, backmost first). The script, configuration and value tools take a `target` string instead: `"applet"` for the applet itself, `"<page>"` for a page, and `"<page>/<widget>"` for a widget.

**Behaviours.** Pages and widgets get their functionality from named behaviours in three categories (`applet`, `page`, `widget`). The behaviour tools let the LLM inspect which behaviours are registered (including their `missing`, `broken` and `unused` flags), read and rescript them, rename them (updating all users), unregister them, and list all pages/widgets using a given behaviour. Behaviour-specific configurable properties simply pass through `page_patch` / `widget_patch` and `configure`.

## Agent Skills

The `skills/` folder contains two ready-made [Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) that make an AI assistant considerably more effective when working with the broker:

- **`skills/wat-ai-broker`** — teaches the assistant *how to drive a live applet through the broker*: always check `connection_status` first, explore the applet structure before editing, use the addressing conventions correctly (names over indices, `target` strings, full behaviour names like `"native_controls.Button"`), and edit carefully while the user may be working in the same tab.
- **`skills/wat-reference`** — the knowledge companion: WAT's data model, all visual properties, the complete scripting API, and per-widget documentation of every built-in behaviour (in `references/*.md`). With it, the assistant writes correct `widget_add`, `widget_patch`, `configure` and `script_set` calls on the first try instead of probing the applet with exploratory `widget_get` calls.

Install **both** skills — `wat-ai-broker` provides the workflow, `wat-reference` the background knowledge, and the former refers to the latter.

Each skill is a plain folder with a `SKILL.md` (plus optional `references/`), following the common Agent-Skills format. Installation therefore is just a copy:

```bash
# Claude Code — personal (available in all projects):
cp -r skills/wat-ai-broker skills/wat-reference ~/.claude/skills/

# Claude Code — per project (shared with the team via git):
cp -r skills/wat-ai-broker skills/wat-reference .claude/skills/
```

For claude.ai or the Claude desktop app, zip each skill folder and upload it under *Settings → Capabilities → Skills*. Other skill-capable assistants work analogously — consult their documentation for the proper skills directory.

Once installed, the skills activate automatically whenever a conversation touches a running WAT applet — no manual invocation needed (explicit requests like "use the wat-ai-broker skill" work, too).

## Building from source

```bash
npm run build
```

This runs [esbuild](https://esbuild.github.io) to bundle `src/WAT-AI-Broker.ts` into a single file, **`dist/WAT-AI-Broker.js`**. The npm dependencies (`express`, `ws`, `zod`, `@modelcontextprotocol/sdk`) are kept external, so `node_modules` must be present at runtime.

`npm run check` type-checks the TypeScript source with [tsc](https://www.typescriptlang.org) (no emit).

## Source Code

The broker is developed as aspect-oriented notes in a Browser-based Notebook (BBN) and exported to this repository as a single monolithic TypeScript module, **`src/WAT-AI-Broker.ts`**, covering three aspects:

- **Broker** — the WebSocket server. It accepts exactly one WAT connection at a time, authenticates it with a shared token, tracks the connection state (applet name, current page, connected-at timestamp), and routes requests/responses by UUID with a 30-second timeout.
- **MCP Server** — the MCP server factory. It registers all 44 tools with their Zod input schemas and forwards each call to WAT via the broker. A fresh MCP server is created per MCP session; all sessions share the one broker singleton.
- **HTTP Server** — the HTTP entry point. It wires up Express, the Streamable-HTTP transport (one transport per session), the `/health` endpoint, and the startup guards.

A build step bundles the module into a single distributable file (see [Building from source](#building-from-source)).

## Testing

```bash
npm test
```

The suite contains 150 unit tests ([Vitest](https://vitest.dev)) covering the WebSocket handshake and lifecycle, request routing and timeouts, the MCP helpers and tool forwarding, the Zod input schemas, screenshot handling and the startup guards. It uses fake WebSocket and mocked MCP infrastructure — no real network, transport or WAT instance is required. See [TestPlan.md](./TestPlan.md) for details.

## Requirements

- Node.js ≥ 22
- a running [WebApp Tinkerer](https://github.com/rozek/webapp-tinkerer) instance configured with a matching access token

## License

[MIT](./LICENSE.md) © Andreas Rozek