Читать на русском | 📋 Changelog

🐝 MCP Swarm v1.2.0 — Universal AI Agent Coordination Platform

🐝 v1.2.0 — Platform Expansion: 35 Smart Tools (9 new), Vault with audit trail & auto-lock, Setup Wizard, Analytics Store, Embeddings Cascade (multi-provider), Vector Backends (6 adapters: Local, Chroma, Supabase, Qdrant, Pinecone, Turso), Auto-Index, Agent Profiles, Scheduled Tasks with pause/resume, Plugin Loader, Doctor CLI (--json), 100% ESM, full type safety. Update: npm install -g mcp-swarm@latest

MCP Swarm is a global "nervous system" for your AI assistants. It turns separate agents (Claude, Cursor, Windsurf, OpenCode) into a coordinated team that can work on massive projects without conflicts or context loss.

---

🎬 Quick Demo

┌──────────────────────────────────────────────────────────────┐
│  Claude Code (Agent 1)          Cursor (Agent 2)            │
│  ┌─────────────────────┐        ┌─────────────────────┐     │
│  │ swarm_task create    │        │ swarm_task list      │     │
│  │ "Fix auth module"    │───────▶│ → picks up task      │     │
│  │                      │        │                      │     │
│  │ swarm_file reserve   │        │ swarm_file reserve   │     │
│  │ auth.ts ✅ locked    │        │ utils.ts ✅ locked   │     │
│  │                      │        │                      │     │
│  │ swarm_chat broadcast │◄──────▶│ swarm_chat broadcast │     │
│  │ "Auth fixed!"        │        │ "Utils updated!"     │     │
│  └─────────────────────┘        └─────────────────────┘     │
│                                                              │
│  🌐 Hub (Cloudflare)  ←→  🐝 Companion (localhost:37373)   │
│  Real-time sync            Web Dashboard + Bridge            │
└──────────────────────────────────────────────────────────────┘

Open http://localhost:37373 to see the live dashboard!

---

🧠 What Is This?

When you use multiple AI tools simultaneously, they often collide: editing the same files, redoing each other's work, or simply not knowing what a colleague did five minutes ago.

MCP Swarm solves this once and for all:

1. Teamwork: Agents see each other and communicate.
2. Safety: File Locking prevents two agents from writing to the same file simultaneously.
3. Memory: Everything done today is saved in the swarm/ folder. Tomorrow, any agent picks up right where it left off.
4. Leadership: The system automatically elects an Orchestrator who assigns tasks and keeps order.

---

🛠 35 Smart Tools: The Swarm Toolkit

In v1.2.1, we expanded to 35 Smart Tools (from 26 in v1.1.x) — 9 new tools for secrets, analytics, embeddings, vector backends, auto-indexing (Drift-Memory), agent profiles, scheduled tasks, and plugins. Each tool uses an action parameter to expose multiple operations.

🚀 Core System (2)

#	Tool	Includes	Key Actions
1	swarm_agent	agent + companion	register, whoami, init, status, stop, pause, resume
2	swarm_control	control + pulse	stop, resume, status, pulse_update, pulse_get

📋 Task & Plan Management (2)

#	Tool	Includes	Key Actions
3	swarm_task	task + briefing	create, list, update, decompose, save_briefing, load_briefing
4	swarm_plan	plan + spec	create, add, next, start, complete, prompt, export, spec_start, spec_phase

🔒 Files & Git (3)

#	Tool	Includes	Key Actions
5	swarm_file	file + snapshot	reserve, release, list, forecast, snapshot_create, snapshot_rollback
6	swarm_worktree	worktree + hooks	create, list, remove, hook_install, hook_run
7	swarm_git	git + dependency	sync, pr, health, cleanup, dep_signal, dep_sync

💬 Collaboration (4)

#	Tool	Includes	Key Actions
8	swarm_chat	chat + review	broadcast, dashboard, thought, request, respond
9	swarm_voting	voting + auction	start, vote, list, auction_announce, auction_bid
10	swarm_orchestrator	orchestrator	elect, info, heartbeat, resign, executors
11	swarm_message	message + mcp	send, inbox, ack, reply, mcp_scan, mcp_authorize

🛡️ Security (1)

#	Tool	Includes	Key Actions
12	swarm_defence	defence + immune + consensus	scan, validate_agent, quarantine, trust, alert, join, elect, propose, vote

📊 Analytics (3)

#	Tool	Includes	Key Actions
13	swarm_budget	cost + budget	log, agent, project, limit, analyze, recommend, route
14	swarm_moe	moe + sona	moe_route, moe_feedback, moe_experts, sona_route, sona_learn, sona_specialists
15	swarm_quality	quality + regression	run, report, threshold, pr_ready, baseline, check_regression

