# BrowserCard-AI-Broker #

**a small MCP server that lets an LLM build, inspect and drive a running [BrowserCard](https://github.com/rozek/browser-card) deck live in the browser**

BrowserCard-AI-Broker (abbreviation: **the broker**) is the bridge between an AI assistant and a running [BrowserCard](https://github.com/rozek/browser-card) instance.

BrowserCard decks usually live entirely in the browser — there is no server and no way for an external process to reach the deck directly. The broker closes the gap between the AI assistant and BrowserCard: 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 BrowserCard on the other, forwarding every tool call to the connected tab and returning its result.

With it, an MCP-capable assistant can list cards and widgets, read and edit their properties, add or delete elements, change geometry, get and set scripts, store custom state, evaluate live expressions, navigate the deck and even capture a screenshot of the current card — all against the deck the user is looking at, in real time (and, with little bit of care, while the user is also actively working with that deck).

## How it works

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

| Port (default) | Protocol | Who connects | Path |
|---|---|---|---|
| `3456` | MCP over Streamable HTTP | the LLM / MCP client | `POST/GET/DELETE /mcp`, `GET /health` |
| `3457` | WebSocket | the BrowserCard tab | `/bc` |

```
   ┌────────────┐   MCP / HTTP    ┌───────────────────────┐   WebSocket    ┌──────────────┐
   │ LLM client │ ◄────────────►  │ BrowserCard-AI-Broker │ ◄───────────►  │ BrowserCard  │
   │  (Claude…) │   :3456 /mcp    │   (this process)      │   :3457 /bc    │   (browser)  │
   └────────────┘                 └───────────────────────┘                └──────────────┘
```

### Connection handshake

When BrowserCard connects to `ws://localhost:3457/bc`, its first message must be a `hello` carrying the shared access token plus the current deck name and card. 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`). BrowserCard also sends `notify` events (e.g. `card_changed`) so the broker's status stays current.

## Installation

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

## Configuration

The broker is configured entirely through environment variables:

| Variable | Required | Default | Purpose |
|---|---|---|---|
| `BC_ACCESS_TOKEN` | **yes** | — | shared secret; must match the token configured in BrowserCard. The process exits immediately if it is unset. |
| `BC_MCP_PORT` | no | `3456` | port the MCP client connects to (`/mcp`) |
| `BC_MCP_HOST` | no | `127.0.0.1` | interface the MCP HTTP server binds to |
| `BC_BROKER_PORT` | no | `3457` | WebSocket port BrowserCard connects to (`/bc`) |

## Running

Build once, then start:

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

`GET /health` returns `200` with the current status when a BrowserCard 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:3456/health
```

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

```json
{
  "connected": true,
  "deck_name": "My Deck",
  "current_card": "Intro",
  "connected_at": "2026-06-25T07:24:44.000Z"
}
```

## Configuring an MCP client

Point your MCP client at the Streamable-HTTP endpoint:

```
http://127.0.0.1:3456/mcp
```

A typical configuration looks as follows:

```json
{
  "mcpServers": {
    "browsercard-ai-client": {
      "type": "http",
      "url": "http://127.0.0.1:3456/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": {
    "browsercard-ai-client": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:3456/mcp"]
    }
  }
}
```

## Configuring BrowserCard

In BrowserCard, configure its MCP connector to reach `ws://localhost:3457/bc` using the same `BC_ACCESS_TOKEN`. Once the tab is open and connected, every tool call from the LLM operates on that deck.

## Available tools

30 tools in 9 groups. Every tool except `connection_status` requires a connected BrowserCard instance.

- **connection** — `connection_status` (works even without a connected tab)
- **deck** — `deck_get`, `deck_patch`, `deck_save`
- **navigation** — `list_cards`, `list_widgets`, `find`
- **cards** — `card_get`, `card_patch`, `card_add`, `card_delete`, `card_reorder`, `card_move`
- **widgets** — `widget_get`, `widget_patch`, `widget_add`, `widget_delete`, `widget_transfer`, `widget_reorder`
- **geometry** — `widget_get_rect`, `widget_set_rect` (pixel rects, abstracting BrowserCard's anchor/offset model)
- **scripting** — `script_get`, `script_set`
- **extras** — `extras_get`, `extras_set`, `extras_delete` (custom, non-schema state)
- **live interaction** — `live_eval`, `live_send`, `live_navigate`, `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).

**Nested cards.** Cards can be nested into a hierarchy. `list_cards` reports each card's `parent_id`, `depth` and `path` (ancestor names + own name, `/`-joined); `card_add` accepts an optional `parent_id` to insert a child; `card_move` re-parents a card with its whole subtree (rejecting cycles); `card_delete` removes a card together with its subtree (cascade); `card_reorder`'s index is relative to the card's siblings. Cards are still addressed by their stable `id` — `path` is a read-only convenience and `/` is therefore not allowed inside names.

## 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/browsercard-live`** — teaches the assistant *how to drive a live deck through the broker*: always check `connection_status` first, explore the deck structure before editing, use the addressing and target conventions correctly (stable `bc-card-N` / `bc-widget-N` ids, `"deck"` / `"<card>"` / `"<card>/<widget>"` targets), call `deck_save` when persistence matters, and edit carefully while the user may be working in the same tab.
- **`skills/browsercard-reference`** — the knowledge companion: BrowserCard's data model, the complete property reference for all widget types (`button`, `field`, `shape`, `picture`, `generic`) and the full scripting API. With it, the assistant writes correct `widget_add`, `widget_patch` and `script_set` calls on the first try instead of probing the deck with exploratory `widget_get` calls.

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

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

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

# Claude Code — per project (shared with the team via git):
cp -r skills/browsercard-live skills/browsercard-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 BrowserCard deck — no manual invocation needed (explicit requests like "use the browsercard-live skill" work, too).

## Building from source

```bash
npm run build
```

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

## Source Code

Internally the process is split into three modules under `src/`:

- **`src/Broker.js`** — the WebSocket server. It accepts exactly one BrowserCard connection at a time, authenticates it with a shared token, tracks the connection state (deck name, current card, connected-at timestamp), and routes requests/responses by UUID with a 30-second timeout.
- **`src/createServer.js`** — the MCP server factory. It registers all 30 tools with their Zod input schemas and forwards each call to BrowserCard via the broker. A fresh MCP server is created per MCP session; all sessions share the one broker singleton.
- **`src/index.js`** — 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 all three into a single distributable file (see [Building from source](#building-from-source)).

## Testing

```bash
npm test
```

The suite contains 106 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 BrowserCard instance is required. See [TestPlan.md](./TestPlan.md) for details.

## Requirements

- Node.js ≥ 22
- a running [BrowserCard](https://github.com/rozek/browser-card) instance configured with a matching access token

## License

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