@vdoninja/mcp 0.4.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +111 -0
  3. package/SKILL.md +8 -6
  4. package/assets/browser-agent/audio-worklet.js +17 -0
  5. package/assets/browser-agent/client.js +124 -0
  6. package/assets/browser-agent/index.html +50 -0
  7. package/assets/cloudflare/worker-proxy.js +3 -0
  8. package/docs/.nojekyll +0 -0
  9. package/docs/404.html +28 -0
  10. package/docs/advanced-diagnostics.html +101 -0
  11. package/docs/assets/apple-touch-icon.png +0 -0
  12. package/docs/assets/favicon.svg +7 -0
  13. package/docs/assets/how-it-works.svg +62 -0
  14. package/docs/assets/icon-192.png +0 -0
  15. package/docs/assets/icon-512.png +0 -0
  16. package/docs/assets/icon-maskable-512.png +0 -0
  17. package/docs/assets/icons.svg +42 -0
  18. package/docs/assets/logo.svg +7 -0
  19. package/docs/assets/og-image.png +0 -0
  20. package/docs/assets/site.css +735 -0
  21. package/docs/assets/site.js +289 -0
  22. package/docs/browser-agent.html +122 -0
  23. package/docs/browser-worker.html +165 -0
  24. package/docs/client-config-examples.html +254 -0
  25. package/docs/direction.html +175 -0
  26. package/docs/favicon.ico +0 -0
  27. package/docs/guide.html +872 -0
  28. package/docs/http-relay.html +154 -0
  29. package/docs/index.html +834 -0
  30. package/docs/mcp-tool-contract.html +226 -0
  31. package/docs/quickstart-and-compat.html +222 -0
  32. package/docs/site.webmanifest +16 -0
  33. package/docs/sitemap.xml +63 -0
  34. package/docs/ssapp-integration.html +594 -0
  35. package/docs/vdo-ninja-p2p-data-notes.html +225 -0
  36. package/package.json +67 -11
  37. package/references/advanced-diagnostics.md +6 -4
  38. package/references/browser-agent.md +53 -0
  39. package/references/browser-worker.md +142 -0
  40. package/references/client-config-examples.md +253 -0
  41. package/references/direction.md +88 -0
  42. package/references/http-relay.md +107 -0
  43. package/references/mcp-tool-contract.md +16 -6
  44. package/references/quickstart-and-compat.md +18 -6
  45. package/references/ssapp-integration.md +371 -0
  46. package/references/vdo-ninja-p2p-data-notes.md +3 -1
  47. package/scripts/demo-file-workflow.js +25 -6
  48. package/scripts/demo-message-workflow.js +25 -6
  49. package/scripts/install-mcp.js +55 -4
  50. package/scripts/lib/bridge-session.js +143 -26
  51. package/scripts/lib/bridge-utils.js +3 -0
  52. package/scripts/lib/browser-agent.js +255 -0
  53. package/scripts/lib/browser-media.js +79 -0
  54. package/scripts/lib/browser-routes.js +119 -0
  55. package/scripts/lib/browser-rpc.js +214 -0
  56. package/scripts/lib/browser-setup.js +133 -0
  57. package/scripts/lib/browser-worker.js +216 -0
  58. package/scripts/lib/fake-network-sdk.js +3 -0
  59. package/scripts/lib/http-relay-transport.js +294 -0
  60. package/scripts/lib/load-vdo-sdk.js +3 -0
  61. package/scripts/lib/mcp-stdio-parser.js +3 -0
  62. package/scripts/lib/ssapp-worker.js +198 -0
  63. package/scripts/lib/tool-profiles.js +3 -0
  64. package/scripts/vdo-data-bridge.js +3 -0
  65. package/scripts/vdo-mcp-browser-agent.js +132 -0
  66. package/scripts/vdo-mcp-browser.js +218 -0
  67. package/scripts/vdo-mcp-relay.js +207 -0
  68. package/scripts/vdo-mcp-server.js +87 -8
  69. package/scripts/vdo-mcp-ssapp.js +208 -0
  70. package/scripts/vdo-mcp-streamable-http.js +23 -4
  71. package/server.json +26 -10
