@vdoninja/mcp 0.4.0 → 0.4.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Seguin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# VDO.Ninja MCP (`@vdoninja/mcp`)
+
+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.
+
+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.
+
+[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)
+
+HTML guides are also included in the package's `docs/` folder for offline reading.
+
+## Get started
+
+Install from a stable folder; the installer registers an absolute script path with your MCP client.
+
+```bash
+npm install @vdoninja/mcp
+npx vdon-mcp-install
+```
+
+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.
+
+Ask the first agent to connect:
+
+```json
+{ "name": "vdo_connect", "arguments": { "room": "project_room", "stream_id": "planner" } }
+```
+
+Ask the second agent to join and connect to the first:
+
+```json
+{ "name": "vdo_connect", "arguments": { "room": "project_room", "stream_id": "reviewer", "target_stream_id": "planner" } }
+```
+
+Wait for the peer to appear in `vdo_sync_peers`, then send a message using the returned session ID:
+
+```json
+{ "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 } }
+```
+
+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.
+
+See the [quickstart](https://steveseguin.github.io/ninjamcp/quickstart-and-compat.html) for connection troubleshooting and secure presets.
+
+## What you can do
+
+| 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` |
+
+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.
+
+## Choose a connection
+
+| 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). |
+
+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.
+
+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.
+
+## Where this fits
+
+| 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) |
+
+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.
+
+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.
+
+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).
+
+## Optional remote Chrome
+
+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.
+
+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.
+
+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.
+
+## Optional remote SSApp
+
+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.
+
+## Run from a checkout
+
+```bash
+npm install
+node scripts/vdo-mcp-server.js
+```
+
+`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
+
+MIT. Copyright (c) 2026 Steve Seguin.
+
+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/SKILL.md

@@ -27,13 +27,14 @@ Use this skill to run VDO.Ninja as an MCP data bridge in Codex, Claude Code, and
 ## Fast Path
 
 1. Install MCP registration:
-`npm i @vdoninja/mcp @roamhq/wrtc`
+`npm i @vdoninja/mcp`
 
 2. Register for Codex/Claude:
 `npx vdon-mcp-install`
 
 3. Start server:
 `npx vdon-mcp-server`
+If run directly in a terminal, it prints a short running banner and a first-call hint.
 
 4. Optional least-privilege tool profile:
 `VDON_MCP_TOOL_PROFILE=core|file|state|full npx vdon-mcp-server`
@@ -80,11 +81,12 @@ For secure presets, set `VDON_MCP_JOIN_TOKEN_SECRET` before install/runtime.
 
 - Product test bar: `npm run test:mcp`
 - Full engineering suite: `npm run test:mcp:all`
-- Live diagnostics (optional): `MCP/references/advanced-diagnostics.md`
+- Live diagnostics (optional): `references/advanced-diagnostics.md`
 
 ## References
 
-- Operator quickstart: `MCP/references/quickstart-and-compat.md`
-- Tool contract: `MCP/references/mcp-tool-contract.md`
-- Transport notes: `MCP/references/vdo-ninja-p2p-data-notes.md`
-- Registry manifest: `MCP/server.json`
+- Operator quickstart: `references/quickstart-and-compat.md`
+- Client config examples: `references/client-config-examples.md`
+- Tool contract: `references/mcp-tool-contract.md`
+- Transport notes: `references/vdo-ninja-p2p-data-notes.md`
+- Registry manifest: `server.json`

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>

package/docs/advanced-diagnostics.html

@@ -0,0 +1,101 @@
+<!doctype html>
+<html lang="en" data-icons="assets/icons.svg">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Advanced diagnostics · VDO.Ninja MCP</title>
+  <meta name="description" content="Check network connectivity and diagnose connection reliability.">
+  <meta name="color-scheme" content="light dark">
+  <link rel="canonical" href="https://steveseguin.github.io/ninjamcp/advanced-diagnostics.html">
+  <link rel="icon" href="assets/favicon.svg" type="image/svg+xml">
+  <link rel="stylesheet" href="assets/site.css">
+  <script>document.documentElement.classList.add('js');</script>
+</head>
+<body class="reference-page">
+<a class="skip-link" href="#main">Skip to content</a>
+<header class="nav">
+<div class="wrap">
+<a aria-label="VDO.Ninja MCP home" class="brand" href="./">
+<img alt="" height="28" src="assets/logo.svg" width="28"/>
+<span>VDO.Ninja <small>MCP</small></span>
+</a>
+<nav aria-label="Primary" class="nav-links">
+<a href="./#how">How it works</a>
+<a href="./#privacy">Privacy</a>
+<a href="./#tools">Tools</a>
+<a href="./#faq">FAQ</a>
+<a aria-current="page" href="guide.html">Docs</a>
+</nav>
+<div class="nav-cta">
+<a class="btn btn-ghost" href="https://github.com/steveseguin/ninjamcp"><svg aria-hidden="true" class="icon-sm"><use href="assets/icons.svg#i-github"></use></svg>GitHub</a>
+<a class="btn btn-dark" href="https://www.npmjs.com/package/@vdoninja/mcp"><svg aria-hidden="true" class="icon-sm"><use href="assets/icons.svg#i-package"></use></svg>npm</a>
+</div>
+<button aria-expanded="false" aria-label="Menu" class="nav-toggle" type="button"><svg aria-hidden="true" class="icon"><use href="assets/icons.svg#i-menu"></use></svg></button>
+</div>
+</header>
+<div class="docs">
+  <aside class="sidebar" aria-label="Documentation" id="guide-contents"><h5>Documentation</h5><a href="guide.html">Getting started</a><h5>On this page</h5><a href="#overview">Overview</a><a href="#live-test-commands">Live Test Commands</a><a href="#preset-matrix-notes">Preset Matrix Notes</a><a href="#soak-matrix-knobs">Soak / Matrix Knobs</a><a href="#important">Important</a><h5>More guides</h5><a href="quickstart-and-compat.html">Quickstart</a><a href="client-config-examples.html">Client configuration</a><a href="http-relay.html">HTTP relay</a><a href="browser-worker.html">Remote Chrome</a><a href="browser-agent.html">Voice companion</a><a href="ssapp-integration.html">Remote SSApp</a><a href="mcp-tool-contract.html">Tool contract</a><a href="vdo-ninja-p2p-data-notes.html">WebRTC data notes</a><a href="direction.html">Project direction</a></aside>
+  <main class="docs-main" id="main">
+    <button class="btn docs-toggle" type="button" aria-controls="guide-contents" aria-expanded="false">Contents</button>
+    <header>
+      <p class="guide-breadcrumb"><a href="guide.html">Documentation</a> / Advanced diagnostics</p>
+      <h1 id="vdoninja-mcp-advanced-diagnostics">VDO.Ninja MCP Advanced Diagnostics</h1>
+      <p class="guide-format"><a href="https://github.com/steveseguin/ninjamcp/blob/main/references/advanced-diagnostics.md">Read in Markdown</a></p>
+    </header>
+    <section class="doc-section guide-intro" id="overview">
+<p>This page is optional. Use it when you are debugging reliability or network edge cases.</p>
+</section><section class="doc-section" id="live-test-commands"><h2>Live Test Commands</h2>
+<pre><code class="lang-sh">LIVE_VDO_TEST=1 npm run test:mcp:live
+LIVE_VDO_TEST=1 npm run test:mcp:soak
+LIVE_VDO_TEST=1 npm run test:mcp:matrix
+LIVE_VDO_TEST=1 npm run test:mcp:preset:matrix
+LIVE_VDO_TEST=1 SOAK_MATRIX_SWEEP_RUNS=20 npm run test:mcp:matrix:sweep
+</code></pre>
+<p>Secure preset matrix:</p>
+<pre><code class="lang-sh">LIVE_VDO_TEST=1 VDON_MCP_JOIN_TOKEN_SECRET=change_me npm run test:mcp:preset:matrix
+</code></pre>
+</section><section class="doc-section" id="preset-matrix-notes"><h2>Preset Matrix Notes</h2>
+<ul>
+<li><code>PRESET_MATRIX_ADAPTIVE_FALLBACK=1</code> enables candidate fallback.</li>
+<li><code>PRESET_MATRIX_ALLOW_DIRECT_FALLBACK=1</code> allows direct fallback after TURN candidates.</li>
+<li><code>PRESET_MATRIX_STRICT=1</code> fails process when any profile fails.</li>
+<li><code>PRESET_CONNECT_ATTEMPTS</code>, <code>PRESET_CONNECT_TIMEOUT_MS</code>, and <code>PRESET_CHANNEL_READY_TIMEOUT_MS</code> control connect behavior.</li>
+</ul>
+<p>Artifacts are written to:</p>
+<ul>
+<li><code>tests/artifacts/latest-preset-matrix-report.json</code></li>
+<li><code>tests/artifacts/latest-preset-matrix-summary.txt</code></li>
+<li><code>tests/artifacts/history/preset-matrix-*.json</code></li>
+<li><code>tests/artifacts/history/preset-matrix-*.txt</code></li>
+</ul>
+</section><section class="doc-section" id="soak-matrix-knobs"><h2>Soak / Matrix Knobs</h2>
+<ul>
+<li>Smoke: <code>LIVE_SMOKE_RETRIES</code>, <code>LIVE_SMOKE_TIMEOUT_MS</code></li>
+<li>Soak: <code>SOAK_RETRIES</code>, <code>SOAK_TIMEOUT_MS</code></li>
+<li>Matrix: <code>SOAK_MATRIX_PROFILE_RETRIES</code>, <code>SOAK_MATRIX_PROFILE_TIMEOUT_MS</code></li>
+<li>Sweep: <code>SOAK_MATRIX_SWEEP_RUNS</code>, <code>SOAK_MATRIX_SWEEP_TIMEOUT_MS</code>, <code>SOAK_MATRIX_SWEEP_MIN_SUCCESS_RATE</code></li>
+</ul>
+</section><section class="doc-section" id="important"><h2>Important</h2>
+<ul>
+<li>WebRTC data channels are the transport.</li>
+<li>TURN helps reachability but is not a universal bypass for all enterprise firewall policies.</li>
+</ul></section>
+    <nav class="pager" aria-label="More documentation"><a href="guide.html#guides"><small>Keep reading</small><b>Browse all guides</b></a><a href="https://discord.vdo.ninja"><small>Need help?</small><b>Ask on Discord</b></a></nav>
+  </main>
+</div>
+<footer class="footer">
+<div class="wrap">
+<a class="brand" href="./"><img alt="" height="24" src="assets/logo.svg" width="24"/><span>VDO.Ninja <small>MCP</small></span></a>
+<nav aria-label="Footer">
+<a href="./">Home</a>
+<a href="https://github.com/steveseguin/ninjamcp">GitHub</a>
+<a href="https://www.npmjs.com/package/@vdoninja/mcp">npm</a>
+<a href="https://discord.vdo.ninja">Discord</a>
+<a href="https://vdo.ninja">VDO.Ninja</a>
+</nav>
+<span>MIT · © 2026 Steve Seguin</span>
+</div>
+</footer>
+<script src="assets/site.js" defer></script>
+</body>
+</html>

package/docs/assets/favicon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="VDO.Ninja MCP">
+  <rect width="64" height="64" rx="16" fill="#14161b"/>
+  <path d="M8 27.5c7.5-4 15.5-6 24-6s16.5 2 24 6v9c-7.5 4-15.5 6-24 6s-16.5-2-24-6z" fill="#3d5afe"/>
+  <circle cx="21" cy="32" r="5" fill="#fff"/>
+  <circle cx="43" cy="32" r="5" fill="#fff"/>
+  <path d="M27.8 32h8.6" stroke="#fff" stroke-width="2.4" stroke-linecap="round" stroke-dasharray="0.1 4.1"/>
+</svg>

package/docs/assets/how-it-works.svg

@@ -0,0 +1,62 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 350" width="900" height="350" role="img" aria-label="Two agents, each with a local VDO.Ninja MCP server, connected by a direct encrypted WebRTC data channel. A handshake server helps them connect; a TURN relay is a fallback.">
+  <title>How VDO.Ninja MCP works</title>
+  <style>
+    text { font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, Arial, sans-serif; fill: #4a4e58; font-size: 13px; }
+    .strong { fill: #111318; font-weight: 600; font-size: 14px; }
+    .mono { font-family: ui-monospace, "SF Mono", Consolas, monospace; font-size: 11.5px; fill: #80848e; }
+    .ok { fill: #16a34a; font-weight: 600; font-size: 12.5px; }
+    .box { fill: #ffffff; stroke: #d6d6d0; stroke-width: 1.2; }
+    .soft { fill: #f3f3f0; stroke: #e4e4df; stroke-width: 1.2; }
+    .machine { fill: none; stroke: #d6d6d0; stroke-width: 1.2; stroke-dasharray: 5 5; }
+    .ln { stroke: #80848e; stroke-width: 1.4; fill: none; }
+    .dash { stroke: #80848e; stroke-width: 1.3; stroke-dasharray: 4 5; fill: none; }
+    .p2p { stroke: #16a34a; stroke-width: 3; fill: none; }
+  </style>
+  <defs>
+    <marker id="a" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0 10 5 0 10z" fill="#80848e"/></marker>
+    <marker id="g" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse"><path d="M0 0 10 5 0 10z" fill="#16a34a"/></marker>
+  </defs>
+  <rect x="0.5" y="0.5" width="899" height="349" rx="20" fill="#fafaf8" stroke="#e4e4df"/>
+  <g transform="translate(0 10)">
+    <rect class="machine" x="16" y="98" width="346" height="134" rx="16"/>
+    <rect class="machine" x="538" y="98" width="346" height="134" rx="16"/>
+    <text x="32" y="122" class="mono">MACHINE A</text>
+    <text x="868" y="122" class="mono" text-anchor="end">MACHINE B</text>
+
+    <rect class="box" x="32" y="136" width="122" height="80" rx="12"/>
+    <text x="93" y="170" class="strong" text-anchor="middle">Agent A</text>
+    <text x="93" y="190" text-anchor="middle">MCP client</text>
+    <rect class="box" x="214" y="136" width="132" height="80" rx="12"/>
+    <text x="280" y="170" class="strong" text-anchor="middle">MCP server</text>
+    <text x="280" y="190" class="mono" text-anchor="middle">vdon-mcp-server</text>
+    <path class="ln" d="M154 176h58" marker-end="url(#a)" marker-start="url(#a)"/>
+    <text x="184" y="166" class="mono" text-anchor="middle">stdio</text>
+
+    <rect class="box" x="554" y="136" width="132" height="80" rx="12"/>
+    <text x="620" y="170" class="strong" text-anchor="middle">MCP server</text>
+    <text x="620" y="190" class="mono" text-anchor="middle">vdon-mcp-server</text>
+    <rect class="box" x="746" y="136" width="122" height="80" rx="12"/>
+    <text x="807" y="170" class="strong" text-anchor="middle">Agent B</text>
+    <text x="807" y="190" text-anchor="middle">MCP client</text>
+    <path class="ln" d="M688 176h56" marker-end="url(#a)" marker-start="url(#a)"/>
+    <text x="716" y="166" class="mono" text-anchor="middle">stdio</text>
+
+    <path class="p2p" d="M348 176h204" marker-end="url(#g)" marker-start="url(#g)"/>
+    <text x="450" y="164" class="ok" text-anchor="middle">WebRTC data channel</text>
+    <text x="450" y="196" class="mono" text-anchor="middle">DTLS-encrypted</text>
+
+    <rect class="soft" x="370" y="8" width="160" height="56" rx="12"/>
+    <text x="450" y="32" class="strong" text-anchor="middle">Handshake server</text>
+    <text x="450" y="50" class="mono" text-anchor="middle">wss.vdo.ninja</text>
+    <path class="dash" d="M300 136 382 66"/>
+    <path class="dash" d="M600 136 518 66"/>
+    <text x="300" y="86" class="mono" text-anchor="middle">find peers</text>
+    <text x="600" y="86" class="mono" text-anchor="middle">find peers</text>
+
+    <rect class="soft" x="350" y="266" width="200" height="56" rx="12"/>
+    <text x="450" y="290" class="strong" text-anchor="middle">TURN relay</text>
+    <text x="450" y="308" class="mono" text-anchor="middle">fallback · ciphertext only</text>
+    <path class="dash" d="M300 216 382 266"/>
+    <path class="dash" d="M600 216 518 266"/>
+  </g>
+</svg>