# DualStream MCP Server
Our first Open Source project!
The official [Model Context Protocol](https://modelcontextprotocol.io) server for [DualStream](https://dualstream.gg), the streaming studio that produces desktop (16:9) and mobile (9:16) streams simultaneously from a single pipeline.

This server lets AI assistants like Claude operate your DualStream studio: switch scenes, save instant-replay clips, build entire scene layouts from scratch, restyle your alerts and widgets, and react to what happens on stream. Everything runs locally on your machine, with your explicit approval, and every change renders on both your desktop and mobile canvases.

```
AI assistant (Claude Code, Claude Desktop, or any MCP client)
        |  MCP over stdio
        v
DualStream MCP server  (this package)
        |  JSON-RPC over WebSocket, 127.0.0.1 only
        v
DualStream desktop app
```

## What you can ask for

Once connected, you talk to your assistant in plain language:

- "Switch to my BRB scene"
- "Clip the last 30 seconds"
- "Create a scene called MAIN with my webcam in the bottom right, cropped to a circle, and my primary display fullscreen behind it"
- "Make me a starting-soon scene for a charity stream in my brand colors, both canvases"
- "Restyle my alerts to match this palette"
- "Move the camera up a bit and give it a soft shadow"

The assistant discovers your actual hardware (cameras, displays, windows, microphones), composes layouts for the desktop and mobile canvases independently, and iterates with you until it looks right.

## Before you start

You need three things installed. Each is a normal download-and-run installer:

1. **The [DualStream desktop app](https://dualstream.gg)** (Windows or macOS): the studio this server controls.
2. **[Node.js](https://nodejs.org)**: pick the big green LTS button (version 22 or newer). This is the runtime that runs the server; you won't interact with it directly.
3. **An AI assistant that supports MCP**, such as [Claude Desktop](https://claude.ai/download) or the [Claude CLI](https://claude.com/claude-code).

## Installation

### Step 1: Get this project onto your computer

Click the green **Code** button at the top of this GitHub page and choose **Download ZIP**, then unzip it somewhere you'll remember, for example your Documents folder. (If you're comfortable with git, `git clone` works too.)

### Step 2: Build it

Open a terminal **in the unzipped folder**:

- **Windows:** open the folder in File Explorer, click the address bar, type `cmd`, and press Enter.
- **macOS:** right-click the folder and choose **New Terminal at Folder** (or drag the folder onto Terminal).

Then run these two commands, one after the other:

```bash
npm install
npm run build
```

Each prints some text and returns to the prompt. That's it; the server is built.

### Step 3: Tell your assistant about it

You need the full path to the folder from Step 1. In Windows File Explorer, click the address bar and copy it (it looks like `C:\Users\you\Documents\DualStreamMCP`). On macOS, right-click the folder, hold Option, and choose **Copy as Pathname**.

**Claude Desktop**: open **Settings → Developer → Edit Config**, and add this (replace the path with yours; on Windows, use double backslashes as shown):

```json
{
  "mcpServers": {
    "dualstream": {
      "command": "node",
      "args": ["C:\\Users\\you\\Documents\\DualStreamMCP\\dist\\index.js"]
    }
  }
}
```

**Claude CLI**: one command (replace the path with yours):

```bash
claude mcp add dualstream -- node "C:\Users\you\Documents\DualStreamMCP\dist\index.js"
```

Any other MCP client works the same way: run `node <folder>/dist/index.js` as a stdio server.

### Step 4: Say hello

Restart your assistant, make sure DualStream is running, and ask: *"What scene am I live on in DualStream?"* The first time, DualStream will pop up an approval prompt; that's the security model working (see below). Approve it, and you're done.

## First connection and security

The DualStream app runs a small control server bound to `127.0.0.1` only. Nothing is reachable from the network, and this MCP server must run on the same machine as the app. There is no cloud component: the intelligence is whatever AI assistant you connect, and your stream never leaves your control.

Pairing is automatic. The app publishes a pairing token in its config directory, and this server picks it up on its own; you never type a password. The first time an assistant connects, DualStream shows a consent prompt naming the client. You choose Allow, Always allow, or Deny. Until you approve, the connection can't do anything. You can see every connected client, disconnect any of them, and revoke remembered approvals at any time under **Settings, General, External Control** in the app.

If you deny a connection, the server closes it. If you reset the pairing token in the app's settings, every connected client is disconnected and must re-pair.

## Tools

### Scenes and clips

| Tool | Description |
|---|---|
| `get_scenes` | List all scenes. |
| `get_active_scene` | The scene currently live, or null. |
| `activate_scene` | Switch the live output to a scene, by id or name. |
| `get_state_snapshot` | Full scene state in one call; the resync anchor. |
| `trigger_clip` | Save the last N seconds as a clip pair (a horizontal and a vertical file). |
| `get_recent_events` | Poll buffered app events (scene changes, clips saved, relayed stream events) with sequence numbers. |
| `get_connection_status` | Whether the app is reachable, app version, and this connection's approval state. |
| `wait_for_event` | Block until the next event arrives (or return buffered ones immediately). The live-reaction primitive behind automations. |

### Scene composition

Build and edit scenes source by source. Layouts on the desktop (1920x1080) and mobile (1080x1920) canvases are controlled independently, so a small round facecam on desktop can be a full-width square camera on mobile.

| Tool | Description |
|---|---|
| `list_devices` | Enumerate cameras, capture cards, displays, windows, and audio inputs, ready to add. |
| `create_scene` | Create a new scene, optionally switching to it. |
| `list_sources` | The sources in a scene with their per-canvas layout. |
| `add_source` | Add a camera, display, window, or audio device to a scene. |
| `remove_source` | Remove a source. |
| `set_source_transform` | Position and size a source, per canvas. |
| `set_source_crop` | Crop pixels off a source's edges. |
| `set_source_shape` | Mask a source to a circle, squircle, or rounded rectangle. |
| `set_source_effects` | Apply a border, shadow, glow, or blur. |
| `set_source_order` | Change layer order (front, back, up, down). |

### Recipes

Recipes are DualStream's shareable scene templates: a background plus positioned sources for both canvases, saved as JSON on disk.

| Tool | Description |
|---|---|
| `list_recipes` | List installed recipes. |
| `apply_recipe` | Build a live scene from a recipe, or apply one into an existing scene. |
| `save_recipe` | Author a brand-new recipe from a manifest and save it to your library. |

### Widgets

| Tool | Description |
|---|---|
| `get_widget_settings` | Read the current settings of the alert box, chat box, goal tracker, or prediction tracker. |
| `update_widget_settings` | Apply new settings. Reads and writes use the same shape, so an assistant can fetch, modify, and send back. |

### AI Card

| Tool | Description |
|---|---|
| `post_card` | Post a short card onto the stream (a title and optional message), rendered by the alert system with the styling you configured. The AI Card alert type is off by default; enable it in the alerts inspector to allow posting. |

### Automations

Automations pair a stream-event trigger (a raid, a big cheer, a hype train
ending) with a standing instruction for your assistant. When a matching event
happens, DualStream relays it to the assistant with your instruction attached;
the assistant composes and posts the card. Only events matching an enabled
automation ever leave the app, and the assistant only listens while you have a
session open. The full doc format, event vocabulary, and rehearsal flow are in
[contract/automations-v1.md](contract/automations-v1.md).

| Tool | Description |
|---|---|
| `list_automations` | Your stored automations and their standing instructions. |
| `save_automation` | Create or update an automation; matching events start relaying immediately. |
| `delete_automation` | Remove an automation. |

A typical live session: tell your assistant you are going live; it reads your
automations, then loops on `wait_for_event`; waiting costs nothing, and each
handled event is one short exchange (welcome the raiders, thank the whale,
post the card).

Tool errors are structured JSON with a `retryable` flag, so assistants know the difference between "try again in a second" (replay buffer still warming up, connection waiting for your approval) and "something is actually wrong."

## Configuration

Everything works with zero configuration when the app and this server run under the same user account. These environment variables exist for unusual setups:

| Variable | Purpose | Default |
|---|---|---|
| `DUALSTREAM_MCP_CLIENT_NAME` | The name shown in DualStream's consent prompt and client list | `claude-mcp` |
| `DUALSTREAM_CONTROL_PASSWORD` | Fallback credential if the app does not publish a pairing token | unset |
| `DUALSTREAM_WS_CONTROL_FILE` | Override the discovery file path | platform config dir |
| `DUALSTREAM_MCP_LOG_LEVEL` | `error`, `warn`, `info`, or `debug` | `info` |

Discovery reads `ws-control.json` from the app's config directory (`%APPDATA%\app.dualstream.io\` on Windows, `~/Library/Application Support/app.dualstream.io/` on macOS). The app writes this file on every start, before the control server reports ready.

## Troubleshooting

**Tools return `app_not_running`.** The DualStream app isn't open, or hasn't finished starting. Launch it; the server reconnects on its own the moment the app is up.

**Tools return `consent_pending`.** The connection is waiting for you. Approve it in the consent prompt inside DualStream (or under Settings, General, External Control).

**Tools return `authentication_required` or `authentication_failed`.** The app has auth enabled but this server couldn't obtain the token. Make sure the app and the server run as the same user. If you recently reset the pairing token, the reconnect handles it automatically; a stale `DUALSTREAM_CONTROL_PASSWORD` in your environment can also cause this.

**Something else is off.** Call `get_connection_status` first; it distinguishes "app not running" from auth, consent, and protocol problems. The server logs single-line JSON to stderr; set `DUALSTREAM_MCP_LOG_LEVEL=debug` for detail.

## Design notes

- **Local by design.** The control plane is loopback-only. A hosted or remote connector cannot reach it, and never should.
- **Event-driven, no timers.** In-flight requests settle only on a server response or socket close, never a wall-clock timeout. Reconnection is triggered by watching the discovery file the app rewrites on start; there are no polling loops.
- **stdout is the protocol channel.** All logging goes to stderr as single-line JSON.
- **Contract-pinned.** Responses are validated against the vendored control contract (see [`contract/`](contract/)); an app speaking a newer protocol version fails loudly with an upgrade message rather than misbehaving quietly.
- **Consent is enforced server-side.** The approval gate lives in the DualStream app, not in this package; a modified client gains nothing.

The [`contract/`](contract/) directory also contains authoring references an assistant can use directly: the recipe manifest format, the scene-composition guide (including layout patterns for the mobile canvas), the automations format, and [`PROTOCOL.md`](contract/PROTOCOL.md): a full method, event, and error-code reference generated from the contract fixture.

## Development

```bash
npm run typecheck   # strict TypeScript over src and tests
npm test            # unit + full MCP round-trips against a wire-faithful mock of the app
npm run build       # emit dist/
npm run smoke       # live end-to-end against a running DualStream app
                    # (switches a scene and back, saves one 10-second clip pair)
```

The mock control server in `test/` implements the real wire protocol, including the pairing handshake and consent flow, with an independent implementation of the auth algorithm, so the test suite genuinely cross-checks the client.

## About DualStream

DualStream is a streaming studio for creators who go live on desktop and mobile platforms at the same time: one pipeline, two canvases, every scene and widget rendered natively for both. Download it for Windows or macOS at [dualstream.gg](https://dualstream.gg).

## License

[Apache-2.0](LICENSE)