@vdoninja/mcp 0.4.0 → 0.4.1

package/LICENSE-SDK-EXCEPTION

@@ -0,0 +1,54 @@
+VDO.Ninja MCP Unmodified Distribution Exception
+==============================================
+
+This document grants an additional permission under Section 7 of the GNU Affero
+General Public License version 3 (AGPL-3.0-only) for the VDO.Ninja MCP package.
+
+1. Covered MCP Files
+--------------------
+This exception applies only to files distributed as part of an official
+`@vdoninja/mcp` package release (the "Covered MCP Files"), including files
+listed in the package's published `files` allowlist.
+
+2. Official Distributions
+-------------------------
+An "Official Distribution" of Covered MCP Files means a copy distributed by
+Steve Seguin as part of:
+
+- the npm package `@vdoninja/mcp@X.Y.Z` (a specific published version), and/or
+- a tagged release `vX.Y.Z` of:
+  - https://github.com/steveseguin/ninjasdk (directory `MCP/`), or
+  - https://github.com/steveseguin/ninjamcp
+
+and any byte-for-byte identical mirror of that exact Official Distribution.
+
+3. Unmodified
+-------------
+"Unmodified" means byte-for-byte identical to an Official Distribution of the
+same Covered MCP File, including preservation of any license notices.
+
+4. Additional Permission
+------------------------
+Notwithstanding the other terms of the AGPL-3.0-only, you are granted permission
+to use, copy, combine, bundle, link, and convey the Covered MCP Files in
+Unmodified form as part of a larger work (a "Larger Work"), and to convey that
+Larger Work under terms of your choice (including proprietary terms), without
+requiring that the Larger Work as a whole be licensed under the AGPL.
+
+5. Conditions
+-------------
+This additional permission applies only if:
+
+- the Covered MCP Files are Unmodified; and
+- you comply with the AGPL-3.0-only requirements applicable to conveying verbatim
+  copies of the Covered MCP Files (including preserving notices and providing
+  recipients a copy of the AGPL license).
+
+6. Modified Versions
+--------------------
+If you modify any Covered MCP File, this additional permission does not apply to
+that modified file or to any Larger Work that includes that modified file.
+
+7. No Other Permissions
+-----------------------
+This exception grants no rights beyond those stated above.

package/README.md

