@vdoninja/mcp 0.4.0 → 0.4.2

package/scripts/vdo-mcp-relay.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+
+'use strict';
+
+const http = require('node:http');
+const crypto = require('node:crypto');
+
+const MAX_BODY_BYTES = 768 * 1024;
+const RETENTION_MS = 5 * 60 * 1000;
+
+function json(res, status, body) {
+  res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+  res.end(JSON.stringify(body));
+}
+
+// One relay instance serves a trusted group. The bearer token grants relay access;
+// room encryption keys stay on the clients and are never sent to this server.
+async function startRelayServer(options = {}) {
+  const token = options.token || process.env.VDON_RELAY_TOKEN;
+  if (typeof token !== 'string' || token.length < 32 || /[^\x21-\x7e]/.test(token)) {
+    throw new Error('VDON_RELAY_TOKEN requires at least 32 printable non-space characters');
+  }
+  const expectedAuth = crypto.createHash('sha256').update(`Bearer ${token}`).digest();
+  const rooms = new Map();
+  const responses = new Set();
+  const sockets = new Set();
+  let closing = false;
+  let closePromise;
+
+  function prune(room) {
+    const cutoff = Date.now() - RETENTION_MS;
+    while (room.events.length && (room.events.length > 512 || room.bytes > 8 * 1024 * 1024 || room.events[0].ts < cutoff)) {
+      const removed = room.events.shift();
+      room.bytes -= removed.bytes;
+      room.ids.delete(removed.id);
+    }
+  }
+
+  function readEvents(room, cursor) {
+    prune(room);
+    const latest = `${room.epoch}:${room.seq}`;
+    if (cursor === null) return { cursor: latest, events: [] };
+    const match = /^([a-f0-9-]{36}):(\d+)$/.exec(cursor);
+    const seq = match ? Number(match[2]) : NaN;
+    const oldest = room.events.length ? room.events[0].seq : room.seq + 1;
+    if (!match || match[1] !== room.epoch || !Number.isSafeInteger(seq) || seq < oldest - 1 || seq > room.seq) {
+      return { error: 'relay_history_lost', cursor: latest, events: [] };
+    }
+    const events = [];
+    let bytes = 0;
+    for (const event of room.events) {
+      if (event.seq <= seq) continue;
+      if (events.length && bytes + event.bytes > 1024 * 1024) break;
+      bytes += event.bytes;
+      events.push({ id: event.id, box: event.box });
+    }
+    return { cursor: `${room.epoch}:${seq + events.length}`, events };
+  }
+
+  async function handle(req, res) {
+    if (closing) return json(res, 503, { error: 'relay_closing' });
+    const auth = crypto.createHash('sha256').update(req.headers.authorization || '').digest();
+    if (!crypto.timingSafeEqual(auth, expectedAuth)) return json(res, 401, { error: 'unauthorized' });
+    let url;
+    try { url = new URL(req.url, 'http://relay.local'); } catch (_) {
+      return json(res, 400, { error: 'invalid_url' });
+    }
+    const match = /^\/v1\/rooms\/([a-f0-9]{64})\/events$/.exec(url.pathname);
+    if (!match) return json(res, 404, { error: 'not_found' });
+    if (!['GET', 'POST'].includes(req.method)) return json(res, 405, { error: 'method_not_allowed' });
+    let room = rooms.get(match[1]);
+    if (!room) {
+      if (rooms.size >= 16) return json(res, 503, { error: 'relay_room_limit' });
+      room = { epoch: crypto.randomUUID(), seq: 0, events: [], ids: new Map(), bytes: 0, waiters: new Set(), touched: Date.now() };
+      rooms.set(match[1], room);
+    }
+    room.touched = Date.now();
+    if (req.method === 'GET') {
+      const cursor = url.searchParams.get('after');
+      const result = readEvents(room, cursor);
+      const wait = Math.min(25000, Math.max(0, Number(url.searchParams.get('wait_ms')) || 0));
+      if (result.error || result.events.length || cursor === null || !wait) {
+        return json(res, result.error ? 409 : 200, result);
+      }
+      if (room.waiters.size >= 32 || responses.size >= 128) return json(res, 429, { error: 'relay_reader_limit' });
+      const finish = () => {
+        cleanup();
+        const next = readEvents(room, cursor);
+        json(res, next.error ? 409 : 200, next);
+      };
+      const cleanup = () => {
+        clearTimeout(timer);
+        room.waiters.delete(finish);
+        responses.delete(res);
+        res.removeListener('close', cleanup);
+      };
+      const timer = setTimeout(finish, wait);
+      room.waiters.add(finish);
+      responses.add(res);
+      res.on('close', cleanup);
+      return;
+    }
+
+    if (!String(req.headers['content-type'] || '').startsWith('application/json')) {
+      return json(res, 415, { error: 'json_required' });
+    }
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of req) {
+      bytes += chunk.length;
+      if (bytes > MAX_BODY_BYTES) {
+        json(res, 413, { error: 'event_too_large' });
+        return;
+      }
+      chunks.push(chunk);
+    }
+    let event;
+    try { event = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch (_) {
+      return json(res, 400, { error: 'invalid_json' });
+    }
+    if (!event || typeof event.id !== 'string' || !/^[a-f0-9-]{36}$/.test(event.id) ||
+        typeof event.box !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(event.box) || event.box.length < 40) {
+      return json(res, 400, { error: 'invalid_event' });
+    }
+    prune(room);
+    const previous = room.ids.get(event.id);
+    if (previous) {
+      if (previous.box !== event.box) return json(res, 409, { error: 'event_id_conflict' });
+      return json(res, 200, { accepted: true, duplicate: true });
+    }
+    const stored = { id: event.id, box: event.box, seq: ++room.seq, ts: Date.now(), bytes };
+    room.events.push(stored);
+    room.ids.set(stored.id, stored);
+    room.bytes += bytes;
+    prune(room);
+    json(res, 202, { accepted: true });
+    for (const finish of Array.from(room.waiters)) finish();
+  }
+
+  const server = http.createServer((req, res) => {
+    handle(req, res).catch(() => {
+      if (!res.headersSent && !res.destroyed) json(res, 400, { error: 'invalid_request' });
+      else res.destroy();
+    });
+  });
+  server.on('connection', (socket) => {
+    sockets.add(socket);
+    socket.once('close', () => sockets.delete(socket));
+  });
+  server.requestTimeout = 30000;
+  server.headersTimeout = 10000;
+  server.maxConnections = 256;
+  const cleanup = setInterval(() => {
+    for (const [name, room] of rooms) {
+      prune(room);
+      if (!room.waiters.size && Date.now() - room.touched > RETENTION_MS) rooms.delete(name);
+    }
+  }, 30000);
+  cleanup.unref();
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(options.port === undefined ? 8790 : options.port, options.host || '127.0.0.1', resolve);
+    });
+  } catch (error) {
+    clearInterval(cleanup);
+    throw error;
+  }
+  return {
+    server,
+    port: server.address().port,
+    close() {
+      if (closePromise) return closePromise;
+      closing = true;
+      clearInterval(cleanup);
+      closePromise = new Promise((resolve, reject) => {
+        server.close((error) => error ? reject(error) : resolve());
+        for (const res of responses) res.destroy();
+        for (const socket of sockets) socket.destroy();
+      });
+      return closePromise;
+    }
+  };
+}
+
+if (require.main === module) {
+  if (process.argv.includes('--help')) {
+    console.log('Usage: vdon-mcp-relay\nEnvironment: VDON_RELAY_TOKEN (required), VDON_RELAY_HOST (127.0.0.1), VDON_RELAY_PORT (8790).\nUse an HTTPS reverse proxy for remote clients. See references/http-relay.md.');
+  } else {
+    const port = Number(process.env.VDON_RELAY_PORT || 8790);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      console.error('VDON_RELAY_PORT must be between 1 and 65535');
+      process.exitCode = 1;
+    } else {
+      startRelayServer({ host: process.env.VDON_RELAY_HOST, port }).then((relay) => {
+        console.error(`Ninja MCP relay listening on port ${relay.port}`);
+        const stop = () => relay.close().catch(() => { process.exitCode = 1; });
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+      }).catch((error) => { console.error(error.message); process.exitCode = 1; });
+    }
+  }
+}
+
+module.exports = { startRelayServer };