🧠 Intelligence (4)

#	Tool	Includes	Key Actions
16	swarm_vector	HNSW search	init, add, search, get, delete, duplicates, embed
17	swarm_booster	fast executor	execute, can_boost, stats, history, types
18	swarm_brain	brainstorm + debug	bs_start, bs_ask, bs_propose, dbg_start, dbg_hypothesis, dbg_fix
19	swarm_context	context + pool + batch	estimate, compress, pool_add, pool_search, batch_queue, batch_result

🏗️ Infra (7)

#	Tool	Includes	Key Actions
20	swarm_health	health + preemption	check, dead, reassign, trigger, resolve_urgent
21	swarm_external	external + platform	enable_github, sync_all, create_issue, platform_request
22	swarm_expertise	expertise + routing	track, suggest, experts, route_find_agent, route_auto_assign
23	swarm_knowledge	knowledge + docs + advice	archive, search, doc_generate, advice_request
24	swarm_session	session + timeline + screenshot	start, log, stop, replay, timeline_generate, screenshot_share
25	swarm_clusters	clusters + conflict	init, list, find, conflict_predict, conflict_hotspots
26	swarm_telegram	telegram + qa	setup, send, notify_*, qa_start, qa_iterate, qa_report

🆕 New in v1.2.0 (8)

#	Tool	Description	Key Actions
27	swarm_vault	Secret management (AES-256-GCM)	init, unlock, set, get, delete, list, rotate, export, import, lock, status, audit
28	swarm_analytics	Task/event metrics & storage	log_task, log_event, get_tasks, get_events, get_metrics, summary, cleanup
29	swarm_memory	Drift-Memory (Co-occurrence) + Context	index_*, smart_*, cograph_record, cograph_query, cograph_drift, cograph_suggest
30	swarm_embeddings	Multi-provider embeddings + backends	embed, health, costs, backend_status, backend_migrate, backend_switch, backend_health
31	swarm_profiles	Agent profiles & specialization	get, list, default, instructions
32	swarm_scheduler	Cron-based task scheduler	add, list, check_due, check_missed, remove
33	swarm_plugins	Plugin loader & discovery	discover, load, load_all, init_dir
34	swarm_github	GitHub Issue ↔ Task sync	auth_status, list_issues, create_issue, close_issue, sync_from_github
35	swarm_setup	Setup wizard & config	wizard_prompt, wizard_run, config_get, config_exists

---

Usage Examples

🧠 swarm_moe — AI Model Routing (includes SONA)

// Route a task to the best model (21 experts)
swarm_moe({
  action: "moe_route",
  content: "Write a React component for user auth",
  preferredTier: "premium",
  maxCost: 0.05,
  repoPath
})
// → { selectedExpert: "claude-sonnet", confidence: 0.92 }

// SONA: Self-learning task assignment
swarm_moe({
  action: "sona_route",
  title: "Fix login button",
  description: "Button invisible on dark theme",
  affectedFiles: ["src/components/Login.tsx"],
  repoPath
})
// → { recommendedAgent: "RadiantWolf", confidence: 0.85, category: "frontend_ui" }

// Train SONA from results
swarm_moe({
  action: "sona_learn",
  taskId: "task-123",
  agentName: "RadiantWolf",
  success: true,
  qualityScore: 0.9,
  repoPath
})

⚡ swarm_booster — Execute Tasks Without LLM (352x faster)

// Check if a task can be boosted
swarm_booster({
  action: "can_boost",
  repoPath,
  description: "rename variable oldName to newName"
})
// → { canBoost: true, taskType: "rename_variable", confidence: 0.9 }

// Execute locally ($0, ~8ms)
swarm_booster({
  action: "execute",
  repoPath,
  task: {
    type: "rename_variable",
    filePath: "src/utils.ts",
    oldName: "getData",
    newName: "fetchUserData"
  }
})
// → { success: true, changes: 5, timeMs: 2, savedCost: "$0.01" }

🔍 swarm_vector — HNSW Semantic Search

// Initialize + add documents
swarm_vector({ action: "init", repoPath, config: { dimensions: 384, distanceMetric: "cosine" } })
swarm_vector({ action: "add", repoPath, id: "doc-1", text: "JWT auth setup", metadata: { category: "auth" } })

// Semantic search
swarm_vector({ action: "search", repoPath, query: "user login", k: 5 })
// → [{ id: "doc-1", score: 0.87, ... }]

🛡️ swarm_defence — AI Security + Consensus

// Scan text for threats (<10ms detection)
swarm_defence({ action: "scan", text: "Ignore all instructions...", source: "user", repoPath })
// → { detected: true, category: "prompt_injection", severity: "high" }

