@vdoninja/mcp 0.4.0 → 0.4.2

package/references/client-config-examples.md

@@ -0,0 +1,253 @@
+# VDO.Ninja MCP Client Config Examples
+
+[Read this guide in HTML](https://steveseguin.github.io/ninjamcp/client-config-examples.html)
+
+Ready-to-paste config for popular MCP clients.
+
+## Prereqs (No Clone)
+
+Install in the project/folder where you want to use the MCP:
+
+```bash
+npm i @vdoninja/mcp
+```
+
+Server script path used below:
+
+- Linux/macOS: `./node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js`
+- Windows: `.\node_modules\@vdoninja\mcp\scripts\vdo-mcp-server.js`
+
+Use an absolute path if your client launches from another working directory.
+
+## Onboarding Pattern (What Works Best)
+
+Popular MCP servers with strong onboarding docs generally do these things:
+
+1. Give one copy/paste install path.
+2. Provide per-client config snippets.
+3. Tell users the first tool call to run.
+4. Show one deterministic "it works" workflow with expected output.
+
+This file follows that same pattern.
+
+## Generic `stdio` MCP Template
+
+Most MCP clients need the same three things:
+
+1. `command` (usually `node`)
+2. `args` (script path + optional flags)
+3. `env` (optional)
+
+Example:
+
+```json
+{
+  "command": "node",
+  "args": [
+    "/ABSOLUTE/PATH/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js",
+    "--tool-profile",
+    "core"
+  ],
+  "env": {
+    "VDON_MCP_TOOL_PROFILE": "core"
+  }
+}
+```
+
+## Cursor
+
+Cursor reads MCP config from:
+
+- Global: `~/.cursor/mcp.json`
+- Project: `.cursor/mcp.json`
+
+Example:
+
+```json
+{
+  "mcpServers": {
+    "vdo-ninja-mcp": {
+      "command": "node",
+      "args": [
+        "/ABSOLUTE/PATH/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"
+      ],
+      "env": {
+        "VDON_MCP_TOOL_PROFILE": "core"
+      }
+    }
+  }
+}
+```
+
+## Gemini CLI
+
+Gemini CLI supports MCP via `mcpServers` in `settings.json`.
+
+Common config file locations:
+
+- Project: `.gemini/settings.json`
+- Linux/macOS: `~/.gemini/settings.json`
+- Windows: `%USERPROFILE%\\.gemini\\settings.json`
+
+Example:
+
+```json
+{
+  "mcpServers": {
+    "vdo-ninja-mcp": {
+      "command": "node",
+      "args": [
+        "/ABSOLUTE/PATH/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"
+      ],
+      "env": {
+        "VDON_MCP_TOOL_PROFILE": "core"
+      }
+    }
+  }
+}
+```
+
+After restarting Gemini CLI, use `/mcp` to confirm server status.
+
+## OpenCode
+
+OpenCode MCP config lives under `mcp` in OpenCode config.
+
+Common config file locations:
+
+- Global: `~/.config/opencode/opencode.json`
+- Project: `opencode.json` (project root)
+
+Example:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "vdo-ninja-mcp": {
+      "type": "local",
+      "command": [
+        "node",
+        "/ABSOLUTE/PATH/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js",
+        "--tool-profile",
+        "core"
+      ],
+      "enabled": true,
+      "environment": {
+        "VDON_MCP_TOOL_PROFILE": "core"
+      }
+    }
+  }
+}
+```
+
+## Codex CLI and Claude Code (CLI Automation)
+
+Auto-register if either/both CLIs are installed:
+
+```bash
+npx vdon-mcp-install
+```
+
+If only one CLI is installed:
+
+```bash
+npx vdon-mcp-install --codex-only
+npx vdon-mcp-install --claude-only
+```
+
+## Sanity Check (All Clients)
+
+First tool call should be:
+
+```json
+{ "name": "vdo_capabilities", "arguments": {} }
+```
+
+Then connect:
+
+```json
+{ "name": "vdo_connect", "arguments": { "room": "lab_1" } }
+```
+
+If `vdo_capabilities` works, your MCP wiring is correct.
+
+## Context Budget Note
+
+Adding MCP servers increases tool/context footprint. Start with one MCP and least-privilege profile (`core`) first, then add more only as needed.
+
+## First Functional Workflows (Clear Result)
+
+Use unique room names to avoid collisions.
+
+### Codex to Codex (Two Terminals)
+
+1. Install/register once:
+
+```bash
+npm i @vdoninja/mcp
+npx vdon-mcp-install --codex-only
+```
+
+2. Open two Codex sessions (`A` and `B`) with MCP enabled.
+3. In session `A`, call:
+
+```json
+{ "name": "vdo_connect", "arguments": { "room": "codex_lab_001", "stream_id": "codex_a" } }
+```
+
+4. In session `B`, call:
+
+```json
+{ "name": "vdo_connect", "arguments": { "room": "codex_lab_001", "stream_id": "codex_b", "target_stream_id": "codex_a" } }
+```
+
+5. In session `A`, send:
+
+```json
+{
+  "name": "vdo_send",
+  "arguments": {
+    "session_id": "<codex_a_session_id>",
+    "data": { "type": "chat.message", "text": "hello from codex_a" }
+  }
+}
+```
+
+6. In session `B`, receive:
+
+```json
+{
+  "name": "vdo_receive",
+  "arguments": {
+    "session_id": "<codex_b_session_id>",
+    "wait_ms": 1000
+  }
+}
+```
+
+Expected result: a `data_received` event containing `"hello from codex_a"`.
+
+### Claude to Claude (Two Terminals)
+
+1. Install/register once:
+
+```bash
+npm i @vdoninja/mcp
+npx vdon-mcp-install --claude-only
+```
+
+2. Repeat the same tool flow as above with a new room name, e.g. `claude_lab_001`.
+
+Expected result: the second Claude session receives the message in `vdo_receive` with `event.type = "data_received"`.
+
+### Fast Scripted Proof (No Manual Tool Calls)
+
+If you just want a quick pass/fail:
+
+```bash
+npx vdon-mcp-demo-message
+npx vdon-mcp-demo-file
+```
+
+Expected result: each script exits successfully and reports message/file workflow completion.

package/references/direction.md

@@ -0,0 +1,88 @@
+# Direction: live tools and perception for MCP agents
+
+[Read this guide in HTML](https://steveseguin.github.io/ninjamcp/direction.html)
+
+Ninja MCP should give an MCP-capable agent a focused way to reach trusted peers, use authorized remote tools, and see and hear selected live context across computers. Keep setup small, prefer direct peer connections, and preserve useful data interactions when WebRTC is unavailable.
+
+The defining experience is an agent working with someone through their existing AI client: the person shows a camera or screen, the agent uses an authorized remote tool or consults a peer, and the result comes back with live context. The person can interrupt speech, change the request, take back control, or stop sharing immediately.
+
+Two agents exchanging a short text message must remain easy. Media, a model-provider account, a background daemon, and a workflow engine should be optional.
+
+## Complement ninja-p2p
+
+| Project | Main responsibility | User's starting point |
+| --- | --- | --- |
+| **Ninja MCP** | Active connections, MCP tool contracts, scoped remote operations, and live media access, including an optional shared Chrome worker. | Add an MCP server to an existing AI client and call a tool. |
+| [ninja-p2p](https://github.com/steveseguin/ninja-p2p) | The continuing team workspace: sidecars, identities and profiles, local inbox/outbox, handoffs, receipts, wake hooks, files, and the operator dashboard. | Start a sidecar, join the team, and retain work between agent turns. |
+| [VDO.Ninja SDK](https://sdk.vdo.ninja/) | Reusable peer connectivity, data channels, and audio/video transport. | Build an application or adapter. |
+
+ninja-p2p owns the room's continuing conversation and work lifecycle. Ninja MCP owns how an MCP client accesses an active peer or remote capability. A shared Chrome worker belongs with Ninja MCP's remote tool adapters; assigning its work and retaining the team's handoffs belong with ninja-p2p. Voice and vision support both experiences through shared SDK media adapters. See [ninja-p2p's north star](https://github.com/steveseguin/ninja-p2p/blob/main/docs/north-star.md).
+
+Keep both usable independently. An optional Ninja MCP adapter should expose ninja-p2p's existing directory, inbox, handoff, and receipt operations, with ninja-p2p remaining the owner of those records. It should preserve origin, request identity, permissions, and the difference between storage acknowledgement and task completion. Extend that integration for background work instead of adding a second inbox, wake scheduler, or team task store to Ninja MCP.
+
+Current room and file envelopes differ between the packages. Sharing the SDK or a room name does not provide application interoperability; use matching packages until an explicit adapter is available. Coordinate reusable relay contracts and media adapters across the projects while keeping their storage and execution guarantees explicit.
+
+## Available foundation
+
+- MCP tools for messages, files, peer discovery, and shared state.
+- Direct WebRTC and optional TURN connectivity.
+- An explicit, self-hosted encrypted HTTP relay for machines and networks without WebRTC.
+- Tool profiles, peer allowlists, join tokens, and per-peer protocol MACs.
+- An optional [Chrome worker](browser-worker.md) with individual client credentials, tab leases, snapshots, screenshots, and SDK tab audio/video.
+- Guided browser setup, connection diagnostics, and automatic WebRTC/HTTP routing with one request identity and worker result cache.
+- An optional [browser companion](browser-agent.md) with OpenAI Realtime speech, selected browser frames, explicit control permission, and interruption.
+- An optional [SSApp bridge](ssapp-integration.md) for the running app's MCP tools, screenshots, input and dialogs, with individual credentials and one controller at a time.
+
+The HTTP path uses POST and long polling with bounded replay. It is a live transport, not a durable inbox. Ordinary room sessions choose matching transports explicitly; the browser adapter can use both. Browser media uses WebRTC separately. A compatible ninja-p2p relay can serve both projects, while its hosted mailboxes retain work between agent turns. Relay acceptance, agent wake, and completed work remain separate outcomes.
+
+## What to build next
+
+1. **Make live tool interactions dependable.** Expose peer capabilities, active connection status, bounded requests, and clear results through a small MCP surface. Distinguish queue acceptance, peer responses, progress, and completion. Bind remote operations to an authenticated caller and an explicit worker permission. Receiving a message never grants permission to execute commands.
+2. **Extend dependable routing beyond browser tools.** Preserve request identity, authentication, and receipt meaning when moving between direct WebRTC, TURN, and the HTTP relay. Carry the browser adapter's direct, relay-only, and automatic policies into other tool adapters where execution can be reconciled. Add SSE where it helps, and make interrupted or uncertain operations visible. Build the optional ninja-p2p adapter for work that must wait in a persistent inbox. Keep large file bytes separate from latency-sensitive events.
+3. **Expand shared perception deliberately.** Build on the browser companion's microphone, selected frames, timestamps, and interruptible speech. Add camera and screen selection before expanding providers, keeping recipients visible and recording off by default. Preserve text and selected snapshots when live media cannot connect. Reuse the media adapter in ninja-p2p's team dashboard.
+4. **Connect to continuing collaboration.** Expose ninja-p2p handoffs and receipts through an optional MCP adapter, preserving the sidecar's state and delivery semantics. Map progress, artifacts, input requests, cancellation, and results to the owning worker or task system. An A2A adapter should share those contracts across the projects. Keep delegation limits and background wake policy with the system that runs them.
+
+Transporting a video track does not make a model understand it. Media adapters should support native streaming models or a pipeline of speech recognition, a text/vision model, and speech synthesis. Stop queued speech on interruption; treat cancelling the underlying task as a separate action.
+
+## Build on the VDO.Ninja SDK
+
+The MCP bridge already uses `@vdoninja/sdk`. Reuse its media publishing and track events for voice, camera, screen, and browser streams. Its request/reply helpers provide a starting point for remote operations; application authorization, stable task IDs, and retry handling still belong to the worker. Keep large transfers on separate data channels and use queue limits so file traffic does not delay controls. See the [SDK API](https://sdk.vdo.ninja/docs/api-reference.html) and [remote-control guide](https://sdk.vdo.ninja/docs/remote-control.html).
+
+The SDK's RPC helpers and Ninja MCP's room protocol are separate interfaces. Connect them through a versioned adapter that preserves authentication and request identity across WebRTC and HTTP. Do not assume an SDK request handler inherits the MCP bridge's peer checks.
+
+## Optional shared Chrome worker
+
+The [browser worker](browser-worker.md) lets people and agents use one isolated remote Chrome tab. The host runs a local Chrome DevTools MCP server and a Ninja room participant. Agents send authenticated tool requests through Ninja MCP; the worker executes them locally and returns results. The host connects outward through WebRTC or the configured HTTPS relay, keeping Chrome's debugging endpoint private. This design needs no VPN, VNC, or VLC. Connectivity still depends on the host's allowed outbound routes.
+
+The adapter pins [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) and Puppeteer as optional dependencies, with explicit page targeting and a separate browser runtime. An extension-based server such as [mcp-chrome](https://github.com/hangwin/mcp-chrome) remains an alternative for an operator's existing browser. [Remote Ninja](https://github.com/steveseguin/remote_ninja) provides an existing VDO.Ninja example of forwarding remote operations to a local application.
+
+Allow multiple observers and give one agent a time-limited control lease for a tab. Hold the lease across a multi-step interaction, check its owner and generation before executing queued commands, and reject stale commands after handoff. Use explicit page IDs and require fresh page state after navigation. Operations affecting the whole browser need coordination across tabs. A human can revoke control; disconnected controllers must not retain an indefinite lock.
+
+Optional live video and captured tab audio travel through SDK media tracks, separately from commands and file transfers. The host explicitly enables Chrome tab capture for the isolated worker. Snapshots remain available when live media cannot connect, and visual responses carry capture timestamps. The browser companion consumes selected frames and the operator's microphone, with separate controls for live viewing, model sharing, and browser control.
+
+The first worker milestone is two agents taking turns on one isolated tab, a human watching its SDK stream, and correlated command results across reconnects. Use bounded requests, enforce permissions at the worker, and reconcile uncertain outcomes before retrying clicks or form submissions. Live audio capture and interruption belong in that milestone's media path; a video recording alone does not provide an interactive call. Shared room membership or possession of a relay key must not automatically grant browser control.
+
+## Ideas to carry forward
+
+| Project | Useful contribution |
+| --- | --- |
+| [Reason Network](https://github.com/reason-machines/reason-network) | A directory of live sessions, context-aware addressing, immediate or deferred delivery, and relay-backed connectivity. |
+| [A2A](https://a2a-protocol.org/latest/specification/) | Capability cards, explicit task lifecycles, streaming progress, and artifacts. |
+| [Agent Relay](https://github.com/AgentWorkforce/relay) | Direct messages, channels, threads, and an inspectable conversation. |
+| [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) | Durable mail and searchable threads for ninja-p2p's continuing workspace, accessible through an optional MCP adapter. |
+| [agents-party](https://github.com/1gr14/agents-party) | A shared room where people can follow and participate in agent collaboration. |
+| [ntfy](https://docs.ntfy.sh/subscribe/api/) and [NATS JetStream](https://docs.nats.io/learn/jetstream/delivery-and-acknowledgment) | Replay cursors, bounded retrieval, explicit acknowledgements, and redelivery. |
+| [Pipecat](https://github.com/pipecat-ai/pipecat), [LiveKit Agents](https://docs.livekit.io/agents/), and [FastRTC](https://github.com/gradio-app/fastrtc) | Agents as media participants, interchangeable media/model adapters, interruption handling, and short runnable examples. |
+| [Social Stream](https://github.com/steveseguin/social_stream/blob/main/api.md) | Simple POST and SSE interaction patterns for a separately operated agent relay. |
+
+Use these as design references. Adopt an idea when it helps participants communicate, retain context, share perception, or control the work. Keep orchestration platforms, public directories, file reservations, and search optional until their value justifies their complexity.
+
+## Product boundaries
+
+Ninja MCP should stay useful to one MCP client using one remote capability. ninja-p2p should stay useful to a continuing team using its CLI, library, or dashboard. The SDK and shared transport/media adapters support both. A feature belongs in Ninja MCP when it improves tool access, active-session reliability, remote control, or live perception; durable team coordination belongs in ninja-p2p.
+
+Privacy needs explicit membership and route visibility. Future invitations should be revocable and scoped. Relay authentication and encryption are separate concerns; a TLS connection alone does not hide plaintext from a relay. Cloud model processing must be visible even when transport to the agent is encrypted.
+
+Reliable delivery does not guarantee exactly-once execution of an external action. Preserve request IDs, use idempotency where supported, and expose an uncertain outcome after a crash instead of silently repeating consequential work.
+
+Judge progress by successful collaborations with a clear result and less manual context copying. Track time to first exchange, missing or duplicate deliveries, reconnect delay, file integrity, and resource cost. For media, measure transport delay, model response time, and interruption response separately.

package/references/http-relay.md

@@ -0,0 +1,107 @@
+# Connect without WebRTC
+
+[Read this guide in HTML](https://steveseguin.github.io/ninjamcp/http-relay.html)
+
+Use the HTTP relay when a machine cannot run the native WebRTC library or its network blocks WebRTC. Two MCP sessions join the same encrypted room through a relay you operate. Messages, file transfers, and shared state use the existing MCP tools.
+
+WebRTC remains the default. Select `transport: "http"` on both participants to use the relay. Sessions using different transports do not discover each other; reconnect both with matching settings when switching.
+
+## Run the relay
+
+The relay needs Node.js 18 or newer and no native dependencies. From a checkout:
+
+```powershell
+$env:VDON_RELAY_TOKEN = '<a random access token, at least 32 characters>'
+node scripts/vdo-mcp-relay.js
+```
+
+From an installed package, use `npx vdon-mcp-relay`. The default listener is `127.0.0.1:8790`. Set `VDON_RELAY_HOST` and `VDON_RELAY_PORT` to change it.
+
+Generate the access token and a separate room key by running this command twice:
+
+```bash
+node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
+```
+
+Keep the room key on the participating clients. The relay receives only the access token. Give each private group its own relay instance and token, and use a different encryption key for each room.
+
+For other computers to connect, put the relay behind an HTTPS reverse proxy on your server. Forward `/v1/rooms/` unchanged, preserve the `Authorization` header, disable caching, allow request bodies up to 768 KiB, and allow responses to wait at least 30 seconds. Keep the Node listener private to the proxy. Remote clients require HTTPS; plain HTTP is accepted only for loopback addresses.
+
+## Configure each MCP client
+
+Install without the optional native WebRTC library if needed:
+
+```bash
+npm install @vdoninja/mcp --omit=optional
+```
+
+Set these variables in the environment of each MCP server process. In a client that supports a JSON server configuration:
+
+```json
+{
+  "command": "node",
+  "args": ["/absolute/path/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"],
+  "env": {
+    "VDON_MCP_RELAY_URL": "https://relay.example.com",
+    "VDON_MCP_RELAY_TOKEN": "<relay access token>",
+    "VDON_MCP_RELAY_KEY": "<64 hex characters from the second command>"
+  }
+}
+```
+
+For two clients on the relay computer, use `http://127.0.0.1:8790`. Both clients need the same relay URL, access token, room key, and room name. Each needs a different `stream_id`.
+
+Keep secrets in the server environment where possible. `vdo_connect` also accepts `relay_url`, `relay_token`, and `relay_key` for clients that need separate settings per session. These secrets are omitted from status and connection results.
+
+## Join and send
+
+Connect the first agent:
+
+```json
+{ "name": "vdo_connect", "arguments": { "transport": "http", "room": "project_room", "stream_id": "planner" } }
+```
+
+Connect the second agent:
+
+```json
+{ "name": "vdo_connect", "arguments": { "transport": "http", "room": "project_room", "stream_id": "reviewer" } }
+```
+
+Use `vdo_sync_peers` to wait for discovery, then address a peer by its stream ID:
+
+```json
+{ "name": "vdo_send", "arguments": { "session_id": "<planner-session>", "target": "reviewer", "data": { "text": "Please review the plan." } } }
+{ "name": "vdo_receive", "arguments": { "session_id": "<reviewer-session>", "wait_ms": 1000 } }
+```
+
+File tools use the same target and retain chunk hashes, acknowledgements, retries, and completion checks. For shared state with `require_session_mac: true`, use the peer UUID from `vdo_sync_peers` as the state operation's `target`; the MAC belongs to that peer connection.
+
+## Delivery and recovery
+
+The relay accepts encrypted events through POST. Clients receive them through long polling with a cursor. Each request returns as soon as an event is available, or after 25 seconds. This path does not need SSE or WebSockets.
+
+| Result or event | Meaning and action |
+| --- | --- |
+| `vdo_send`: `delivery_stage: "queued"` | The local transport accepted the message. Save its `message_id` if you need to track it. |
+| `relay_receipt`: `stage: "relay_accepted"` | The relay accepted the event. This does not confirm peer receipt or task completion; have the other agent reply when those matter. |
+| `relay_receipt`: `stage: "delivery_unknown"` | POST retries failed. The relay may have accepted a request whose response was lost. Check with the peer before repeating a consequential task. |
+| `data_received` | The receiving bridge accepted a message. Its `message_id` matches the sender's ID. The AI client still needs to poll and act on it. |
+| `relay_connection` | The reader lost or regained connectivity. Use `vdo_status` to inspect the current connection. |
+| `relay_history_lost` | The cursor is no longer available. Reconcile outstanding tasks with peers, request a state snapshot, and inspect unfinished file transfers before resuming. |
+| `relay_message_rejected` | An event failed decryption or validation. Check matching room keys and synchronized clocks. |
+
+Retries within the retained history reuse the same encrypted event ID. Distinct messages with identical text keep distinct IDs. Reconnection resumes a running session's cursor; process restarts start a new session. New sessions begin with current traffic rather than retrieving past conversations.
+
+The relay keeps at most 512 events or 8 MiB per room for up to five minutes, across at most 16 rooms. It has no disk archive. A restart clears its history. Use the relay for live collaboration; use an application inbox for durable offline work. A busy room or large transfer can exhaust replay before five minutes.
+
+Queues and request sizes are bounded. `vdo_send` can return `ok: false` when the transport has no known peer, is disconnected, or its queue is full. Wait for discovery or recovery before retrying. File tools already split payloads into chunks; avoid sending whole large files as ordinary messages.
+
+## Trust and privacy
+
+Room payloads use AES-256-GCM with a fresh random nonce and a key derived from the shared room key. The room identifier and event ID are authenticated with each encrypted message. The relay sees connection addresses, opaque room identifiers, timing, and sizes, but does not receive the room key or plaintext payloads.
+
+Every holder of a room key can decrypt that room's traffic, including messages addressed to another participant, and can claim a participant identity. A target selects delivery; it is not a private subchannel within the room. Share keys only with trusted participants and use separate rooms for separate trust groups. Use the existing join-token and allowlist controls to restrict application delivery; an allowlist alone does not establish a cryptographic identity. Rotate shared keys and reconnect participants when access changes.
+
+This group-key mode has no forward secrecy: a disclosed key can decrypt previously captured room traffic. Use WebRTC when its connection-level privacy is required. Keep clocks synchronized; expired or far-future events are rejected.
+
+The HTTP relay carries data. The optional [browser adapter](browser-worker.md) supports automatic WebRTC/HTTP routing for its commands and images; live browser audio/video still uses WebRTC. Ordinary room sessions choose their transport explicitly. The `vdon-mcp-http` command exposes MCP itself over HTTP; `vdon-mcp-relay` carries encrypted events between peers. They are different services.

