@vdoninja/mcp 0.4.0

package/references/vdo-ninja-p2p-data-notes.md

@@ -0,0 +1,156 @@
+# VDO.Ninja P2P Data Notes for MCP Workflows
+
+This file captures operational constraints from this repository's SDK docs.
+
+## Hard Platform Constraints
+
+1. Signaling is not an app-data tunnel.
+- Only handshake/signaling data should traverse WebSocket.
+- Application payloads are expected over WebRTC data channels.
+
+2. Room scale is bounded.
+- Documented guidance is about 80 peers per room (viewer limits can apply).
+- For higher fanout, split rooms or use server-mediated patterns.
+
+3. Serverless philosophy is enforced.
+- No server-side state relay for your app protocol.
+- Design as peer-to-peer first.
+
+## Topologies That Work
+
+1. Two-peer data link (recommended).
+- Peer A: `announce({ streamID })`
+- Peer B: `view(streamID, { audio:false, video:false })`
+- Result: one bidirectional data channel.
+
+2. Multi-peer data mesh.
+- Use `autoConnect(room)` half-mesh mode to avoid duplicate pair connections.
+- Move to full mesh only when media exchange actually needs two directional AV links.
+
+3. Targeted delivery.
+- Use `sendData(data, "uuid")` or advanced target objects.
+- Keep `preference: "any"` unless you explicitly need publisher-only/viewer-only/all-channel behavior.
+
+## Delivery Semantics
+
+- WebRTC data channels are typically configured for reliable, ordered delivery in SDK defaults.
+- Reliability applies after channel establishment; it does not guarantee every network can establish the channel.
+- TURN improves establishment success in restrictive NAT/firewall environments but does not guarantee universal reachability.
+- This MCP skill layers app-level reliability for file transfer:
+  - chunk SHA-256 validation
+  - ACK/NACK feedback
+  - resume from `next_seq` after interruption
+
+## Firewall/NAT Guidance
+
+1. Prefer TURN when needed.
+- `forceTURN: true` can push connections through relay infrastructure.
+- This helps restrictive networks but changes latency/cost characteristics.
+
+2. Treat fallback as last resort.
+- `allowFallback: true` allows `sendData` fallback through signaling when P2P is unavailable.
+- Use for control/survivability, not sustained throughput.
+
+3. Expect hard failure zones.
+- Some enterprise/WSL/network setups can still block WebRTC UDP.
+- Build retry and reconnection logic regardless of TURN.
+
+## Keep-Alive and Session Continuity
+
+1. Keep a heartbeat.
+- Send lightweight periodic app-level heartbeats.
+- Optionally send SDK pings (`sendPing`) to connected peers.
+
+2. Reconnect predictably.
+- On disconnect/error, recreate SDK instance, reconnect, re-join room, re-announce, and re-view targets.
+- Make handlers idempotent to tolerate duplicate or delayed messages around reconnection.
+
+3. Define canonical IDs.
+- Room and stream IDs should use alphanumeric + underscore.
+- Rely on sanitized IDs consistently across all peers.
+
+## Bridge Runtime Knobs
+
+`MCP/scripts/vdo-data-bridge.js` supports:
+
+- `VDON_ROOM` (required in real deployments)
+- `VDON_STREAM_ID` (optional; random if omitted)
+- `VDON_TARGET_STREAM_ID` (optional; auto-view peer stream for two-peer links)
+- `VDON_HOST` (default `wss://wss.vdo.ninja`)
+- `VDON_PASSWORD` (`false` to disable encryption; omitted uses SDK default)
+- `VDON_FORCE_TURN` (`true`/`false`)
+- `VDON_HEARTBEAT_MS` (default `15000`)
+- `VDON_RECONNECT_MS` (default `3000`)
+- `VDON_MAX_RECONNECT_MS` (default `30000`)
+- `VDON_DEBUG` (`true`/`false`)
+
+## App Envelope Suggestions
+
+Use explicit envelope types and IDs over raw strings:
+
+```json
+{
+  "type": "mcp.request",
+  "id": "req_123",
+  "method": "tool.call",
+  "payload": { "name": "lookup", "args": { "q": "abc" } }
+}
+```
+
+```json
+{
+  "type": "mcp.response",
+  "id": "req_123",
+  "ok": true,
+  "payload": { "result": "..." }
+}
+```
+
+Avoid reserved SDK pub/sub types (`subscribe`, `unsubscribe`, `channelMessage`) for custom envelopes.
+
+## File Transfer Envelope Pattern Used Here
+
+This MCP implementation reserves protocol envelopes with:
+
+- `__vdo_mcp: \"vdo_mcp_bridge_v1\"`
+- `kind: \"sync.*\" | \"file.*\"`
+
+File transfer handshake:
+
+1. `file.offer`
+2. `file.accept`
+3. `file.chunk` + `file.ack` / `file.nack`
+4. `file.complete`
+5. `file.complete_ack`
+
+Resume flow:
+
+1. `file.resume_req`
+2. `file.resume_state` (`next_seq`)
+
+## Disk Spooling And Large Files
+
+- This MCP implementation can spool large incoming transfers to disk.
+- Tune via `vdo_connect`:
+  - `file_spool_dir`
+  - `file_spool_threshold_bytes`
+  - `keep_spool_files`
+- Use `vdo_file_send_path` to avoid base64 memory overhead on large local files.
+- Use `vdo_file_save` to persist completed incoming transfers directly.
+
+## Room State Sync (CRDT-lite)
+
+- Shared state is replicated using `state.patch` and `state.snapshot`.
+- Conflict resolution is tuple-based LWW:
+  - higher `clock` wins
+  - tie breaks by `actor` lexical order
+- MCP surface:
+  - `vdo_state_set`
+  - `vdo_state_get`
+  - `vdo_state_sync`
+
+## Local Source Pointers
+
+- `README.md`
+- `AI-INTEGRATION.md`
+- `docs/api-reference.md`