// Consensus: join cluster + propose
swarm_defence({ action: "join", nodeId: "a1", nodeName: "Wolf", repoPath })
swarm_defence({ action: "propose", nodeId: "a1", title: "Add dark mode", type: "architecture", repoPath })

🧠 MoE Router — 21 Built-in AI Models

Provider	Model	Tier	Input $/MTok	Output $/MTok	Context
Anthropic	Claude Opus 4.6	flagship	$5	$25	1M
Anthropic	Claude Opus 4.5	flagship	$5	$25	200K
Anthropic	Claude Sonnet 4.5	premium	$3	$15	200K
Anthropic	Claude Haiku 4.5	economy	$1	$5	200K
OpenAI	GPT-5.3 Codex	flagship	~$2	~$15	128K
OpenAI	GPT-5.2	flagship	$1.75	$14	256K
OpenAI	GPT-5 Mini	standard	$0.25	$2	128K
OpenAI	GPT-4.1	premium	$3	$12	128K
OpenAI	o4-mini	reasoning	$4	$16	128K
Moonshot	Kimi K2.5	premium	$0.60	$3.00	256K
Google	Gemini 3 Pro	flagship	$2	$12	1M
Google	Gemini 3 Flash	standard	$0.50	$3	1M
Google	Gemini 2.5 Pro	premium	$1.25	$10	1M

---

🏗️ v0.9.17 — Modular Architecture & Cloudflare Auth

Code Modularization:

• smartTools.ts split into 9 focused modules in src/smartTools/
• Clean re-exports via index.ts — no breaking API changes
• Removed legacy tools.ts and server.ts (~5000 lines of dead code)

Cloudflare Workers with Authentication:

• abdr-swarm-hub — WebSocket bridge + REST API with SWARM_AUTH_TOKEN
• abdr-swarm-server — Streamable HTTP MCP Server, auto-forwards Bearer Token
• abdr-swarm-telegram — Bot with protected /register endpoint

CI/CD Pipeline:

• GitHub Actions: main + develop branches
• TypeScript check (tsc --noEmit) before build
• Node.js matrix: 18, 20, 22
• Auto npm publish on main push

---

📊 v0.9.12 — Real-time Dashboard & Enhanced Controls

Dashboard WebSocket Widgets:

• ConnectionStatusWidget — Live Hub connection status with reconnect button
• ActivityTimelineWidget — Real-time Swarm event stream
• FileLocksWidget — Active file locks with live updates
• CostTrackingWidget — API usage and budget progress
• VotingWidget — Real-time proposals and voting

Dashboard WebSocket Setup:

# In dashboard/.env
NEXT_PUBLIC_HUB_URL=wss://mcp-swarm-hub.YOUR-SUBDOMAIN.workers.dev

Telegram Code Reviews (NEW):

• /reviews — List pending code reviews with inline approve/reject buttons
• /approve [id] — Approve a review directly from Telegram
• /reject [id] [reason] — Reject a review with a reason

Example:

You: /reviews

Bot: 📋 Pending Code Reviews:

1. 🔵 Review #abc123
   Files: src/utils.ts, src/index.ts
   Author: RadiantWolf
   Created: 2 hours ago
   
   [✅ Approve] [❌ Reject]

You: /approve abc123
Bot: ✅ Review abc123 approved!

Auto-start Companion + Bridge (v1.0.5): When launching mcp-swarm-remote, it automatically:

1. Starts the companion daemon
2. Passes MCP_SERVER_URL so the bridge auto-connects
3. All 26 smart tools work through the bridge (was only 3 in v1.0.4)

# Everything starts automatically — bridge included!
npx -y -p mcp-swarm mcp-swarm-remote --url https://your-server.workers.dev/mcp

# Disable auto-start if needed
npx -y -p mcp-swarm mcp-swarm-remote --url https://... --no-companion

How the Remote Bridge works (v1.0.5):

IDE → mcp-swarm-remote → HTTP POST → Cloudflare Worker
                                          ↓ toolNeedsBridge("swarm_*") = true
                                     WebSocket → Companion (local)
                                          ↓ executeLocalTool()
                                     allSmartTools handler(args)
                                          ↓ result
                                     WebSocket ← Companion
                                          ↓
IDE ← mcp-swarm-remote ← HTTP response ← Cloudflare Worker

Companion runs on port 37373 and provides:

• Full bridge — all 26 tools × all actions via local filesystem
• Auto-reconnect on disconnect
• Health checks on /health endpoint

---

🔄 Swarm Lifecycle

1. Getting Started (New or Existing Project)

Open your project and say: "Use MCP Swarm. Register and become the orchestrator if you're first." The first agent calls register and elect.

