@vdoninja/mcp 0.4.0

package/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: mcp
+description: Use VDO.Ninja WebRTC data channels as MCP tools for bot-to-bot messaging and reliable file transfer, with clear transport limits, optional TURN, and optional join-token/session-MAC security.
+---
+
+# VDO.Ninja MCP Skill
+
+Use this skill to run VDO.Ninja as an MCP data bridge in Codex, Claude Code, and compatible MCP clients.
+
+## What It Is For
+
+- Fast bot-to-bot data messaging.
+- Reliable file send/receive over WebRTC data channels.
+- Optional secure room membership and peer allowlists.
+
+## What It Is Not
+
+- Not a generic TCP tunnel.
+- Not guaranteed firewall bypass.
+
+## Core Transport Truth
+
+- Transport is WebRTC data channels.
+- TURN can improve success on restrictive networks.
+- TURN is not guaranteed to bypass all enterprise policies.
+
+## Fast Path
+
+1. Install MCP registration:
+`npm i @vdoninja/mcp @roamhq/wrtc`
+
+2. Register for Codex/Claude:
+`npx vdon-mcp-install`
+
+3. Start server:
+`npx vdon-mcp-server`
+
+4. Optional least-privilege tool profile:
+`VDON_MCP_TOOL_PROFILE=core|file|state|full npx vdon-mcp-server`
+
+5. First tool call:
+`{ "name": "vdo_capabilities", "arguments": {} }`
+
+## Two Primary Workflows
+
+### Workflow A: Messaging
+
+- Connect peer A and peer B with `vdo_connect`.
+- Send with `vdo_send`.
+- Receive with `vdo_receive`.
+- Demo script: `npm run mcp:demo:message`
+
+### Workflow B: File Transfer
+
+- Send with `vdo_file_send` or `vdo_file_send_path`.
+- Track with `vdo_file_transfers`.
+- Read with `vdo_file_receive` or persist with `vdo_file_save`.
+- Resume interrupted send with `vdo_file_resume`.
+- Demo script: `npm run mcp:demo:file`
+
+## Security Controls
+
+- `join_token` + `join_token_secret`
+- `enforce_join_token`
+- `allow_peer_stream_ids`
+- `require_session_mac`
+
+For secure presets, set `VDON_MCP_JOIN_TOKEN_SECRET` before install/runtime.
+`@vdoninja/mcp` depends on `@vdoninja/sdk`, so SDK installs transitively.
+
+## AI Agent Contract
+
+- Call `vdo_capabilities` first.
+- Call `vdo_connect` before send/file/state tools.
+- Prefer least-privilege tool profile.
+- For files, use file tools instead of manual chunking via `vdo_send`.
+- Handle `validation_error` and retry idempotently.
+
+## Testing
+
+- Product test bar: `npm run test:mcp`
+- Full engineering suite: `npm run test:mcp:all`
+- Live diagnostics (optional): `MCP/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`

package/assets/cloudflare/worker-proxy.js

@@ -0,0 +1,89 @@
+/**
+ * Cloudflare Worker proxy template for a remote MCP HTTP endpoint.
+ *
+ * This Worker does not run WebRTC itself.
+ * It forwards MCP JSON-RPC requests to an upstream vdo-mcp-streamable-http server.
+ *
+ * Required secrets/config:
+ * - MCP_UPSTREAM_URL: e.g. https://your-origin.example.com/mcp
+ * - MCP_UPSTREAM_TOKEN: bearer token expected by upstream server
+ */
+
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+
+    if (request.method === 'OPTIONS') {
+      return new Response(null, {
+        status: 204,
+        headers: corsHeaders(env)
+      });
+    }
+
+    if (url.pathname === '/health') {
+      return json({
+        ok: true,
+        mode: 'cloudflare_proxy',
+        ts: new Date().toISOString()
+      }, 200, env);
+    }
+
+    if (url.pathname !== '/mcp') {
+      return json({ ok: false, error: 'not_found' }, 404, env);
+    }
+
+    if (request.method !== 'POST') {
+      return json({ ok: false, error: 'method_not_allowed' }, 405, env);
+    }
+
+    const upstreamUrl = env.MCP_UPSTREAM_URL;
+    if (!upstreamUrl) {
+      return json({ ok: false, error: 'missing_upstream_url' }, 500, env);
+    }
+
+    const upstreamToken = env.MCP_UPSTREAM_TOKEN || '';
+    const body = await request.text();
+
+    const headers = {
+      'content-type': 'application/json'
+    };
+    if (upstreamToken) {
+      headers.authorization = `Bearer ${upstreamToken}`;
+    }
+
+    const upstreamRes = await fetch(upstreamUrl, {
+      method: 'POST',
+      headers,
+      body
+    });
+
+    const upstreamBody = await upstreamRes.text();
+    return new Response(upstreamBody, {
+      status: upstreamRes.status,
+      headers: {
+        ...corsHeaders(env),
+        'content-type': upstreamRes.headers.get('content-type') || 'application/json; charset=utf-8'
+      }
+    });
+  }
+};
+
+function json(payload, status, env) {
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: {
+      ...corsHeaders(env),
+      'content-type': 'application/json; charset=utf-8'
+    }
+  });
+}
+
+function corsHeaders(env) {
+  const allowOrigin = env.MCP_ALLOW_ORIGIN || '*';
+  return {
+    'access-control-allow-origin': allowOrigin,
+    'access-control-allow-methods': 'GET,POST,OPTIONS',
+    'access-control-allow-headers': 'authorization,content-type',
+    'access-control-max-age': '600'
+  };
+}