package/references/mcp-tool-contract.md

@@ -1,10 +1,12 @@
 # VDO.Ninja MCP Tool Contract
 
+[Read this guide in HTML](https://steveseguin.github.io/ninjamcp/mcp-tool-contract.html)
+
 Implemented by:
 
-- `MCP/scripts/vdo-mcp-server.js`
-- Installer automation: `MCP/scripts/install-mcp.js`
-- Discovery manifest: `MCP/server.json`
+- `scripts/vdo-mcp-server.js`
+- Installer automation: `scripts/install-mcp.js`
+- Discovery manifest: `server.json`
 
 ## Transport
 
@@ -23,7 +25,7 @@ Implemented by:
 
 ## Server CLI Flags
 
-Supported by `MCP/scripts/vdo-mcp-server.js`:
+Supported by `scripts/vdo-mcp-server.js`:
 
 - `--tool-profile <core|file|state|full>`
 - `--max-message-bytes <bytes>`
@@ -56,13 +58,19 @@ Enforcement:
 
 ### `vdo_connect` notable options
 
-- transport: `room`, `stream_id`, `target_stream_id`, `host`, `force_turn`
+- transport: `room`, `stream_id`, `target_stream_id`, `transport` (`webrtc` by default or `http`)
+- WebRTC: `host`, `password`, `force_turn`
+- HTTP relay: `relay_url`, `relay_token`, `relay_key`, with defaults from `VDON_MCP_RELAY_URL`, `VDON_MCP_RELAY_TOKEN`, `VDON_MCP_RELAY_KEY`; see [relay setup and delivery semantics](http-relay.md)
 - 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`
 
+`vdo_status` identifies the selected `transport`. HTTP is an explicit peer transport, independent of the HTTP endpoint used to expose MCP. Both participants must use the same transport. WebRTC-only options are rejected in HTTP mode; encryption cannot be disabled on the HTTP relay.
+
+In HTTP mode, `vdo_send` returns `message_id` and `delivery_stage` (`queued` or `rejected`). A later `relay_receipt` event reports `relay_accepted` or `delivery_unknown`. Acceptance does not confirm peer consumption. `data_received` includes the matching `message_id`. `relay_history_lost` means a replay gap requires application reconciliation. Ordinary message queues and relay history are in memory; file completion still requires the existing peer acknowledgement.
+
 ## Sync Tools
 
 - `vdo_sync_peers`: peer handshake/auth/state capabilities
@@ -77,6 +85,8 @@ Enforcement:
 - `vdo_file_receive`: read completed incoming payload (`base64`/`utf8`/`json`)
 - `vdo_file_save`: save completed incoming transfer directly to disk
 
+A retained incoming `transfer_id` is bound to its originating peer UUID and offer metadata (content hash, byte count, chunk layout, name, and MIME type). Identical retries from that peer can resume or confirm completion. Reusing the ID for different content/metadata or from another peer is rejected; use a new ID for a new transfer. Reconnection with a new peer UUID does not transfer ownership of an existing retained ID. Completion acknowledgements must match the sender's content hash and byte count.
+
 ## State Sync Tools (CRDT-lite)
 
 - `vdo_state_set`: update key/value with local monotonic clock
@@ -140,7 +150,7 @@ Tools return `isError: true` with:
 Automated registration:
 
 ```bash
-npm i @vdoninja/mcp @roamhq/wrtc
+npm i @vdoninja/mcp
 npx vdon-mcp-install
 ```
 

package/references/quickstart-and-compat.md

@@ -1,5 +1,7 @@
 # VDO.Ninja MCP Quickstart
 
+[Read this guide in HTML](https://steveseguin.github.io/ninjamcp/quickstart-and-compat.html)
+
 This is the fast path for users and AI agents.
 
 ## Transport Truth
@@ -13,7 +15,7 @@ This is the fast path for users and AI agents.
 Install locally (no clone), including a Node WebRTC implementation:
 
 ```bash
-npm i @vdoninja/mcp @roamhq/wrtc
+npm i @vdoninja/mcp
 ```
 
 Register MCP for Codex/Claude:
@@ -28,6 +30,9 @@ Start the local MCP server:
 npx vdon-mcp-server
 ```
 
+If started directly in a terminal, it prints a short `Server running (stdio)` banner and a first-call hint.
+If started by an MCP client, no interactive banner may appear, which is normal.
+
 Optional least-privilege profile:
 
 ```bash
@@ -38,7 +43,7 @@ Repo-local equivalents still work when developing in this repo:
 
 ```bash
 npm run mcp:install
-node MCP/scripts/vdo-mcp-server.js
+node scripts/vdo-mcp-server.js
 ```
 
 AI-first sanity check (recommended first call):
@@ -186,13 +191,20 @@ 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`.
+- Works with any MCP client that supports local `stdio` transport (Codex CLI, Claude Code, Cursor, and other MCP-compatible CLIs).
+- Codex and Claude can be auto-registered via `npx vdon-mcp-install`.
+- Cursor and other GUI tools typically need manual MCP JSON config using:
+  - `command`: your Node executable
+  - `args`: path to `.../node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js` plus optional flags
+- Ready-to-paste per-client examples are in `references/client-config-examples.md`.
+- Registry metadata is in `server.json`.
+- Tool contracts are in `references/mcp-tool-contract.md`.
 - `@vdoninja/mcp` depends on `@vdoninja/sdk`, so SDK is installed transitively.
+- `@vdoninja/mcp` is MIT licensed. Its SDK dependency is separately licensed
+  under MPL-2.0, with some separately marked wrappers and adapters under MIT.
 
 ## Optional Advanced Diagnostics
 
 For soak/matrix/preset-matrix/sweep tuning and all reliability knobs, use:
 
-- `MCP/references/advanced-diagnostics.md`
+- `references/advanced-diagnostics.md`