package/scripts/vdo-mcp-server.js

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+
 'use strict';
 
 const { BridgeSession } = require('./lib/bridge-session');
+const { validateRelayConfig } = require('./lib/http-relay-transport');
 const { McpStdioParser, writeMcpMessage } = require('./lib/mcp-stdio-parser');
 const {
   DEFAULT_TOOL_PROFILE,
@@ -24,7 +28,7 @@ const {
 const SUPPORTED_PROTOCOL_VERSIONS = ['2025-06-18', '2024-11-05'];
 const SERVER_INFO = {
   name: 'vdo-ninja-mcp',
-  version: '0.4.0'
+  version: '0.4.2'
 };
 const DEFAULT_MAX_MESSAGE_BYTES = 1024 * 1024;
 
@@ -32,11 +36,15 @@ function buildTools() {
   return [
     {
       name: 'vdo_connect',
-      description: 'Start a VDO.Ninja data-channel session and optionally auto-view a target stream.',
+      description: 'Start a room session using WebRTC (default) or a configured encrypted HTTP relay.',
       inputSchema: {
         type: 'object',
         properties: {
           room: { type: 'string', description: 'Room name (alphanumeric/underscore recommended).' },
+          transport: { type: 'string', enum: ['webrtc', 'http'], description: 'Peer transport. HTTP requires a self-hosted relay; it works without WebRTC.' },
+          relay_url: { type: 'string', description: 'HTTPS relay origin; defaults to VDON_MCP_RELAY_URL. Loopback HTTP is allowed.' },
+          relay_token: { type: 'string', description: 'Relay access token; prefer VDON_MCP_RELAY_TOKEN in the server environment.' },
+          relay_key: { type: 'string', description: 'Shared room encryption key: 32 random bytes as 64 hex characters. Prefer VDON_MCP_RELAY_KEY.' },
           stream_id: { type: 'string', description: 'Local stream id. Randomized when omitted.' },
           target_stream_id: { type: 'string', description: 'Optional remote stream id to auto-view.' },
           host: { type: 'string', description: 'WebSocket endpoint. Defaults to wss://wss.vdo.ninja.' },
@@ -76,7 +84,7 @@ function buildTools() {
     },
     {
       name: 'vdo_send',
-      description: 'Send one payload over an active session data channel.',
+      description: 'Send one payload over an active session. Success means locally accepted; HTTP relay receipts arrive through vdo_receive.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -500,6 +508,38 @@ Options:
 `.trim();
 }
 
+function isInteractiveTerminal(stream) {
+  return !!(stream && stream.isTTY);
+}
+
+function buildStartupBanner(server) {
+  const profile = server && server.toolProfile && server.toolProfile.name
+    ? server.toolProfile.name
+    : DEFAULT_TOOL_PROFILE;
+  return [
+    '[vdon-mcp] Server running (stdio) and waiting for MCP client input.',
+    `[vdon-mcp] Active tool profile: ${profile}`,
+    '[vdon-mcp] First tool call: {"name":"vdo_capabilities","arguments":{}}',
+    '[vdon-mcp] Stop with Ctrl+C'
+  ];
+}
+
+function maybeWriteStartupBanner(options, server) {
+  const env = options.env || process.env;
+  const disabled = toBool(env.VDON_MCP_NO_STARTUP_BANNER, false);
+  if (disabled) return false;
+
+  const input = options.input || process.stdin;
+  const output = options.output || process.stdout;
+  const errorOutput = options.errorOutput || process.stderr;
+
+  const interactive = isInteractiveTerminal(input) && isInteractiveTerminal(output) && isInteractiveTerminal(errorOutput);
+  if (!interactive) return false;
+
+  errorOutput.write(`${buildStartupBanner(server).join('\n')}\n`);
+  return true;
+}
+
 class VdoMcpServer {
   constructor(options = {}) {
     this.protocolVersion = SUPPORTED_PROTOCOL_VERSIONS[0];
@@ -574,7 +614,8 @@ class VdoMcpServer {
         'join_token', 'join_token_secret', 'join_token_ttl_ms', 'enforce_join_token', 'allow_peer_stream_ids',
         'file_chunk_bytes', 'file_max_bytes', 'file_ack_timeout_ms', 'file_max_retries', 'require_session_mac',
         'file_spool_dir', 'file_spool_threshold_bytes', 'keep_spool_files',
-        'state_max_keys', 'state_max_snapshot_entries'
+        'state_max_keys', 'state_max_snapshot_entries',
+        'transport', 'relay_url', 'relay_token', 'relay_key'
       ],
       'vdo_connect'
     );
@@ -584,6 +625,22 @@ class VdoMcpServer {
       throw new Error('room is required');
     }
 
+    const transport = args.transport === undefined ? 'webrtc' : args.transport;
+    if (!['webrtc', 'http'].includes(transport)) throw new Error('invalid transport: use webrtc or http');
+    const relayConfig = {
+      relayUrl: args.relay_url === undefined ? process.env.VDON_MCP_RELAY_URL : args.relay_url,
+      relayToken: args.relay_token === undefined ? process.env.VDON_MCP_RELAY_TOKEN : args.relay_token,
+      relayKey: args.relay_key === undefined ? process.env.VDON_MCP_RELAY_KEY : args.relay_key
+    };
+    if (transport === 'http') {
+      validateRelayConfig(relayConfig);
+      if (args.host !== undefined || args.password !== undefined || args.force_turn !== undefined) {
+        throw new Error('host, password, and force_turn are WebRTC-only fields; use relay_url and relay_key for HTTP');
+      }
+    } else if (['relay_url', 'relay_token', 'relay_key'].some((key) => args[key] !== undefined)) {
+      throw new Error('relay options require transport: http');
+    }
+
     if (args.host !== undefined && typeof args.host !== 'string') {
       throw new Error('host must be a string');
     }
@@ -633,6 +690,8 @@ class VdoMcpServer {
       : this.defaultAllowPeerStreamIDs;
 
     return {
+      transport,
+      ...(transport === 'http' ? relayConfig : {}),
       host: typeof args.host === 'string' && args.host.trim() ? args.host : 'wss://wss.vdo.ninja',
       room,
       streamID,
@@ -749,7 +808,8 @@ class VdoMcpServer {
       session_id: sessionId,
       ...session.getStatus(),
       effective_config: {
-        host: config.host,
+        transport: config.transport,
+        host: config.transport === 'http' ? config.relayUrl : config.host,
         room: config.room,
         stream_id: config.streamID,
         target_stream_id: config.targetStreamID,
@@ -791,7 +851,11 @@ class VdoMcpServer {
     return {
       ok,
       session_id: args.session_id,
-      used_target: target || null
+      used_target: target || null,
+      ...(session.config.transport === 'http' ? {
+        message_id: ok ? session.sdk.lastMessageId : null,
+        delivery_stage: ok ? 'queued' : 'rejected'
+      } : {})
     };
   }
 
@@ -869,10 +933,21 @@ class VdoMcpServer {
       features: {
         session_messaging: true,
         file_transfer: hasFileTools,
-        shared_state_sync: hasStateTools
+        shared_state_sync: hasStateTools,
+        live_audio_video: false
       },
       transport_truth: {
         type: 'webrtc_data_channel',
+        default_transport: 'webrtc',
+        supported_transports: ['webrtc', 'http'],
+        http_relay: {
+          independent_of_webrtc: true,
+          receive: 'long_poll',
+          encryption: 'AES-256-GCM with a shared room key',
+          retention: 'bounded in-memory replay; no offline inbox',
+          automatic_failover: false,
+          send_success: 'local_queue_acceptance; relay_receipt is not peer consumption'
+        },
         generic_tcp_tunnel: false,
         turn_relays_help_reachability: true,
         guaranteed_firewall_bypass: false,
@@ -1328,6 +1403,8 @@ async function runMcpStdioLoop(options = {}) {
     onExit
   });
 
+  maybeWriteStartupBanner(options, server);
+
   const parser = new McpStdioParser({ maxMessageBytes });
   let chain = Promise.resolve();
   let closed = false;
@@ -1421,5 +1498,7 @@ module.exports = {
   buildTools,
   makeToolResult,
   classifyToolError,
-  parseCliArgs
+  parseCliArgs,
+  buildStartupBanner,
+  maybeWriteStartupBanner
 };

package/scripts/vdo-mcp-ssapp.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+'use strict';
+
+const fs = require('node:fs');
+const readline = require('node:readline');
+const { loadConfig: loadBrowserConfig, makeSession } = require('./vdo-mcp-browser');
+const { BrowserRpcWorker, BrowserRpcClient } = require('./lib/browser-rpc');
+const { SsappController, RPC_OPTIONS, controlOrigin, validateCommand } = require('./lib/ssapp-worker');
+const { McpStdioParser, writeMcpMessage } = require('./lib/mcp-stdio-parser');
+
+const managementTool = (name, description, properties = {}, required = []) => ({ name, description,
+  inputSchema: { type: 'object', properties, required, additionalProperties: false } });
+const MANAGEMENT = [
+  managementTool('ninja_ssapp_status', 'Discover the remote SSApp instance, versions, permissions and control owner. After app restart, list fresh targets and claim control again.'),
+  managementTool('ninja_ssapp_claim', 'Claim or renew control of this SSApp instance for this MCP connection. Other agents can observe. Reconcile uncertain outcomes before using reconciled: true.', {
+    ttl_ms: { type: 'integer', minimum: 1000, maximum: 120000 }, reconciled: { type: 'boolean' }
+  }),
+  managementTool('ninja_ssapp_release', 'Release control for another agent. An already executing action may finish.'),
+  managementTool('ninja_ssapp_result', 'Read a retained transport result by request_id. Unknown does not mean an action failed; inspect SSApp before retrying.', { request_id: { type: 'string' } }, ['request_id'])
+];
+
+function loadConfig(file) {
+  const config = loadBrowserConfig(file);
+  if (config.backend !== 'ssapp') throw new Error('Use an SSApp configuration generated with vdon-mcp-ssapp --setup');
+  if (config.clients) {
+    if (!config.ssapp) throw new Error('Configure the local SSApp MCP command on the host');
+    validateCommand(config.ssapp);
+    controlOrigin(config.ssapp.controlUrl);
+    for (const value of Object.values(config.clients)) {
+      if (value.tools !== undefined && (!Array.isArray(value.tools) || value.tools.some((tool) => typeof tool !== 'string' || !tool.startsWith('ssapp_')))) throw new Error('Client tools must be an array of ssapp_* tool names');
+      if (value.allowHostFiles !== undefined && typeof value.allowHostFiles !== 'boolean') throw new Error('allowHostFiles must be a boolean');
+    }
+  }
+  return config;
+}
+
+async function startWorker(config) {
+  if (!config.clients || config.backend !== 'ssapp') throw new Error('Use the SSApp worker.json on the host');
+  const session = makeSession(config, true);
+  const controller = new SsappController(config);
+  const callers = new Map();
+  const routes = () => session.sessions ? Array.from(session.sessions.values()) : [session];
+  const rpc = new BrowserRpcWorker(session, config, (...args) => controller.execute(...args), { ...RPC_OPTIONS,
+    onAuthenticated: (client, event) => {
+      const peer = routes().flatMap((route) => route.listSyncPeers()).find((peer) => event.uuid === peer.uuid || event.uuid.endsWith(':' + peer.uuid));
+      if (peer?.stream_id) callers.set(client, peer.stream_id);
+    } });
+  const disconnectCheck = setInterval(() => {
+    const owner = controller.lease?.owner;
+    const stream = callers.get(owner);
+    if (owner && stream && !routes().some((route) => route.listSyncPeers().some((peer) => peer.stream_id === stream && route.hasOpenDataChannel(peer.uuid)))) controller.revoke();
+  }, 1000);
+  disconnectCheck.unref();
+  let closing;
+  const close = () => closing || (closing = (async () => { clearInterval(disconnectCheck); rpc.close(); const stopping = controller.close(); await session.stop(); await stopping; })());
+  try { await controller.ensure(); await session.start(); } catch (failure) { await close(); throw failure; }
+  return { session, rpc, controller, close };
+}
+
+class SsappClient {
+  constructor(config, options = {}) {
+    this.config = config;
+    this.session = options.session || makeSession(config, false);
+    this.rpc = new BrowserRpcClient(this.session, config, RPC_OPTIONS);
+    this.discovery = null; this.lease = null; this.connecting = null;
+  }
+  async connect() {
+    if (!this.connecting) this.connecting = this.session.start().then(() => this.rpc.connect()).catch((failure) => { this.connecting = null; throw failure; });
+    await this.connecting;
+  }
+  async discover() {
+    await this.connect();
+    const value = await this.rpc.request('discover', {}, 60000);
+    if (value.error) throw new Error(value.error);
+    if (value.backend !== 'ssapp' || value.contract !== 1) throw new Error('Incompatible remote SSApp worker');
+    if (value.instance?.instanceId !== this.discovery?.instance?.instanceId) this.lease = null;
+    this.discovery = value;
+    return value;
+  }
+  async call(name, args = {}) {
+    if (!this.discovery) await this.discover();
+    if (name === 'ninja_ssapp_status') return this.discover();
+    const common = { instance: this.discovery.instance?.instanceId, lease: this.lease };
+    let response;
+    if (name === 'ninja_ssapp_claim') {
+      response = await this.rpc.request('claim', { ...args, ...common }, 60000);
+      if (response.lease) this.lease = response.lease;
+    } else if (name === 'ninja_ssapp_release') {
+      response = await this.rpc.request('release', common, 60000); this.lease = null;
+    } else if (name === 'ninja_ssapp_result') response = await this.rpc.request('result', args, 60000);
+    else response = await this.rpc.request('call', { ...common, name, arguments: args }, 60000);
+    if (['worker_restarted', 'fresh_app_discovery_required', 'valid_app_lease_required'].includes(response.error)) this.lease = null;
+    return response;
+  }
+  async close() {
+    if (this.lease) await this.rpc.request('release', { lease: this.lease }, 3000).catch(() => {});
+    this.lease = null; this.rpc.close(); await this.session.stop();
+  }
+}
+
+function mcpResult(response, discovery) {
+  const metadata = { backend: 'ssapp', request_id: response.request_id, route: response.route, instanceId: discovery?.instance?.instanceId };
+  if (Array.isArray(response.result?.content) && !response.error) return { ...response.result, _meta: { ...response.result._meta, ninja: metadata } };
+  if (!response.error) return { content: [{ type: 'text', text: JSON.stringify(response) }], _meta: { ninja: metadata } };
+  const structuredContent = { ok: false, ssappVersion: discovery?.instance?.ssappVersion || 'unknown', apiVersion: discovery?.instance?.apiVersion || 'unknown',
+    error: { code: response.error, message: response.message || response.error, ...(response.execution ? { execution: response.execution } : {}) } };
+  return { isError: true, content: [{ type: 'text', text: JSON.stringify(structuredContent) }], structuredContent, _meta: { ninja: metadata } };
+}
+
+async function startClient(config, input = process.stdin, output = process.stdout) {
+  if (config.clients) throw new Error('Use an individual agent JSON file');
+  const client = new SsappClient(config);
+  const parser = new McpStdioParser({ maxMessageBytes: 65536 });
+  const active = new Set(); let closed = false, closing;
+  const dispatch = async (message, mode) => {
+    if (closed || !message || message.jsonrpc !== '2.0' || message.id === undefined) return;
+    const reply = (value) => writeMcpMessage(output, { jsonrpc: '2.0', id: message.id, ...value }, mode);
+    if (active.size >= 12) return reply({ error: { code: -32000, message: 'Too many pending requests' } });
+    try {
+      if (message.method === 'initialize') {
+        const discovery = await client.discover();
+        return reply({ result: { protocolVersion: '2025-06-18', capabilities: { tools: { listChanged: false } }, serverInfo: discovery.serverInfo,
+          instructions: 'These SSApp tools operate the remote host. Call ninja_ssapp_status and list targets; claim control before mutations and release after the task. Keep ssapp_* arguments unchanged. Host file paths refer to that computer. ' + discovery.instructions,
+          _meta: { ninja: { backend: 'ssapp', instance: discovery.instance } } } });
+      }
+      if (message.method === 'ping') return reply({ result: {} });
+      if (message.method === 'tools/list') {
+        const discovery = await client.discover();
+        return reply({ result: { ...discovery.catalog, tools: [...MANAGEMENT, ...discovery.catalog.tools] } });
+      }
+      if (message.method !== 'tools/call') return reply({ error: { code: -32601, message: 'Method not found' } });
+      const params = message.params || {};
+      if (typeof params.name !== 'string' || params.arguments && (typeof params.arguments !== 'object' || Array.isArray(params.arguments))) return reply({ error: { code: -32602, message: 'Invalid tool arguments' } });
+      const response = await client.call(params.name, params.arguments || {});
+      reply({ result: mcpResult(response, client.discovery) });
+    } catch (failure) {
+      if (message.method !== 'tools/call') return reply({ error: { code: -32000, message: failure.message } });
+      reply({ result: mcpResult({ error: failure.code || 'ninja_ssapp_error', message: failure.message }, client.discovery) });
+    }
+  };
+  parser.on('message', ({ message, mode }) => {
+    const pending = dispatch(message, mode); active.add(pending); pending.finally(() => active.delete(pending));
+  });
+  parser.on('error', () => writeMcpMessage(output, { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Invalid MCP request' } }, parser.mode));
+  const close = () => closing || (closing = (async () => {
+    closed = true;
+    const releasing = client.lease ? client.rpc.request('release', { lease: client.lease }, 3000).catch(() => {}) : Promise.resolve();
+    await Promise.allSettled([...active, releasing]); await client.close();
+  })());
+  input.on('data', (chunk) => { parser.push(chunk); if (parser.buffer.length > 65536) { parser.buffer = Buffer.alloc(0); close().catch(() => {}); } });
+  return { client, close };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes('--help')) {
+    console.log('vdon-mcp-ssapp --setup <private-directory> --adapter-config <copied-mcp.json> [--transport webrtc|http|auto] [--relay-config <relay.json>]\nvdon-mcp-ssapp --worker --config <worker.json>\nvdon-mcp-ssapp --config <agent1.json>\nvdon-mcp-ssapp --doctor --config <agent1.json>'); return;
+  }
+  if (args[0] === '--setup') {
+    const directory = args[1]; const options = { backend: 'ssapp' }; let adapterFile;
+    if (!directory || directory.startsWith('--')) throw new Error('Choose a private setup directory');
+    for (let i = 2; i < args.length; i += 2) {
+      if (!args[i + 1]) throw new Error(`Missing value for ${args[i]}`);
+      if (args[i] === '--transport') options.transport = args[i + 1];
+      else if (args[i] === '--relay-config') options.relayConfig = args[i + 1];
+      else if (args[i] === '--adapter-config') adapterFile = args[i + 1];
+      else throw new Error(`Unknown option ${args[i]}`);
+    }
+    if (!adapterFile) throw new Error('Save SSApp\'s copied MCP setup to a private file and pass --adapter-config');
+    const adapter = JSON.parse(fs.readFileSync(adapterFile, 'utf8'));
+    const entries = adapter.mcpServers ? Object.values(adapter.mcpServers) : [adapter];
+    if (entries.length !== 1) throw new Error('Adapter configuration must contain exactly one SSApp MCP command');
+    options.ssapp = { ...entries[0], controlUrl: controlOrigin(entries[0].env?.SSAPP_CONTROL_URL) };
+    validateCommand(options.ssapp);
+    const result = require('./lib/browser-setup').createSetup(directory, options);
+    console.error(`Created private SSApp credentials in ${result.directory}. Start the host with --worker --config worker.json; give each agent only its own JSON file.`); return;
+  }
+  const worker = args[0] === '--worker', doctor = args[0] === '--doctor';
+  if (worker || doctor) args.shift();
+  if (args.length !== 2 || args[0] !== '--config') throw new Error('Use --config <file>');
+  const config = loadConfig(args[1]);
+  if (doctor) {
+    if (config.clients) throw new Error('Use an individual agent JSON file for --doctor');
+    const client = new SsappClient(config);
+    let connected = false;
+    try {
+      const d = await client.discover(); connected = !!d.instance;
+      console.log(JSON.stringify({ ok: connected, backend: d.backend, app: d.instance, mcp: d.serverInfo, role: d.role, tools: d.catalog.tools.length, route: d.route,
+        ...(connected ? {} : { action: 'Start SSApp with API 1.4.1 or newer and enable Local AI / Automation.' }) }, null, 2));
+    }
+    finally { await client.close(); }
+    process.exit(connected ? 0 : 1);
+  }
+  const service = worker ? await startWorker(config) : await startClient(config);
+  const shutdown = () => service.close().then(() => process.stdout.write('', () => process.exit(0)), (failure) => { console.error(failure.message); process.exit(1); });
+  process.once('SIGINT', shutdown); process.once('SIGTERM', shutdown);
+  if (worker) {
+    console.error('SSApp bridge running. Enter revoke to release control, or stop to disconnect the bridge.');
+    const terminal = readline.createInterface({ input: process.stdin });
+    terminal.on('line', (line) => { if (line.trim() === 'revoke') { service.controller.revoke(); console.error('Control revoked. An already executing action may finish.'); } if (line.trim() === 'stop') { terminal.close(); shutdown(); } });
+    terminal.on('SIGINT', shutdown);
+  } else { process.stdin.once('end', shutdown); process.stdin.once('close', shutdown); }
+}
+
+if (require.main === module) main().catch((failure) => { console.error(failure.message); process.exitCode = 1; });
+module.exports = { MANAGEMENT, loadConfig, startWorker, SsappClient, startClient, mcpResult };

package/scripts/vdo-mcp-streamable-http.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+
 'use strict';
 
 const http = require('node:http');
@@ -101,8 +104,17 @@ async function startStreamableHttpServer(options = {}) {
   const runInQueue = createQueueRunner();
 
   const httpServer = http.createServer(async (req, res) => {
-    const reqUrl = new URL(req.url || '/', `http://${req.headers.host || `${host}:${port}`}`);
     const corsHeaders = withCorsHeaders({}, allowOrigin);
+    let reqUrl;
+    try {
+      reqUrl = new URL(req.url || '/', `http://${req.headers.host || `${host}:${port}`}`);
+    } catch (error) {
+      jsonResponse(res, 400, {
+        ok: false,
+        error: 'invalid_url'
+      }, corsHeaders);
+      return;
+    }
 
     if (req.method === 'OPTIONS') {
       res.writeHead(204, corsHeaders);
@@ -209,14 +221,15 @@ async function startStreamableHttpServer(options = {}) {
     endpoint: endpointPath
   });
 
+  let closePromise;
   return {
     server: httpServer,
     mcpServer: server,
     baseUrl,
     endpointUrl: `${baseUrl}${endpointPath}`,
-    close: async () => {
-      await server.shutdownAll();
-      await new Promise((resolve, reject) => {
+    close: () => {
+      if (closePromise) return closePromise;
+      closePromise = new Promise((resolve, reject) => {
         httpServer.close((error) => {
           if (error && error.code !== 'ERR_SERVER_NOT_RUNNING' && error.code !== 'EPERM') {
             reject(error);
@@ -224,7 +237,13 @@ async function startStreamableHttpServer(options = {}) {
           }
           resolve();
         });
+      }).finally(() => {
+        // Stop admission and drain HTTP before cleanup. Disconnected clients
+        // can leave dispatches running after their sockets close, so queue
+        // cleanup behind all accepted MCP work as well.
+        return runInQueue(() => server.shutdownAll());
       });
+      return closePromise;
     }
   };
 }