package/assets/cloudflare/wrangler.toml.example

@@ -0,0 +1,10 @@
+name = "vdo-ninja-mcp-proxy"
+main = "worker-proxy.js"
+compatibility_date = "2026-02-22"
+
+[vars]
+MCP_ALLOW_ORIGIN = "*"
+
+# Set these as secrets:
+# wrangler secret put MCP_UPSTREAM_URL
+# wrangler secret put MCP_UPSTREAM_TOKEN

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@vdoninja/mcp",
+  "version": "0.4.0",
+  "description": "VDO.Ninja MCP bridge for WebRTC data-channel messaging, file transfer, and room sync.",
+  "license": "AGPL-3.0-only",
+  "homepage": "https://github.com/steveseguin/ninjasdk/tree/main/MCP",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/steveseguin/ninjasdk.git",
+    "directory": "MCP"
+  },
+  "bugs": {
+    "url": "https://github.com/steveseguin/ninjasdk/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "vdo.ninja",
+    "webrtc",
+    "data-channel",
+    "p2p",
+    "ai"
+  ],
+  "bin": {
+    "vdon-mcp-install": "scripts/install-mcp.js",
+    "vdon-mcp-server": "scripts/vdo-mcp-server.js",
+    "vdon-mcp-http": "scripts/vdo-mcp-streamable-http.js",
+    "vdon-mcp-demo-message": "scripts/demo-message-workflow.js",
+    "vdon-mcp-demo-file": "scripts/demo-file-workflow.js"
+  },
+  "scripts": {
+    "mcp:install": "node scripts/install-mcp.js",
+    "mcp:server": "node scripts/vdo-mcp-server.js",
+    "mcp:http": "node scripts/vdo-mcp-streamable-http.js",
+    "demo:message": "node scripts/demo-message-workflow.js",
+    "demo:file": "node scripts/demo-file-workflow.js"
+  },
+  "files": [
+    "SKILL.md",
+    "server.json",
+    "assets/cloudflare/worker-proxy.js",
+    "assets/cloudflare/wrangler.toml.example",
+    "references/advanced-diagnostics.md",
+    "references/mcp-tool-contract.md",
+    "references/quickstart-and-compat.md",
+    "references/vdo-ninja-p2p-data-notes.md",
+    "scripts/demo-file-workflow.js",
+    "scripts/demo-message-workflow.js",
+    "scripts/install-mcp.js",
+    "scripts/vdo-data-bridge.js",
+    "scripts/vdo-mcp-server.js",
+    "scripts/vdo-mcp-streamable-http.js",
+    "scripts/lib/bridge-session.js",
+    "scripts/lib/bridge-utils.js",
+    "scripts/lib/fake-network-sdk.js",
+    "scripts/lib/load-vdo-sdk.js",
+    "scripts/lib/mcp-stdio-parser.js",
+    "scripts/lib/tool-profiles.js"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@vdoninja/sdk": "^1.3.18"
+  }
+}

package/references/advanced-diagnostics.md