@@ -0,0 +1,324 @@
+# VDO.Ninja MCP (`@vdoninja/mcp`)
+
+## TL;DR
+
+This package gives an AI app a small set of tools for talking to another AI app. Two Codex, Claude, Cursor, or other MCP sessions can join the same VDO.Ninja room, send messages, exchange files, and keep shared task state without you building a new messaging server.
+
+If your AI client supports MCP and you want **tools it can call**, use this package. If you want an **always-on agent room with a local inbox**, use [`ninja-p2p`](https://github.com/steveseguin/ninja-p2p) instead.
+
+**Best for:** MCP-native agent handoffs, file delivery, and small shared-state workflows.
+
+**Not for:** a general VPN, permanent storage, or a large public chat network.
+
+Package: [`@vdoninja/mcp`](https://www.npmjs.com/package/@vdoninja/mcp) | [Quickstart](references/quickstart-and-compat.md) | [Client setup examples](references/client-config-examples.md) | [Support](https://discord.vdo.ninja)
+
+## What It Looks Like
+
+One agent joins a room:
+
+```json
+{ "name": "vdo_connect", "arguments": { "room": "family_calendar", "stream_id": "planner" } }
+```
+
+A second agent joins the same room, then sends it a message:
+
+```json
+{ "name": "vdo_connect", "arguments": { "room": "family_calendar", "stream_id": "reviewer", "target_stream_id": "planner" } }
+{ "name": "vdo_send", "arguments": { "session_id": "<reviewer-session>", "data": { "text": "I checked the plan. Tuesday has a conflict." } } }
+```
+
+Those are normal MCP tool calls. This server translates them into VDO.Ninja SDK operations over WebRTC data channels.
+
+## Which VDO.Ninja Package Do I Need?
+
+| Your goal | Use |
+| --- | --- |
+| Add connect/send/file/state tools to an MCP client | **`@vdoninja/mcp`** |
+| Give agents a persistent room and local inbox | [`@vdoninja/ninja-p2p`](https://github.com/steveseguin/ninja-p2p) |
+| Build directly with WebRTC media or data channels | [`@vdoninja/sdk`](https://github.com/steveseguin/ninjasdk) |
+
+This package uses VDO.Ninja's existing room, discovery, and WebRTC behavior. It does not add signaling-server commands. `@vdoninja/sdk` and the Node WebRTC runtime install as package dependencies.
+
+## Why This MCP
+
+- Open source (`AGPL-3.0-only` with additional unmodified-distribution exception) and free to use.
+- Peer-to-peer first: no central relay required for normal data flow.
+- End-to-end encrypted WebRTC data transport (DTLS + SCTP data channels).
+- Reliable data channel mode available for ordered/loss-recovered delivery.
+- Low infrastructure overhead for bot-to-bot messaging and file sync.
+- Works for local LAN, remote internet peers, and hybrid topologies.
+- TURN support improves connectivity when direct P2P is blocked.
+- Good fit for multi-agent coordination without exposing plaintext payloads to a middlebox.
+
+## Common and Interesting Use Cases
+
+- AI swarm coordination: multiple agents in a private room exchanging tasks, state, and results.
+- Bot-to-bot handoff: one agent collects context, another executes, another validates, all over P2P.
+- Private file exchange: send logs, artifacts, prompts, and generated outputs directly between agents.
+- Human + AI war room: operator plus several bots sharing near-real-time status updates.
+- Edge + cloud hybrid: local on-device agent syncs with remote agents without standing up a custom tunnel.
+- Temporary secure collaboration spaces: ad-hoc rooms with join tokens and peer allowlists.
+- Cross-tool interop: Codex and Claude instances sharing updates through the same bridge contract.
+
+## Fun Agent-to-Agent Rooms
+
+These are real patterns teams are starting to use:
+
+- Claude Code to Codex CLI pair mode where one agent asks for a second opinion and gets patch/test feedback.
+- OpenClaw-to-OpenClaw specialist rooms where one local assistant asks another for tool-specific help.
+- Small LLM idea circles (3-5 agents) sharing proposals, critiques, and final votes.
+- Private "night shift" automation where bots sync status/events/files without broad network exposure.
+
+OpenClaw project link:
+
+- https://github.com/openclaw/openclaw
+
+## Quick Example: Claude + Codex Helper Loop
+
+1. Claude-side session:
+```json
+{
+  "name": "vdo_connect",
+  "arguments": {
+    "room": "agent_help_room",
+    "stream_id": "claude_agent"
+  }
+}
+```
+
+2. Codex-side session:
+```json
+{
+  "name": "vdo_connect",
+  "arguments": {
+    "room": "agent_help_room",
+    "stream_id": "codex_agent",
+    "target_stream_id": "claude_agent"
+  }
+}
+```
+
+3. Claude sends task:
+```json
+{
+  "name": "vdo_send",
+  "arguments": {
+    "session_id": "<claude_session>",
+    "data": {
+      "type": "help.request",
+      "task": "review patch for race condition"
+    }
+  }
+}
+```
+
+4. Codex replies:
+```json
+{
+  "name": "vdo_send",
+  "arguments": {
+    "session_id": "<codex_session>",
+    "data": {
+      "type": "help.reply",
+      "summary": "found 2 edge cases",
+      "next_steps": ["add timeout guard", "add retry test"]
+    }
+  }
+}
+```
+
+## High-Value AI Advantages
+
+- Agents share messages/files/state directly, without opening broad machine-to-machine network access.
+- You can limit tool access with profiles (`core|file|state|full`) so each agent only gets what it needs.
+- Rooms can be short-lived: create for a task, then close when done.
+- Easy to start: no private subnet setup, no custom tunnel setup.
+- Works between browser peers and Node peers.
+- Data channels can be reliable and ordered, which is good for control messages.
+- Security options are built in: join tokens, stream allowlists, and session MAC checks.
+
+## Clever Real-World Patterns
+
+- Reviewer team: one writer agent, several reviewer agents, and one decider agent sharing feedback in the same room.
+- State recovery: agents can re-sync shared state with `vdo_state_sync` after reconnects.
+- File pipeline: one agent sends artifacts, another indexes them, another summarizes them.
+- Human override: a person can join the room to inspect progress and step in when needed.
+- Local-first flow: keep sensitive work local and only send required outputs to remote agents.
+- Burst jobs: create short-lived agent groups per task instead of running a permanent private network.
+
+## Compared with VPN Overlays (e.g., Tailscale)
+
+Where this MCP is often better for AI workflows:
+
+- You need agent-to-agent messaging/file/state, not full network access between hosts.
+- You want tool-level permissions instead of giving every machine broad private-network reach.
+- You want browser and Node agents working together quickly.
+- You want temporary collaboration sessions without managing a permanent virtual network.
+
+Where overlays are often better:
+
+- You need always-on private IP connectivity across many services.
+- You need many protocols (databases, SSH, internal web apps) over one virtual network.
+- You need centralized network policy and audit at the infrastructure layer.
+
+Practical framing:
+
+- This MCP is not a full replacement for Tailscale.
+- It is a strong complement for AI-native, data-channel-first collaboration.
+
+## Transport Truth
+
+- This is **WebRTC data transport**, not a generic TCP/SSH tunnel.
+- Data channels can run in reliable/ordered mode (SCTP over DTLS).
+- Default behavior is direct P2P when possible (great for LAN/local-network speed and low latency).
+- Privacy mode is opt-in via `force_turn=true`: this can reduce direct IP exposure between peers, but may reduce connection success in some environments.
+- TURN improves success on restrictive networks, but it is not a guaranteed firewall bypass for every enterprise policy.
+
+## Quickstart (No Clone)
+
+Install from a stable folder. The installer stores an absolute script path in Codex/Claude config.
+
+```bash
+npm i @vdoninja/mcp
+npx vdon-mcp-install
+npx vdon-mcp-server
+```
+
+When started directly in a terminal, `vdon-mcp-server` now prints a short "server running" banner and a first-call hint.
+
+First MCP call (recommended):
+
+```json
+{ "name": "vdo_capabilities", "arguments": {} }
+```
+
+Useful install variants:
+
+- `npx vdon-mcp-install --codex-only`
+- `npx vdon-mcp-install --claude-only`
+- `npx vdon-mcp-install --preset core|file|state|secure-core|secure-full`
+- `npx vdon-mcp-install --uninstall`
+
+## Onboarding Guides
+
+- Operator quickstart: `references/quickstart-and-compat.md`
+- Client setup examples (Cursor, Gemini CLI, OpenCode): `references/client-config-examples.md`
+- First functional workflows (Codex-to-Codex and Claude-to-Claude): `references/client-config-examples.md`
+
+## Typical Workflows
+
+Message demo:
+
+```bash
+npx vdon-mcp-demo-message
+```
+
+Purpose: prove end-to-end room connect + message send/receive over data channels.
+
+File demo:
+
+```bash
+npx vdon-mcp-demo-file
+```
+
+Purpose: prove reliable chunked file transfer and receive path.
+
+Live network mode (instead of local fake mode):
+
+```bash
+MCP_DEMO_FAKE=0 npx vdon-mcp-demo-message
+MCP_DEMO_FAKE=0 npx vdon-mcp-demo-file
+```
+
+Privacy-first relay mode (opt-in):
+
+```bash
+MCP_DEMO_FAKE=0 MCP_DEMO_FORCE_TURN=1 npx vdon-mcp-demo-message
+MCP_DEMO_FAKE=0 MCP_DEMO_FORCE_TURN=1 npx vdon-mcp-demo-file
+```
+
+## Security and Least Privilege
+
+Use secure controls where needed:
+
+- `join_token` and `join_token_secret`
+- `enforce_join_token: true`
+- `allow_peer_stream_ids: [...]`
+- `require_session_mac: true`
+
+Server profile scoping:
+
+```bash
+VDON_MCP_TOOL_PROFILE=core npx vdon-mcp-server
+```
+
+Set `VDON_MCP_JOIN_TOKEN_SECRET` before secure preset installs/runtime.
+
+## Compatibility
+
+- Codex MCP CLI
+- Claude Code MCP CLI
+- Other MCP clients that support stdio command servers
+
+Manual command wiring example:
+
+```json
+{
+  "name": "vdo-ninja-mcp",
+  "command": "node",
+  "args": ["node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"]
+}
+```
+
+## Local Development (This Repo)
+
+Start server:
+
+```bash
+node scripts/vdo-mcp-server.js
+```
+
+Install registration from local checkout:
+
+```bash
+node scripts/install-mcp.js
+```
+
+## Testing
+
+Fast product-focused suite:
+
+```bash
+node tests/run-mcp-tests-minimal.js
+```
+
+Full suite:
+
+```bash
+node tests/run-mcp-tests.js
+```
+
+Live diagnostics:
+
+```bash
+node tests/live-turn-smoke.js
+node tests/live-turn-soak.js
+node tests/live-turn-matrix.js
+node tests/live-turn-preset-matrix.js
+```
+
+## Key Files
+
+- `scripts/vdo-mcp-server.js` (stdio MCP server)
+- `scripts/vdo-mcp-streamable-http.js` (streamable HTTP bridge)
+- `scripts/install-mcp.js` (Codex/Claude installer automation)
+- `references/quickstart-and-compat.md` (operator quickstart)
+- `references/mcp-tool-contract.md` (tool semantics and contracts)
+- `server.json` (MCP discovery manifest metadata)
+
+## License
+
+AGPL-3.0-only with additional unmodified-distribution exception.
+
+- Main license text: `LICENSE`
+- Additional permission: `LICENSE-SDK-EXCEPTION`

package/SKILL.md

@@ -27,13 +27,14 @@ Use this skill to run VDO.Ninja as an MCP data bridge in Codex, Claude Code, and
 ## Fast Path
 
 1. Install MCP registration:
-`npm i @vdoninja/mcp @roamhq/wrtc`
+`npm i @vdoninja/mcp`
 
 2. Register for Codex/Claude:
 `npx vdon-mcp-install`
 
 3. Start server:
 `npx vdon-mcp-server`
+If run directly in a terminal, it prints a short running banner and a first-call hint.
 
 4. Optional least-privilege tool profile:
 `VDON_MCP_TOOL_PROFILE=core|file|state|full npx vdon-mcp-server`
@@ -80,11 +81,12 @@ For secure presets, set `VDON_MCP_JOIN_TOKEN_SECRET` before install/runtime.
 
 - Product test bar: `npm run test:mcp`
 - Full engineering suite: `npm run test:mcp:all`
-- Live diagnostics (optional): `MCP/references/advanced-diagnostics.md`
+- Live diagnostics (optional): `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`
+- Operator quickstart: `references/quickstart-and-compat.md`
+- Client config examples: `references/client-config-examples.md`
+- Tool contract: `references/mcp-tool-contract.md`
+- Transport notes: `references/vdo-ninja-p2p-data-notes.md`
+- Registry manifest: `server.json`

package/package.json

@@ -1,16 +1,15 @@
 {
   "name": "@vdoninja/mcp",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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",
+  "homepage": "https://github.com/steveseguin/ninjamcp",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/steveseguin/ninjasdk.git",
-    "directory": "MCP"
+    "url": "git+https://github.com/steveseguin/ninjamcp.git"
   },
   "bugs": {
-    "url": "https://github.com/steveseguin/ninjasdk/issues"
+    "url": "https://github.com/steveseguin/ninjamcp/issues"
   },
   "keywords": [
     "mcp",
@@ -29,18 +28,32 @@
     "vdon-mcp-demo-file": "scripts/demo-file-workflow.js"
   },
   "scripts": {
+    "test": "node tests/run-mcp-tests-minimal.js",
+    "test:all": "node tests/run-mcp-tests.js",
+    "check": "npm run test:all",
+    "test:mcp": "node tests/run-mcp-tests-minimal.js",
+    "test:mcp:all": "node tests/run-mcp-tests.js",
+    "test:mcp:live": "node tests/live-turn-smoke.js",
+    "test:mcp:soak": "node tests/live-turn-soak.js",
+    "test:mcp:matrix": "node tests/live-turn-matrix.js",
+    "test:mcp:preset:matrix": "node tests/live-turn-preset-matrix.js",
+    "test:mcp:matrix:sweep": "node tests/live-turn-matrix-sweep.js",
     "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"
+    "demo:file": "node scripts/demo-file-workflow.js",
+    "prepublishOnly": "npm run test:all"
   },
   "files": [
+    "LICENSE",
+    "LICENSE-SDK-EXCEPTION",
     "SKILL.md",
     "server.json",
     "assets/cloudflare/worker-proxy.js",
     "assets/cloudflare/wrangler.toml.example",
     "references/advanced-diagnostics.md",
+    "references/client-config-examples.md",
     "references/mcp-tool-contract.md",
     "references/quickstart-and-compat.md",
     "references/vdo-ninja-p2p-data-notes.md",
@@ -61,6 +74,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@vdoninja/sdk": "^1.3.18"
+    "@roamhq/wrtc": "^0.9.1",
+    "@vdoninja/sdk": "^1.4.0"
   }
 }

package/references/advanced-diagnostics.md

@@ -27,10 +27,10 @@ LIVE_VDO_TEST=1 VDON_MCP_JOIN_TOKEN_SECRET=change_me npm run test:mcp:preset:mat
 
 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`
+- `tests/artifacts/latest-preset-matrix-report.json`
+- `tests/artifacts/latest-preset-matrix-summary.txt`
+- `tests/artifacts/history/preset-matrix-*.json`
+- `tests/artifacts/history/preset-matrix-*.txt`
 
 ## Soak / Matrix Knobs