@vdoninja/mcp 0.4.1 → 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 -661
  2. package/README.md +59 -272
  3. package/assets/browser-agent/audio-worklet.js +17 -0
  4. package/assets/browser-agent/client.js +124 -0
  5. package/assets/browser-agent/index.html +50 -0
  6. package/assets/cloudflare/worker-proxy.js +3 -0
  7. package/docs/.nojekyll +0 -0
  8. package/docs/404.html +28 -0
  9. package/docs/advanced-diagnostics.html +101 -0
  10. package/docs/assets/apple-touch-icon.png +0 -0
  11. package/docs/assets/favicon.svg +7 -0
  12. package/docs/assets/how-it-works.svg +62 -0
  13. package/docs/assets/icon-192.png +0 -0
  14. package/docs/assets/icon-512.png +0 -0
  15. package/docs/assets/icon-maskable-512.png +0 -0
  16. package/docs/assets/icons.svg +42 -0
  17. package/docs/assets/logo.svg +7 -0
  18. package/docs/assets/og-image.png +0 -0
  19. package/docs/assets/site.css +735 -0
  20. package/docs/assets/site.js +289 -0
  21. package/docs/browser-agent.html +122 -0
  22. package/docs/browser-worker.html +165 -0
  23. package/docs/client-config-examples.html +254 -0
  24. package/docs/direction.html +175 -0
  25. package/docs/favicon.ico +0 -0
  26. package/docs/guide.html +872 -0
  27. package/docs/http-relay.html +154 -0
  28. package/docs/index.html +834 -0
  29. package/docs/mcp-tool-contract.html +226 -0
  30. package/docs/quickstart-and-compat.html +222 -0
  31. package/docs/site.webmanifest +16 -0
  32. package/docs/sitemap.xml +63 -0
  33. package/docs/ssapp-integration.html +594 -0
  34. package/docs/vdo-ninja-p2p-data-notes.html +225 -0
  35. package/package.json +51 -9
  36. package/references/advanced-diagnostics.md +2 -0
  37. package/references/browser-agent.md +53 -0
  38. package/references/browser-worker.md +142 -0
  39. package/references/client-config-examples.md +2 -0
  40. package/references/direction.md +88 -0
  41. package/references/http-relay.md +107 -0
  42. package/references/mcp-tool-contract.md +11 -1
  43. package/references/quickstart-and-compat.md +4 -1
  44. package/references/ssapp-integration.md +371 -0
  45. package/references/vdo-ninja-p2p-data-notes.md +2 -0
  46. package/scripts/demo-file-workflow.js +3 -0
  47. package/scripts/demo-message-workflow.js +3 -0
  48. package/scripts/install-mcp.js +5 -2
  49. package/scripts/lib/bridge-session.js +143 -26
  50. package/scripts/lib/bridge-utils.js +3 -0
  51. package/scripts/lib/browser-agent.js +255 -0
  52. package/scripts/lib/browser-media.js +79 -0
  53. package/scripts/lib/browser-routes.js +119 -0
  54. package/scripts/lib/browser-rpc.js +214 -0
  55. package/scripts/lib/browser-setup.js +133 -0
  56. package/scripts/lib/browser-worker.js +216 -0
  57. package/scripts/lib/fake-network-sdk.js +3 -0
  58. package/scripts/lib/http-relay-transport.js +294 -0
  59. package/scripts/lib/load-vdo-sdk.js +3 -0
  60. package/scripts/lib/mcp-stdio-parser.js +3 -0
  61. package/scripts/lib/ssapp-worker.js +198 -0
  62. package/scripts/lib/tool-profiles.js +3 -0
  63. package/scripts/vdo-data-bridge.js +3 -0
  64. package/scripts/vdo-mcp-browser-agent.js +132 -0
  65. package/scripts/vdo-mcp-browser.js +218 -0
  66. package/scripts/vdo-mcp-relay.js +207 -0
  67. package/scripts/vdo-mcp-server.js +50 -7
  68. package/scripts/vdo-mcp-ssapp.js +208 -0
  69. package/scripts/vdo-mcp-streamable-http.js +23 -4
  70. package/server.json +22 -4
  71. package/LICENSE-SDK-EXCEPTION +0 -54
