@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.
- package/LICENSE +21 -661
- package/README.md +59 -272
- package/assets/browser-agent/audio-worklet.js +17 -0
- package/assets/browser-agent/client.js +124 -0
- package/assets/browser-agent/index.html +50 -0
- package/assets/cloudflare/worker-proxy.js +3 -0
- package/docs/.nojekyll +0 -0
- package/docs/404.html +28 -0
- package/docs/advanced-diagnostics.html +101 -0
- package/docs/assets/apple-touch-icon.png +0 -0
- package/docs/assets/favicon.svg +7 -0
- package/docs/assets/how-it-works.svg +62 -0
- package/docs/assets/icon-192.png +0 -0
- package/docs/assets/icon-512.png +0 -0
- package/docs/assets/icon-maskable-512.png +0 -0
- package/docs/assets/icons.svg +42 -0
- package/docs/assets/logo.svg +7 -0
- package/docs/assets/og-image.png +0 -0
- package/docs/assets/site.css +735 -0
- package/docs/assets/site.js +289 -0
- package/docs/browser-agent.html +122 -0
- package/docs/browser-worker.html +165 -0
- package/docs/client-config-examples.html +254 -0
- package/docs/direction.html +175 -0
- package/docs/favicon.ico +0 -0
- package/docs/guide.html +872 -0
- package/docs/http-relay.html +154 -0
- package/docs/index.html +834 -0
- package/docs/mcp-tool-contract.html +226 -0
- package/docs/quickstart-and-compat.html +222 -0
- package/docs/site.webmanifest +16 -0
- package/docs/sitemap.xml +63 -0
- package/docs/ssapp-integration.html +594 -0
- package/docs/vdo-ninja-p2p-data-notes.html +225 -0
- package/package.json +51 -9
- package/references/advanced-diagnostics.md +2 -0
- package/references/browser-agent.md +53 -0
- package/references/browser-worker.md +142 -0
- package/references/client-config-examples.md +2 -0
- package/references/direction.md +88 -0
- package/references/http-relay.md +107 -0
- package/references/mcp-tool-contract.md +11 -1
- package/references/quickstart-and-compat.md +4 -1
- package/references/ssapp-integration.md +371 -0
- package/references/vdo-ninja-p2p-data-notes.md +2 -0
- package/scripts/demo-file-workflow.js +3 -0
- package/scripts/demo-message-workflow.js +3 -0
- package/scripts/install-mcp.js +5 -2
- package/scripts/lib/bridge-session.js +143 -26
- package/scripts/lib/bridge-utils.js +3 -0
- package/scripts/lib/browser-agent.js +255 -0
- package/scripts/lib/browser-media.js +79 -0
- package/scripts/lib/browser-routes.js +119 -0
- package/scripts/lib/browser-rpc.js +214 -0
- package/scripts/lib/browser-setup.js +133 -0
- package/scripts/lib/browser-worker.js +216 -0
- package/scripts/lib/fake-network-sdk.js +3 -0
- package/scripts/lib/http-relay-transport.js +294 -0
- package/scripts/lib/load-vdo-sdk.js +3 -0
- package/scripts/lib/mcp-stdio-parser.js +3 -0
- package/scripts/lib/ssapp-worker.js +198 -0
- package/scripts/lib/tool-profiles.js +3 -0
- package/scripts/vdo-data-bridge.js +3 -0
- package/scripts/vdo-mcp-browser-agent.js +132 -0
- package/scripts/vdo-mcp-browser.js +218 -0
- package/scripts/vdo-mcp-relay.js +207 -0
- package/scripts/vdo-mcp-server.js +50 -7
- package/scripts/vdo-mcp-ssapp.js +208 -0
- package/scripts/vdo-mcp-streamable-http.js +23 -4
- package/server.json +22 -4
- package/LICENSE-SDK-EXCEPTION +0 -54
|
@@ -0,0 +1,254 @@
|
|
|
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>Client configuration · VDO.Ninja MCP</title>
|
|
7
|
+
<meta name="description" content="Configure Ninja MCP in your preferred AI client.">
|
|
8
|
+
<meta name="color-scheme" content="light dark">
|
|
9
|
+
<link rel="canonical" href="https://steveseguin.github.io/ninjamcp/client-config-examples.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="#prereqs-no-clone">Prereqs (No Clone)</a><a href="#onboarding-pattern-what-works-best">Onboarding Pattern (What Works Best)</a><a href="#generic-stdio-mcp-template">Generic stdio MCP Template</a><a href="#cursor">Cursor</a><a href="#gemini-cli">Gemini CLI</a><a href="#opencode">OpenCode</a><a href="#codex-cli-and-claude-code-cli-automation">Codex CLI and Claude Code (CLI Automation)</a><a href="#sanity-check-all-clients">Sanity Check (All Clients)</a><a href="#context-budget-note">Context Budget Note</a><a href="#first-functional-workflows-clear-result">First Functional Workflows (Clear Result)</a><h5>More guides</h5><a href="quickstart-and-compat.html">Quickstart</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> / Client configuration</p>
|
|
42
|
+
<h1 id="vdoninja-mcp-client-config-examples">VDO.Ninja MCP Client Config Examples</h1>
|
|
43
|
+
<p class="guide-format"><a href="https://github.com/steveseguin/ninjamcp/blob/main/references/client-config-examples.md">Read in Markdown</a></p>
|
|
44
|
+
</header>
|
|
45
|
+
<section class="doc-section guide-intro" id="overview">
|
|
46
|
+
<p>Ready-to-paste config for popular MCP clients.</p>
|
|
47
|
+
</section><section class="doc-section" id="prereqs-no-clone"><h2>Prereqs (No Clone)</h2>
|
|
48
|
+
<p>Install in the project/folder where you want to use the MCP:</p>
|
|
49
|
+
<pre><code class="lang-sh">npm i @vdoninja/mcp
|
|
50
|
+
</code></pre>
|
|
51
|
+
<p>Server script path used below:</p>
|
|
52
|
+
<ul>
|
|
53
|
+
<li>Linux/macOS: <code>./node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js</code></li>
|
|
54
|
+
<li>Windows: <code>.\node_modules\@vdoninja\mcp\scripts\vdo-mcp-server.js</code></li>
|
|
55
|
+
</ul>
|
|
56
|
+
<p>Use an absolute path if your client launches from another working directory.</p>
|
|
57
|
+
</section><section class="doc-section" id="onboarding-pattern-what-works-best"><h2>Onboarding Pattern (What Works Best)</h2>
|
|
58
|
+
<p>Popular MCP servers with strong onboarding docs generally do these things:</p>
|
|
59
|
+
<ol>
|
|
60
|
+
<li>Give one copy/paste install path.</li>
|
|
61
|
+
<li>Provide per-client config snippets.</li>
|
|
62
|
+
<li>Tell users the first tool call to run.</li>
|
|
63
|
+
<li>Show one deterministic "it works" workflow with expected output.</li>
|
|
64
|
+
</ol>
|
|
65
|
+
<p>This file follows that same pattern.</p>
|
|
66
|
+
</section><section class="doc-section" id="generic-stdio-mcp-template"><h2>Generic <code>stdio</code> MCP Template</h2>
|
|
67
|
+
<p>Most MCP clients need the same three things:</p>
|
|
68
|
+
<ol>
|
|
69
|
+
<li><code>command</code> (usually <code>node</code>)</li>
|
|
70
|
+
<li><code>args</code> (script path + optional flags)</li>
|
|
71
|
+
<li><code>env</code> (optional)</li>
|
|
72
|
+
</ol>
|
|
73
|
+
<p>Example:</p>
|
|
74
|
+
<pre><code class="lang-json">{
|
|
75
|
+
"command": "node",
|
|
76
|
+
"args": [
|
|
77
|
+
"/ABSOLUTE/PATH/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js",
|
|
78
|
+
"--tool-profile",
|
|
79
|
+
"core"
|
|
80
|
+
],
|
|
81
|
+
"env": {
|
|
82
|
+
"VDON_MCP_TOOL_PROFILE": "core"
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
</code></pre>
|
|
86
|
+
</section><section class="doc-section" id="cursor"><h2>Cursor</h2>
|
|
87
|
+
<p>Cursor reads MCP config from:</p>
|
|
88
|
+
<ul>
|
|
89
|
+
<li>Global: <code>~/.cursor/mcp.json</code></li>
|
|
90
|
+
<li>Project: <code>.cursor/mcp.json</code></li>
|
|
91
|
+
</ul>
|
|
92
|
+
<p>Example:</p>
|
|
93
|
+
<pre><code class="lang-json">{
|
|
94
|
+
"mcpServers": {
|
|
95
|
+
"vdo-ninja-mcp": {
|
|
96
|
+
"command": "node",
|
|
97
|
+
"args": [
|
|
98
|
+
"/ABSOLUTE/PATH/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"
|
|
99
|
+
],
|
|
100
|
+
"env": {
|
|
101
|
+
"VDON_MCP_TOOL_PROFILE": "core"
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
</code></pre>
|
|
107
|
+
</section><section class="doc-section" id="gemini-cli"><h2>Gemini CLI</h2>
|
|
108
|
+
<p>Gemini CLI supports MCP via <code>mcpServers</code> in <code>settings.json</code>.</p>
|
|
109
|
+
<p>Common config file locations:</p>
|
|
110
|
+
<ul>
|
|
111
|
+
<li>Project: <code>.gemini/settings.json</code></li>
|
|
112
|
+
<li>Linux/macOS: <code>~/.gemini/settings.json</code></li>
|
|
113
|
+
<li>Windows: <code>%USERPROFILE%\\.gemini\\settings.json</code></li>
|
|
114
|
+
</ul>
|
|
115
|
+
<p>Example:</p>
|
|
116
|
+
<pre><code class="lang-json">{
|
|
117
|
+
"mcpServers": {
|
|
118
|
+
"vdo-ninja-mcp": {
|
|
119
|
+
"command": "node",
|
|
120
|
+
"args": [
|
|
121
|
+
"/ABSOLUTE/PATH/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"
|
|
122
|
+
],
|
|
123
|
+
"env": {
|
|
124
|
+
"VDON_MCP_TOOL_PROFILE": "core"
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
</code></pre>
|
|
130
|
+
<p>After restarting Gemini CLI, use <code>/mcp</code> to confirm server status.</p>
|
|
131
|
+
</section><section class="doc-section" id="opencode"><h2>OpenCode</h2>
|
|
132
|
+
<p>OpenCode MCP config lives under <code>mcp</code> in OpenCode config.</p>
|
|
133
|
+
<p>Common config file locations:</p>
|
|
134
|
+
<ul>
|
|
135
|
+
<li>Global: <code>~/.config/opencode/opencode.json</code></li>
|
|
136
|
+
<li>Project: <code>opencode.json</code> (project root)</li>
|
|
137
|
+
</ul>
|
|
138
|
+
<p>Example:</p>
|
|
139
|
+
<pre><code class="lang-json">{
|
|
140
|
+
"$schema": "https://opencode.ai/config.json",
|
|
141
|
+
"mcp": {
|
|
142
|
+
"vdo-ninja-mcp": {
|
|
143
|
+
"type": "local",
|
|
144
|
+
"command": [
|
|
145
|
+
"node",
|
|
146
|
+
"/ABSOLUTE/PATH/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js",
|
|
147
|
+
"--tool-profile",
|
|
148
|
+
"core"
|
|
149
|
+
],
|
|
150
|
+
"enabled": true,
|
|
151
|
+
"environment": {
|
|
152
|
+
"VDON_MCP_TOOL_PROFILE": "core"
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
</code></pre>
|
|
158
|
+
</section><section class="doc-section" id="codex-cli-and-claude-code-cli-automation"><h2>Codex CLI and Claude Code (CLI Automation)</h2>
|
|
159
|
+
<p>Auto-register if either/both CLIs are installed:</p>
|
|
160
|
+
<pre><code class="lang-sh">npx vdon-mcp-install
|
|
161
|
+
</code></pre>
|
|
162
|
+
<p>If only one CLI is installed:</p>
|
|
163
|
+
<pre><code class="lang-sh">npx vdon-mcp-install --codex-only
|
|
164
|
+
npx vdon-mcp-install --claude-only
|
|
165
|
+
</code></pre>
|
|
166
|
+
</section><section class="doc-section" id="sanity-check-all-clients"><h2>Sanity Check (All Clients)</h2>
|
|
167
|
+
<p>First tool call should be:</p>
|
|
168
|
+
<pre><code class="lang-json">{ "name": "vdo_capabilities", "arguments": {} }
|
|
169
|
+
</code></pre>
|
|
170
|
+
<p>Then connect:</p>
|
|
171
|
+
<pre><code class="lang-json">{ "name": "vdo_connect", "arguments": { "room": "lab_1" } }
|
|
172
|
+
</code></pre>
|
|
173
|
+
<p>If <code>vdo_capabilities</code> works, your MCP wiring is correct.</p>
|
|
174
|
+
</section><section class="doc-section" id="context-budget-note"><h2>Context Budget Note</h2>
|
|
175
|
+
<p>Adding MCP servers increases tool/context footprint. Start with one MCP and least-privilege profile (<code>core</code>) first, then add more only as needed.</p>
|
|
176
|
+
</section><section class="doc-section" id="first-functional-workflows-clear-result"><h2>First Functional Workflows (Clear Result)</h2>
|
|
177
|
+
<p>Use unique room names to avoid collisions.</p>
|
|
178
|
+
<h3 id="codex-to-codex-two-terminals">Codex to Codex (Two Terminals)</h3>
|
|
179
|
+
<ol>
|
|
180
|
+
<li>Install/register once:</li>
|
|
181
|
+
</ol>
|
|
182
|
+
<pre><code class="lang-sh">npm i @vdoninja/mcp
|
|
183
|
+
npx vdon-mcp-install --codex-only
|
|
184
|
+
</code></pre>
|
|
185
|
+
<ol start="2">
|
|
186
|
+
<li>Open two Codex sessions (<code>A</code> and <code>B</code>) with MCP enabled.</li>
|
|
187
|
+
<li>In session <code>A</code>, call:</li>
|
|
188
|
+
</ol>
|
|
189
|
+
<pre><code class="lang-json">{ "name": "vdo_connect", "arguments": { "room": "codex_lab_001", "stream_id": "codex_a" } }
|
|
190
|
+
</code></pre>
|
|
191
|
+
<ol start="4">
|
|
192
|
+
<li>In session <code>B</code>, call:</li>
|
|
193
|
+
</ol>
|
|
194
|
+
<pre><code class="lang-json">{ "name": "vdo_connect", "arguments": { "room": "codex_lab_001", "stream_id": "codex_b", "target_stream_id": "codex_a" } }
|
|
195
|
+
</code></pre>
|
|
196
|
+
<ol start="5">
|
|
197
|
+
<li>In session <code>A</code>, send:</li>
|
|
198
|
+
</ol>
|
|
199
|
+
<pre><code class="lang-json">{
|
|
200
|
+
"name": "vdo_send",
|
|
201
|
+
"arguments": {
|
|
202
|
+
"session_id": "<codex_a_session_id>",
|
|
203
|
+
"data": { "type": "chat.message", "text": "hello from codex_a" }
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
</code></pre>
|
|
207
|
+
<ol start="6">
|
|
208
|
+
<li>In session <code>B</code>, receive:</li>
|
|
209
|
+
</ol>
|
|
210
|
+
<pre><code class="lang-json">{
|
|
211
|
+
"name": "vdo_receive",
|
|
212
|
+
"arguments": {
|
|
213
|
+
"session_id": "<codex_b_session_id>",
|
|
214
|
+
"wait_ms": 1000
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
</code></pre>
|
|
218
|
+
<p>Expected result: a <code>data_received</code> event containing <code>"hello from codex_a"</code>.</p>
|
|
219
|
+
<h3 id="claude-to-claude-two-terminals">Claude to Claude (Two Terminals)</h3>
|
|
220
|
+
<ol>
|
|
221
|
+
<li>Install/register once:</li>
|
|
222
|
+
</ol>
|
|
223
|
+
<pre><code class="lang-sh">npm i @vdoninja/mcp
|
|
224
|
+
npx vdon-mcp-install --claude-only
|
|
225
|
+
</code></pre>
|
|
226
|
+
<ol start="2">
|
|
227
|
+
<li>Repeat the same tool flow as above with a new room name, e.g. <code>claude_lab_001</code>.</li>
|
|
228
|
+
</ol>
|
|
229
|
+
<p>Expected result: the second Claude session receives the message in <code>vdo_receive</code> with <code>event.type = "data_received"</code>.</p>
|
|
230
|
+
<h3 id="fast-scripted-proof-no-manual-tool-calls">Fast Scripted Proof (No Manual Tool Calls)</h3>
|
|
231
|
+
<p>If you just want a quick pass/fail:</p>
|
|
232
|
+
<pre><code class="lang-sh">npx vdon-mcp-demo-message
|
|
233
|
+
npx vdon-mcp-demo-file
|
|
234
|
+
</code></pre>
|
|
235
|
+
<p>Expected result: each script exits successfully and reports message/file workflow completion.</p></section>
|
|
236
|
+
<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>
|
|
237
|
+
</main>
|
|
238
|
+
</div>
|
|
239
|
+
<footer class="footer">
|
|
240
|
+
<div class="wrap">
|
|
241
|
+
<a class="brand" href="./"><img alt="" height="24" src="assets/logo.svg" width="24"/><span>VDO.Ninja <small>MCP</small></span></a>
|
|
242
|
+
<nav aria-label="Footer">
|
|
243
|
+
<a href="./">Home</a>
|
|
244
|
+
<a href="https://github.com/steveseguin/ninjamcp">GitHub</a>
|
|
245
|
+
<a href="https://www.npmjs.com/package/@vdoninja/mcp">npm</a>
|
|
246
|
+
<a href="https://discord.vdo.ninja">Discord</a>
|
|
247
|
+
<a href="https://vdo.ninja">VDO.Ninja</a>
|
|
248
|
+
</nav>
|
|
249
|
+
<span>MIT · © 2026 Steve Seguin</span>
|
|
250
|
+
</div>
|
|
251
|
+
</footer>
|
|
252
|
+
<script src="assets/site.js" defer></script>
|
|
253
|
+
</body>
|
|
254
|
+
</html>
|
|
@@ -0,0 +1,175 @@
|
|
|
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>Project direction · VDO.Ninja MCP</title>
|
|
7
|
+
<meta name="description" content="Live tools and perception for MCP agents, alongside ninja-p2p and the VDO.Ninja SDK.">
|
|
8
|
+
<meta name="color-scheme" content="light dark">
|
|
9
|
+
<link rel="canonical" href="https://steveseguin.github.io/ninjamcp/direction.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="#complement-ninja-p2p">Complement ninja-p2p</a><a href="#available-foundation">Available foundation</a><a href="#what-to-build-next">What to build next</a><a href="#build-on-the-vdoninja-sdk">Build on the VDO.Ninja SDK</a><a href="#optional-shared-chrome-worker">Optional shared Chrome worker</a><a href="#ideas-to-carry-forward">Ideas to carry forward</a><a href="#product-boundaries">Product boundaries</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="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></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> / Project direction</p>
|
|
42
|
+
<h1 id="direction-live-tools-and-perception-for-mcp-agents">Direction: live tools and perception for MCP agents</h1>
|
|
43
|
+
<p class="guide-format"><a href="https://github.com/steveseguin/ninjamcp/blob/main/references/direction.md">Read in Markdown</a></p>
|
|
44
|
+
</header>
|
|
45
|
+
<section class="doc-section guide-intro" id="overview">
|
|
46
|
+
<p>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.</p>
|
|
47
|
+
<p>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.</p>
|
|
48
|
+
<p>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.</p>
|
|
49
|
+
</section><section class="doc-section" id="complement-ninja-p2p"><h2>Complement ninja-p2p</h2>
|
|
50
|
+
<div aria-label="Scrollable reference table" class="table-wrap" role="region" tabindex="0"><table>
|
|
51
|
+
<thead>
|
|
52
|
+
<tr>
|
|
53
|
+
<th scope="col">Project</th>
|
|
54
|
+
<th scope="col">Main responsibility</th>
|
|
55
|
+
<th scope="col">User's starting point</th>
|
|
56
|
+
</tr>
|
|
57
|
+
</thead>
|
|
58
|
+
<tbody>
|
|
59
|
+
<tr>
|
|
60
|
+
<td><strong>Ninja MCP</strong></td>
|
|
61
|
+
<td>Active connections, MCP tool contracts, scoped remote operations, and live media access, including an optional shared Chrome worker.</td>
|
|
62
|
+
<td>Add an MCP server to an existing AI client and call a tool.</td>
|
|
63
|
+
</tr>
|
|
64
|
+
<tr>
|
|
65
|
+
<td><a href="https://github.com/steveseguin/ninja-p2p">ninja-p2p</a></td>
|
|
66
|
+
<td>The continuing team workspace: sidecars, identities and profiles, local inbox/outbox, handoffs, receipts, wake hooks, files, and the operator dashboard.</td>
|
|
67
|
+
<td>Start a sidecar, join the team, and retain work between agent turns.</td>
|
|
68
|
+
</tr>
|
|
69
|
+
<tr>
|
|
70
|
+
<td><a href="https://sdk.vdo.ninja/">VDO.Ninja SDK</a></td>
|
|
71
|
+
<td>Reusable peer connectivity, data channels, and audio/video transport.</td>
|
|
72
|
+
<td>Build an application or adapter.</td>
|
|
73
|
+
</tr>
|
|
74
|
+
</tbody>
|
|
75
|
+
</table></div>
|
|
76
|
+
<p>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 <a href="https://github.com/steveseguin/ninja-p2p/blob/main/docs/north-star.md">ninja-p2p's north star</a>.</p>
|
|
77
|
+
<p>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.</p>
|
|
78
|
+
<p>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.</p>
|
|
79
|
+
</section><section class="doc-section" id="available-foundation"><h2>Available foundation</h2>
|
|
80
|
+
<ul>
|
|
81
|
+
<li>MCP tools for messages, files, peer discovery, and shared state.</li>
|
|
82
|
+
<li>Direct WebRTC and optional TURN connectivity.</li>
|
|
83
|
+
<li>An explicit, self-hosted encrypted HTTP relay for machines and networks without WebRTC.</li>
|
|
84
|
+
<li>Tool profiles, peer allowlists, join tokens, and per-peer protocol MACs.</li>
|
|
85
|
+
<li>An optional <a href="browser-worker.html">Chrome worker</a> with individual client credentials, tab leases, snapshots, screenshots, and SDK tab audio/video.</li>
|
|
86
|
+
<li>Guided browser setup, connection diagnostics, and automatic WebRTC/HTTP routing with one request identity and worker result cache.</li>
|
|
87
|
+
<li>An optional <a href="browser-agent.html">browser companion</a> with OpenAI Realtime speech, selected browser frames, explicit control permission, and interruption.</li>
|
|
88
|
+
<li>An optional <a href="ssapp-integration.html">SSApp bridge</a> for the running app's MCP tools, screenshots, input and dialogs, with individual credentials and one controller at a time.</li>
|
|
89
|
+
</ul>
|
|
90
|
+
<p>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.</p>
|
|
91
|
+
</section><section class="doc-section" id="what-to-build-next"><h2>What to build next</h2>
|
|
92
|
+
<ol>
|
|
93
|
+
<li><strong>Make live tool interactions dependable.</strong> 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.</li>
|
|
94
|
+
<li><strong>Extend dependable routing beyond browser tools.</strong> 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.</li>
|
|
95
|
+
<li><strong>Expand shared perception deliberately.</strong> 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.</li>
|
|
96
|
+
<li><strong>Connect to continuing collaboration.</strong> 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.</li>
|
|
97
|
+
</ol>
|
|
98
|
+
<p>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.</p>
|
|
99
|
+
</section><section class="doc-section" id="build-on-the-vdoninja-sdk"><h2>Build on the VDO.Ninja SDK</h2>
|
|
100
|
+
<p>The MCP bridge already uses <code>@vdoninja/sdk</code>. 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 <a href="https://sdk.vdo.ninja/docs/api-reference.html">SDK API</a> and <a href="https://sdk.vdo.ninja/docs/remote-control.html">remote-control guide</a>.</p>
|
|
101
|
+
<p>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.</p>
|
|
102
|
+
</section><section class="doc-section" id="optional-shared-chrome-worker"><h2>Optional shared Chrome worker</h2>
|
|
103
|
+
<p>The <a href="browser-worker.html">browser worker</a> 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.</p>
|
|
104
|
+
<p>The adapter pins <a href="https://github.com/ChromeDevTools/chrome-devtools-mcp">Chrome DevTools MCP</a> and Puppeteer as optional dependencies, with explicit page targeting and a separate browser runtime. An extension-based server such as <a href="https://github.com/hangwin/mcp-chrome">mcp-chrome</a> remains an alternative for an operator's existing browser. <a href="https://github.com/steveseguin/remote_ninja">Remote Ninja</a> provides an existing VDO.Ninja example of forwarding remote operations to a local application.</p>
|
|
105
|
+
<p>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.</p>
|
|
106
|
+
<p>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.</p>
|
|
107
|
+
<p>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.</p>
|
|
108
|
+
</section><section class="doc-section" id="ideas-to-carry-forward"><h2>Ideas to carry forward</h2>
|
|
109
|
+
<div aria-label="Scrollable reference table" class="table-wrap" role="region" tabindex="0"><table>
|
|
110
|
+
<thead>
|
|
111
|
+
<tr>
|
|
112
|
+
<th scope="col">Project</th>
|
|
113
|
+
<th scope="col">Useful contribution</th>
|
|
114
|
+
</tr>
|
|
115
|
+
</thead>
|
|
116
|
+
<tbody>
|
|
117
|
+
<tr>
|
|
118
|
+
<td><a href="https://github.com/reason-machines/reason-network">Reason Network</a></td>
|
|
119
|
+
<td>A directory of live sessions, context-aware addressing, immediate or deferred delivery, and relay-backed connectivity.</td>
|
|
120
|
+
</tr>
|
|
121
|
+
<tr>
|
|
122
|
+
<td><a href="https://a2a-protocol.org/latest/specification/">A2A</a></td>
|
|
123
|
+
<td>Capability cards, explicit task lifecycles, streaming progress, and artifacts.</td>
|
|
124
|
+
</tr>
|
|
125
|
+
<tr>
|
|
126
|
+
<td><a href="https://github.com/AgentWorkforce/relay">Agent Relay</a></td>
|
|
127
|
+
<td>Direct messages, channels, threads, and an inspectable conversation.</td>
|
|
128
|
+
</tr>
|
|
129
|
+
<tr>
|
|
130
|
+
<td><a href="https://github.com/Dicklesworthstone/mcp_agent_mail">MCP Agent Mail</a></td>
|
|
131
|
+
<td>Durable mail and searchable threads for ninja-p2p's continuing workspace, accessible through an optional MCP adapter.</td>
|
|
132
|
+
</tr>
|
|
133
|
+
<tr>
|
|
134
|
+
<td><a href="https://github.com/1gr14/agents-party">agents-party</a></td>
|
|
135
|
+
<td>A shared room where people can follow and participate in agent collaboration.</td>
|
|
136
|
+
</tr>
|
|
137
|
+
<tr>
|
|
138
|
+
<td><a href="https://docs.ntfy.sh/subscribe/api/">ntfy</a> and <a href="https://docs.nats.io/learn/jetstream/delivery-and-acknowledgment">NATS JetStream</a></td>
|
|
139
|
+
<td>Replay cursors, bounded retrieval, explicit acknowledgements, and redelivery.</td>
|
|
140
|
+
</tr>
|
|
141
|
+
<tr>
|
|
142
|
+
<td><a href="https://github.com/pipecat-ai/pipecat">Pipecat</a>, <a href="https://docs.livekit.io/agents/">LiveKit Agents</a>, and <a href="https://github.com/gradio-app/fastrtc">FastRTC</a></td>
|
|
143
|
+
<td>Agents as media participants, interchangeable media/model adapters, interruption handling, and short runnable examples.</td>
|
|
144
|
+
</tr>
|
|
145
|
+
<tr>
|
|
146
|
+
<td><a href="https://github.com/steveseguin/social_stream/blob/main/api.md">Social Stream</a></td>
|
|
147
|
+
<td>Simple POST and SSE interaction patterns for a separately operated agent relay.</td>
|
|
148
|
+
</tr>
|
|
149
|
+
</tbody>
|
|
150
|
+
</table></div>
|
|
151
|
+
<p>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.</p>
|
|
152
|
+
</section><section class="doc-section" id="product-boundaries"><h2>Product boundaries</h2>
|
|
153
|
+
<p>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.</p>
|
|
154
|
+
<p>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.</p>
|
|
155
|
+
<p>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.</p>
|
|
156
|
+
<p>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.</p></section>
|
|
157
|
+
<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>
|
|
158
|
+
</main>
|
|
159
|
+
</div>
|
|
160
|
+
<footer class="footer">
|
|
161
|
+
<div class="wrap">
|
|
162
|
+
<a class="brand" href="./"><img alt="" height="24" src="assets/logo.svg" width="24"/><span>VDO.Ninja <small>MCP</small></span></a>
|
|
163
|
+
<nav aria-label="Footer">
|
|
164
|
+
<a href="./">Home</a>
|
|
165
|
+
<a href="https://github.com/steveseguin/ninjamcp">GitHub</a>
|
|
166
|
+
<a href="https://www.npmjs.com/package/@vdoninja/mcp">npm</a>
|
|
167
|
+
<a href="https://discord.vdo.ninja">Discord</a>
|
|
168
|
+
<a href="https://vdo.ninja">VDO.Ninja</a>
|
|
169
|
+
</nav>
|
|
170
|
+
<span>MIT · © 2026 Steve Seguin</span>
|
|
171
|
+
</div>
|
|
172
|
+
</footer>
|
|
173
|
+
<script src="assets/site.js" defer></script>
|
|
174
|
+
</body>
|
|
175
|
+
</html>
|
package/docs/favicon.ico
ADDED
|
Binary file
|