@@ -0,0 +1,45 @@
+# VDO.Ninja MCP Advanced Diagnostics
+
+This page is optional. Use it when you are debugging reliability or network edge cases.
+
+## Live Test Commands
+
+```bash
+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
+```
+
+Secure preset matrix:
+
+```bash
+LIVE_VDO_TEST=1 VDON_MCP_JOIN_TOKEN_SECRET=change_me npm run test:mcp:preset:matrix
+```
+
+## Preset Matrix Notes
+
+- `PRESET_MATRIX_ADAPTIVE_FALLBACK=1` enables candidate fallback.
+- `PRESET_MATRIX_ALLOW_DIRECT_FALLBACK=1` allows direct fallback after TURN candidates.
+- `PRESET_MATRIX_STRICT=1` fails process when any profile fails.
+- `PRESET_CONNECT_ATTEMPTS`, `PRESET_CONNECT_TIMEOUT_MS`, and `PRESET_CHANNEL_READY_TIMEOUT_MS` control connect behavior.
+
+Artifacts are written to:
+
+- `MCP/tests/artifacts/latest-preset-matrix-report.json`
+- `MCP/tests/artifacts/latest-preset-matrix-summary.txt`
+- `MCP/tests/artifacts/history/preset-matrix-*.json`
+- `MCP/tests/artifacts/history/preset-matrix-*.txt`
+
+## Soak / Matrix Knobs
+
+- Smoke: `LIVE_SMOKE_RETRIES`, `LIVE_SMOKE_TIMEOUT_MS`
+- Soak: `SOAK_RETRIES`, `SOAK_TIMEOUT_MS`
+- Matrix: `SOAK_MATRIX_PROFILE_RETRIES`, `SOAK_MATRIX_PROFILE_TIMEOUT_MS`
+- Sweep: `SOAK_MATRIX_SWEEP_RUNS`, `SOAK_MATRIX_SWEEP_TIMEOUT_MS`, `SOAK_MATRIX_SWEEP_MIN_SUCCESS_RATE`
+
+## Important
+
+- WebRTC data channels are the transport.
+- TURN helps reachability but is not a universal bypass for all enterprise firewall policies.

package/references/mcp-tool-contract.md