• New project: The server auto-creates rule files (CLAUDE.md, GEMINI.md, etc.) and folders.
• Existing Swarm project: The server picks up history from the swarm/ folder.

2. Orchestrator — The Heart of the System

The first agent that becomes Orchestrator enters an infinite loop. It:

• Never goes silent.
• Constantly monitors PULSE.md.
• Distributes incoming tasks.
• Only sleeps when a human hits "Stop."

3. The Next Morning

When you shut down your computer, the state is saved in Git/Files. In the morning, the first launched agent checks: "Is there a live Orchestrator?" If not — it takes the role, reads yesterday's tasks, and continues coordinating the team. History is never reset.

---

🔄 Upgrading from Previous Versions

If you installed MCP Swarm via npm:

npm install -g mcp-swarm@latest

If you cloned the repository:

cd /path/to/Swarm_MCP
git pull
npm install
npm run build

🙏 We apologize for the Zod compatibility issue in v0.9.14–0.9.15. The zod@^3.23.8 semver range resolved to v3.25.76 (Zod v4 bridge), which removed the internal _parse() method used by IDE clients for schema validation, breaking all 54 Smart Tools.

---

⚙️ Installation

🚀 One-Click Install (Recommended)

Windows (PowerShell):

irm https://raw.githubusercontent.com/AbdrAbdr/MCP-Swarm/main/install.ps1 | iex

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/AbdrAbdr/MCP-Swarm/main/install.sh | bash

The installer automatically:

• ✅ Checks/installs Node.js
• ✅ Finds your IDEs (Claude Desktop, Cursor, Windsurf, OpenCode, VS Code)
• ✅ Asks for your Telegram ID for notifications
• ✅ Adds config (without overwriting existing MCP servers!)

---

📦 Alternative: via npx

If Node.js is already installed:

npx mcp-swarm-install

Or with parameters:

npx mcp-swarm-install --telegram-user-id YOUR_TELEGRAM_ID --auto-install --yes

---

🔧 Manual Installation

Clone and build

# Windows
git clone https://github.com/AbdrAbdr/MCP-Swarm.git C:/MCP/Swarm_MCP
cd C:/MCP/Swarm_MCP && npm install && npm run build

# macOS
git clone https://github.com/AbdrAbdr/MCP-Swarm.git ~/Documents/Swarm_MCP
cd ~/Documents/Swarm_MCP && npm install && npm run build

# Linux
git clone https://github.com/AbdrAbdr/MCP-Swarm.git ~/mcp/Swarm_MCP
cd ~/mcp/Swarm_MCP && npm install && npm run build

IDE Configuration

🖥️ Claude Desktop

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-swarm": {
      "command": "node",
      "args": ["C:/MCP/Swarm_MCP/dist/serverSmart.js"],
      "env": {
        "SWARM_HUB_URL": "wss://mcp-swarm-hub.YOUR-SUBDOMAIN.workers.dev/ws",
        "SWARM_PROJECT": "default",
        "TELEGRAM_USER_ID": "YOUR_TELEGRAM_USER_ID",
        "TELEGRAM_BOT_URL": "https://YOUR-TELEGRAM-BOT.workers.dev"
      }
    }
  }
}

🎯 Cursor

Settings → Features → MCP Servers → Add New

Or create .cursor/mcp.json in your home directory:

{
  "mcpServers": {
    "mcp-swarm": {
      "command": "node",
      "args": ["C:/MCP/Swarm_MCP/dist/serverSmart.js"],
      "env": {
        "SWARM_HUB_URL": "wss://mcp-swarm-hub.YOUR-SUBDOMAIN.workers.dev/ws",
        "SWARM_PROJECT": "default",
        "TELEGRAM_USER_ID": "YOUR_TELEGRAM_USER_ID",
        "TELEGRAM_BOT_URL": "https://YOUR-TELEGRAM-BOT.workers.dev"
      }
    }
  }
}

🌊 Windsurf

Cascade → Settings → MCP Servers → Add Server

Or create ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "mcp-swarm": {
      "command": "node",
      "args": ["C:/MCP/Swarm_MCP/dist/serverSmart.js"],
      "env": {
        "SWARM_HUB_URL": "wss://mcp-swarm-hub.YOUR-SUBDOMAIN.workers.dev/ws",
        "SWARM_PROJECT": "default",
        "TELEGRAM_USER_ID": "YOUR_TELEGRAM_USER_ID",
        "TELEGRAM_BOT_URL": "https://YOUR-TELEGRAM-BOT.workers.dev"
      }
    }
  }
}

💻 OpenCode CLI

Create ~/.opencode/mcp.json:

