BrowserCard AI Broker

a small MCP server that lets an LLM build, inspect and drive a running BrowserCard deck live in the browser

BrowserCard-AI-Broker (abbreviation: the broker) is the bridge between an AI assistant and a running BrowserCard 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 (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

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:

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

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:

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

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

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

# 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

npm run build

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

Testing

npm test

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

Requirements

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

License

MIT © Andreas Rozek