内容
# VDO.Ninja MCP (`@vdoninja/mcp`)
## 简介
本软件包为AI应用程序提供了一组与另一个AI应用程序通信的工具。两个Codex、Claude、Cursor或其他MCP会话可以加入同一个VDO.Ninja房间，发送消息、交换文件并保持共享任务状态，而无需您构建新的消息服务器。
如果您的AI客户端支持MCP并且您想要**它可以调用的工具**，请使用此软件包。如果您想要一个**具有本地收件箱的始终在线代理房间**，请改用[`ninja-p2p`](https://github.com/steveseguin/ninja-p2p)。
**最适合：** MCP原生代理交接、文件交付和小共享状态工作流。
**不适合：** 通用VPN、永久存储或大型公共聊天网络。
软件包：[`@vdoninja/mcp`](https://www.npmjs.com/package/@vdoninja/mcp) | [快速入门](references/quickstart-and-compat.md) | [客户端设置示例](references/client-config-examples.md) | [支持](https://discord.vdo.ninja)
## 它是什么样子
一个代理加入房间：
```json
{ "name": "vdo_connect", "arguments": { "room": "family_calendar", "stream_id": "planner" } }
```
第二个代理加入同一个房间，然后向它发送消息：
```json
{ "name": "vdo_connect", "arguments": { "room": "family_calendar", "stream_id": "reviewer", "target_stream_id": "planner" } }
{ "name": "vdo_send", "arguments": { "session_id": "<reviewer-session>", "data": { "text": "I checked the plan. Tuesday has a conflict." } } }
```
这些是正常的MCP工具调用。此服务器将它们翻译成VDO.Ninja SDK通过WebRTC数据通道的操作。
## 我需要哪个VDO.Ninja软件包？
| 您的目标 | 使用 |
| --- | --- |
| 向MCP客户端添加连接/发送/文件/状态工具 | **`@vdoninja/mcp`** |
| 为代理提供持久房间和本地收件箱 | [`@vdoninja/ninja-p2p`](https://github.com/steveseguin/ninja-p2p) |
| 直接使用WebRTC媒体或数据通道构建 | [`@vdoninja/sdk`](https://github.com/steveseguin/ninjasdk) |
此软件包使用VDO.Ninja现有的房间、发现和WebRTC行为。它不添加信令服务器命令。`@vdoninja/sdk`和Node WebRTC运行时作为软件包依赖项安装。
## 为什么选择这个MCP
- 开源（`AGPL-3.0-only`，附加未修改分发例外）和免费使用。
- 点对点优先：正常数据流不需要中央中继。
- 端到端加密WebRTC数据传输（DTLS + SCTP数据通道）。
- 可用可靠数据通道模式，用于有序/丢失恢复的交付。
- 机器人间消息和文件同步的基础设施开销低。
- 适用于本地LAN、远程互联网对等和混合拓扑。
- TURN支持在直接P2P被阻止时改善连接性。
- 适合多代理协调，而无需向中间设备暴露纯文本有效载体。
## 常见和有趣的用例
- AI集群协调：多个代理在一个私有房间中交换任务、状态和结果。
- 机器人间交接：一个代理收集上下文，另一个执行，另一个验证，所有这些都通过P2P。
- 私有文件交换：在代理之间直接发送日志、工件、提示和生成的输出。
- 人类 + AI作战室：操作员与多个机器人共享近实时状态更新。
- 边缘 + 云混合：本地设备代理与远程代理同步，无需建立自定义隧道。
- 临时安全协作空间：具有加入令牌和对等允许列表的临时房间。
- 跨工具互操作：Codex和Claude实例通过同一个桥接合约共享更新。
## 有趣的代理间房间
这些是团队开始使用的真实模式：
- Claude Code至Codex CLI配对模式，一个代理请求第二意见并获得补丁/测试反馈。
- OpenClaw至OpenClaw专家房间，一个本地助手向另一个请求特定工具帮助。
- 小型LLM创意圈（3-5个代理）共享提案、批评和最终投票。
- 私有“夜班”自动化，机器人在不暴露广泛网络的情况下同步状态/事件/文件。
OpenClaw项目链接：
- https://github.com/openclaw/openclaw
## 快速示例：Claude + Codex助手循环
1. Claude侧会话：
```json
{
"name": "vdo_connect",
"arguments": {
"room": "agent_help_room",
"stream_id": "claude_agent"
}
}
```
2. Codex侧会话：
```json
{
"name": "vdo_connect",
"arguments": {
"room": "agent_help_room",
"stream_id": "codex_agent",
"target_stream_id": "claude_agent"
}
}
```
3. Claude发送任务：
```json
{
"name": "vdo_send",
"arguments": {
"session_id": "<claude_session>",
"data": {
"type": "help.request",
"task": "review patch for race condition"
}
}
}
```
4. Codex回复：
```json
{
"name": "vdo_send",
"arguments": {
"session_id": "<codex_session>",
"data": {
"type": "help.reply",
"summary": "found 2 edge cases",
"next_steps": ["add timeout guard", "add retry test"]
}
}
}
```
## 高价值AI优势
- 代理直接共享消息/文件/状态，而无需打开广泛的机器间网络访问。
- 您可以使用配置文件（`core|file|state|full`）限制工具访问权限，以便每个代理仅获得所需的内容。
- 房间可以是短暂的：为任务创建，然后完成后关闭。
- 易于启动：无需私有子网设置，无需自定义隧道设置。
- 适用于浏览器对等和Node对等。
- 数据通道可以是可靠的和有序的，这对于控制消息很有用。
- 内置安全选项：加入令牌、流允许列表和会话MAC检查。
## 聪明的现实世界模式
- 审查团队：一个编写代理、多个审查代理和一个决策代理在同一个房间中共享反馈。
- 状态恢复：代理可以在重新连接后使用`vdo_state_sync`重新同步共享状态。
- 文件管道：一个代理发送工件，另一个索引它们，另一个总结它们。
- 人类干预：人员可以加入房间检查进度，并在需要时介入。
- 本地优先流程：保持敏感工作本地，仅向远程代理发送所需输出。
- 突发作业：为每个任务创建短暂的代理组，而不是运行永久的私有网络。
## 与VPN覆盖（例如Tailscale）比较
此MCP通常更适合AI工作流的地方：
- 您需要代理间消息/文件/状态，而不是主机之间的完全网络访问。
- 您想要工具级权限，而不是给予每个机器广泛的私有网络访问权限。
- 您希望浏览器和Node代理快速协同工作。
- 您想要临时协作会话，而无需管理永久虚拟网络。
覆盖通常更好的地方：
- 您需要跨多个服务始终在线的私有IP连接。
- 您需要一种协议（数据库、SSH、内部Web应用程序）通过一个虚拟网络。
- 您需要在基础设施层有集中式网络策略和审计。
实用框架：
- 此MCP不是Tailscale的完整替代品。
- 它是AI原生、数据通道优先协作的强大补充。
## 传输真相
- 这是 **WebRTC数据传输**，而不是通用TCP/SSH隧道。
- 数据通道可以在可靠/有序模式（SCTP over DTLS）下运行。
- 默认行为是在可能的情况下直接P2P（适用于LAN/本地网络速度和低延迟）。
- 隐私模式通过`force_turn=true`选择加入：这可以减少对等体之间的直接IP暴露，但在某些环境中可能会降低连接成功率。
- TURN改善了受限网络上的成功率，但它不是针对每个企业策略的保证防火墙绕过。
## 快速入门（无需克隆）
从稳定文件夹安装。安装程序在Codex/Claude配置中存储绝对脚本路径。
```bash
npm i @vdoninja/mcp
npx vdon-mcp-install
npx vdon-mcp-server
```
当直接在终端中启动时，`vdon-mcp-server`现在打印一个简短的“服务器运行”横幅和首次调用提示。
第一个MCP调用（推荐）：
```json
{ "name": "vdo_capabilities", "arguments": {} }
```
有用的安装变体：
- `npx vdon-mcp-install --codex-only`
- `npx vdon-mcp-install --claude-only`
- `npx vdon-mcp-install --preset core|file|state|secure-core|secure-full`
- `npx vdon-mcp-install --uninstall`
## 入门指南
- 操作员快速入门：`references/quickstart-and-compat.md`
- 客户端设置示例（Cursor、Gemini CLI、OpenCode）：`references/client-config-examples.md`
- 首次功能工作流（Codex至Codex和Claude至Claude）：`references/client-config-examples.md`
## 典型工作流
消息演示：
```bash
npx vdon-mcp-demo-message
```
目的：证明端到端房间连接+消息发送/接收通过数据通道。
文件演示：
```bash
npx vdon-mcp-demo-file
```
目的：证明可靠的分组文件传输和接收路径。
实时网络模式（代替本地伪造模式）：
```bash
MCP_DEMO_FAKE=0 npx vdon-mcp-demo-message
MCP_DEMO_FAKE=0 npx vdon-mcp-demo-file
```
隐私优先中继模式（选择加入）：
```bash
MCP_DEMO_FAKE=0 MCP_DEMO_FORCE_TURN=1 npx vdon-mcp-demo-message
MCP_DEMO_FAKE=0 MCP_DEMO_FORCE_TURN=1 npx vdon-mcp-demo-file
```
## 安全性和最小权限
在需要时使用安全控件：
- `join_token`和`join_token_secret`
- `enforce_join_token: true`
- `allow_peer_stream_ids: [...]`
- `require_session_mac: true`
服务器配置文件范围：
```bash
VDON_MCP_TOOL_PROFILE=core npx vdon-mcp-server
```
在安全预设安装/运行时设置`VDON_MCP_JOIN_TOKEN_SECRET`。
## 兼容性
- Codex MCP CLI
- Claude Code MCP CLI
- 其他支持stdio命令服务器的MCP客户端
手动命令连接示例：
```json
{
"name": "vdo-ninja-mcp",
"command": "node",
"args": ["node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"]
}
```
## 本地开发（此仓库）
启动服务器：
```bash
node scripts/vdo-mcp-server.js
```
从本地checkout安装注册：
```bash
node scripts/install-mcp.js
```
## 测试
快速产品聚焦套件：
```bash
node tests/run-mcp-tests-minimal.js
```
完整套件：
```bash
node tests/run-mcp-tests.js
```
实时诊断：
```bash
node tests/live-turn-smoke.js
node tests/live-turn-soak.js
node tests/live-turn-matrix.js
node tests/live-turn-preset-matrix.js
```
## 关键文件
- `scripts/vdo-mcp-server.js`（stdio MCP服务器）
- `scripts/vdo-mcp-streamable-http.js`（可流式HTTP桥接器）
- `scripts/install-mcp.js`（Codex/Claude安装程序自动化）
- `references/quickstart-and-compat.md`（操作员快速入门）
- `references/mcp-tool-contract.md`（工具语义和合约）
- `server.json`（MCP发现清单元数据）
## 许可证
AGPL-3.0-only，附加未修改分发例外。
- 主要许可证文本：`LICENSE`
- 附加权限：`LICENSE-SDK-EXCEPTION`