{
  "mcpServers": {
    "mcp-swarm": {
      "command": "node",
      "args": ["C:/MCP/Swarm_MCP/dist/serverSmart.js"],
      "env": {
        "SWARM_HUB_URL": "wss://mcp-swarm-hub.YOUR-SUBDOMAIN.workers.dev/ws",
        "SWARM_PROJECT": "default",
        "TELEGRAM_USER_ID": "YOUR_TELEGRAM_USER_ID",
        "TELEGRAM_BOT_URL": "https://YOUR-TELEGRAM-BOT.workers.dev"
      }
    }
  }
}

🤖 VS Code + Copilot/Continue

Create .vscode/mcp.json in your home directory:

{
  "servers": {
    "mcp-swarm": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/MCP/Swarm_MCP/dist/serverSmart.js"],
      "env": {
        "SWARM_HUB_URL": "wss://mcp-swarm-hub.YOUR-SUBDOMAIN.workers.dev/ws",
        "SWARM_PROJECT": "default",
        "TELEGRAM_USER_ID": "YOUR_TELEGRAM_USER_ID",
        "TELEGRAM_BOT_URL": "https://YOUR-TELEGRAM-BOT.workers.dev"
      }
    }
  }
}

⚠️ Important: Replace C:/MCP/Swarm_MCP with the actual path to your cloned repository!

• Windows: C:/MCP/Swarm_MCP
• macOS: /Users/USERNAME/Documents/Swarm_MCP
• Linux: /home/USERNAME/mcp/Swarm_MCP

---

☁️ Installation (Remote — No Local Files)

Now uses Streamable HTTP transport instead of SSE for Cloudflare Workers compatibility!

🆓 Cloudflare Workers — IT'S FREE!

MCP Swarm uses Cloudflare Workers for cloud infrastructure. You don't need to pay anything!

Free Tier limits (more than enough for personal use):

Resource	Free Limit	For MCP Swarm
Workers Requests	100,000 / day	~1000 agents/day
Durable Objects Requests	1,000,000 / month	Enough for a large team
Durable Objects Storage	1 GB	Years of message history
WebSocket Messages	Unlimited	∞
CPU Time	10ms / request	Sufficient

💡 For reference: If you work 8 hours a day with 5 agents, you use ~5% of the free limit.

Step 1: Create a Cloudflare Account (free)

1. Go to dash.cloudflare.com
2. Sign up (email + password)
3. Verify your email
4. Done! No credit card needed.

Step 2: Deploy Your Infrastructure

# 1. Clone the repository
git clone https://github.com/AbdrAbdr/MCP-Swarm.git
cd Swarm_MCP

# 2. Log in to Cloudflare (opens browser)
npx wrangler login

# 3. Deploy the Hub (agent coordination)
cd cloudflare/hub
npx wrangler deploy
# ✅ Note the URL: wss://mcp-swarm-hub.YOUR-SUBDOMAIN.workers.dev/ws

# 4. Deploy the MCP Server
cd ../mcp-server
# Open wrangler.toml and replace HUB_URL with your Hub URL from step 3
npx wrangler deploy
# ✅ Note the URL: https://mcp-swarm-server.YOUR-SUBDOMAIN.workers.dev/mcp

Step 3: Telegram Bot (Optional but Recommended)

Get real-time notifications about tasks, agents, errors, and code reviews in Telegram.

Where each Telegram credential goes:

Credential	Where to store	How to get
TELEGRAM_USER_ID	mcp_config.json → env	Send /start to @userinfobot
TELEGRAM_BOT_URL	mcp_config.json → env	URL of your deployed bot worker
TELEGRAM_BOT_TOKEN	Cloudflare Secret (via CLI)	Create bot in @BotFather
Bot Username	Nowhere — Telegram only	Set during creation in @BotFather

⚠️ Security: TELEGRAM_BOT_TOKEN is a secret — it goes into Cloudflare via npx wrangler secret put, never into mcp_config.json or any config file!

3.1: Get your Telegram User ID

1. Open Telegram
2. Search for @userinfobot or go to t.me/userinfobot
3. Press Start
4. Copy the User ID (a number like 123456789)

3.2: Create a bot via @BotFather

