@vdoninja/mcp 0.4.1 → 0.4.2

package/README.md

@@ -1,324 +1,111 @@
 # VDO.Ninja MCP (`@vdoninja/mcp`)
 
-## TL;DR
+Give an MCP client live tools for exchanging messages, files, and small shared-state updates with peers on other computers. The MCP server manages active connections while your AI client calls the tools and consumes incoming events.
 
-This package gives an AI app a small set of tools for talking to another AI app. Two Codex, Claude, Cursor, or other MCP sessions can join the same VDO.Ninja room, send messages, exchange files, and keep shared task state without you building a new messaging server.
+WebRTC is the default peer transport. An optional [self-hosted HTTP relay](https://steveseguin.github.io/ninjamcp/http-relay.html) works when WebRTC is unavailable.
 
-If your AI client supports MCP and you want **tools it can call**, use this package. If you want an **always-on agent room with a local inbox**, use [`ninja-p2p`](https://github.com/steveseguin/ninja-p2p) instead.
+[Package](https://www.npmjs.com/package/@vdoninja/mcp) | [HTML guides](https://steveseguin.github.io/ninjamcp/guide.html#guides) | [Client setup](https://steveseguin.github.io/ninjamcp/client-config-examples.html) | [Tool reference](https://steveseguin.github.io/ninjamcp/mcp-tool-contract.html) | [Support](https://discord.vdo.ninja)
 
-**Best for:** MCP-native agent handoffs, file delivery, and small shared-state workflows.
+HTML guides are also included in the package's `docs/` folder for offline reading.
 
-**Not for:** a general VPN, permanent storage, or a large public chat network.
+## Get started
 
-Package: [`@vdoninja/mcp`](https://www.npmjs.com/package/@vdoninja/mcp) | [Quickstart](references/quickstart-and-compat.md) | [Client setup examples](references/client-config-examples.md) | [Support](https://discord.vdo.ninja)
+Install from a stable folder; the installer registers an absolute script path with your MCP client.
 
-## What It Looks Like
-
-One agent joins a room:
-
-```json
-{ "name": "vdo_connect", "arguments": { "room": "family_calendar", "stream_id": "planner" } }
-```
-
-A second agent joins the same room, then sends it a message:
-
-```json
-{ "name": "vdo_connect", "arguments": { "room": "family_calendar", "stream_id": "reviewer", "target_stream_id": "planner" } }
-{ "name": "vdo_send", "arguments": { "session_id": "<reviewer-session>", "data": { "text": "I checked the plan. Tuesday has a conflict." } } }
+```bash
+npm install @vdoninja/mcp
+npx vdon-mcp-install
 ```
 
-Those are normal MCP tool calls. This server translates them into VDO.Ninja SDK operations over WebRTC data channels.
-
-## Which VDO.Ninja Package Do I Need?
-
-| Your goal | Use |
-| --- | --- |
-| Add connect/send/file/state tools to an MCP client | **`@vdoninja/mcp`** |
-| Give agents a persistent room and local inbox | [`@vdoninja/ninja-p2p`](https://github.com/steveseguin/ninja-p2p) |
-| Build directly with WebRTC media or data channels | [`@vdoninja/sdk`](https://github.com/steveseguin/ninjasdk) |
-
-This package uses VDO.Ninja's existing room, discovery, and WebRTC behavior. It does not add signaling-server commands. `@vdoninja/sdk` and the Node WebRTC runtime install as package dependencies.
-
-## Why This MCP
-
-- Open source (`AGPL-3.0-only` with additional unmodified-distribution exception) and free to use.
-- Peer-to-peer first: no central relay required for normal data flow.
-- End-to-end encrypted WebRTC data transport (DTLS + SCTP data channels).
-- Reliable data channel mode available for ordered/loss-recovered delivery.
-- Low infrastructure overhead for bot-to-bot messaging and file sync.
-- Works for local LAN, remote internet peers, and hybrid topologies.
-- TURN support improves connectivity when direct P2P is blocked.
-- Good fit for multi-agent coordination without exposing plaintext payloads to a middlebox.
-
-## Common and Interesting Use Cases
-
-- AI swarm coordination: multiple agents in a private room exchanging tasks, state, and results.
-- Bot-to-bot handoff: one agent collects context, another executes, another validates, all over P2P.
-- Private file exchange: send logs, artifacts, prompts, and generated outputs directly between agents.
-- Human + AI war room: operator plus several bots sharing near-real-time status updates.
-- Edge + cloud hybrid: local on-device agent syncs with remote agents without standing up a custom tunnel.
-- Temporary secure collaboration spaces: ad-hoc rooms with join tokens and peer allowlists.
-- Cross-tool interop: Codex and Claude instances sharing updates through the same bridge contract.
-
-## Fun Agent-to-Agent Rooms
-
-These are real patterns teams are starting to use:
-
-- Claude Code to Codex CLI pair mode where one agent asks for a second opinion and gets patch/test feedback.
-- OpenClaw-to-OpenClaw specialist rooms where one local assistant asks another for tool-specific help.
-- Small LLM idea circles (3-5 agents) sharing proposals, critiques, and final votes.
-- Private "night shift" automation where bots sync status/events/files without broad network exposure.
-
-OpenClaw project link:
+The installer supports Codex and Claude Code. Use `--codex-only` or `--claude-only` to choose one, or follow the [manual setup examples](https://steveseguin.github.io/ninjamcp/client-config-examples.html) for other MCP clients. Your client launches the server; `npx vdon-mcp-server` starts it directly for manual use.
 
-- https://github.com/openclaw/openclaw
+Ask the first agent to connect:
 
-## Quick Example: Claude + Codex Helper Loop
-
-1. Claude-side session:
-```json
-{
-  "name": "vdo_connect",
-  "arguments": {
-    "room": "agent_help_room",
-    "stream_id": "claude_agent"
-  }
-}
-```
-
-2. Codex-side session:
 ```json
-{
-  "name": "vdo_connect",
-  "arguments": {
-    "room": "agent_help_room",
-    "stream_id": "codex_agent",
-    "target_stream_id": "claude_agent"
-  }
-}
+{ "name": "vdo_connect", "arguments": { "room": "project_room", "stream_id": "planner" } }
 ```
 
-3. Claude sends task:
-```json
-{
-  "name": "vdo_send",
-  "arguments": {
-    "session_id": "<claude_session>",
-    "data": {
-      "type": "help.request",
-      "task": "review patch for race condition"
-    }
-  }
-}
-```
+Ask the second agent to join and connect to the first:
 
-4. Codex replies:
 ```json
-{
-  "name": "vdo_send",
-  "arguments": {
-    "session_id": "<codex_session>",
-    "data": {
-      "type": "help.reply",
-      "summary": "found 2 edge cases",
-      "next_steps": ["add timeout guard", "add retry test"]
-    }
-  }
-}
-```
-
-## High-Value AI Advantages
-
-- Agents share messages/files/state directly, without opening broad machine-to-machine network access.
-- You can limit tool access with profiles (`core|file|state|full`) so each agent only gets what it needs.
-- Rooms can be short-lived: create for a task, then close when done.
-- Easy to start: no private subnet setup, no custom tunnel setup.
-- Works between browser peers and Node peers.
-- Data channels can be reliable and ordered, which is good for control messages.
-- Security options are built in: join tokens, stream allowlists, and session MAC checks.
-
-## Clever Real-World Patterns
-
-- Reviewer team: one writer agent, several reviewer agents, and one decider agent sharing feedback in the same room.
-- State recovery: agents can re-sync shared state with `vdo_state_sync` after reconnects.
-- File pipeline: one agent sends artifacts, another indexes them, another summarizes them.
-- Human override: a person can join the room to inspect progress and step in when needed.
-- Local-first flow: keep sensitive work local and only send required outputs to remote agents.
-- Burst jobs: create short-lived agent groups per task instead of running a permanent private network.
-
-## Compared with VPN Overlays (e.g., Tailscale)
-
-Where this MCP is often better for AI workflows:
-
-- You need agent-to-agent messaging/file/state, not full network access between hosts.
-- You want tool-level permissions instead of giving every machine broad private-network reach.
-- You want browser and Node agents working together quickly.
-- You want temporary collaboration sessions without managing a permanent virtual network.
-
-Where overlays are often better:
-
-- You need always-on private IP connectivity across many services.
-- You need many protocols (databases, SSH, internal web apps) over one virtual network.
-- You need centralized network policy and audit at the infrastructure layer.
-
-Practical framing:
-
-- This MCP is not a full replacement for Tailscale.
-- It is a strong complement for AI-native, data-channel-first collaboration.
-
-## Transport Truth
-
-- This is **WebRTC data transport**, not a generic TCP/SSH tunnel.
-- Data channels can run in reliable/ordered mode (SCTP over DTLS).
-- Default behavior is direct P2P when possible (great for LAN/local-network speed and low latency).
-- Privacy mode is opt-in via `force_turn=true`: this can reduce direct IP exposure between peers, but may reduce connection success in some environments.
-- TURN improves success on restrictive networks, but it is not a guaranteed firewall bypass for every enterprise policy.
-
-## Quickstart (No Clone)
-
-Install from a stable folder. The installer stores an absolute script path in Codex/Claude config.
-
-```bash
-npm i @vdoninja/mcp
-npx vdon-mcp-install
-npx vdon-mcp-server
+{ "name": "vdo_connect", "arguments": { "room": "project_room", "stream_id": "reviewer", "target_stream_id": "planner" } }
 ```
 
-When started directly in a terminal, `vdon-mcp-server` now prints a short "server running" banner and a first-call hint.
-
-First MCP call (recommended):
+Wait for the peer to appear in `vdo_sync_peers`, then send a message using the returned session ID:
 
 ```json
-{ "name": "vdo_capabilities", "arguments": {} }
+{ "name": "vdo_send", "arguments": { "session_id": "<reviewer-session>", "target": "planner", "data": { "text": "Please send me the plan to review." } } }
+{ "name": "vdo_receive", "arguments": { "session_id": "<planner-session>", "wait_ms": 1000 } }
 ```
 
-Useful install variants:
-
-- `npx vdon-mcp-install --codex-only`
-- `npx vdon-mcp-install --claude-only`
-- `npx vdon-mcp-install --preset core|file|state|secure-core|secure-full`
-- `npx vdon-mcp-install --uninstall`
-
-## Onboarding Guides
-
-- Operator quickstart: `references/quickstart-and-compat.md`
-- Client setup examples (Cursor, Gemini CLI, OpenCode): `references/client-config-examples.md`
-- First functional workflows (Codex-to-Codex and Claude-to-Claude): `references/client-config-examples.md`
-
-## Typical Workflows
-
-Message demo:
-
-```bash
-npx vdon-mcp-demo-message
-```
+These are MCP tool calls made by your AI client. A successful send means the transport accepted the payload; ask the recipient to reply when you need confirmation. Clients use `vdo_receive` to retrieve incoming events.
 
-Purpose: prove end-to-end room connect + message send/receive over data channels.
+See the [quickstart](https://steveseguin.github.io/ninjamcp/quickstart-and-compat.html) for connection troubleshooting and secure presets.
 
-File demo:
+## What you can do
 
-```bash
-npx vdon-mcp-demo-file
-```
+| Goal | Tools |
+| --- | --- |
+| Connect, discover peers, and inspect a room | `vdo_connect`, `vdo_sync_peers`, `vdo_status` |
+| Exchange messages and hand off work | `vdo_send`, `vdo_receive` |
+| Send and save artifacts with integrity checks and retries | `vdo_file_send_path`, `vdo_file_receive`, `vdo_file_save` |
+| Share small task state and recover a snapshot | `vdo_state_set`, `vdo_state_get`, `vdo_state_sync` |
+| Inspect available tools and transport behavior | `vdo_capabilities` |
+| End a session | `vdo_disconnect` |
 
-Purpose: prove reliable chunked file transfer and receive path.
+Choose a tool profile with `npx vdon-mcp-install --preset core`, `file`, or `state`. The `full` profile includes all tools. Use `secure-core` or `secure-full` with a configured `VDON_MCP_JOIN_TOKEN_SECRET` for join-token enforcement and session MACs. The [tool reference](https://steveseguin.github.io/ninjamcp/mcp-tool-contract.html) describes peer allowlists and other connection controls.
 
-Live network mode (instead of local fake mode):
+## Choose a connection
 
-```bash
-MCP_DEMO_FAKE=0 npx vdon-mcp-demo-message
-MCP_DEMO_FAKE=0 npx vdon-mcp-demo-file
-```
+| Path | When to use it |
+| --- | --- |
+| WebRTC | Default for direct peer messaging and files. Payloads travel over encrypted data channels. |
+| WebRTC with `force_turn: true` | Route through TURN when you need it. TURN still requires a WebRTC runtime and network support. |
+| HTTP relay with `transport: "http"` | Use a relay you operate when WebRTC cannot run or connect. Follow the [relay setup guide](https://steveseguin.github.io/ninjamcp/http-relay.html). |
 
-Privacy-first relay mode (opt-in):
+The HTTP relay uses encrypted room messages, POST, and long polling. Both peers must select HTTP and share the relay settings. It has bounded in-memory replay, with visible events for lost history; use an application inbox when work must survive process restarts or long periods offline. Room-key holders can decrypt the room's traffic, so use separate rooms for separate trust groups.
 
-```bash
-MCP_DEMO_FAKE=0 MCP_DEMO_FORCE_TURN=1 npx vdon-mcp-demo-message
-MCP_DEMO_FAKE=0 MCP_DEMO_FORCE_TURN=1 npx vdon-mcp-demo-file
-```
+The native WebRTC dependency installs by default. For HTTP-only machines, install with `npm install @vdoninja/mcp --omit=optional` and configure a relay. Ordinary room sessions select their transport explicitly; the optional browser adapter also supports automatic routing.
 
-## Security and Least Privilege
+## Where this fits
 
-Use secure controls where needed:
+| Your goal | Use |
+| --- | --- |
+| Connect an MCP client to live peers and exchange messages, files, and state | **This package** |
+| Keep a team connected between agent turns, with local inboxes, handoffs, wake hooks, and a dashboard | [ninja-p2p](https://github.com/steveseguin/ninja-p2p) |
+| Build directly with WebRTC audio, video, or data | [VDO.Ninja SDK](https://github.com/steveseguin/ninjasdk) |
 
-- `join_token` and `join_token_secret`
-- `enforce_join_token: true`
-- `allow_peer_stream_ids: [...]`
-- `require_session_mac: true`
+Choose Ninja MCP when your client should manage an active interaction through MCP tools. Choose ninja-p2p when a background sidecar should retain incoming work and notify an agent between turns. Ninja MCP's ordinary event queues and shared state live in the server process; use ninja-p2p for persistent agent inbox workflows.
 
-Server profile scoping:
+Both use the VDO.Ninja SDK, but their message and file protocols differ. A common room name alone does not connect their higher-level workflows. A dedicated adapter is planned; until then, use matching packages on both ends of each workflow.
 
-```bash
-VDON_MCP_TOOL_PROFILE=core npx vdon-mcp-server
-```
+Ninja MCP's direction is live access to remote peers, tools, and perception through MCP. ninja-p2p's direction is the continuing team workspace and its handoffs. See [Ninja MCP's direction](https://steveseguin.github.io/ninjamcp/direction.html) and [ninja-p2p's direction](https://github.com/steveseguin/ninja-p2p/blob/main/docs/north-star.md).
 
-Set `VDON_MCP_JOIN_TOKEN_SECRET` before secure preset installs/runtime.
+## Optional remote Chrome
 
-## Compatibility
+The [browser worker](https://steveseguin.github.io/ninjamcp/browser-worker.html) lets agents share an isolated, headless Chrome tab over WebRTC or your HTTP relay. Each agent has a separate credential; one controller holds the tab while others observe. Tools return page snapshots and screenshots. Hosts can also enable live tab audio/video through the VDO.Ninja SDK.
 
-- Codex MCP CLI
-- Claude Code MCP CLI
-- Other MCP clients that support stdio command servers
+Install the optional browser packages on the host, run `vdon-mcp-browser --setup`, and register it as a separate MCP server. The [setup guide](https://steveseguin.github.io/ninjamcp/browser-worker.html) covers connection checks, automatic WebRTC/HTTP routing, control handoff, and private viewing links.
 
-Manual command wiring example:
+The optional [browser companion](https://steveseguin.github.io/ninjamcp/browser-agent.html) adds a speaking agent with microphone, browser-frame sharing, interruption, and control permissions. It uses an OpenAI API key; ordinary MCP tools and live browser viewing do not require a model account.
 
-```json
-{
-  "name": "vdo-ninja-mcp",
-  "command": "node",
-  "args": ["node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"]
-}
-```
+## Optional remote SSApp
 
-## Local Development (This Repo)
+For an existing Social Stream Ninja Standalone instance, the optional [SSApp bridge](https://steveseguin.github.io/ninjamcp/ssapp-integration.html)
+forwards its MCP tools, screenshots, and input over WebRTC or the HTTP relay. Agents use separate credentials
+and take turns controlling the app; SSApp keeps its existing sessions and windows.
 
-Start server:
+## Run from a checkout
 
 ```bash
+npm install
 node scripts/vdo-mcp-server.js
 ```
 
-Install registration from local checkout:
-
-```bash
-node scripts/install-mcp.js
-```
-
-## Testing
-
-Fast product-focused suite:
-
-```bash
-node tests/run-mcp-tests-minimal.js
-```
-
-Full suite:
-
-```bash
-node tests/run-mcp-tests.js
-```
-
-Live diagnostics:
-
-```bash
-node tests/live-turn-smoke.js
-node tests/live-turn-soak.js
-node tests/live-turn-matrix.js
-node tests/live-turn-preset-matrix.js
-```
-
-## Key Files
-
-- `scripts/vdo-mcp-server.js` (stdio MCP server)
-- `scripts/vdo-mcp-streamable-http.js` (streamable HTTP bridge)
-- `scripts/install-mcp.js` (Codex/Claude installer automation)
-- `references/quickstart-and-compat.md` (operator quickstart)
-- `references/mcp-tool-contract.md` (tool semantics and contracts)
-- `server.json` (MCP discovery manifest metadata)
+`npm run check` runs the existing suite. `npm run demo:message` and `npm run demo:file` run local simulated workflows; set `MCP_DEMO_FAKE=0` to use live WebRTC peers. See [advanced diagnostics](https://steveseguin.github.io/ninjamcp/advanced-diagnostics.html) for live network checks.
 
 ## License
 
-AGPL-3.0-only with additional unmodified-distribution exception.
+MIT. Copyright (c) 2026 Steve Seguin.
 
-- Main license text: `LICENSE`
-- Additional permission: `LICENSE-SDK-EXCEPTION`
+The `@vdoninja/sdk` dependency has its own terms: MPL-2.0, with some separately marked wrappers and adapters under MIT. Preserve its copyright and license notices when redistributing it and comply with the MPL-2.0 for covered SDK files. Those terms do not require the rest of an application to use the MPL-2.0.

package/assets/browser-agent/audio-worklet.js

@@ -0,0 +1,17 @@
+'use strict';
+class NinjaMicrophone extends AudioWorkletProcessor {
+  constructor() { super(); this.samples = new Int16Array(2400); this.offset = 0; }
+  process(inputs) {
+    const input = inputs[0] && inputs[0][0];
+    if (!input) return true;
+    for (const value of input) {
+      this.samples[this.offset++] = Math.round(Math.max(-1, Math.min(1, value)) * 32767);
+      if (this.offset === this.samples.length) {
+        this.port.postMessage(this.samples.buffer, [this.samples.buffer]);
+        this.samples = new Int16Array(2400); this.offset = 0;
+      }
+    }
+    return true;
+  }
+}
+registerProcessor('ninja-microphone', NinjaMicrophone);

package/assets/browser-agent/client.js

@@ -0,0 +1,124 @@
+'use strict';
+const $ = (id) => document.getElementById(id);
+const token = location.hash.slice(1);
+history.replaceState(null, '', location.pathname);
+const socket = new WebSocket(`ws://${location.host}/operator?token=${encodeURIComponent(token)}`);
+let connected = false, micStream, micContext, micNode, outputContext, sdk, mediaStream;
+let micEpoch = 0, mediaEpoch = 0, playbackEpoch = 0, playbackPlayed = 0, playbackEnd = 0, playbackItem = null;
+const sources = new Map();
+const send = (event) => { if (socket.readyState === WebSocket.OPEN && socket.bufferedAmount < 1000000) socket.send(JSON.stringify(event)); };
+const log = (text) => { $('log').textContent = ($('log').textContent + text).slice(-20000); $('log').scrollTop = $('log').scrollHeight; };
+function sharing() {
+  send({ type: 'permissions', microphone: connected && $('microphone').checked, share: $('frames').checked, control: $('control').checked });
+  const parts = [];
+  if (connected && $('microphone').checked) parts.push('microphone');
+  if (connected && $('frames').checked) parts.push('browser frames and page content');
+  $('sharing').textContent = parts.length ? `Sending ${parts.join(' + ')} to OpenAI.${$('control').checked ? ' Browser control enabled.' : ''}` : 'Microphone and browser sharing are off.';
+}
+async function stopMic() {
+  micEpoch++;
+  if (micNode) micNode.disconnect(); micNode = null;
+  if (micStream) micStream.getTracks().forEach((track) => track.stop()); micStream = null;
+  const context = micContext; micContext = null;
+  if (context) await context.close().catch(() => {});
+}
+async function startMic() {
+  if (!connected || !$('microphone').checked || micStream) return;
+  const epoch = ++micEpoch;
+  try {
+    const stream = await navigator.mediaDevices.getUserMedia({ audio: { echoCancellation: true, noiseSuppression: true }, video: false });
+    if (epoch !== micEpoch || !connected || !$('microphone').checked) { stream.getTracks().forEach((track) => track.stop()); return; }
+    micStream = stream;
+    const context = new AudioContext({ sampleRate: 24000 });
+    micContext = context;
+    await context.audioWorklet.addModule('/audio-worklet.js');
+    if (epoch !== micEpoch) return;
+    micNode = new AudioWorkletNode(micContext, 'ninja-microphone');
+    micNode.port.onmessage = (event) => {
+      if (!connected || !$('microphone').checked) return;
+      send({ type: 'audio', data: btoa(String.fromCharCode(...new Uint8Array(event.data))) });
+    };
+    const silent = micContext.createGain(); silent.gain.value = 0;
+    micContext.createMediaStreamSource(micStream).connect(micNode); micNode.connect(silent); silent.connect(micContext.destination);
+    await micContext.resume();
+  } catch (error) { if (epoch !== micEpoch) return; $('error').textContent = `Microphone: ${error.message}`; $('microphone').checked = false; await stopMic(); sharing(); }
+}
+function stopPlayback(report = true) {
+  playbackEpoch++;
+  let played = playbackPlayed;
+  if (outputContext) for (const segment of sources.values()) played += Math.max(0, Math.min(segment.duration, outputContext.currentTime - segment.start));
+  if (playbackItem && report) send({ type: 'playback', item_id: playbackItem, played_ms: played * 1000 });
+  for (const source of sources.keys()) { source.onended = null; try { source.stop(); } catch (_) {} }
+  sources.clear(); playbackItem = null; playbackEnd = 0; playbackPlayed = 0;
+}
+async function audio(event) {
+  if (!connected) return;
+  const epoch = playbackEpoch;
+  outputContext = outputContext || new AudioContext({ sampleRate: 24000 });
+  await outputContext.resume();
+  if (epoch !== playbackEpoch || !connected) return;
+  const bytes = Uint8Array.from(atob(event.data), (value) => value.charCodeAt(0));
+  const samples = new Int16Array(bytes.buffer);
+  const buffer = outputContext.createBuffer(1, samples.length, 24000);
+  const data = buffer.getChannelData(0); for (let i = 0; i < samples.length; i++) data[i] = samples[i] / 32768;
+  if (playbackItem !== event.item_id) { stopPlayback(false); playbackItem = event.item_id; playbackEnd = outputContext.currentTime; }
+  if (playbackEnd - outputContext.currentTime > 30) { send({ type: 'interrupt' }); stopPlayback(); return; }
+  const source = outputContext.createBufferSource(); source.buffer = buffer; source.connect(outputContext.destination);
+  const start = Math.max(outputContext.currentTime, playbackEnd); source.start(start); playbackEnd = start + buffer.duration;
+  sources.set(source, { start, duration: buffer.duration }); source.onended = () => { if (sources.delete(source)) playbackPlayed += buffer.duration; };
+}
+async function stopWatching() {
+  mediaEpoch++;
+  const viewer = sdk; sdk = null;
+  if (mediaStream) mediaStream.getTracks().forEach((track) => track.stop()); mediaStream = null;
+  $('video').srcObject = null; $('video').hidden = true; $('video').muted = true;
+  $('watch').disabled = false; $('unwatch').hidden = true; $('sound').hidden = true;
+  $('placeholder').hidden = !$('preview').hidden;
+  if (viewer) await viewer.disconnect().catch(() => {});
+}
+async function watch(media) {
+  if (!media.enabled) throw new Error('Live browser media is off or unavailable. Enable media on the host, or share browser frames for HTTP-compatible vision.');
+  await stopWatching();
+  const epoch = mediaEpoch;
+  $('watch').disabled = true; $('unwatch').hidden = false; $('sound').hidden = false;
+  const viewer = new VDONinjaSDK({ password: media.password, ...(media.signaling_host ? { host: media.signaling_host } : {}) });
+  sdk = viewer;
+  const stream = new MediaStream(); mediaStream = stream; $('video').srcObject = stream;
+  viewer.addEventListener('track', (event) => { if (epoch !== mediaEpoch) { event.detail.track.stop(); return; } stream.addTrack(event.detail.track); $('video').hidden = false; $('preview').hidden = true; $('placeholder').hidden = true; });
+  await viewer.connect(); if (epoch !== mediaEpoch) { await viewer.disconnect(); return; }
+  await viewer.joinRoom({ room: media.room, password: media.password }); if (epoch !== mediaEpoch) { await viewer.disconnect(); return; }
+  await viewer.view(media.stream_id, { audio: true, video: true });
+}
+socket.onmessage = async ({ data }) => {
+  try {
+    const event = JSON.parse(data);
+    if (event.type === 'hello') { $('identity').textContent = `${event.worker} · ${event.transport} · ${event.provider} / ${event.model}`; if (!event.key_available) $('error').textContent = 'Set OPENAI_API_KEY before starting this operator server to enable the agent. Browser checks and live viewing still work.'; }
+    else if (event.type === 'status') {
+      connected = !!event.connected; $('status').textContent = connected ? 'Agent connected' : 'Stopped'; $('start').disabled = connected;
+      if (connected) { sharing(); await startMic(); } else { await stopMic(); stopPlayback(); $('microphone').checked = false; $('frames').checked = false; $('control').checked = false; sharing(); }
+      if (event.message) log(event.message + '\n');
+    } else if (event.type === 'audio') await audio(event);
+    else if (event.type === 'interrupt') stopPlayback();
+    else if (event.type === 'text_delta') log(event.text);
+    else if (event.type === 'turn_done') log('\n');
+    else if (event.type === 'tool') log(`\n${event.name}: ${event.stage}${event.route ? ` (${event.route})` : ''}\n`);
+    else if (event.type === 'error') { $('error').textContent = event.message; $('start').disabled = connected; }
+    else if (event.type === 'worker') log(`Worker authenticated · ${event.role} · ${event.route}\n`);
+    else if (event.type === 'preview') { if ($('video').hidden) { $('preview').src = `data:${event.mime};base64,${event.data}`; $('preview').hidden = false; $('placeholder').hidden = true; } $('frameTime').textContent = `Frame sent to OpenAI · ${event.captured_at}`; }
+    else if (event.type === 'media') await watch(event);
+  } catch (error) { $('error').textContent = error.message; }
+};
+socket.onclose = () => { connected = false; stopMic(); stopPlayback(false); stopWatching(); $('status').textContent = 'Disconnected'; $('error').textContent = 'The local operator disconnected. Reopen its private URL to reconnect.'; $('sharing').textContent = 'Sharing stopped.'; };
+$('start').onclick = async () => { outputContext = outputContext || new AudioContext({ sampleRate: 24000 }); await outputContext.resume(); $('error').textContent = ''; $('start').disabled = true; send({ type: 'start' }); };
+$('stop').onclick = () => { stopPlayback(); send({ type: 'stop' }); stopMic(); };
+$('interrupt').onclick = () => { stopPlayback(); send({ type: 'interrupt' }); };
+$('microphone').onchange = async () => { sharing(); if ($('microphone').checked) await startMic(); else await stopMic(); };
+$('frames').onchange = () => { if (!$('frames').checked) $('control').checked = false; sharing(); if (connected && $('frames').checked) send({ type: 'frame' }); };
+$('control').onchange = () => { if ($('control').checked) $('frames').checked = true; sharing(); };
+$('check').onclick = () => send({ type: 'check' });
+$('watch').onclick = () => send({ type: 'watch' });
+$('unwatch').onclick = stopWatching;
+$('sound').onclick = () => { $('video').muted = !$('video').muted; $('sound').textContent = $('video').muted ? 'Hear browser audio' : 'Mute browser audio'; };
+$('message').onsubmit = (event) => { event.preventDefault(); if (!connected) { $('error').textContent = 'Start the agent before sending a message.'; return; } const text = $('text').value.trim(); if (!text) return; stopPlayback(); log(`\nYou: ${text}\n`); send({ type: 'text', text }); $('text').value = ''; };
+setInterval(() => { if (connected && $('frames').checked) send({ type: 'frame' }); }, 3000);
+window.addEventListener('pagehide', () => { stopMic(); if (sdk) sdk.disconnect(); socket.close(); });

package/assets/browser-agent/index.html

@@ -0,0 +1,50 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Ninja · Browser companion</title>
+<style>
+:root { color-scheme: dark; font: 16px/1.5 system-ui, sans-serif; background: #10151e; color: #e9eef7; }
+body { margin: 0 auto; padding: 28px; max-width: 1160px; }
+header { display: flex; align-items: center; justify-content: space-between; gap: 20px; }
+h1 { font-size: 26px; margin: 0; } h2 { font-size: 17px; margin-top: 0; }
+.muted { color: #a9b7ca; } .status { border: 1px solid #455369; border-radius: 20px; padding: 5px 12px; }
+.layout { display: grid; grid-template-columns: minmax(0, 1fr) 320px; gap: 20px; margin-top: 24px; }
+.panel { background: #182130; border: 1px solid #2f4058; border-radius: 14px; padding: 20px; }
+.stage { display: grid; place-items: center; min-height: 300px; background: #090d13; border-radius: 9px; overflow: hidden; }
+.stage img, .stage video { width: 100%; max-height: 450px; object-fit: contain; }
+[hidden] { display: none !important; }
+label { display: block; margin: 16px 0; } input[type=checkbox] { width: 18px; height: 18px; vertical-align: middle; margin-right: 8px; accent-color: #6dcfbc; }
+button, input[type=text] { font: inherit; border-radius: 7px; border: 1px solid #50647e; padding: 9px 12px; }
+button { background: #283b53; color: white; cursor: pointer; } button:hover { background: #345471; }
+button:disabled { opacity: .45; cursor: default; } button.primary { background: #257c6f; } button.stop { background: #773c48; }
+.row { display: flex; flex-wrap: wrap; gap: 8px; margin: 12px 0; }
+form { display: flex; gap: 8px; margin-top: 16px; } input[type=text] { min-width: 0; flex: 1; background: #111923; color: white; }
+#log { white-space: pre-wrap; max-height: 260px; overflow: auto; font-size: 14px; }
+#sharing { color: #8ee5ce; min-height: 48px; } #error { color: #ffc4bb; min-height: 24px; }
+small { display: block; color: #a9b7ca; }
+@media(max-width: 780px) { .layout { grid-template-columns: 1fr; } body { padding: 16px; } header { align-items: start; } }
+</style>
+<header><div><h1>Ninja browser companion</h1><div class="muted" id="identity">Connecting to the local operator…</div></div><span class="status" id="status">Stopped</span></header>
+<div class="layout">
+  <main class="panel">
+    <div class="stage"><span id="placeholder" class="muted">Choose a browser view to begin.</span><img id="preview" alt="Latest shared browser frame" hidden><video id="video" autoplay muted playsinline hidden></video></div>
+    <div class="row"><button id="watch">Watch live browser</button><button id="unwatch" hidden>Stop watching</button><button id="sound" hidden>Hear browser audio</button><button id="check">Check worker</button></div>
+    <small id="frameTime">Live viewing uses VDO.Ninja. Model sharing is controlled separately.</small>
+    <form id="message"><input id="text" type="text" maxlength="8000" placeholder="Ask your browser companion…" aria-label="Message to the agent"><button id="send">Send</button></form>
+    <p id="error" role="alert"></p><div id="log" aria-live="polite"></div>
+  </main>
+  <aside class="panel">
+    <h2>Talk and work together</h2>
+    <p class="muted">Start an OpenAI voice session, then choose what the agent can hear, see, and control.</p>
+    <label><input id="microphone" type="checkbox">Share my microphone</label>
+    <label><input id="frames" type="checkbox">Share browser frames</label>
+    <label><input id="control" type="checkbox">Allow browser control</label>
+    <div id="sharing">Microphone and browser sharing are off.</div>
+    <div class="row"><button id="start" class="primary">Start agent</button><button id="interrupt">Interrupt</button><button id="stop" class="stop">End session</button></div>
+    <small>Shared microphone audio, browser images, and tool results go to OpenAI. Browser frames update about every three seconds. Control follows the worker's tab lease. Interrupt stops speech and queued actions; an action already sent may finish.</small>
+    <p><small>AI-generated voice. No local recording. Sessions end after 15 minutes. Watching the SDK stream alone does not send it to OpenAI.</small></p>
+  </aside>
+</div>
+<script src="/sdk.js"></script><script src="/client.js"></script>
+</html>

package/assets/cloudflare/worker-proxy.js

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+
 /**
  * Cloudflare Worker proxy template for a remote MCP HTTP endpoint.
  *

package/docs/404.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="en" data-icons="/ninjamcp/assets/icons.svg">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Page not found · VDO.Ninja MCP</title>
+  <meta name="robots" content="noindex">
+  <meta name="color-scheme" content="light dark">
+  <link rel="icon" href="/ninjamcp/favicon.ico" sizes="32x32">
+  <link rel="icon" href="/ninjamcp/assets/favicon.svg" type="image/svg+xml">
+  <link rel="apple-touch-icon" href="/ninjamcp/assets/apple-touch-icon.png">
+  <link rel="stylesheet" href="/ninjamcp/assets/site.css">
+</head>
+<body>
+<main class="hero" style="min-height:100vh;display:grid;place-items:center;padding:24px">
+  <div class="wrap">
+    <a href="/ninjamcp/" aria-label="VDO.Ninja MCP home"><img src="/ninjamcp/assets/logo.svg" alt="" width="64" height="64" style="margin:0 auto"></a>
+    <h1 style="font-size:clamp(36px,6vw,56px);max-width:none">This line is dead.</h1>
+    <p class="lede">The page you asked for isn't here. It may have moved when the docs were reorganized.</p>
+    <div class="hero-actions">
+      <a class="btn btn-dark btn-lg" href="/ninjamcp/">Home</a>
+      <a class="btn btn-lg" href="/ninjamcp/guide.html">Documentation</a>
+      <a class="btn btn-lg" href="/ninjamcp/#faq">FAQ</a>
+    </div>
+  </div>
+</main>
+</body>
+</html>