package/docs/http-relay.html ADDED
@@ -0,0 +1,154 @@
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>HTTP relay · VDO.Ninja MCP</title>
7
+ <meta name="description" content="Connect through an encrypted relay when WebRTC is unavailable.">
8
+ <meta name="color-scheme" content="light dark">
9
+ <link rel="canonical" href="https://steveseguin.github.io/ninjamcp/http-relay.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="#run-the-relay">Run the relay</a><a href="#configure-each-mcp-client">Configure each MCP client</a><a href="#join-and-send">Join and send</a><a href="#delivery-and-recovery">Delivery and recovery</a><a href="#trust-and-privacy">Trust and privacy</a><h5>More guides</h5><a href="quickstart-and-compat.html">Quickstart</a><a href="client-config-examples.html">Client configuration</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> / HTTP relay</p>
42
+ <h1 id="connect-without-webrtc">Connect without WebRTC</h1>
43
+ <p class="guide-format"><a href="https://github.com/steveseguin/ninjamcp/blob/main/references/http-relay.md">Read in Markdown</a></p>
44
+ </header>
45
+ <section class="doc-section guide-intro" id="overview">
46
+ <p>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.</p>
47
+ <p>WebRTC remains the default. Select <code>transport: "http"</code> on both participants to use the relay. Sessions using different transports do not discover each other; reconnect both with matching settings when switching.</p>
48
+ </section><section class="doc-section" id="run-the-relay"><h2>Run the relay</h2>
49
+ <p>The relay needs Node.js 18 or newer and no native dependencies. From a checkout:</p>
50
+ <pre><code class="lang-sh">$env:VDON_RELAY_TOKEN = '&lt;a random access token, at least 32 characters&gt;'
51
+ node scripts/vdo-mcp-relay.js
52
+ </code></pre>
53
+ <p>From an installed package, use <code>npx vdon-mcp-relay</code>. The default listener is <code>127.0.0.1:8790</code>. Set <code>VDON_RELAY_HOST</code> and <code>VDON_RELAY_PORT</code> to change it.</p>
54
+ <p>Generate the access token and a separate room key by running this command twice:</p>
55
+ <pre><code class="lang-sh">node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
56
+ </code></pre>
57
+ <p>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.</p>
58
+ <p>For other computers to connect, put the relay behind an HTTPS reverse proxy on your server. Forward <code>/v1/rooms/</code> unchanged, preserve the <code>Authorization</code> 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.</p>
59
+ </section><section class="doc-section" id="configure-each-mcp-client"><h2>Configure each MCP client</h2>
60
+ <p>Install without the optional native WebRTC library if needed:</p>
61
+ <pre><code class="lang-sh">npm install @vdoninja/mcp --omit=optional
62
+ </code></pre>
63
+ <p>Set these variables in the environment of each MCP server process. In a client that supports a JSON server configuration:</p>
64
+ <pre><code class="lang-json">{
65
+ "command": "node",
66
+ "args": ["/absolute/path/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"],
67
+ "env": {
68
+ "VDON_MCP_RELAY_URL": "https://relay.example.com",
69
+ "VDON_MCP_RELAY_TOKEN": "&lt;relay access token&gt;",
70
+ "VDON_MCP_RELAY_KEY": "&lt;64 hex characters from the second command&gt;"
71
+ }
72
+ }
73
+ </code></pre>
74
+ <p>For two clients on the relay computer, use <code>http://127.0.0.1:8790</code>. Both clients need the same relay URL, access token, room key, and room name. Each needs a different <code>stream_id</code>.</p>
75
+ <p>Keep secrets in the server environment where possible. <code>vdo_connect</code> also accepts <code>relay_url</code>, <code>relay_token</code>, and <code>relay_key</code> for clients that need separate settings per session. These secrets are omitted from status and connection results.</p>
76
+ </section><section class="doc-section" id="join-and-send"><h2>Join and send</h2>
77
+ <p>Connect the first agent:</p>
78
+ <pre><code class="lang-json">{ "name": "vdo_connect", "arguments": { "transport": "http", "room": "project_room", "stream_id": "planner" } }
79
+ </code></pre>
80
+ <p>Connect the second agent:</p>
81
+ <pre><code class="lang-json">{ "name": "vdo_connect", "arguments": { "transport": "http", "room": "project_room", "stream_id": "reviewer" } }
82
+ </code></pre>
83
+ <p>Use <code>vdo_sync_peers</code> to wait for discovery, then address a peer by its stream ID:</p>
84
+ <pre><code class="lang-json">{ "name": "vdo_send", "arguments": { "session_id": "&lt;planner-session&gt;", "target": "reviewer", "data": { "text": "Please review the plan." } } }
85
+ { "name": "vdo_receive", "arguments": { "session_id": "&lt;reviewer-session&gt;", "wait_ms": 1000 } }
86
+ </code></pre>
87
+ <p>File tools use the same target and retain chunk hashes, acknowledgements, retries, and completion checks. For shared state with <code>require_session_mac: true</code>, use the peer UUID from <code>vdo_sync_peers</code> as the state operation's <code>target</code>; the MAC belongs to that peer connection.</p>
88
+ </section><section class="doc-section" id="delivery-and-recovery"><h2>Delivery and recovery</h2>
89
+ <p>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.</p>
90
+ <div aria-label="Scrollable reference table" class="table-wrap" role="region" tabindex="0"><table>
91
+ <thead>
92
+ <tr>
93
+ <th scope="col">Result or event</th>
94
+ <th scope="col">Meaning and action</th>
95
+ </tr>
96
+ </thead>
97
+ <tbody>
98
+ <tr>
99
+ <td><code>vdo_send</code>: <code>delivery_stage: "queued"</code></td>
100
+ <td>The local transport accepted the message. Save its <code>message_id</code> if you need to track it.</td>
101
+ </tr>
102
+ <tr>
103
+ <td><code>relay_receipt</code>: <code>stage: "relay_accepted"</code></td>
104
+ <td>The relay accepted the event. This does not confirm peer receipt or task completion; have the other agent reply when those matter.</td>
105
+ </tr>
106
+ <tr>
107
+ <td><code>relay_receipt</code>: <code>stage: "delivery_unknown"</code></td>
108
+ <td>POST retries failed. The relay may have accepted a request whose response was lost. Check with the peer before repeating a consequential task.</td>
109
+ </tr>
110
+ <tr>
111
+ <td><code>data_received</code></td>
112
+ <td>The receiving bridge accepted a message. Its <code>message_id</code> matches the sender's ID. The AI client still needs to poll and act on it.</td>
113
+ </tr>
114
+ <tr>
115
+ <td><code>relay_connection</code></td>
116
+ <td>The reader lost or regained connectivity. Use <code>vdo_status</code> to inspect the current connection.</td>
117
+ </tr>
118
+ <tr>
119
+ <td><code>relay_history_lost</code></td>
120
+ <td>The cursor is no longer available. Reconcile outstanding tasks with peers, request a state snapshot, and inspect unfinished file transfers before resuming.</td>
121
+ </tr>
122
+ <tr>
123
+ <td><code>relay_message_rejected</code></td>
124
+ <td>An event failed decryption or validation. Check matching room keys and synchronized clocks.</td>
125
+ </tr>
126
+ </tbody>
127
+ </table></div>
128
+ <p>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.</p>
129
+ <p>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.</p>
130
+ <p>Queues and request sizes are bounded. <code>vdo_send</code> can return <code>ok: false</code> 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.</p>
131
+ </section><section class="doc-section" id="trust-and-privacy"><h2>Trust and privacy</h2>
132
+ <p>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.</p>
133
+ <p>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.</p>
134
+ <p>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.</p>
135
+ <p>The HTTP relay carries data. The optional <a href="browser-worker.html">browser adapter</a> 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 <code>vdon-mcp-http</code> command exposes MCP itself over HTTP; <code>vdon-mcp-relay</code> carries encrypted events between peers. They are different services.</p></section>
136
+ <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>
137
+ </main>
138
+ </div>
139
+ <footer class="footer">
140
+ <div class="wrap">
141
+ <a class="brand" href="./"><img alt="" height="24" src="assets/logo.svg" width="24"/><span>VDO.Ninja <small>MCP</small></span></a>
142
+ <nav aria-label="Footer">
143
+ <a href="./">Home</a>
144
+ <a href="https://github.com/steveseguin/ninjamcp">GitHub</a>
145
+ <a href="https://www.npmjs.com/package/@vdoninja/mcp">npm</a>
146
+ <a href="https://discord.vdo.ninja">Discord</a>
147
+ <a href="https://vdo.ninja">VDO.Ninja</a>
148
+ </nav>
149
+ <span>MIT · © 2026 Steve Seguin</span>
150
+ </div>
151
+ </footer>
152
+ <script src="assets/site.js" defer></script>
153
+ </body>
154
+ </html>