@vdoninja/mcp 0.4.0 → 0.4.2

package/docs/assets/site.js

@@ -0,0 +1,289 @@
+// VDO.Ninja MCP site behaviour: copy buttons, code highlighting, scroll story, tabs, tool profiles, docs nav.
+(function () {
+  'use strict';
+
+  const $ = (sel, root = document) => root.querySelector(sel);
+  const $$ = (sel, root = document) => Array.from(root.querySelectorAll(sel));
+  const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  const ICONS = document.documentElement.dataset.icons || 'assets/icons.svg';
+
+  function icon(name, cls = 'icon-sm') {
+    return `<svg class="${cls}" aria-hidden="true"><use href="${ICONS}#${name}"></use></svg>`;
+  }
+
+  function escapeHtml(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  }
+
+  // ---------- Highlighting ----------
+  function highlightJson(text) {
+    return escapeHtml(text).replace(
+      /("(?:\\.|[^"\\])*")(\s*:)?|\b(true|false|null)\b|(-?\b\d+(?:\.\d+)?\b)/g,
+      (m, str, colon, lit, num) => {
+        if (str) return colon ? `<span class="c-key">${str}</span>${colon}` : `<span class="c-str">${str}</span>`;
+        if (lit) return `<span class="c-num">${lit}</span>`;
+        if (num) return `<span class="c-num">${num}</span>`;
+        return m;
+      }
+    );
+  }
+
+  function highlightShell(text) {
+    return text.split('\n').map((line) => {
+      if (!line.trim()) return '';
+      if (/^\s*#/.test(line)) return `<span class="c-dim">${escapeHtml(line)}</span>`;
+      return `<span class="ln-cmd">${escapeHtml(line)}</span>`;
+    }).join('\n');
+  }
+
+  $$('pre code.lang-json, .term-step .json').forEach((el) => { el.innerHTML = highlightJson(el.textContent); });
+  $$('pre code.lang-sh').forEach((el) => {
+    el.parentElement.classList.add('lang-sh');
+    el.innerHTML = highlightShell(el.textContent.replace(/\n$/, ''));
+  });
+
+  // ---------- Copy buttons ----------
+  async function copyText(text, btn) {
+    try {
+      await navigator.clipboard.writeText(text);
+    } catch (e) {
+      const ta = document.createElement('textarea');
+      ta.value = text; ta.style.position = 'fixed'; ta.style.opacity = '0';
+      document.body.appendChild(ta); ta.select();
+      try { document.execCommand('copy'); } catch (err) { /* ignore */ }
+      ta.remove();
+    }
+    const label = btn.querySelector('.label');
+    btn.classList.add('done');
+    if (label) label.textContent = 'Copied';
+    clearTimeout(btn._t);
+    btn._t = setTimeout(() => { btn.classList.remove('done'); if (label) label.textContent = 'Copy'; }, 1600);
+  }
+
+  $$('pre').forEach((pre) => {
+    if (pre.classList.contains('no-copy') || pre.querySelector('.copy')) return;
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.className = 'copy';
+    btn.setAttribute('aria-label', 'Copy code');
+    btn.innerHTML = `${icon('i-copy', 'icon-xs')}<span class="label">Copy</span>`;
+    btn.addEventListener('click', () => {
+      const code = pre.querySelector('code') || pre;
+      const lines = code.textContent.split('\n').filter((l) => !/^\s*#/.test(l) || !pre.classList.contains('lang-sh'));
+      copyText(lines.join('\n').trim(), btn);
+    });
+    pre.appendChild(btn);
+  });
+
+  $$('[data-copy]').forEach((btn) => {
+    btn.addEventListener('click', () => copyText(btn.dataset.copy, btn));
+  });
+
+  // ---------- Live package version (optional; hidden if the registry can't be reached) ----------
+  const versionEl = $('[data-npm-version]');
+  if (versionEl && window.fetch) {
+    fetch('https://registry.npmjs.org/@vdoninja/mcp/latest')
+      .then((r) => (r.ok ? r.json() : null))
+      .then((pkg) => {
+        if (pkg && /^\d+\.\d+\.\d+/.test(pkg.version || '')) {
+          versionEl.textContent = ` · v${pkg.version}`;
+          versionEl.hidden = false;
+        }
+      })
+      .catch(() => {});
+  }
+
+  // ---------- Mobile nav ----------
+  const nav = $('.nav');
+  const navToggle = $('.nav-toggle');
+  if (nav && navToggle) {
+    navToggle.addEventListener('click', () => {
+      const open = nav.classList.toggle('open');
+      navToggle.setAttribute('aria-expanded', String(open));
+    });
+    $$('.nav-links a').forEach((a) => a.addEventListener('click', () => {
+      nav.classList.remove('open');
+      navToggle.setAttribute('aria-expanded', 'false');
+    }));
+  }
+
+  // ---------- Tabs ----------
+  $$('[data-tabs]').forEach((root) => {
+    const tabs = $$('[role="tab"]', root);
+    const select = (tab) => {
+      tabs.forEach((t) => {
+        const on = t === tab;
+        t.setAttribute('aria-selected', String(on));
+        t.tabIndex = on ? 0 : -1;
+        const panel = document.getElementById(t.getAttribute('aria-controls'));
+        if (panel) panel.hidden = !on;
+      });
+    };
+    tabs.forEach((tab, i) => {
+      tab.addEventListener('click', () => select(tab));
+      tab.addEventListener('keydown', (e) => {
+        if (e.key !== 'ArrowRight' && e.key !== 'ArrowLeft') return;
+        const next = tabs[(i + (e.key === 'ArrowRight' ? 1 : tabs.length - 1)) % tabs.length];
+        next.focus(); select(next);
+      });
+    });
+  });
+
+  // ---------- Tool profiles ----------
+  const PROFILES = {
+    core: { groups: ['session', 'sync'], note: '9 tools: connect, message, and peer sync. Smallest context footprint.' },
+    file: { groups: ['session', 'sync', 'file'], note: '15 tools: core plus chunked, resumable file transfer.' },
+    state: { groups: ['session', 'sync', 'state'], note: '12 tools: core plus shared room state.' },
+    full: { groups: ['session', 'sync', 'file', 'state'], note: 'All 18 tools. The default when no profile is set.' }
+  };
+  const profileRoot = $('[data-profiles]');
+  if (profileRoot) {
+    const buttons = $$('button', profileRoot);
+    const note = $('.profile-note');
+    const apply = (name) => {
+      const p = PROFILES[name];
+      buttons.forEach((b) => b.setAttribute('aria-pressed', String(b.dataset.profile === name)));
+      $$('[data-group]').forEach((g) => g.classList.toggle('off', !p.groups.includes(g.dataset.group)));
+      if (note) note.innerHTML = `${p.note} <code>--tool-profile ${name}</code>`;
+    };
+    buttons.forEach((b) => b.addEventListener('click', () => apply(b.dataset.profile)));
+    apply('full');
+  }
+
+  // ---------- Scroll story ----------
+  const story = $('[data-story]');
+  if (story) {
+    const stage = $('.stage', story);
+    const items = $$('.story-steps li', story);
+    const pillNum = $('.caption-pill .num', story);
+    const pillTxt = $('.caption-pill .txt', story);
+    const termSteps = $$('.term-step', story);
+    const termTitle = $('.term-title', story);
+    const dashes = $('.dashes', story);
+    const packets = $('.packets', story);
+    const statusA = $('.agent-a .status', story);
+    const statusB = $('.agent-b .status', story);
+    const STATUS = [
+      ['not connected', ''], ['MCP ready', 'ready'], ['in room', 'ready'], ['in room', 'ready'],
+      ['connected', 'live'], ['connected', 'live'], ['connected', 'live'], ['connected', 'live'], ['connected', 'live']
+    ];
+    const STATUS_B = STATUS.map((s, i) => (i === 2 ? ['MCP ready', 'ready'] : s));
+    const PACKETS = { 5: ['go-ab', 1, false], 6: ['go-ba', 1, false], 7: ['go-ab', 6, true], 8: ['go-ba', 1, false] };
+
+    items.forEach((li, i) => {
+      const b = document.createElement('button');
+      b.type = 'button';
+      b.setAttribute('aria-label', `Step ${i + 1}`);
+      b.addEventListener('click', () => {
+        const top = li.getBoundingClientRect().top + window.scrollY - window.innerHeight * 0.5 + 2;
+        window.scrollTo({ top, behavior: reduceMotion ? 'auto' : 'smooth' });
+      });
+      dashes.appendChild(b);
+    });
+    const dashButtons = $$('button', dashes);
+
+    const setStatus = (el, [text, cls]) => {
+      el.textContent = text;
+      el.className = `status ${cls}`.trim();
+    };
+
+    let current = -1;
+    const setStep = (i) => {
+      if (i === current) return;
+      current = i;
+      stage.dataset.step = String(i);
+
+      $$('[data-steps]', stage).forEach((el) => {
+        el.hidden = !el.dataset.steps.split(' ').includes(String(i));
+      });
+      $$('.agent', stage).forEach((a) => a.classList.toggle('on', i >= 1));
+      setStatus(statusA, STATUS[i]);
+      setStatus(statusB, STATUS_B[i]);
+
+      $('.node-server', stage).classList.toggle('is-active', i === 2 || i === 3);
+      $('.node-server', stage).classList.toggle('is-quiet', i >= 4);
+      $('.l-sig-a', stage).setAttribute('class', `l-sig l-sig-a ${i === 2 || i === 3 ? 'on' : i >= 4 ? 'faded' : ''}`);
+      $('.l-sig-b', stage).setAttribute('class', `l-sig l-sig-b ${i === 3 ? 'on' : i >= 4 ? 'faded' : ''}`);
+      $('.l-p2p', stage).setAttribute('class', `l-p2p ${i >= 4 ? 'on' : ''}`);
+      $$('.l-relay', stage).forEach((l) => l.setAttribute('class', `l-relay ${i === 4 ? 'on' : ''}`));
+      $('.node-relay', stage).classList.toggle('is-quiet', i !== 4);
+      $('.p2p-label', stage).classList.toggle('on', i >= 4);
+
+      packets.className = 'packets';
+      packets.innerHTML = '';
+      const p = PACKETS[i];
+      if (p && !reduceMotion) {
+        const [dir, n, chunk] = p;
+        for (let k = 0; k < n; k += 1) {
+          const dot = document.createElement('i');
+          dot.className = chunk ? 'packet chunk' : 'packet';
+          dot.style.setProperty('--d', `${k * (chunk ? 0.35 : 0) + 0.2}s`);
+          dot.style.setProperty('--n', chunk ? '1' : '2');
+          packets.appendChild(dot);
+        }
+        void packets.offsetWidth;
+        packets.classList.add(dir);
+      }
+
+      const item = items[i];
+      pillNum.textContent = String(i).padStart(2, '0');
+      pillTxt.innerHTML = item.innerHTML;
+      termSteps.forEach((t) => t.classList.toggle('is-active', t.dataset.step === String(i)));
+      const active = termSteps.find((t) => t.dataset.step === String(i));
+      if (active && termTitle) termTitle.textContent = active.dataset.title || '';
+      dashButtons.forEach((b, k) => b.classList.toggle('on', k <= i));
+    };
+
+    let ticking = false;
+    const onScroll = () => {
+      ticking = false;
+      const line = window.innerHeight * 0.55;
+      let idx = 0;
+      items.forEach((li, k) => { if (li.getBoundingClientRect().top < line) idx = k; });
+      setStep(idx);
+    };
+    window.addEventListener('scroll', () => {
+      if (!ticking) { ticking = true; requestAnimationFrame(onScroll); }
+    }, { passive: true });
+    window.addEventListener('resize', onScroll);
+    onScroll();
+  }
+
+  // ---------- Docs: sidebar toggle + scrollspy ----------
+  const docsToggle = $('.docs-toggle');
+  if (docsToggle) {
+    const closeSidebar = () => {
+      document.body.classList.remove('sidebar-open');
+      docsToggle.setAttribute('aria-expanded', 'false');
+    };
+    docsToggle.setAttribute('aria-expanded', 'false');
+    docsToggle.addEventListener('click', () => {
+      const expanded = document.body.classList.toggle('sidebar-open');
+      docsToggle.setAttribute('aria-expanded', String(expanded));
+    });
+    $$('.sidebar a').forEach((a) => a.addEventListener('click', closeSidebar));
+    document.addEventListener('keydown', (event) => {
+      if (event.key === 'Escape' && document.body.classList.contains('sidebar-open')) {
+        closeSidebar();
+        docsToggle.focus();
+      }
+    });
+  }
+  const sideLinks = $$('.sidebar a[href^="#"]');
+  const sections = $$('.doc-section');
+  if (sideLinks.length && sections.length) {
+    const map = new Map(sideLinks.map((a) => [a.getAttribute('href').slice(1), a]));
+    let spyTicking = false;
+    const spy = () => {
+      spyTicking = false;
+      let current = sections[0];
+      sections.forEach((s) => { if (s.getBoundingClientRect().top < 140) current = s; });
+      if (window.innerHeight + window.scrollY >= document.body.scrollHeight - 4) current = sections[sections.length - 1];
+      sideLinks.forEach((a) => a.classList.toggle('active', a === map.get(current.id)));
+    };
+    window.addEventListener('scroll', () => {
+      if (!spyTicking) { spyTicking = true; requestAnimationFrame(spy); }
+    }, { passive: true });
+    spy();
+  }
+})();

package/docs/browser-agent.html

@@ -0,0 +1,122 @@
+<!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>Voice companion · VDO.Ninja MCP</title>
+  <meta name="description" content="Talk to an agent while sharing selected browser views and controls.">
+  <meta name="color-scheme" content="light dark">
+  <link rel="canonical" href="https://steveseguin.github.io/ninjamcp/browser-agent.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="#start-a-conversation">Start a conversation</a><a href="#control-what-is-shared">Control what is shared</a><a href="#watch-the-browser">Watch the browser</a><a href="#resolve-connection-problems">Resolve connection problems</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="ssapp-integration.html">Remote SSApp</a><a href="mcp-tool-contract.html">Tool contract</a><a href="advanced-diagnostics.html">Advanced diagnostics</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> / Voice companion</p>
+      <h1 id="talk-to-an-agent-while-sharing-a-browser">Talk to an agent while sharing a browser</h1>
+      <p class="guide-format"><a href="https://github.com/steveseguin/ninjamcp/blob/main/references/browser-agent.md">Read in Markdown</a></p>
+    </header>
+    <section class="doc-section guide-intro" id="overview">
+<p>The browser companion lets you speak or type to an OpenAI Realtime agent, share selected views of your remote Chrome tab, and let it use the browser tools. You can also watch and hear the tab through VDO.Ninja. The browser host can be on another computer; the companion runs locally beside your microphone and speakers.</p>
+</section><section class="doc-section" id="start-a-conversation"><h2>Start a conversation</h2>
+<p>First <a href="browser-worker.html">start a browser worker</a> and copy one controller credential file to your computer. Use a separate credential for each agent or companion running at the same time.</p>
+<p>Set <code>OPENAI_API_KEY</code> in the local companion process, then launch:</p>
+<pre><code class="lang-sh">npx vdon-mcp-browser-agent --config /private/agent1.json
+</code></pre>
+<p>From a checkout, run <code>node scripts/vdo-mcp-browser-agent.js --config /private/agent1.json</code>. Open the private loopback URL printed in the terminal on that same computer. Keep the terminal running. The API key stays in the local server process; it is not sent to the remote browser host or the operator page.</p>
+<ol>
+<li>Select <strong>Check worker</strong> to confirm authenticated access.</li>
+<li>Select <strong>Start agent</strong>, then choose <strong>Share my microphone</strong> to speak. You can also type a message.</li>
+<li>Enable <strong>Share browser frames</strong> when you want the agent to see the tab. Frames update about every three seconds; the agent can also read page snapshots.</li>
+<li>Enable <strong>Allow browser control</strong> when you want the agent to navigate, click, or type. This also enables browser sharing. The worker's controller role and tab lease still apply.</li>
+</ol>
+<p>The default model is <code>gpt-realtime-2.1</code>. Set <code>VDON_BROWSER_MODEL</code> to select another Realtime model that supports audio, images, and function calls. Model usage is billed to your OpenAI account. Each conversation ends after 15 minutes; start a new one to continue.</p>
+</section><section class="doc-section" id="control-what-is-shared"><h2>Control what is shared</h2>
+<div aria-label="Scrollable reference table" class="table-wrap" role="region" tabindex="0"><table>
+<thead>
+<tr>
+<th scope="col">Control</th>
+<th scope="col">Effect</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Share my microphone</td>
+<td>Sends microphone audio to OpenAI while the agent session is connected. Turning it off stops microphone capture and clears pending input audio.</td>
+</tr>
+<tr>
+<td>Share browser frames</td>
+<td>Sends browser images and requested page content to OpenAI. Turning it off stops new image and tool requests and releases held control. Content already sent remains part of that model conversation.</td>
+</tr>
+<tr>
+<td>Allow browser control</td>
+<td>Allows the agent to claim the shared tab and use input tools. Turning it off releases held leases and prevents queued control requests from starting.</td>
+</tr>
+<tr>
+<td>Interrupt</td>
+<td>Stops queued speech and agent actions. An action already sent to the worker may finish; inspect its result before repeating it.</td>
+</tr>
+<tr>
+<td>End session</td>
+<td>Closes the model connection, stops microphone capture and frame sharing, and releases held control.</td>
+</tr>
+</tbody>
+</table></div>
+<p>The sharing indicator identifies the selected inputs and OpenAI as their recipient. The application does not record locally. OpenAI processes the microphone audio, selected browser images, typed messages, and tool results sent during the session. The voice you hear is AI generated.</p>
+<p>Other authorized observers can still see the worker's tab. To revoke another controller, use <code>revoke 1</code> in the host terminal. Stop the worker to close the browser and end access for everyone.</p>
+</section><section class="doc-section" id="watch-the-browser"><h2>Watch the browser</h2>
+<p>Enable <code>"media": { "enabled": true }</code> in the host's <code>worker.json</code>, or add <code>--media</code> during setup. Select <strong>Watch live browser</strong> in the companion and <strong>Hear browser audio</strong> to unmute. This uses the SDK stream directly and does not require an OpenAI key. Watching alone does not share that stream with the model.</p>
+<p>The model receives selected browser frames and your shared microphone; captured tab audio is for the human viewer. Live viewing requires WebRTC. With an HTTP connection, keep using text, microphone conversation, page snapshots, screenshots, and browser controls even when the live view cannot connect. The companion's connection to OpenAI uses an outbound secure WebSocket.</p>
+</section><section class="doc-section" id="resolve-connection-problems"><h2>Resolve connection problems</h2>
+<ul>
+<li>If <strong>Check worker</strong> fails, run <code>vdon-mcp-browser --doctor --config /private/agent1.json</code>. Confirm that the host is running with matching credentials and a common route.</li>
+<li>If the model will not connect, set the API key in the companion process, check model access, and restart the companion. Viewing and worker diagnostics remain available without a key.</li>
+<li>If another agent holds the tab, let it release control or wait for its lease to expire. Sharing a browser does not bypass that ownership.</li>
+<li>If a tool reports an uncertain outcome, have the agent use <code>browser_result</code> and inspect the page before repeating an action. A returned tool result and completion of your requested task are separate outcomes.</li>
+</ul>
+<p>The page accepts one local operator connection. Reopen the original private URL after a reload or disconnect; its access token is removed from the address bar after connection. Keep that URL and the agent credential file private.</p></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/browser-worker.html

@@ -0,0 +1,165 @@
+<!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>Remote Chrome · VDO.Ninja MCP</title>
+  <meta name="description" content="Share a remote Chrome tab, with separate agent credentials and control handoff.">
+  <meta name="color-scheme" content="light dark">
+  <link rel="canonical" href="https://steveseguin.github.io/ninjamcp/browser-worker.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="#start-the-host">Start the host</a><a href="#connect-an-agent">Connect an agent</a><a href="#share-control-and-recover-a-connection">Share control and recover a connection</a><a href="#keep-working-when-webrtc-is-unavailable">Keep working when WebRTC is unavailable</a><a href="#watch-live-tab-audio-and-video">Watch live tab audio and video</a><a href="#choose-the-hosts-access-deliberately">Choose the host&#x27;s access deliberately</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-agent.html">Voice companion</a><a href="ssapp-integration.html">Remote SSApp</a><a href="mcp-tool-contract.html">Tool contract</a><a href="advanced-diagnostics.html">Advanced diagnostics</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> / Remote Chrome</p>
+      <h1 id="share-a-remote-chrome-browser">Share a remote Chrome browser</h1>
+      <p class="guide-format"><a href="https://github.com/steveseguin/ninjamcp/blob/main/references/browser-worker.md">Read in Markdown</a></p>
+    </header>
+    <section class="doc-section guide-intro" id="overview">
+<p>Run an isolated, headless Chrome tab on one computer and let agents use it through Ninja MCP. The host connects outward using WebRTC or your HTTP relay. Chrome's debugging endpoint stays on loopback; agents need no VPN or desktop streaming software.</p>
+<p>Each agent gets its own credential. Controllers take turns using a tab lease; observers can read snapshots, request screenshots, and watch optional live tab audio/video.</p>
+</section><section class="doc-section" id="start-the-host"><h2>Start the host</h2>
+<p>Install Chrome and Node.js 22.12 or later. In your Ninja MCP installation folder, install the optional browser packages:</p>
+<pre><code class="lang-sh">npm install @vdoninja/mcp chrome-devtools-mcp@1.11.0 puppeteer-core@24.37.5
+npx vdon-mcp-browser --setup ./private-browser
+npx vdon-mcp-browser --worker --config ./private-browser/worker.json
+</code></pre>
+<p>The setup prompts for a connection and optional live media. For a direct connection without prompts, add <code>--transport webrtc</code>. From a checkout, use <code>node scripts/vdo-mcp-browser.js</code> in place of <code>npx vdon-mcp-browser</code>. Keep the generated directory outside source control and accessible only to the host account. It contains four credential files:</p>
+<div aria-label="Scrollable reference table" class="table-wrap" role="region" tabindex="0"><table>
+<thead>
+<tr>
+<th scope="col">File</th>
+<th scope="col">Give it to</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>worker.json</code></td>
+<td>The browser host only; it contains every client key.</td>
+</tr>
+<tr>
+<td><code>agent1.json</code>, <code>agent2.json</code></td>
+<td>One controller each.</td>
+</tr>
+<tr>
+<td><code>viewer.json</code></td>
+<td>An observer who may see the shared tab but cannot control it.</td>
+</tr>
+</tbody>
+</table></div>
+<p>Copy each client file privately to its intended agent's machine. Give additional clients distinct random 32-byte hex keys and add their IDs, keys, and <code>controller</code> or <code>observer</code> roles to <code>worker.json</code>. Restart the worker to apply credential changes. Use one client credential per active agent process.</p>
+<p>Setup also writes <code>mcp-client.json</code> with the local agent registration. Adjust its absolute paths when copying it to another computer. <code>--init</code> remains available for creating WebRTC credentials without prompts.</p>
+<p>The worker starts with one empty shared tab and an ephemeral Chrome profile. Your ordinary Chrome windows and logged-in profile are separate. To select a Chrome executable, add an absolute <code>executable</code> path to <code>worker.json</code>. When browser packages live elsewhere, set <code>dependencies</code> to their installation directory.</p>
+</section><section class="doc-section" id="connect-an-agent"><h2>Connect an agent</h2>
+<p>The agent machine needs Ninja MCP, but does not need Chrome or the optional browser packages. Add this separate server to the agent's MCP configuration, using absolute paths:</p>
+<pre><code class="lang-json">{
+  "mcpServers": {
+    "ninja-browser": {
+      "command": "node",
+      "args": [
+        "/absolute/path/node_modules/@vdoninja/mcp/scripts/vdo-mcp-browser.js",
+        "--config",
+        "/absolute/private/path/agent1.json"
+      ]
+    }
+  }
+}
+</code></pre>
+<p>On Windows, use paths such as <code>C:/Ninja/node_modules/@vdoninja/mcp/scripts/vdo-mcp-browser.js</code>. Existing message, file, and state tools remain available through the ordinary Ninja MCP server.</p>
+<p>Check the host packages or authenticate to the running worker from a client:</p>
+<pre><code class="lang-sh">npx vdon-mcp-browser --doctor --config ./private-browser/worker.json
+npx vdon-mcp-browser --doctor --config ./private-browser/agent1.json
+</code></pre>
+<p>The client check lists tabs without taking control. Its output distinguishes relay access from an authenticated worker response and names the route that returned the result.</p>
+<p>Ask the agent to list tabs, claim the shared tab, navigate, and take a snapshot:</p>
+<pre><code class="lang-json">{ "name": "browser_tabs", "arguments": {} }
+{ "name": "browser_claim", "arguments": { "pageId": 1 } }
+{ "name": "browser_call", "arguments": { "pageId": 1, "lease": "&lt;returned lease&gt;", "action": "navigate", "url": "https://example.com" } }
+{ "name": "browser_observe", "arguments": { "pageId": 1 } }
+</code></pre>
+<p>Use the returned snapshot token and element UID for input:</p>
+<pre><code class="lang-json">{ "name": "browser_call", "arguments": { "pageId": 1, "lease": "&lt;returned lease&gt;", "snapshot": "&lt;snapshot token&gt;", "action": "click", "uid": "&lt;element uid&gt;" } }
+{ "name": "browser_observe", "arguments": { "pageId": 1, "screenshot": true } }
+{ "name": "browser_release", "arguments": { "pageId": 1, "lease": "&lt;returned lease&gt;" } }
+</code></pre>
+<p><code>fill</code> takes <code>uid</code> and <code>value</code>; <code>key</code> takes a page key such as <code>Enter</code>, <code>Tab</code>, or an arrow key. Navigation accepts HTTP and HTTPS URLs. Remote tools do not expose script evaluation, local file uploads, browser shortcuts, or the media publisher's private page. They share the initial tab; newly opened tabs are not exposed. Continue work in the shared tab by navigating it to the desired URL.</p>
+</section><section class="doc-section" id="share-control-and-recover-a-connection"><h2>Share control and recover a connection</h2>
+<p>A lease lasts 60 seconds by default. Set <code>ttl_ms</code> between 1,000 and 120,000 when claiming; renew by passing the same lease to <code>browser_claim</code>. Another controller can claim after release or expiry. A disconnected agent's lease expires on that same deadline.</p>
+<p>Take a fresh accessibility snapshot after claiming, navigating, or acting. Snapshot tokens expire after 30 seconds. Another agent's accessibility snapshot replaces the current element references; take a fresh one if an input call returns <code>fresh_snapshot_required</code>. Screenshots do not replace those references.</p>
+<p>The host can enter <code>revoke 1</code> in its worker terminal to invalidate the current lease immediately. An action already executing may finish. Stop the worker to close the browser and end all access.</p>
+<p>Requests have IDs, deadlines, and bounded retries. A lost response is retried with the same ID; the running worker returns its cached result instead of repeating the action. Recent results remain available for at least two minutes after their request deadline:</p>
+<pre><code class="lang-json">{ "name": "browser_result", "arguments": { "request_id": "&lt;uncertain request ID&gt;" } }
+</code></pre>
+<p>An <code>outcome_unknown</code> response or an unknown result does not mean the action failed to execute. Inspect the page before deciding whether to repeat a click or submission. Results are held in memory; restarting the worker creates a new browser and invalidates old commands. Results are limited to 2 MiB; screenshots cover the viewport and use JPEG compression.</p>
+</section><section class="doc-section" id="keep-working-when-webrtc-is-unavailable"><h2>Keep working when WebRTC is unavailable</h2>
+<p>For automatic browser routing, create a new group with a private relay configuration:</p>
+<pre><code class="lang-sh">npx vdon-mcp-browser --setup ./private-browser --transport auto --relay-config /private/relay.json
+</code></pre>
+<p>The relay file uses <code>{ "url": "https://relay.example.com", "token": "&lt;access token&gt;" }</code>. You can reuse a ninja-p2p relay configuration and the same hosted relay service; setup creates a separate browser room and encryption key. Mailbox credentials and OAuth connections are separate and are not used here.</p>
+<p><code>auto</code> prefers an available WebRTC data channel. If a request needs retrying, it tries the other available route with the same encrypted request and ID. One worker owns the result cache and control leases across both routes. After a WebRTC timeout, new requests prefer HTTP for 30 seconds while the direct connection recovers. Tool results report which route replied.</p>
+<p>Use <code>--transport http</code> for HTTP only, or <code>--transport webrtc</code> for direct connections only. An automatic participant can reach a participant using either one of those routes, provided their connection and browser credentials match. Both routes carry commands, results, and screenshots; live media still needs WebRTC.</p>
+<p>For an existing group, set <code>connection.transport</code> to <code>"auto"</code> or <code>"http"</code> in its files, and supply the same relay settings to each participating process. These environment variables override the generated settings:</p>
+<ul>
+<li><code>VDON_MCP_RELAY_URL</code>: your HTTPS relay origin.</li>
+<li><code>VDON_MCP_RELAY_TOKEN</code>: relay access token.</li>
+<li><code>VDON_MCP_RELAY_KEY</code>: room encryption key.</li>
+</ul>
+<p>Follow the <a href="http-relay.html">relay setup guide</a> to host a compatible relay. Browser credentials remain separate from relay credentials; sharing a room key does not grant browser access. Automatic routing applies to this browser adapter; ordinary Ninja MCP room sessions select their transport explicitly.</p>
+</section><section class="doc-section" id="watch-live-tab-audio-and-video"><h2>Watch live tab audio and video</h2>
+<p>Add this option to <code>worker.json</code>, then restart:</p>
+<pre><code class="lang-json">"media": { "enabled": true }
+</code></pre>
+<p>Call <code>browser_media</code> to get track status and a private VDO.Ninja viewing link. The host captures only the shared tab, including its audio, through Chrome tab capture and publishes it using the VDO.Ninja SDK. The publisher uses a separate browser context and fresh media credentials on every worker start. Microphone and desktop capture are not enabled. Recording is off.</p>
+<p>Anyone holding the viewing link can watch and hear that stream. Share it only with intended viewers; restart the worker to replace the link. Media access does not grant control. The capture persists when the shared tab navigates, so stop the worker before opening content you do not want viewers to see.</p>
+<p>Live media requires WebRTC even when commands use HTTP. If <code>browser_media</code> reports unavailable media or an ended track, use <code>browser_observe</code> screenshots and restart after restoring capture or connectivity. An optional <code>media.host</code> selects a different SDK signaling endpoint; clients then receive connection settings instead of a default VDO.Ninja link.</p>
+<p>For a speaking agent that sees selected browser frames and uses these tools, open the optional <a href="browser-agent.html">browser companion</a>. Live viewing and model sharing have separate controls.</p>
+</section><section class="doc-section" id="choose-the-hosts-access-deliberately"><h2>Choose the host's access deliberately</h2>
+<p>All configured viewers can see the shared tab, and controllers can interact with sites using the host's network access. Run the worker under an account or container with only the network and filesystem access you intend to share. A separate Chrome profile is not an operating-system sandbox. Avoid signing into personal accounts in this shared tab.</p>
+<p>Browser requests and results use a separate AES-GCM key for each client over either transport. Keep credential files private. Removing a client requires updating the host configuration and restarting; possession of that client's file grants its configured role until then.</p>
+<p>The adapter uses the pinned <a href="https://github.com/ChromeDevTools/chrome-devtools-mcp">Chrome DevTools MCP</a> release and <a href="https://sdk.vdo.ninja/">VDO.Ninja SDK</a>. Chrome runs with its sandbox enabled. The worker binds no public browser-control port and changes no ordinary Ninja MCP transport defaults.</p></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>