@@ -0,0 +1,184 @@
+# VDO.Ninja MCP Tool Contract
+
+Implemented by:
+
+- `MCP/scripts/vdo-mcp-server.js`
+- Installer automation: `MCP/scripts/install-mcp.js`
+- Discovery manifest: `MCP/server.json`
+
+## Transport
+
+- JSON-RPC 2.0 over stdio
+- Input:
+  - newline-delimited JSON messages
+  - `Content-Length` framed messages
+- Output:
+  - framed when framed input is detected
+  - newline JSON otherwise
+
+## Runtime Limit
+
+- `VDON_MCP_MAX_MESSAGE_BYTES` (default `1048576`)
+- `VDON_MCP_TOOL_PROFILE` (default `full`, values: `core|file|state|full`)
+
+## Server CLI Flags
+
+Supported by `MCP/scripts/vdo-mcp-server.js`:
+
+- `--tool-profile <core|file|state|full>`
+- `--max-message-bytes <bytes>`
+- `--join-token-secret <secret>`
+- `--enforce-join-token <true|false>`
+- `--allow-peer-stream-ids <a,b,c>`
+- `--require-session-mac <true|false>`
+
+## Capability Profiles
+
+- `core`: `vdo_connect`, `vdo_send`, `vdo_receive`, `vdo_status`, `vdo_disconnect`, `vdo_list_sessions`, `vdo_capabilities`, `vdo_sync_peers`, `vdo_sync_announce`
+- `file`: `core` + all file transfer tools
+- `state`: `core` + all state sync tools
+- `full`: `core` + file + state tools
+
+Enforcement:
+
+- `tools/list` only advertises tools in the active profile.
+- Calling a disabled tool returns `validation_error`.
+
+## Core Session Tools
+
+- `vdo_connect`
+- `vdo_send`
+- `vdo_receive`
+- `vdo_status`
+- `vdo_disconnect`
+- `vdo_list_sessions`
+- `vdo_capabilities`
+
+### `vdo_connect` notable options
+
+- transport: `room`, `stream_id`, `target_stream_id`, `host`, `force_turn`
+- resiliency: `heartbeat_ms`, `reconnect_ms`, `max_reconnect_ms`
+- security: `join_token`, `join_token_secret`, `join_token_ttl_ms`, `enforce_join_token`, `allow_peer_stream_ids`, `require_session_mac`
+- file defaults: `file_chunk_bytes`, `file_max_bytes`, `file_ack_timeout_ms`, `file_max_retries`
+- file spooling: `file_spool_dir`, `file_spool_threshold_bytes`, `keep_spool_files`
+- state limits: `state_max_keys`, `state_max_snapshot_entries`
+
+## Sync Tools
+
+- `vdo_sync_peers`: peer handshake/auth/state capabilities
+- `vdo_sync_announce`: force immediate sync hello
+
+## File Transfer Tools
+
+- `vdo_file_send`: send from `data_base64`
+- `vdo_file_send_path`: send directly from local `file_path`
+- `vdo_file_resume`: resume outgoing transfer by `transfer_id`
+- `vdo_file_transfers`: inspect incoming/outgoing transfer state
+- `vdo_file_receive`: read completed incoming payload (`base64`/`utf8`/`json`)
+- `vdo_file_save`: save completed incoming transfer directly to disk
+
+## State Sync Tools (CRDT-lite)
+
+- `vdo_state_set`: update key/value with local monotonic clock
+- `vdo_state_get`: read key or full state snapshot
+- `vdo_state_sync`: request/send full snapshot (`mode: request|send`)
+
+Merge rule is tuple-based last-writer:
+
+1. higher `clock` wins
+2. if equal clock, lexicographically higher `actor` wins
+
+## Protocol Envelope Family
+
+Internal control/file/state envelopes use:
+
+```json
+{
+  "__vdo_mcp": "vdo_mcp_bridge_v1",
+  "kind": "sync.* | file.* | state.*",
+  "payload": {}
+}
+```
+
+## Event Types via `vdo_receive`
+
+Lifecycle:
+
+- `ready`, `connected`, `disconnected`, `connection_failed`, `sdk_error`, `reconnect_scheduled`
+- `peer_connected`, `peer_disconnected`, `data_channel_open`, `data_channel_close`
+- `data_received`, `send_error`, `send_rejected`, `heartbeat_sent`
+
+Sync/security:
+
+- `sync_hello_sent`, `sync_peer_updated`, `sync_peer_rejected`, `protocol_auth_failed`
+
+File:
+
+- `file_offer_received`, `file_chunk_received`, `file_chunk_rejected`, `file_received`, `file_transfer_complete`, `file_transfer_cancelled`
+
+State:
+
+- `state_updated`, `state_snapshot_merged`, `state_protocol_unhandled`
+
+## Error Shape
+
+Tools return `isError: true` with:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "type": "validation_error | tool_error",
+    "message": "...",
+    "tool": "..."
+  }
+}
+```
+
+## Client Wiring
+
+Automated registration:
+
+```bash
+npm i @vdoninja/mcp @roamhq/wrtc
+npx vdon-mcp-install
+```
+
+Preset registrations:
+
+```bash
+npx vdon-mcp-install --preset core
+npx vdon-mcp-install --preset file
+npx vdon-mcp-install --preset state
+npx vdon-mcp-install --preset secure-core
+npx vdon-mcp-install --preset secure-full
+```
+
+Removal:
+
+```bash
+npx vdon-mcp-install --uninstall
+```
+
+Codex-style:
+
+```json
+{
+  "name": "vdo-ninja-mcp",
+  "command": "node",
+  "args": ["node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"]
+}
+```
+
+Claude Code-style:
+
+```json
+{
+  "mcpServers": {
+    "vdo-ninja-mcp": {
+      "command": "node",
+      "args": ["node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"]
+    }
+  }
+}
+```

package/references/quickstart-and-compat.md

@@ -0,0 +1,198 @@
+# VDO.Ninja MCP Quickstart
+
+This is the fast path for users and AI agents.
+
+## Transport Truth
+
+- This bridge uses **WebRTC data channels**.
+- It is **not** a generic TCP/SSH tunnel.
+- TURN improves connectivity on restrictive networks, but it is **not** a guaranteed firewall bypass.
+
+## 60-Second Setup
+
+Install locally (no clone), including a Node WebRTC implementation:
+
+```bash
+npm i @vdoninja/mcp @roamhq/wrtc
+```
+
+Register MCP for Codex/Claude:
+
+```bash
+npx vdon-mcp-install
+```
+
+Start the local MCP server:
+
+```bash
+npx vdon-mcp-server
+```
+
+Optional least-privilege profile:
+
+```bash
+VDON_MCP_TOOL_PROFILE=core npx vdon-mcp-server
+```
+
+Repo-local equivalents still work when developing in this repo:
+
+```bash
+npm run mcp:install
+node MCP/scripts/vdo-mcp-server.js
+```
+
+AI-first sanity check (recommended first call):
+
+```json
+{ "name": "vdo_capabilities", "arguments": {} }
+```
+
+## Workflow A: Bot-to-Bot Message
+
+1. Connect peer A:
+
+```json
+{ "name": "vdo_connect", "arguments": { "room": "lab_1", "stream_id": "agent_a" } }
+```
+
+2. Connect peer B:
+
+```json
+{ "name": "vdo_connect", "arguments": { "room": "lab_1", "stream_id": "agent_b", "target_stream_id": "agent_a" } }
+```
+
+3. Send:
+
+```json
+{
+  "name": "vdo_send",
+  "arguments": {
+    "session_id": "<agent_a_session_id>",
+    "data": { "type": "chat.message", "text": "hello from agent_a" }
+  }
+}
+```
+
+4. Receive:
+
+```json
+{
+  "name": "vdo_receive",
+  "arguments": {
+    "session_id": "<agent_b_session_id>",
+    "max_events": 100,
+    "wait_ms": 1000
+  }
+}
+```
+
+Runnable demo script:
+
+```bash
+npx vdon-mcp-demo-message
+```
+
+For live network mode instead of fake/local demo mode:
+
+```bash
+MCP_DEMO_FAKE=0 MCP_DEMO_FORCE_TURN=1 npx vdon-mcp-demo-message
+```
+
+## Workflow B: File Send/Receive
+
+1. Reuse two connected peers from Workflow A.
+
+2. Send file payload from agent A:
+
+```json
+{
+  "name": "vdo_file_send",
+  "arguments": {
+    "session_id": "<agent_a_session_id>",
+    "name": "notes.txt",
+    "mime": "text/plain",
+    "data_base64": "<base64>"
+  }
+}
+```
+
+3. On agent B, watch transfers:
+
+```json
+{
+  "name": "vdo_file_transfers",
+  "arguments": {
+    "session_id": "<agent_b_session_id>",
+    "direction": "incoming"
+  }
+}
+```
+
+4. Read completed file:
+
+```json
+{
+  "name": "vdo_file_receive",
+  "arguments": {
+    "session_id": "<agent_b_session_id>",
+    "transfer_id": "<transfer_id>",
+    "encoding": "utf8"
+  }
+}
+```
+
+Runnable demo script:
+
+```bash
+npx vdon-mcp-demo-file
+```
+
+For live network mode:
+
+```bash
+MCP_DEMO_FAKE=0 MCP_DEMO_FORCE_TURN=1 npx vdon-mcp-demo-file
+```
+
+## Security Baseline
+
+Use secure mode when needed:
+
+- `join_token` + `join_token_secret`
+- `enforce_join_token: true`
+- `allow_peer_stream_ids: [...]`
+- `require_session_mac: true`
+
+For secure preset installs, set `VDON_MCP_JOIN_TOKEN_SECRET` first.
+
+## Minimal Test Bar
+
+Default MCP test run (fast, product-focused):
+
+```bash
+npm run test:mcp
+```
+
+This runs:
+
+- conformance
+- server smoke
+- sync security smoke
+
+Full engineering suite (advanced):
+
+```bash
+npm run test:mcp:all
+```
+
+## Compatibility Notes
+
+- Codex and Claude Code both work via command-based local MCP registration.
+- Registry metadata is in `MCP/server.json`.
+- Tool contracts are in `MCP/references/mcp-tool-contract.md`.
+- `@vdoninja/mcp` depends on `@vdoninja/sdk`, so SDK is installed transitively.
+
+## Optional Advanced Diagnostics
+
+For soak/matrix/preset-matrix/sweep tuning and all reliability knobs, use:
+
+- `MCP/references/advanced-diagnostics.md`