WAT-AI-Broker

a small MCP server that lets an LLM build, inspect and drive a running 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 (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 (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

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:

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 command you may use for that purpose:

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:

{
  "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:

{
  "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:

{
  "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 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 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:

# 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

npm run build

This runs esbuild 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 (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).

Testing

npm test

The suite contains 150 unit tests (Vitest) 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 for details.

Requirements

• Node.js ≥ 22
• a running WebApp Tinkerer instance configured with a matching access token

License

MIT © Andreas Rozek