{"id":50510061,"url":"https://github.com/steveseguin/ninjamcp","last_synced_at":"2026-06-02T19:30:48.447Z","repository":{"id":340488478,"uuid":"1166277332","full_name":"steveseguin/ninjamcp","owner":"steveseguin","description":"Let your Ai talk to other Ais, peer-to-peer, encrypted, for free. MCP-version","archived":false,"fork":false,"pushed_at":"2026-02-25T04:28:55.000Z","size":144,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-25T09:43:50.936Z","etag":null,"topics":["claude","codex","data-channels","e2ee","mcp","openclaw","p2p"],"latest_commit_sha":null,"homepage":"https://steveseguin.github.io/ninjamcp/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/steveseguin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-25T03:52:23.000Z","updated_at":"2026-02-25T04:28:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/steveseguin/ninjamcp","commit_stats":null,"previous_names":["steveseguin/ninjamcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/steveseguin/ninjamcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveseguin%2Fninjamcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveseguin%2Fninjamcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveseguin%2Fninjamcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveseguin%2Fninjamcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/steveseguin","download_url":"https://codeload.github.com/steveseguin/ninjamcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveseguin%2Fninjamcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33834010,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","codex","data-channels","e2ee","mcp","openclaw","p2p"],"created_at":"2026-06-02T19:30:47.412Z","updated_at":"2026-06-02T19:30:48.441Z","avatar_url":"https://github.com/steveseguin.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VDO.Ninja MCP (`@vdoninja/mcp`)\n\nMCP bridge for VDO.Ninja WebRTC data channels.\n\nUse it to let AI tools (Codex, Claude Code, and compatible MCP clients) do:\n\n- bot-to-bot messaging\n- reliable file transfer\n- shared state synchronization\n\nThe package depends on `@vdoninja/sdk`, so SDK installs transitively.\n\n## Why This MCP\n\n- Open source (`AGPL-3.0-only` with additional unmodified-distribution exception) and free to use.\n- Peer-to-peer first: no central relay required for normal data flow.\n- End-to-end encrypted WebRTC data transport (DTLS + SCTP data channels).\n- Reliable data channel mode available for ordered/loss-recovered delivery.\n- Low infrastructure overhead for bot-to-bot messaging and file sync.\n- Works for local LAN, remote internet peers, and hybrid topologies.\n- TURN support improves connectivity when direct P2P is blocked.\n- Good fit for multi-agent coordination without exposing plaintext payloads to a middlebox.\n\n## Common and Interesting Use Cases\n\n- AI swarm coordination: multiple agents in a private room exchanging tasks, state, and results.\n- Bot-to-bot handoff: one agent collects context, another executes, another validates, all over P2P.\n- Private file exchange: send logs, artifacts, prompts, and generated outputs directly between agents.\n- Human + AI war room: operator plus several bots sharing near-real-time status updates.\n- Edge + cloud hybrid: local on-device agent syncs with remote agents without standing up a custom tunnel.\n- Temporary secure collaboration spaces: ad-hoc rooms with join tokens and peer allowlists.\n- Cross-tool interop: Codex and Claude instances sharing updates through the same bridge contract.\n\n## Fun Agent-to-Agent Rooms\n\nThese are real patterns teams are starting to use:\n\n- Claude Code to Codex CLI pair mode where one agent asks for a second opinion and gets patch/test feedback.\n- OpenClaw-to-OpenClaw specialist rooms where one local assistant asks another for tool-specific help.\n- Small LLM idea circles (3-5 agents) sharing proposals, critiques, and final votes.\n- Private \"night shift\" automation where bots sync status/events/files without broad network exposure.\n\nOpenClaw project link:\n\n- https://github.com/openclaw/openclaw\n\n## Quick Example: Claude + Codex Helper Loop\n\n1. Claude-side session:\n```json\n{\n  \"name\": \"vdo_connect\",\n  \"arguments\": {\n    \"room\": \"agent_help_room\",\n    \"stream_id\": \"claude_agent\"\n  }\n}\n```\n\n2. Codex-side session:\n```json\n{\n  \"name\": \"vdo_connect\",\n  \"arguments\": {\n    \"room\": \"agent_help_room\",\n    \"stream_id\": \"codex_agent\",\n    \"target_stream_id\": \"claude_agent\"\n  }\n}\n```\n\n3. Claude sends task:\n```json\n{\n  \"name\": \"vdo_send\",\n  \"arguments\": {\n    \"session_id\": \"\u003cclaude_session\u003e\",\n    \"data\": {\n      \"type\": \"help.request\",\n      \"task\": \"review patch for race condition\"\n    }\n  }\n}\n```\n\n4. Codex replies:\n```json\n{\n  \"name\": \"vdo_send\",\n  \"arguments\": {\n    \"session_id\": \"\u003ccodex_session\u003e\",\n    \"data\": {\n      \"type\": \"help.reply\",\n      \"summary\": \"found 2 edge cases\",\n      \"next_steps\": [\"add timeout guard\", \"add retry test\"]\n    }\n  }\n}\n```\n\n## High-Value AI Advantages\n\n- Agents share messages/files/state directly, without opening broad machine-to-machine network access.\n- You can limit tool access with profiles (`core|file|state|full`) so each agent only gets what it needs.\n- Rooms can be short-lived: create for a task, then close when done.\n- Easy to start: no private subnet setup, no custom tunnel setup.\n- Works between browser peers and Node peers.\n- Data channels can be reliable and ordered, which is good for control messages.\n- Security options are built in: join tokens, stream allowlists, and session MAC checks.\n\n## Clever Real-World Patterns\n\n- Reviewer team: one writer agent, several reviewer agents, and one decider agent sharing feedback in the same room.\n- State recovery: agents can re-sync shared state with `vdo_state_sync` after reconnects.\n- File pipeline: one agent sends artifacts, another indexes them, another summarizes them.\n- Human override: a person can join the room to inspect progress and step in when needed.\n- Local-first flow: keep sensitive work local and only send required outputs to remote agents.\n- Burst jobs: create short-lived agent groups per task instead of running a permanent private network.\n\n## Compared with VPN Overlays (e.g., Tailscale)\n\nWhere this MCP is often better for AI workflows:\n\n- You need agent-to-agent messaging/file/state, not full network access between hosts.\n- You want tool-level permissions instead of giving every machine broad private-network reach.\n- You want browser and Node agents working together quickly.\n- You want temporary collaboration sessions without managing a permanent virtual network.\n\nWhere overlays are often better:\n\n- You need always-on private IP connectivity across many services.\n- You need many protocols (databases, SSH, internal web apps) over one virtual network.\n- You need centralized network policy and audit at the infrastructure layer.\n\nPractical framing:\n\n- This MCP is not a full replacement for Tailscale.\n- It is a strong complement for AI-native, data-channel-first collaboration.\n\n## Transport Truth\n\n- This is **WebRTC data transport**, not a generic TCP/SSH tunnel.\n- Data channels can run in reliable/ordered mode (SCTP over DTLS).\n- Default behavior is direct P2P when possible (great for LAN/local-network speed and low latency).\n- Privacy mode is opt-in via `force_turn=true`: this can reduce direct IP exposure between peers, but may reduce connection success in some environments.\n- TURN improves success on restrictive networks, but it is not a guaranteed firewall bypass for every enterprise policy.\n\n## Quickstart (No Clone)\n\nInstall from a stable folder. The installer stores an absolute script path in Codex/Claude config.\n\n```bash\nnpm i @vdoninja/mcp @roamhq/wrtc\nnpx vdon-mcp-install\nnpx vdon-mcp-server\n```\n\nFirst MCP call (recommended):\n\n```json\n{ \"name\": \"vdo_capabilities\", \"arguments\": {} }\n```\n\nUseful install variants:\n\n- `npx vdon-mcp-install --codex-only`\n- `npx vdon-mcp-install --claude-only`\n- `npx vdon-mcp-install --preset core|file|state|secure-core|secure-full`\n- `npx vdon-mcp-install --uninstall`\n\n## Typical Workflows\n\nMessage demo:\n\n```bash\nnpx vdon-mcp-demo-message\n```\n\nFile demo:\n\n```bash\nnpx vdon-mcp-demo-file\n```\n\nLive network mode (instead of local fake mode):\n\n```bash\nMCP_DEMO_FAKE=0 npx vdon-mcp-demo-message\nMCP_DEMO_FAKE=0 npx vdon-mcp-demo-file\n```\n\nPrivacy-first relay mode (opt-in):\n\n```bash\nMCP_DEMO_FAKE=0 MCP_DEMO_FORCE_TURN=1 npx vdon-mcp-demo-message\nMCP_DEMO_FAKE=0 MCP_DEMO_FORCE_TURN=1 npx vdon-mcp-demo-file\n```\n\n## Security and Least Privilege\n\nUse secure controls where needed:\n\n- `join_token` and `join_token_secret`\n- `enforce_join_token: true`\n- `allow_peer_stream_ids: [...]`\n- `require_session_mac: true`\n\nServer profile scoping:\n\n```bash\nVDON_MCP_TOOL_PROFILE=core npx vdon-mcp-server\n```\n\nSet `VDON_MCP_JOIN_TOKEN_SECRET` before secure preset installs/runtime.\n\n## Compatibility\n\n- Codex MCP CLI\n- Claude Code MCP CLI\n- Other MCP clients that support stdio command servers\n\nManual command wiring example:\n\n```json\n{\n  \"name\": \"vdo-ninja-mcp\",\n  \"command\": \"node\",\n  \"args\": [\"node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js\"]\n}\n```\n\n## Local Development (This Repo)\n\nStart server:\n\n```bash\nnode scripts/vdo-mcp-server.js\n```\n\nInstall registration from local checkout:\n\n```bash\nnode scripts/install-mcp.js\n```\n\n## Testing\n\nFast product-focused suite:\n\n```bash\nnode tests/run-mcp-tests-minimal.js\n```\n\nFull suite:\n\n```bash\nnode tests/run-mcp-tests.js\n```\n\nLive diagnostics:\n\n```bash\nnode tests/live-turn-smoke.js\nnode tests/live-turn-soak.js\nnode tests/live-turn-matrix.js\nnode tests/live-turn-preset-matrix.js\n```\n\n## Key Files\n\n- `scripts/vdo-mcp-server.js` (stdio MCP server)\n- `scripts/vdo-mcp-streamable-http.js` (streamable HTTP bridge)\n- `scripts/install-mcp.js` (Codex/Claude installer automation)\n- `references/quickstart-and-compat.md` (operator quickstart)\n- `references/mcp-tool-contract.md` (tool semantics and contracts)\n- `server.json` (MCP discovery manifest metadata)\n\n## License\n\nAGPL-3.0-only with additional unmodified-distribution exception.\n\n- Main license text: `LICENSE`\n- Additional permission: `LICENSE-SDK-EXCEPTION`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteveseguin%2Fninjamcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteveseguin%2Fninjamcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteveseguin%2Fninjamcp/lists"}