package/scripts/demo-file-workflow.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+'use strict';
+
+const { VdoMcpServer } = require('./vdo-mcp-server');
+const { createFakeSDKFactory } = require('./lib/fake-network-sdk');
+
+function boolFromValue(value, fallback) {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value === 'boolean') return value;
+  const text = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'y', 'on'].includes(text)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(text)) return false;
+  return fallback;
+}
+
+async function waitUntil(predicate, timeoutMs, stepMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await predicate()) return true;
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((resolve) => setTimeout(resolve, stepMs));
+  }
+  return false;
+}
+
+async function waitForIncomingTransfer(server, sessionId, timeoutMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    // eslint-disable-next-line no-await-in-loop
+    const transfers = await server.callTool('vdo_file_transfers', {
+      session_id: sessionId,
+      direction: 'incoming'
+    });
+    const incoming = Array.isArray(transfers.incoming) ? transfers.incoming : [];
+    const completed = incoming.find((transfer) => transfer && transfer.status === 'completed');
+    if (completed) return completed;
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((resolve) => setTimeout(resolve, 150));
+  }
+  return null;
+}
+
+async function main() {
+  const useFake = boolFromValue(process.env.MCP_DEMO_FAKE, true);
+  const forceTurn = boolFromValue(process.env.MCP_DEMO_FORCE_TURN, false);
+  const host = process.env.MCP_DEMO_HOST || process.env.LIVE_WSS_HOST || 'wss://wss.vdo.ninja';
+  const room = process.env.MCP_DEMO_ROOM || `mcp_demo_file_${Date.now()}`;
+  const fileName = process.env.MCP_DEMO_FILE_NAME || 'demo-note.txt';
+  const fileText = process.env.MCP_DEMO_FILE_TEXT || 'hello from MCP file transfer demo';
+  const connectTimeoutMs = Number.parseInt(process.env.MCP_DEMO_CONNECT_TIMEOUT_MS || '', 10) || 15000;
+  const transferTimeoutMs = Number.parseInt(process.env.MCP_DEMO_TRANSFER_TIMEOUT_MS || '', 10) || 12000;
+
+  const baseOptions = {
+    logger: () => {}
+  };
+  if (useFake) {
+    baseOptions.sdkFactory = createFakeSDKFactory();
+  }
+
+  const serverA = new VdoMcpServer(baseOptions);
+  const serverB = new VdoMcpServer(baseOptions);
+  let sessionA;
+  let sessionB;
+  const startedAt = new Date().toISOString();
+
+  try {
+    console.log(`[demo-file] mode=${useFake ? 'fake' : 'live'} host=${host} force_turn=${forceTurn}`);
+    console.log(`[demo-file] room=${room}`);
+
+    const connectA = await serverA.callTool('vdo_connect', {
+      host,
+      room,
+      stream_id: 'demo_file_a',
+      force_turn: forceTurn
+    });
+    sessionA = connectA.session_id;
+
+    const connectB = await serverB.callTool('vdo_connect', {
+      host,
+      room,
+      stream_id: 'demo_file_b',
+      target_stream_id: 'demo_file_a',
+      force_turn: forceTurn
+    });
+    sessionB = connectB.session_id;
+
+    const connected = await waitUntil(async () => {
+      const [statusA, statusB] = await Promise.all([
+        serverA.callTool('vdo_status', { session_id: sessionA }),
+        serverB.callTool('vdo_status', { session_id: sessionB })
+      ]);
+      return statusA.connected && statusB.connected;
+    }, connectTimeoutMs, 200);
+    if (!connected) {
+      throw new Error('demo-file connect timeout');
+    }
+
+    const payload = Buffer.from(fileText, 'utf8').toString('base64');
+    const sent = await serverA.callTool('vdo_file_send', {
+      session_id: sessionA,
+      data_base64: payload,
+      name: fileName,
+      mime: 'text/plain'
+    });
+    if (!sent.ok) {
+      throw new Error('demo-file send returned ok=false');
+    }
+
+    const completed = await waitForIncomingTransfer(serverB, sessionB, transferTimeoutMs);
+    if (!completed) {
+      throw new Error('demo-file receive timeout');
+    }
+
+    const received = await serverB.callTool('vdo_file_receive', {
+      session_id: sessionB,
+      transfer_id: completed.transfer_id,
+      encoding: 'utf8'
+    });
+    if (received.data_text !== fileText) {
+      throw new Error('demo-file content mismatch');
+    }
+
+    const summary = {
+      ok: true,
+      started_at: startedAt,
+      finished_at: new Date().toISOString(),
+      mode: useFake ? 'fake' : 'live',
+      room,
+      force_turn: forceTurn,
+      host,
+      session_a: sessionA,
+      session_b: sessionB,
+      transfer_id: completed.transfer_id,
+      file_name: fileName,
+      bytes: Buffer.byteLength(fileText, 'utf8')
+    };
+
+    console.log(JSON.stringify(summary, null, 2));
+    console.log('demo-file-workflow.js passed');
+  } finally {
+    try {
+      if (sessionA) await serverA.callTool('vdo_disconnect', { session_id: sessionA });
+    } catch (error) {
+      // Ignore cleanup failures.
+    }
+    try {
+      if (sessionB) await serverB.callTool('vdo_disconnect', { session_id: sessionB });
+    } catch (error) {
+      // Ignore cleanup failures.
+    }
+    try {
+      await serverA.shutdownAll();
+    } catch (error) {
+      // Ignore cleanup failures.
+    }
+    try {
+      await serverB.shutdownAll();
+    } catch (error) {
+      // Ignore cleanup failures.
+    }
+  }
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/scripts/demo-message-workflow.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+'use strict';
+
+const { VdoMcpServer } = require('./vdo-mcp-server');
+const { createFakeSDKFactory } = require('./lib/fake-network-sdk');
+
+function boolFromValue(value, fallback) {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value === 'boolean') return value;
+  const text = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'y', 'on'].includes(text)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(text)) return false;
+  return fallback;
+}
+
+async function waitUntil(predicate, timeoutMs, stepMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await predicate()) return true;
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((resolve) => setTimeout(resolve, stepMs));
+  }
+  return false;
+}
+
+async function waitForMessage(server, sessionId, id, timeoutMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    // eslint-disable-next-line no-await-in-loop
+    const received = await server.callTool('vdo_receive', {
+      session_id: sessionId,
+      max_events: 100,
+      wait_ms: 250
+    });
+    const events = Array.isArray(received.events) ? received.events : [];
+    const match = events.find((event) => (
+      event &&
+      event.type === 'data_received' &&
+      event.data &&
+      event.data.type === 'demo.message' &&
+      event.data.id === id
+    ));
+    if (match) return match;
+  }
+  return null;
+}
+
+async function main() {
+  const useFake = boolFromValue(process.env.MCP_DEMO_FAKE, true);
+  const forceTurn = boolFromValue(process.env.MCP_DEMO_FORCE_TURN, false);
+  const host = process.env.MCP_DEMO_HOST || process.env.LIVE_WSS_HOST || 'wss://wss.vdo.ninja';
+  const room = process.env.MCP_DEMO_ROOM || `mcp_demo_message_${Date.now()}`;
+  const message = process.env.MCP_DEMO_MESSAGE || 'hello from MCP message demo';
+  const connectTimeoutMs = Number.parseInt(process.env.MCP_DEMO_CONNECT_TIMEOUT_MS || '', 10) || 15000;
+  const messageTimeoutMs = Number.parseInt(process.env.MCP_DEMO_MESSAGE_TIMEOUT_MS || '', 10) || 8000;
+
+  const baseOptions = {
+    logger: () => {}
+  };
+  if (useFake) {
+    baseOptions.sdkFactory = createFakeSDKFactory();
+  }
+
+  const serverA = new VdoMcpServer(baseOptions);
+  const serverB = new VdoMcpServer(baseOptions);
+  let sessionA;
+  let sessionB;
+  const startedAt = new Date().toISOString();
+
+  try {
+    console.log(`[demo-message] mode=${useFake ? 'fake' : 'live'} host=${host} force_turn=${forceTurn}`);
+    console.log(`[demo-message] room=${room}`);
+
+    const connectA = await serverA.callTool('vdo_connect', {
+      host,
+      room,
+      stream_id: 'demo_agent_a',
+      force_turn: forceTurn
+    });
+    sessionA = connectA.session_id;
+
+    const connectB = await serverB.callTool('vdo_connect', {
+      host,
+      room,
+      stream_id: 'demo_agent_b',
+      target_stream_id: 'demo_agent_a',
+      force_turn: forceTurn
+    });
+    sessionB = connectB.session_id;
+
+    const connected = await waitUntil(async () => {
+      const [statusA, statusB] = await Promise.all([
+        serverA.callTool('vdo_status', { session_id: sessionA }),
+        serverB.callTool('vdo_status', { session_id: sessionB })
+      ]);
+      return statusA.connected && statusB.connected;
+    }, connectTimeoutMs, 200);
+    if (!connected) {
+      throw new Error('demo-message connect timeout');
+    }
+
+    const id = `demo_msg_${Date.now()}`;
+    const payload = {
+      type: 'demo.message',
+      id,
+      text: message,
+      sent_at: Date.now()
+    };
+
+    const send = await serverA.callTool('vdo_send', {
+      session_id: sessionA,
+      data: payload
+    });
+    if (!send.ok) {
+      throw new Error('demo-message send returned ok=false');
+    }
+
+    const received = await waitForMessage(serverB, sessionB, id, messageTimeoutMs);
+    if (!received) {
+      throw new Error('demo-message receive timeout');
+    }
+
+    const summary = {
+      ok: true,
+      started_at: startedAt,
+      finished_at: new Date().toISOString(),
+      mode: useFake ? 'fake' : 'live',
+      room,
+      force_turn: forceTurn,
+      host,
+      session_a: sessionA,
+      session_b: sessionB,
+      sent_message: payload.text,
+      received_message: received.data.text
+    };
+
+    console.log(JSON.stringify(summary, null, 2));
+    console.log('demo-message-workflow.js passed');
+  } finally {
+    try {
+      if (sessionA) await serverA.callTool('vdo_disconnect', { session_id: sessionA });
+    } catch (error) {
+      // Ignore cleanup failures.
+    }
+    try {
+      if (sessionB) await serverB.callTool('vdo_disconnect', { session_id: sessionB });
+    } catch (error) {
+      // Ignore cleanup failures.
+    }
+    try {
+      await serverA.shutdownAll();
+    } catch (error) {
+      // Ignore cleanup failures.
+    }
+    try {
+      await serverB.shutdownAll();
+    } catch (error) {
+      // Ignore cleanup failures.
+    }
+  }
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});