@vdoninja/mcp 0.4.0 → 0.4.1

package/references/client-config-examples.md

@@ -0,0 +1,251 @@
+# VDO.Ninja MCP Client Config Examples
+
+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/mcp-tool-contract.md

@@ -2,9 +2,9 @@
 
 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 +23,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>`
@@ -140,7 +140,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

@@ -13,7 +13,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 +28,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 +41,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 +189,19 @@ 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.
+- License model matches SDK packaging: AGPL-3.0-only with an additional unmodified-distribution exception (`LICENSE-SDK-EXCEPTION`).
 
 ## Optional Advanced Diagnostics
 
 For soak/matrix/preset-matrix/sweep tuning and all reliability knobs, use:
 
-- `MCP/references/advanced-diagnostics.md`
+- `references/advanced-diagnostics.md`

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

@@ -71,7 +71,7 @@ This file captures operational constraints from this repository's SDK docs.
 
 ## Bridge Runtime Knobs
 
-`MCP/scripts/vdo-data-bridge.js` supports:
+`scripts/vdo-data-bridge.js` supports:
 
 - `VDON_ROOM` (required in real deployments)
 - `VDON_STREAM_ID` (optional; random if omitted)

package/scripts/demo-file-workflow.js

@@ -90,10 +90,22 @@ async function main() {
         serverA.callTool('vdo_status', { session_id: sessionA }),
         serverB.callTool('vdo_status', { session_id: sessionB })
       ]);
-      return statusA.connected && statusB.connected;
+      return (
+        statusA.connected &&
+        statusB.connected &&
+        statusA.peer_count > 0 &&
+        statusB.peer_count > 0
+      );
     }, connectTimeoutMs, 200);
     if (!connected) {
-      throw new Error('demo-file connect timeout');
+      const [statusA, statusB] = await Promise.all([
+        serverA.callTool('vdo_status', { session_id: sessionA }),
+        serverB.callTool('vdo_status', { session_id: sessionB })
+      ]);
+      throw new Error(
+        `demo-file connect timeout (peer_count a=${statusA.peer_count} b=${statusB.peer_count} ` +
+        `connected a=${statusA.connected} b=${statusB.connected})`
+      );
     }
 
     const payload = Buffer.from(fileText, 'utf8').toString('base64');
@@ -162,7 +174,11 @@ async function main() {
   }
 }
 
-main().catch((error) => {
-  console.error(error.message);
-  process.exit(1);
-});
+main()
+  .then(() => {
+    process.exit(0);
+  })
+  .catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+  });

package/scripts/demo-message-workflow.js

@@ -94,10 +94,22 @@ async function main() {
         serverA.callTool('vdo_status', { session_id: sessionA }),
         serverB.callTool('vdo_status', { session_id: sessionB })
       ]);
-      return statusA.connected && statusB.connected;
+      return (
+        statusA.connected &&
+        statusB.connected &&
+        statusA.peer_count > 0 &&
+        statusB.peer_count > 0
+      );
     }, connectTimeoutMs, 200);
     if (!connected) {
-      throw new Error('demo-message connect timeout');
+      const [statusA, statusB] = await Promise.all([
+        serverA.callTool('vdo_status', { session_id: sessionA }),
+        serverB.callTool('vdo_status', { session_id: sessionB })
+      ]);
+      throw new Error(
+        `demo-message connect timeout (peer_count a=${statusA.peer_count} b=${statusB.peer_count} ` +
+        `connected a=${statusA.connected} b=${statusB.connected})`
+      );
     }
 
     const id = `demo_msg_${Date.now()}`;
@@ -161,7 +173,11 @@ async function main() {
   }
 }
 
-main().catch((error) => {
-  console.error(error.message);
-  process.exit(1);
-});
+main()
+  .then(() => {
+    process.exit(0);
+  })
+  .catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+  });

package/scripts/install-mcp.js

@@ -69,6 +69,7 @@ function parseArgs(argv) {
     serverArgs: [],
     codex: true,
     claude: true,
+    targetSelectionExplicit: false,
     claudeScope: 'local',
     dryRun: false
   };
@@ -106,11 +107,13 @@ function parseArgs(argv) {
     if (arg === '--codex-only') {
       out.claude = false;
       out.codex = true;
+      out.targetSelectionExplicit = true;
       continue;
     }
     if (arg === '--claude-only') {
       out.codex = false;
       out.claude = true;
+      out.targetSelectionExplicit = true;
       continue;
     }
     if (arg === '--claude-scope') {
@@ -181,6 +184,16 @@ function assertBinaryExists(name, options) {
   }
 }
 
+function binaryExists(name, options) {
+  const check = runCommand(name, ['--version'], {
+    dryRun: options.dryRun,
+    quiet: true,
+    env: options.env,
+    cwd: options.cwd
+  });
+  return check.ok;
+}
+
 function codexServerExists(name, options) {
   if (options.dryRun) return false;
   const result = runCommand('codex', ['mcp', 'get', name, '--json'], {
@@ -278,8 +291,33 @@ function main() {
     process.stdout.write('Warning: secure preset selected but VDON_MCP_JOIN_TOKEN_SECRET is not set in this shell.\n');
   }
 
-  if (config.codex) assertBinaryExists('codex', options);
-  if (config.claude) assertBinaryExists('claude', options);
+  if (config.codex && !binaryExists('codex', options)) {
+    if (config.targetSelectionExplicit && !config.claude) {
+      assertBinaryExists('codex', options);
+    }
+    process.stdout.write('Warning: Codex CLI not found in PATH. Skipping Codex install target.\n');
+    process.stdout.write('Tip: install Codex CLI, or rerun with --claude-only.\n');
+    config.codex = false;
+  }
+  if (config.claude && !binaryExists('claude', options)) {
+    if (config.targetSelectionExplicit && !config.codex) {
+      assertBinaryExists('claude', options);
+    }
+    process.stdout.write('Warning: Claude Code CLI not found in PATH. Skipping Claude install target.\n');
+    process.stdout.write('Tip: install Claude Code CLI, or rerun with --codex-only.\n');
+    config.claude = false;
+  }
+
+  if (!config.codex && !config.claude) {
+    if (config.action === 'uninstall') {
+      process.stdout.write('No supported CLI targets found in PATH; nothing to uninstall.\n\nDone.\n');
+      return;
+    }
+    throw new Error(
+      'No supported CLI targets found in PATH. Install Codex CLI or Claude Code CLI, ' +
+      'or configure GUI clients manually (e.g. Cursor via mcp.json).'
+    );
+  }
 
   if (config.action === 'install') {
     if (config.codex) installCodex(config, options);
@@ -290,6 +328,16 @@ function main() {
   }
 
   process.stdout.write('\nDone.\n');
+  if (config.action === 'install') {
+    process.stdout.write('\nUsage quickstart:\n');
+    process.stdout.write('  1) Start server: npx vdon-mcp-server\n');
+    process.stdout.write('  2) In your MCP client, call: {"name":"vdo_capabilities","arguments":{}}\n');
+    process.stdout.write('  3) Generic stdio MCP config:\n');
+    process.stdout.write(`     command: ${config.nodeCmd}\n`);
+    process.stdout.write(`     args: [${JSON.stringify(config.serverScript)}${config.serverArgs.map((arg) => `, ${JSON.stringify(arg)}`).join('')}]\n`);
+    process.stdout.write('  4) Client-specific examples (Cursor/Gemini/OpenCode):\n');
+    process.stdout.write('     https://github.com/steveseguin/ninjamcp/blob/main/references/client-config-examples.md\n');
+  }
 }
 
 if (require.main === module) {

package/scripts/vdo-mcp-server.js

@@ -24,7 +24,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.1'
 };
 const DEFAULT_MAX_MESSAGE_BYTES = 1024 * 1024;
 
@@ -500,6 +500,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];
@@ -1328,6 +1360,8 @@ async function runMcpStdioLoop(options = {}) {
     onExit
   });
 
+  maybeWriteStartupBanner(options, server);
+
   const parser = new McpStdioParser({ maxMessageBytes });
   let chain = Promise.resolve();
   let closed = false;
@@ -1421,5 +1455,7 @@ module.exports = {
   buildTools,
   makeToolResult,
   classifyToolError,
-  parseCliArgs
+  parseCliArgs,
+  buildStartupBanner,
+  maybeWriteStartupBanner
 };

package/server.json

@@ -3,19 +3,17 @@
   "name": "io.github.steveseguin/vdo-ninja-mcp",
   "title": "VDO.Ninja MCP Bridge",
   "description": "WebRTC data-channel MCP bridge for VDO.Ninja with reliable messages, files, and room sync.",
-  "version": "0.4.0",
-  "websiteUrl": "https://github.com/steveseguin/ninjasdk/tree/main/MCP",
+  "version": "0.4.1",
+  "websiteUrl": "https://github.com/steveseguin/ninjamcp",
   "repository": {
-    "url": "https://github.com/steveseguin/ninjasdk",
-    "source": "github",
-    "id": "1006762093",
-    "subfolder": "MCP"
+    "url": "https://github.com/steveseguin/ninjamcp",
+    "source": "github"
   },
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@vdoninja/mcp",
-      "version": "0.4.0",
+      "version": "0.4.1",
       "runtimeHint": "node",
       "runtimeArguments": [
         {
@@ -81,7 +79,7 @@
       "url": "http://127.0.0.1:{http_port}/mcp",
       "variables": {
         "http_port": {
-          "description": "Port used by MCP/scripts/vdo-mcp-streamable-http.js.",
+          "description": "Port used by scripts/vdo-mcp-streamable-http.js.",
           "format": "number",
           "default": "8787",
           "isRequired": false