@@ -0,0 +1,226 @@
1
+ <!doctype html>
2
+ <html lang="en" data-icons="assets/icons.svg">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <title>Tool contract · VDO.Ninja MCP</title>
7
+ <meta name="description" content="Tool arguments, transport behavior, permissions, and limits.">
8
+ <meta name="color-scheme" content="light dark">
9
+ <link rel="canonical" href="https://steveseguin.github.io/ninjamcp/mcp-tool-contract.html">
10
+ <link rel="icon" href="assets/favicon.svg" type="image/svg+xml">
11
+ <link rel="stylesheet" href="assets/site.css">
12
+ <script>document.documentElement.classList.add('js');</script>
13
+ </head>
14
+ <body class="reference-page">
15
+ <a class="skip-link" href="#main">Skip to content</a>
16
+ <header class="nav">
17
+ <div class="wrap">
18
+ <a aria-label="VDO.Ninja MCP home" class="brand" href="./">
19
+ <img alt="" height="28" src="assets/logo.svg" width="28"/>
20
+ <span>VDO.Ninja <small>MCP</small></span>
21
+ </a>
22
+ <nav aria-label="Primary" class="nav-links">
23
+ <a href="./#how">How it works</a>
24
+ <a href="./#privacy">Privacy</a>
25
+ <a href="./#tools">Tools</a>
26
+ <a href="./#faq">FAQ</a>
27
+ <a aria-current="page" href="guide.html">Docs</a>
28
+ </nav>
29
+ <div class="nav-cta">
30
+ <a class="btn btn-ghost" href="https://github.com/steveseguin/ninjamcp"><svg aria-hidden="true" class="icon-sm"><use href="assets/icons.svg#i-github"></use></svg>GitHub</a>
31
+ <a class="btn btn-dark" href="https://www.npmjs.com/package/@vdoninja/mcp"><svg aria-hidden="true" class="icon-sm"><use href="assets/icons.svg#i-package"></use></svg>npm</a>
32
+ </div>
33
+ <button aria-expanded="false" aria-label="Menu" class="nav-toggle" type="button"><svg aria-hidden="true" class="icon"><use href="assets/icons.svg#i-menu"></use></svg></button>
34
+ </div>
35
+ </header>
36
+ <div class="docs">
37
+ <aside class="sidebar" aria-label="Documentation" id="guide-contents"><h5>Documentation</h5><a href="guide.html">Getting started</a><h5>On this page</h5><a href="#overview">Overview</a><a href="#transport">Transport</a><a href="#runtime-limit">Runtime Limit</a><a href="#server-cli-flags">Server CLI Flags</a><a href="#capability-profiles">Capability Profiles</a><a href="#core-session-tools">Core Session Tools</a><a href="#sync-tools">Sync Tools</a><a href="#file-transfer-tools">File Transfer Tools</a><a href="#state-sync-tools-crdt-lite">State Sync Tools (CRDT-lite)</a><a href="#protocol-envelope-family">Protocol Envelope Family</a><a href="#event-types-via-vdo_receive">Event Types via vdo_receive</a><a href="#error-shape">Error Shape</a><a href="#client-wiring">Client Wiring</a><h5>More guides</h5><a href="quickstart-and-compat.html">Quickstart</a><a href="client-config-examples.html">Client configuration</a><a href="http-relay.html">HTTP relay</a><a href="browser-worker.html">Remote Chrome</a><a href="browser-agent.html">Voice companion</a><a href="ssapp-integration.html">Remote SSApp</a><a href="advanced-diagnostics.html">Advanced diagnostics</a><a href="vdo-ninja-p2p-data-notes.html">WebRTC data notes</a><a href="direction.html">Project direction</a></aside>
38
+ <main class="docs-main" id="main">
39
+ <button class="btn docs-toggle" type="button" aria-controls="guide-contents" aria-expanded="false">Contents</button>
40
+ <header>
41
+ <p class="guide-breadcrumb"><a href="guide.html">Documentation</a> / Tool contract</p>
42
+ <h1 id="vdoninja-mcp-tool-contract">VDO.Ninja MCP Tool Contract</h1>
43
+ <p class="guide-format"><a href="https://github.com/steveseguin/ninjamcp/blob/main/references/mcp-tool-contract.md">Read in Markdown</a></p>
44
+ </header>
45
+ <section class="doc-section guide-intro" id="overview">
46
+ <p>Implemented by:</p>
47
+ <ul>
48
+ <li><code>scripts/vdo-mcp-server.js</code></li>
49
+ <li>Installer automation: <code>scripts/install-mcp.js</code></li>
50
+ <li>Discovery manifest: <code>server.json</code></li>
51
+ </ul>
52
+ </section><section class="doc-section" id="transport"><h2>Transport</h2>
53
+ <ul>
54
+ <li>JSON-RPC 2.0 over stdio</li>
55
+ <li>Input:</li>
56
+ <li>newline-delimited JSON messages</li>
57
+ <li><code>Content-Length</code> framed messages</li>
58
+ <li>Output:</li>
59
+ <li>framed when framed input is detected</li>
60
+ <li>newline JSON otherwise</li>
61
+ </ul>
62
+ </section><section class="doc-section" id="runtime-limit"><h2>Runtime Limit</h2>
63
+ <ul>
64
+ <li><code>VDON_MCP_MAX_MESSAGE_BYTES</code> (default <code>1048576</code>)</li>
65
+ <li><code>VDON_MCP_TOOL_PROFILE</code> (default <code>full</code>, values: <code>core|file|state|full</code>)</li>
66
+ </ul>
67
+ </section><section class="doc-section" id="server-cli-flags"><h2>Server CLI Flags</h2>
68
+ <p>Supported by <code>scripts/vdo-mcp-server.js</code>:</p>
69
+ <ul>
70
+ <li><code>--tool-profile &lt;core|file|state|full&gt;</code></li>
71
+ <li><code>--max-message-bytes &lt;bytes&gt;</code></li>
72
+ <li><code>--join-token-secret &lt;secret&gt;</code></li>
73
+ <li><code>--enforce-join-token &lt;true|false&gt;</code></li>
74
+ <li><code>--allow-peer-stream-ids &lt;a,b,c&gt;</code></li>
75
+ <li><code>--require-session-mac &lt;true|false&gt;</code></li>
76
+ </ul>
77
+ </section><section class="doc-section" id="capability-profiles"><h2>Capability Profiles</h2>
78
+ <ul>
79
+ <li><code>core</code>: <code>vdo_connect</code>, <code>vdo_send</code>, <code>vdo_receive</code>, <code>vdo_status</code>, <code>vdo_disconnect</code>, <code>vdo_list_sessions</code>, <code>vdo_capabilities</code>, <code>vdo_sync_peers</code>, <code>vdo_sync_announce</code></li>
80
+ <li><code>file</code>: <code>core</code> + all file transfer tools</li>
81
+ <li><code>state</code>: <code>core</code> + all state sync tools</li>
82
+ <li><code>full</code>: <code>core</code> + file + state tools</li>
83
+ </ul>
84
+ <p>Enforcement:</p>
85
+ <ul>
86
+ <li><code>tools/list</code> only advertises tools in the active profile.</li>
87
+ <li>Calling a disabled tool returns <code>validation_error</code>.</li>
88
+ </ul>
89
+ </section><section class="doc-section" id="core-session-tools"><h2>Core Session Tools</h2>
90
+ <ul>
91
+ <li><code>vdo_connect</code></li>
92
+ <li><code>vdo_send</code></li>
93
+ <li><code>vdo_receive</code></li>
94
+ <li><code>vdo_status</code></li>
95
+ <li><code>vdo_disconnect</code></li>
96
+ <li><code>vdo_list_sessions</code></li>
97
+ <li><code>vdo_capabilities</code></li>
98
+ </ul>
99
+ <h3 id="vdo_connect-notable-options"><code>vdo_connect</code> notable options</h3>
100
+ <ul>
101
+ <li>transport: <code>room</code>, <code>stream_id</code>, <code>target_stream_id</code>, <code>transport</code> (<code>webrtc</code> by default or <code>http</code>)</li>
102
+ <li>WebRTC: <code>host</code>, <code>password</code>, <code>force_turn</code></li>
103
+ <li>HTTP relay: <code>relay_url</code>, <code>relay_token</code>, <code>relay_key</code>, with defaults from <code>VDON_MCP_RELAY_URL</code>, <code>VDON_MCP_RELAY_TOKEN</code>, <code>VDON_MCP_RELAY_KEY</code>; see <a href="http-relay.html">relay setup and delivery semantics</a></li>
104
+ <li>resiliency: <code>heartbeat_ms</code>, <code>reconnect_ms</code>, <code>max_reconnect_ms</code></li>
105
+ <li>security: <code>join_token</code>, <code>join_token_secret</code>, <code>join_token_ttl_ms</code>, <code>enforce_join_token</code>, <code>allow_peer_stream_ids</code>, <code>require_session_mac</code></li>
106
+ <li>file defaults: <code>file_chunk_bytes</code>, <code>file_max_bytes</code>, <code>file_ack_timeout_ms</code>, <code>file_max_retries</code></li>
107
+ <li>file spooling: <code>file_spool_dir</code>, <code>file_spool_threshold_bytes</code>, <code>keep_spool_files</code></li>
108
+ <li>state limits: <code>state_max_keys</code>, <code>state_max_snapshot_entries</code></li>
109
+ </ul>
110
+ <p><code>vdo_status</code> identifies the selected <code>transport</code>. 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.</p>
111
+ <p>In HTTP mode, <code>vdo_send</code> returns <code>message_id</code> and <code>delivery_stage</code> (<code>queued</code> or <code>rejected</code>). A later <code>relay_receipt</code> event reports <code>relay_accepted</code> or <code>delivery_unknown</code>. Acceptance does not confirm peer consumption. <code>data_received</code> includes the matching <code>message_id</code>. <code>relay_history_lost</code> means a replay gap requires application reconciliation. Ordinary message queues and relay history are in memory; file completion still requires the existing peer acknowledgement.</p>
112
+ </section><section class="doc-section" id="sync-tools"><h2>Sync Tools</h2>
113
+ <ul>
114
+ <li><code>vdo_sync_peers</code>: peer handshake/auth/state capabilities</li>
115
+ <li><code>vdo_sync_announce</code>: force immediate sync hello</li>
116
+ </ul>
117
+ </section><section class="doc-section" id="file-transfer-tools"><h2>File Transfer Tools</h2>
118
+ <ul>
119
+ <li><code>vdo_file_send</code>: send from <code>data_base64</code></li>
120
+ <li><code>vdo_file_send_path</code>: send directly from local <code>file_path</code></li>
121
+ <li><code>vdo_file_resume</code>: resume outgoing transfer by <code>transfer_id</code></li>
122
+ <li><code>vdo_file_transfers</code>: inspect incoming/outgoing transfer state</li>
123
+ <li><code>vdo_file_receive</code>: read completed incoming payload (<code>base64</code>/<code>utf8</code>/<code>json</code>)</li>
124
+ <li><code>vdo_file_save</code>: save completed incoming transfer directly to disk</li>
125
+ </ul>
126
+ <p>A retained incoming <code>transfer_id</code> 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.</p>
127
+ </section><section class="doc-section" id="state-sync-tools-crdt-lite"><h2>State Sync Tools (CRDT-lite)</h2>
128
+ <ul>
129
+ <li><code>vdo_state_set</code>: update key/value with local monotonic clock</li>
130
+ <li><code>vdo_state_get</code>: read key or full state snapshot</li>
131
+ <li><code>vdo_state_sync</code>: request/send full snapshot (<code>mode: request|send</code>)</li>
132
+ </ul>
133
+ <p>Merge rule is tuple-based last-writer:</p>
134
+ <ol>
135
+ <li>higher <code>clock</code> wins</li>
136
+ <li>if equal clock, lexicographically higher <code>actor</code> wins</li>
137
+ </ol>
138
+ </section><section class="doc-section" id="protocol-envelope-family"><h2>Protocol Envelope Family</h2>
139
+ <p>Internal control/file/state envelopes use:</p>
140
+ <pre><code class="lang-json">{
141
+ "__vdo_mcp": "vdo_mcp_bridge_v1",
142
+ "kind": "sync.* | file.* | state.*",
143
+ "payload": {}
144
+ }
145
+ </code></pre>
146
+ </section><section class="doc-section" id="event-types-via-vdo_receive"><h2>Event Types via <code>vdo_receive</code></h2>
147
+ <p>Lifecycle:</p>
148
+ <ul>
149
+ <li><code>ready</code>, <code>connected</code>, <code>disconnected</code>, <code>connection_failed</code>, <code>sdk_error</code>, <code>reconnect_scheduled</code></li>
150
+ <li><code>peer_connected</code>, <code>peer_disconnected</code>, <code>data_channel_open</code>, <code>data_channel_close</code></li>
151
+ <li><code>data_received</code>, <code>send_error</code>, <code>send_rejected</code>, <code>heartbeat_sent</code></li>
152
+ </ul>
153
+ <p>Sync/security:</p>
154
+ <ul>
155
+ <li><code>sync_hello_sent</code>, <code>sync_peer_updated</code>, <code>sync_peer_rejected</code>, <code>protocol_auth_failed</code></li>
156
+ </ul>
157
+ <p>File:</p>
158
+ <ul>
159
+ <li><code>file_offer_received</code>, <code>file_chunk_received</code>, <code>file_chunk_rejected</code>, <code>file_received</code>, <code>file_transfer_complete</code>, <code>file_transfer_cancelled</code></li>
160
+ </ul>
161
+ <p>State:</p>
162
+ <ul>
163
+ <li><code>state_updated</code>, <code>state_snapshot_merged</code>, <code>state_protocol_unhandled</code></li>
164
+ </ul>
165
+ </section><section class="doc-section" id="error-shape"><h2>Error Shape</h2>
166
+ <p>Tools return <code>isError: true</code> with:</p>
167
+ <pre><code class="lang-json">{
168
+ "ok": false,
169
+ "error": {
170
+ "type": "validation_error | tool_error",
171
+ "message": "...",
172
+ "tool": "..."
173
+ }
174
+ }
175
+ </code></pre>
176
+ </section><section class="doc-section" id="client-wiring"><h2>Client Wiring</h2>
177
+ <p>Automated registration:</p>
178
+ <pre><code class="lang-sh">npm i @vdoninja/mcp
179
+ npx vdon-mcp-install
180
+ </code></pre>
181
+ <p>Preset registrations:</p>
182
+ <pre><code class="lang-sh">npx vdon-mcp-install --preset core
183
+ npx vdon-mcp-install --preset file
184
+ npx vdon-mcp-install --preset state
185
+ npx vdon-mcp-install --preset secure-core
186
+ npx vdon-mcp-install --preset secure-full
187
+ </code></pre>
188
+ <p>Removal:</p>
189
+ <pre><code class="lang-sh">npx vdon-mcp-install --uninstall
190
+ </code></pre>
191
+ <p>Codex-style:</p>
192
+ <pre><code class="lang-json">{
193
+ "name": "vdo-ninja-mcp",
194
+ "command": "node",
195
+ "args": ["node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"]
196
+ }
197
+ </code></pre>
198
+ <p>Claude Code-style:</p>
199
+ <pre><code class="lang-json">{
200
+ "mcpServers": {
201
+ "vdo-ninja-mcp": {
202
+ "command": "node",
203
+ "args": ["node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"]
204
+ }
205
+ }
206
+ }
207
+ </code></pre></section>
208
+ <nav class="pager" aria-label="More documentation"><a href="guide.html#guides"><small>Keep reading</small><b>Browse all guides</b></a><a href="https://discord.vdo.ninja"><small>Need help?</small><b>Ask on Discord</b></a></nav>
209
+ </main>
210
+ </div>
211
+ <footer class="footer">
212
+ <div class="wrap">
213
+ <a class="brand" href="./"><img alt="" height="24" src="assets/logo.svg" width="24"/><span>VDO.Ninja <small>MCP</small></span></a>
214
+ <nav aria-label="Footer">
215
+ <a href="./">Home</a>
216
+ <a href="https://github.com/steveseguin/ninjamcp">GitHub</a>
217
+ <a href="https://www.npmjs.com/package/@vdoninja/mcp">npm</a>
218
+ <a href="https://discord.vdo.ninja">Discord</a>
219
+ <a href="https://vdo.ninja">VDO.Ninja</a>
220
+ </nav>
221
+ <span>MIT · © 2026 Steve Seguin</span>
222
+ </div>
223
+ </footer>
224
+ <script src="assets/site.js" defer></script>
225
+ </body>
226
+ </html>
@@ -0,0 +1,222 @@
1
+ <!doctype html>
2
+ <html lang="en" data-icons="assets/icons.svg">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <title>Quickstart · VDO.Ninja MCP</title>
7
+ <meta name="description" content="Connect two MCP clients and exchange your first message.">
8
+ <meta name="color-scheme" content="light dark">
9
+ <link rel="canonical" href="https://steveseguin.github.io/ninjamcp/quickstart-and-compat.html">
10
+ <link rel="icon" href="assets/favicon.svg" type="image/svg+xml">
11
+ <link rel="stylesheet" href="assets/site.css">
12
+ <script>document.documentElement.classList.add('js');</script>
13
+ </head>
14
+ <body class="reference-page">
15
+ <a class="skip-link" href="#main">Skip to content</a>
16
+ <header class="nav">
17
+ <div class="wrap">
18
+ <a aria-label="VDO.Ninja MCP home" class="brand" href="./">
19
+ <img alt="" height="28" src="assets/logo.svg" width="28"/>
20
+ <span>VDO.Ninja <small>MCP</small></span>
21
+ </a>
22
+ <nav aria-label="Primary" class="nav-links">
23
+ <a href="./#how">How it works</a>
24
+ <a href="./#privacy">Privacy</a>
25
+ <a href="./#tools">Tools</a>
26
+ <a href="./#faq">FAQ</a>
27
+ <a aria-current="page" href="guide.html">Docs</a>
28
+ </nav>
29
+ <div class="nav-cta">
30
+ <a class="btn btn-ghost" href="https://github.com/steveseguin/ninjamcp"><svg aria-hidden="true" class="icon-sm"><use href="assets/icons.svg#i-github"></use></svg>GitHub</a>
31
+ <a class="btn btn-dark" href="https://www.npmjs.com/package/@vdoninja/mcp"><svg aria-hidden="true" class="icon-sm"><use href="assets/icons.svg#i-package"></use></svg>npm</a>
32
+ </div>
33
+ <button aria-expanded="false" aria-label="Menu" class="nav-toggle" type="button"><svg aria-hidden="true" class="icon"><use href="assets/icons.svg#i-menu"></use></svg></button>
34
+ </div>
35
+ </header>
36
+ <div class="docs">
37
+ <aside class="sidebar" aria-label="Documentation" id="guide-contents"><h5>Documentation</h5><a href="guide.html">Getting started</a><h5>On this page</h5><a href="#overview">Overview</a><a href="#transport-truth">Transport Truth</a><a href="#60-second-setup">60-Second Setup</a><a href="#workflow-a-bot-to-bot-message">Workflow A: Bot-to-Bot Message</a><a href="#workflow-b-file-sendreceive">Workflow B: File Send/Receive</a><a href="#security-baseline">Security Baseline</a><a href="#minimal-test-bar">Minimal Test Bar</a><a href="#compatibility-notes">Compatibility Notes</a><a href="#optional-advanced-diagnostics">Optional Advanced Diagnostics</a><h5>More guides</h5><a href="client-config-examples.html">Client configuration</a><a href="http-relay.html">HTTP relay</a><a href="browser-worker.html">Remote Chrome</a><a href="browser-agent.html">Voice companion</a><a href="ssapp-integration.html">Remote SSApp</a><a href="mcp-tool-contract.html">Tool contract</a><a href="advanced-diagnostics.html">Advanced diagnostics</a><a href="vdo-ninja-p2p-data-notes.html">WebRTC data notes</a><a href="direction.html">Project direction</a></aside>
38
+ <main class="docs-main" id="main">
39
+ <button class="btn docs-toggle" type="button" aria-controls="guide-contents" aria-expanded="false">Contents</button>
40
+ <header>
41
+ <p class="guide-breadcrumb"><a href="guide.html">Documentation</a> / Quickstart</p>
42
+ <h1 id="vdoninja-mcp-quickstart">VDO.Ninja MCP Quickstart</h1>
43
+ <p class="guide-format"><a href="https://github.com/steveseguin/ninjamcp/blob/main/references/quickstart-and-compat.md">Read in Markdown</a></p>
44
+ </header>
45
+ <section class="doc-section guide-intro" id="overview">
46
+ <p>This is the fast path for users and AI agents.</p>
47
+ </section><section class="doc-section" id="transport-truth"><h2>Transport Truth</h2>
48
+ <ul>
49
+ <li>This bridge uses <strong>WebRTC data channels</strong>.</li>
50
+ <li>It is <strong>not</strong> a generic TCP/SSH tunnel.</li>
51
+ <li>TURN improves connectivity on restrictive networks, but it is <strong>not</strong> a guaranteed firewall bypass.</li>
52
+ </ul>
53
+ </section><section class="doc-section" id="60-second-setup"><h2>60-Second Setup</h2>
54
+ <p>Install locally (no clone), including a Node WebRTC implementation:</p>
55
+ <pre><code class="lang-sh">npm i @vdoninja/mcp
56
+ </code></pre>
57
+ <p>Register MCP for Codex/Claude:</p>
58
+ <pre><code class="lang-sh">npx vdon-mcp-install
59
+ </code></pre>
60
+ <p>Start the local MCP server:</p>
61
+ <pre><code class="lang-sh">npx vdon-mcp-server
62
+ </code></pre>
63
+ <p>If started directly in a terminal, it prints a short <code>Server running (stdio)</code> banner and a first-call hint.
64
+ If started by an MCP client, no interactive banner may appear, which is normal.</p>
65
+ <p>Optional least-privilege profile:</p>
66
+ <pre><code class="lang-sh">VDON_MCP_TOOL_PROFILE=core npx vdon-mcp-server
67
+ </code></pre>
68
+ <p>Repo-local equivalents still work when developing in this repo:</p>
69
+ <pre><code class="lang-sh">npm run mcp:install
70
+ node scripts/vdo-mcp-server.js
71
+ </code></pre>
72
+ <p>AI-first sanity check (recommended first call):</p>
73
+ <pre><code class="lang-json">{ "name": "vdo_capabilities", "arguments": {} }
74
+ </code></pre>
75
+ </section><section class="doc-section" id="workflow-a-bot-to-bot-message"><h2>Workflow A: Bot-to-Bot Message</h2>
76
+ <ol>
77
+ <li>Connect peer A:</li>
78
+ </ol>
79
+ <pre><code class="lang-json">{ "name": "vdo_connect", "arguments": { "room": "lab_1", "stream_id": "agent_a" } }
80
+ </code></pre>
81
+ <ol start="2">
82
+ <li>Connect peer B:</li>
83
+ </ol>
84
+ <pre><code class="lang-json">{ "name": "vdo_connect", "arguments": { "room": "lab_1", "stream_id": "agent_b", "target_stream_id": "agent_a" } }
85
+ </code></pre>
86
+ <ol start="3">
87
+ <li>Send:</li>
88
+ </ol>
89
+ <pre><code class="lang-json">{
90
+ "name": "vdo_send",
91
+ "arguments": {
92
+ "session_id": "&lt;agent_a_session_id&gt;",
93
+ "data": { "type": "chat.message", "text": "hello from agent_a" }
94
+ }
95
+ }
96
+ </code></pre>
97
+ <ol start="4">
98
+ <li>Receive:</li>
99
+ </ol>
100
+ <pre><code class="lang-json">{
101
+ "name": "vdo_receive",
102
+ "arguments": {
103
+ "session_id": "&lt;agent_b_session_id&gt;",
104
+ "max_events": 100,
105
+ "wait_ms": 1000
106
+ }
107
+ }
108
+ </code></pre>
109
+ <p>Runnable demo script:</p>
110
+ <pre><code class="lang-sh">npx vdon-mcp-demo-message
111
+ </code></pre>
112
+ <p>For live network mode instead of fake/local demo mode:</p>
113
+ <pre><code class="lang-sh">MCP_DEMO_FAKE=0 MCP_DEMO_FORCE_TURN=1 npx vdon-mcp-demo-message
114
+ </code></pre>
115
+ </section><section class="doc-section" id="workflow-b-file-sendreceive"><h2>Workflow B: File Send/Receive</h2>
116
+ <ol>
117
+ <li>
118
+ <p>Reuse two connected peers from Workflow A.</p>
119
+ </li>
120
+ <li>
121
+ <p>Send file payload from agent A:</p>
122
+ </li>
123
+ </ol>
124
+ <pre><code class="lang-json">{
125
+ "name": "vdo_file_send",
126
+ "arguments": {
127
+ "session_id": "&lt;agent_a_session_id&gt;",
128
+ "name": "notes.txt",
129
+ "mime": "text/plain",
130
+ "data_base64": "&lt;base64&gt;"
131
+ }
132
+ }
133
+ </code></pre>
134
+ <ol start="3">
135
+ <li>On agent B, watch transfers:</li>
136
+ </ol>
137
+ <pre><code class="lang-json">{
138
+ "name": "vdo_file_transfers",
139
+ "arguments": {
140
+ "session_id": "&lt;agent_b_session_id&gt;",
141
+ "direction": "incoming"
142
+ }
143
+ }
144
+ </code></pre>
145
+ <ol start="4">
146
+ <li>Read completed file:</li>
147
+ </ol>
148
+ <pre><code class="lang-json">{
149
+ "name": "vdo_file_receive",
150
+ "arguments": {
151
+ "session_id": "&lt;agent_b_session_id&gt;",
152
+ "transfer_id": "&lt;transfer_id&gt;",
153
+ "encoding": "utf8"
154
+ }
155
+ }
156
+ </code></pre>
157
+ <p>Runnable demo script:</p>
158
+ <pre><code class="lang-sh">npx vdon-mcp-demo-file
159
+ </code></pre>
160
+ <p>For live network mode:</p>
161
+ <pre><code class="lang-sh">MCP_DEMO_FAKE=0 MCP_DEMO_FORCE_TURN=1 npx vdon-mcp-demo-file
162
+ </code></pre>
163
+ </section><section class="doc-section" id="security-baseline"><h2>Security Baseline</h2>
164
+ <p>Use secure mode when needed:</p>
165
+ <ul>
166
+ <li><code>join_token</code> + <code>join_token_secret</code></li>
167
+ <li><code>enforce_join_token: true</code></li>
168
+ <li><code>allow_peer_stream_ids: [...]</code></li>
169
+ <li><code>require_session_mac: true</code></li>
170
+ </ul>
171
+ <p>For secure preset installs, set <code>VDON_MCP_JOIN_TOKEN_SECRET</code> first.</p>
172
+ </section><section class="doc-section" id="minimal-test-bar"><h2>Minimal Test Bar</h2>
173
+ <p>Default MCP test run (fast, product-focused):</p>
174
+ <pre><code class="lang-sh">npm run test:mcp
175
+ </code></pre>
176
+ <p>This runs:</p>
177
+ <ul>
178
+ <li>conformance</li>
179
+ <li>server smoke</li>
180
+ <li>sync security smoke</li>
181
+ </ul>
182
+ <p>Full engineering suite (advanced):</p>
183
+ <pre><code class="lang-sh">npm run test:mcp:all
184
+ </code></pre>
185
+ </section><section class="doc-section" id="compatibility-notes"><h2>Compatibility Notes</h2>
186
+ <ul>
187
+ <li>Works with any MCP client that supports local <code>stdio</code> transport (Codex CLI, Claude Code, Cursor, and other MCP-compatible CLIs).</li>
188
+ <li>Codex and Claude can be auto-registered via <code>npx vdon-mcp-install</code>.</li>
189
+ <li>Cursor and other GUI tools typically need manual MCP JSON config using:</li>
190
+ <li><code>command</code>: your Node executable</li>
191
+ <li><code>args</code>: path to <code>.../node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js</code> plus optional flags</li>
192
+ <li>Ready-to-paste per-client examples are in <code>references/client-config-examples.md</code>.</li>
193
+ <li>Registry metadata is in <code>server.json</code>.</li>
194
+ <li>Tool contracts are in <code>references/mcp-tool-contract.md</code>.</li>
195
+ <li><code>@vdoninja/mcp</code> depends on <code>@vdoninja/sdk</code>, so SDK is installed transitively.</li>
196
+ <li><code>@vdoninja/mcp</code> is MIT licensed. Its SDK dependency is separately licensed
197
+ under MPL-2.0, with some separately marked wrappers and adapters under MIT.</li>
198
+ </ul>
199
+ </section><section class="doc-section" id="optional-advanced-diagnostics"><h2>Optional Advanced Diagnostics</h2>
200
+ <p>For soak/matrix/preset-matrix/sweep tuning and all reliability knobs, use:</p>
201
+ <ul>
202
+ <li><code>references/advanced-diagnostics.md</code></li>
203
+ </ul></section>
204
+ <nav class="pager" aria-label="More documentation"><a href="guide.html#guides"><small>Keep reading</small><b>Browse all guides</b></a><a href="https://discord.vdo.ninja"><small>Need help?</small><b>Ask on Discord</b></a></nav>
205
+ </main>
206
+ </div>
207
+ <footer class="footer">
208
+ <div class="wrap">
209
+ <a class="brand" href="./"><img alt="" height="24" src="assets/logo.svg" width="24"/><span>VDO.Ninja <small>MCP</small></span></a>
210
+ <nav aria-label="Footer">
211
+ <a href="./">Home</a>
212
+ <a href="https://github.com/steveseguin/ninjamcp">GitHub</a>
213
+ <a href="https://www.npmjs.com/package/@vdoninja/mcp">npm</a>
214
+ <a href="https://discord.vdo.ninja">Discord</a>
215
+ <a href="https://vdo.ninja">VDO.Ninja</a>
216
+ </nav>
217
+ <span>MIT · © 2026 Steve Seguin</span>
218
+ </div>
219
+ </footer>
220
+ <script src="assets/site.js" defer></script>
221
+ </body>
222
+ </html>
@@ -0,0 +1,16 @@
1
+ {
2
+ "name": "VDO.Ninja MCP",
3
+ "short_name": "Ninja MCP",
4
+ "description": "A private room where AI agents exchange messages, files, and shared state.",
5
+ "start_url": "./",
6
+ "scope": "./",
7
+ "display": "browser",
8
+ "background_color": "#fafaf8",
9
+ "theme_color": "#14161b",
10
+ "icons": [
11
+ { "src": "assets/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
12
+ { "src": "assets/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
13
+ { "src": "assets/icon-maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" },
14
+ { "src": "assets/favicon.svg", "sizes": "any", "type": "image/svg+xml", "purpose": "any" }
15
+ ]
16
+ }
@@ -0,0 +1,63 @@
1
+ <?xml version="1.0" encoding="UTF-8"?>
2
+ <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
3
+ <url>
4
+ <loc>https://steveseguin.github.io/ninjamcp/</loc>
5
+ <changefreq>monthly</changefreq>
6
+ <priority>1.0</priority>
7
+ </url>
8
+ <url>
9
+ <loc>https://steveseguin.github.io/ninjamcp/guide.html</loc>
10
+ <changefreq>monthly</changefreq>
11
+ <priority>0.8</priority>
12
+ </url>
13
+ <url>
14
+ <loc>https://steveseguin.github.io/ninjamcp/quickstart-and-compat.html</loc>
15
+ <changefreq>monthly</changefreq>
16
+ <priority>0.6</priority>
17
+ </url>
18
+ <url>
19
+ <loc>https://steveseguin.github.io/ninjamcp/client-config-examples.html</loc>
20
+ <changefreq>monthly</changefreq>
21
+ <priority>0.6</priority>
22
+ </url>
23
+ <url>
24
+ <loc>https://steveseguin.github.io/ninjamcp/http-relay.html</loc>
25
+ <changefreq>monthly</changefreq>
26
+ <priority>0.6</priority>
27
+ </url>
28
+ <url>
29
+ <loc>https://steveseguin.github.io/ninjamcp/browser-worker.html</loc>
30
+ <changefreq>monthly</changefreq>
31
+ <priority>0.6</priority>
32
+ </url>
33
+ <url>
34
+ <loc>https://steveseguin.github.io/ninjamcp/browser-agent.html</loc>
35
+ <changefreq>monthly</changefreq>
36
+ <priority>0.6</priority>
37
+ </url>
38
+ <url>
39
+ <loc>https://steveseguin.github.io/ninjamcp/ssapp-integration.html</loc>
40
+ <changefreq>monthly</changefreq>
41
+ <priority>0.6</priority>
42
+ </url>
43
+ <url>
44
+ <loc>https://steveseguin.github.io/ninjamcp/mcp-tool-contract.html</loc>
45
+ <changefreq>monthly</changefreq>
46
+ <priority>0.6</priority>
47
+ </url>
48
+ <url>
49
+ <loc>https://steveseguin.github.io/ninjamcp/advanced-diagnostics.html</loc>
50
+ <changefreq>monthly</changefreq>
51
+ <priority>0.6</priority>
52
+ </url>
53
+ <url>
54
+ <loc>https://steveseguin.github.io/ninjamcp/vdo-ninja-p2p-data-notes.html</loc>
55
+ <changefreq>monthly</changefreq>
56
+ <priority>0.6</priority>
57
+ </url>
58
+ <url>
59
+ <loc>https://steveseguin.github.io/ninjamcp/direction.html</loc>
60
+ <changefreq>monthly</changefreq>
61
+ <priority>0.6</priority>
62
+ </url>
63
+ </urlset>