1. Open Telegram, find @BotFather
2. Send /newbot
3. Choose a display name (e.g. "My Swarm Bot")
4. Choose a username (e.g. @MySwarmbotBot) — this is the bot username, used only to find the bot in Telegram
5. Copy the bot token (looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

3.3: Deploy the Telegram bot worker

cd cloudflare/telegram-bot

Set the Hub URL in wrangler.toml:

[vars]
SWARM_HUB_URL = "wss://mcp-swarm-hub.YOUR-SUBDOMAIN.workers.dev/ws"

Store the bot token as a Cloudflare secret:

npx wrangler secret put TELEGRAM_BOT_TOKEN
# Paste the token from step 3.2 and press Enter
# ⚠️ This stores the token SECURELY in Cloudflare, NOT in any file

Deploy the worker:

npx wrangler deploy
# ✅ Note the URL: https://mcp-swarm-telegram.YOUR-SUBDOMAIN.workers.dev

3.4: Set up the webhook

# Option A: Use the simplified setup endpoint
curl https://mcp-swarm-telegram.YOUR-SUBDOMAIN.workers.dev/setup

# Option B: Manual webhook (replace YOUR_TOKEN)
curl "https://api.telegram.org/botYOUR_TOKEN/setWebhook?url=https://mcp-swarm-telegram.YOUR-SUBDOMAIN.workers.dev/webhook"

3.5: Open the bot in Telegram

Find your bot by username (e.g. @MySwarmbotBot), press Start, and verify it responds.

Available commands:

Command	Description
/start	Main menu + your User ID
/projects	List registered projects
/status	Active project status
/agents	Connected agents
/tasks	Current tasks
/new	Create a new task
/logs	View recent event logs
/myid	Your Telegram User ID

v1.1.5 Interactive Features:

• 💬 Free text → Task creation — just type a task description, the bot will ask to confirm
• 🤖 AI Intent Matching — type "статус" or "status" and get instant response without commands
• 📊 Mini App Dashboard — real-time WebSocket dashboard inside Telegram
• 🔔 Push Notifications — Hub automatically notifies about task events, agent deaths, swarm stop/resume
• ⏹ Stop/Resume — control the swarm directly from Telegram buttons
• 📋 Inline Task Management — view details, mark done, cancel, change priority via buttons

📱 For more details, see TELEGRAM.md.

Step 4: Configure Your IDE

Option A: Remote (recommended)

{
  "mcpServers": {
    "mcp-swarm": {
      "command": "npx",
      "args": [
        "-y", "-p", "mcp-swarm",
        "mcp-swarm-remote",
        "--url", "https://mcp-swarm-server.YOUR-SUBDOMAIN.workers.dev/mcp"
      ],
      "env": {
        "SWARM_HUB_URL": "wss://mcp-swarm-hub.YOUR-SUBDOMAIN.workers.dev/ws",
        "TELEGRAM_USER_ID": "YOUR_TELEGRAM_USER_ID",
        "TELEGRAM_BOT_URL": "https://YOUR-TELEGRAM-BOT.workers.dev"
      }
    }
  }
}

💡 npx -y -p mcp-swarm automatically downloads the latest version from npm (currently 1.0.5).

What happens when Remote starts:

1. npx downloads mcp-swarm@latest from npm
2. mcp-swarm-remote starts → checks if companion is running
3. If not → starts companion with:
   • MCP_SERVER_URL (from --url) → Bridge auto-connects to your Worker
   • SWARM_HUB_URL (from env)   → WebSocket to Hub for coordination
4. Companion starts:
   • Bridge → WebSocket → MCP Server Worker (executes 26 tools locally)
   • Hub    → WebSocket → Hub Worker (real-time agent sync)
5. All 26 smart tools work! ✅

---

Option B: Local with Hub

{
  "mcpServers": {
    "mcp-swarm": {
      "command": "node",
      "args": ["C:/path/to/Swarm_MCP/dist/serverSmart.js"],
      "env": {
        "SWARM_HUB_URL": "wss://mcp-swarm-hub.YOUR-SUBDOMAIN.workers.dev/ws",
        "TELEGRAM_USER_ID": "YOUR_TELEGRAM_USER_ID",
        "TELEGRAM_BOT_URL": "https://YOUR-TELEGRAM-BOT.workers.dev"
      }
    }
  }
}

What happens when Local starts:

1. Node.js runs serverSmart.js directly (no npm download)
2. MCP server starts as stdio process → IDE connects via stdin/stdout
3. All 26 tools execute locally — no bridge needed
4. Hub connection (optional) → real-time sync between agents

---

🔄 Comparison

Feature	Remote (A)	Local (B)
Install	npx auto-downloads latest	git clone && npm build
Tools	26 via Bridge	26 directly
Multi-PC	✅ Works from any machine	❌ Only where installed
Updates	✅ Auto (npx latest)	Manual (git pull && build)
Offline	❌ Needs internet	✅ Works offline
Latency	~50–100ms	<10ms

❓ What is YOUR-SUBDOMAIN?

When you deploy a Worker, Cloudflare automatically creates a URL:

https://mcp-swarm-hub.myaccount.workers.dev
                      ^^^^^^^^^
                      This is your subdomain (account name)

You'll see it in the output of npx wrangler deploy.

📖 Detailed documentation: REMOTE.md

---

🆔 Smart Project ID

MCP Swarm automatically determines a unique ID for each project:

┌─────────────────────────────────────────────────────────────┐
│                    getProjectId(repoPath)                    │
├─────────────────────────────────────────────────────────────┤
│  1. SWARM_PROJECT env?  ──────► Use explicitly set value    │
│           ↓ no                                               │
│  2. git remote origin?  ──────► "github_user_repo"          │
│           ↓ no                                               │
│  3. Folder name + hash  ──────► "MCP0_a1b2c3"               │
└─────────────────────────────────────────────────────────────┘

Examples:

• https://github.com/user/my-repo.git → github_user_my-repo
• C:\Users\user\Desktop\MCP\MCP0 → MCP0_a1b2c3
• SWARM_PROJECT="custom-id" → custom-id

This ensures agents from different projects don't end up in the same Hub room.

---

🚀 How to Get Started?

Simply tell any agent in any project:

"Use MCP Swarm. Register and become the orchestrator if you're first."

The magic happens from there. 🐝

---

📱 Telegram Bot — Setup

MCP Swarm supports Telegram notifications via your own bot.

Creating a Bot

1. Open Telegram and find @BotFather
2. Send /newbot and follow the instructions
3. Copy the token (looks like 123456789:ABCdef...)
4. Deploy cloudflare/telegram-bot (see instructions above)

Getting Your User ID

1. Open your bot in Telegram
2. Send /start
3. The bot will show your User ID (a number, e.g. 987654321)

Add User ID to Configuration

For local MCP:

Windows (PowerShell)

$env:TELEGRAM_USER_ID = "987654321"

macOS / Linux

export TELEGRAM_USER_ID="987654321"

In MCP config

{
  "mcpServers": {
    "mcp-swarm": {
      "command": "node",
      "args": ["C:/MCP/Swarm_MCP/dist/serverSmart.js"],
      "env": {
        "SWARM_HUB_URL": "wss://mcp-swarm-hub.YOUR-SUBDOMAIN.workers.dev/ws",
        "TELEGRAM_USER_ID": "987654321"
      }
    }
  }
}

For Remote MCP:

Add telegram_user_id to the URL:

{
  "mcpServers": {
    "mcp-swarm": {
      "url": "https://mcp-swarm-server.YOUR-SUBDOMAIN.workers.dev/mcp/sse?telegram_user_id=YOUR_USER_ID",
      "transport": "sse"
    }
  }
}

Step 3: Launch MCP and Verify

1. Open your project in your IDE
2. Register an agent: swarm_agent({ action: "register", repoPath })
3. The project will automatically appear in the Telegram bot
4. In the bot, press "📂 My Projects" or send /projects
5. Select a project to view its status

🔔 Notifications

The bot sends notifications about:

• 📋 Task creation/completion
• 🤖 Agent joining/disconnection
• 🚨 CI/CD errors
• 👀 Review requests
• 🗳 Votes

⌨️ Bot Commands

Command	Description
/start	Show User ID and instructions
/projects or /link	List your projects
/status	Current project status
/agents	List of agents
/tasks	List of tasks
/reviews	List pending code reviews (v0.9.12)
/approve [id]	Approve code review (v0.9.12)
/reject [id] [reason]	Reject code review (v0.9.12)
/stop	Stop Swarm
/resume	Resume

🔘 Inline Buttons

All notifications come with interactive buttons:

• Claim — take a task
• View — see details
• Approve/Reject — approve/reject a review
• Vote — vote on a decision
• Priority — set priority (🔴Critical, 🟠High, 🟡Medium)

---

🔧 Troubleshooting

❌ "Cannot find module" or "Error: ENOENT"

1. Make sure the project is built:

   cd /path/to/Swarm_MCP
   npm run build

2. Verify the path in your config points to dist/serverSmart.js
3. Use an absolute path (not ./ or ~)

❌ Agent doesn't become orchestrator

An orchestrator may already be active. Check:

cat .swarm/ORCHESTRATOR.json

If lastHeartbeat is older than 60 seconds, the next agent will automatically take the role.

To force a change: delete .swarm/ORCHESTRATOR.json or call swarm_orchestrator({ action: "resign", repoPath }).

❌ "repoPath is required" error

EVERY MCP Swarm call must include repoPath:

// ✅ Correct
swarm_agent({ action: "register", repoPath: "C:/projects/my-app" })

// ❌ Wrong
swarm_agent({ action: "register" })

❌ Cloudflare Hub unavailable

1. Check your internet connection
2. Make sure your Hub is deployed and the URL is correct
3. The system automatically falls back to local Git when Hub is unavailable

❌ swarm/ folder not created automatically

On first call to swarm_agent({ action: "register", repoPath }), the swarm/ folder and all rule files should be created automatically.

If it doesn't work — call manually:

swarm_agent({ action: "init", repoPath: "/path/to/project" })

❌ Files locked by another agent

Check who holds the lock:

swarm_file({ action: "list", repoPath: "/path/to/project" })

If an agent is "dead" (heartbeat > 60 sec), the system will automatically release the files.

---

📊 Architecture

Cloudflare Workers (Your endpoints after deployment)

Worker	URL (example)	Purpose
Hub	wss://mcp-swarm-hub.YOUR-SUBDOMAIN.workers.dev/ws	Agent coordination
MCP Server	https://mcp-swarm-server.YOUR-SUBDOMAIN.workers.dev/mcp	Remote MCP (HTTP)
Telegram Bot	https://mcp-swarm-telegram.YOUR-SUBDOMAIN.workers.dev	Notifications

Diagram

┌─────────────────────────────────────────────────────────────┐
│                  CLOUDFLARE WORKERS                         │
│                                                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐  │
│  │   Hub (DO)      │  │  MCP Server     │  │  Telegram   │  │
│  │   /ws           │◄─│  /mcp (HTTP)    │  │  /webhook   │  │
│  │   /api/*        │  │  (Streamable)   │  │             │  │
│  └─────────────────┘  └─────────────────┘  └─────────────┘  │
│                               │                             │
└───────────────────────────────┼─────────────────────────────┘
                                │ WebSocket
          ┌─────────────────────┼─────────────────────┐
          ▼                     ▼                     ▼
    ┌──────────┐          ┌──────────┐          ┌──────────┐
    │ Windows  │          │   Mac    │          │  Linux   │
    │ (Cursor) │          │(Windsurf)│          │(OpenCode)│
    │          │          │          │          │          │
    │ Companion│          │ Companion│          │ Companion│
    │ + Bridge │          │ + Bridge │          │ + Bridge │
    └──────────┘          └──────────┘          └──────────┘
          │                     │                     │
          └─────────────────────┼─────────────────────┘
                                ▼
                    ┌─────────────────────┐
                    │   YOUR PROJECT      │
                    │   /path/to/project  │
                    │                     │
                    │   .swarm/           │ ← State & messages
                    │   swarm/            │ ← Tasks & agents
                    │   orchestrator/     │ ← Plans & specs
                    │   CLAUDE.md         │ ← Agent rules
                    │   GEMINI.md         │
                    └─────────────────────┘

cloudflare/ structure

cloudflare/
├── hub/              # Coordination Hub (Durable Objects)
│   ├── src/index.ts  # SwarmRoom — tasks, chat, locks
│   └── wrangler.toml
│
├── mcp-server/       # Remote MCP Server (Streamable HTTP)
│   ├── src/index.ts  # MCP-over-HTTP (v0.9.11)
│   └── wrangler.toml
│
└── telegram-bot/     # Telegram Bot (Webhook)
    ├── worker.ts     # Commands: /status, /agents, /tasks
    └── wrangler.toml

---

🩺 Doctor — Health Check CLI

# Human-readable output
npx mcp-swarm-doctor

# JSON output for CI/CD pipelines
npx mcp-swarm-doctor --json

Example output:

🩺 MCP Swarm Doctor
✅ Node.js version: v23.11.1 (>= 18.0.0)
✅ Package installed: mcp-swarm@1.2.0
✅ TypeScript compiled: dist/ exists
✅ Hub URL configured: wss://mcp-swarm-hub.example.workers.dev/ws
⚠️  Telegram not configured: TELEGRAM_USER_ID is missing

JSON mode (--json) returns structured results:

[
  { "name": "node-version", "status": "pass", "message": "v23.11.1 (>= 18.0.0)" },
  { "name": "package", "status": "pass", "message": "mcp-swarm@1.2.0" },
  { "name": "telegram", "status": "warn", "message": "TELEGRAM_USER_ID is missing" }
]

---

📝 Changelog

See CHANGELOG.md

---

🤝 Contributing

PRs welcome! Core principles:

1. All tools must accept repoPath
2. State is saved to files (not memory)
3. Tests before merging

---

⭐ Support the Project

If MCP Swarm helps your team — give us a star on GitHub! ⭐

Your feedback shapes the future of the project:

• 🐛 Found a bug? — Open an Issue
• 💡 Have an idea? — Start a Discussion
• 🔧 Want to contribute? — Fork & PR

---

📜 License

MIT © 2025–2026