MSG Swarm Gateway

Universal MCP Bridge + Multi-Agent Swarm Orchestrator

Turn any web-based AI (ChatGPT, Claude, Grok, Kimi, DeepSeek, Gemini) into a full-powered agent with access to your local PC, terminal, browser, and code execution - with a swarm of parallel agents validated in real-time.

---

What Makes MSG Different

Feature	MCP SuperAssistant	Other Tools	MSG
Web AI Chat Support	11 platforms	2-5	11+ platforms
Local MCP Tools	~10	Varies	33 tools, 8 categories
Multi-Agent Swarm	No	No	Yes - parallel agents
Parallel Validation	No (just pytest)	No	Review agents + pytest
Custom Skills/Plugins	No	Limited	Hot-loadable skill system
Web Dashboard	No	No	Real-time monitoring
Browser Extension	Yes	No	Yes (11 platforms)

---

Architecture

Web AI Chats (ChatGPT, Claude, Grok, Kimi, DeepSeek, Gemini...)
         |
    HTTP/WebSocket (CORS-enabled)
         |
    +----v--------------+---------------+
    |   MSG GATEWAY     |  SWARM ORCH.  |
    |   (FastAPI)       |  (Parallel)   |
    +----v--------------+---------------+
         |
    +----v--------------+
    |  MCP LOCAL TOOLS  |
    |  (33 tools)       |
    +----v--------------+
    |  Your PC          |
    |  Files, Terminal  |
    |  Browser, Code    |
    +-------------------+

---

Quick Start

1. Install Dependencies

pip install mcp[cli] fastapi uvicorn websockets pyyaml jinja2 psutil httpx

Optional (for browser tools):

pip install playwright
playwright install chromium

2. Run MSG

cd msg
python run.py

The dashboard will be available at:

• Dashboard: http://localhost:8765/dashboard
• API Docs: http://localhost:8765/docs
• Tool Explorer: http://localhost:8765/tools

3. Install Browser Extension

1. Open Chrome/Firefox extensions page
2. Enable "Developer mode"
3. Click "Load unpacked" and select the extension/ folder
4. The MSG tool panel will appear on supported AI chat sites

4. Connect Your AI Chat

Option A: Browser Extension (Recommended)

The extension automatically injects MCP tool capabilities into:

• ChatGPT (chatgpt.com)
• Claude (claude.ai)
• Grok (grok.x.ai)
• Kimi (kimi.ai)
• DeepSeek (chat.deepseek.com)
• Gemini (gemini.google.com)
• Perplexity (perplexity.ai)
• Mistral (chat.mistral.ai)
• OpenRouter (openrouter.ai)
• T3 Chat (t3.chat)

Option B: Direct API

Send tool calls directly from any app:

curl -X POST http://localhost:8765/api/v1/tools/execute_command \
  -H "Content-Type: application/json" \
  -d '{"params": {"command": "ls -la"}}'

Option C: WebSocket (Real-time)

const ws = new WebSocket('ws://localhost:8765/ws');
ws.send(JSON.stringify({
    tool: 'read_file',
    params: {path: '/path/to/file.txt'}
}));
ws.onmessage = (e) => console.log(JSON.parse(e.data));

---

33 Built-in MCP Tools

Filesystem (8)

Tool	Description
read_file	Read text file with optional offset/limit
write_file	Write or overwrite a file
append_file	Append content to a file
list_directory	List files with metadata (size, mtime)
search_files	Recursive glob search
create_directory	Create directory structure
delete_path	Delete file or directory
get_file_info	Size, modified time, permissions

Terminal (3)

Tool	Description
execute_command	Run shell command with timeout (security sandboxed)
execute_script	Run a script file
start_background_process	Start daemon process, return PID

Browser (4)

Tool	Description
browser_visit	Navigate to URL, get page content
browser_click	Click element by selector
browser_input	Fill form input
browser_screenshot	Capture page screenshot

Code Execution (3)

Tool	Description
run_python	Execute Python code in isolated subprocess
run_javascript	Execute JS via Node.js
evaluate_expression	Evaluate math/code expressions

System (4)

Tool	Description
get_system_info	CPU, RAM, disk, OS info
list_processes	Running processes
kill_process	Kill process by PID
search_web	Web search via DuckDuckGo

Git (4)

Tool	Description
git_status	Repository status
git_log	Commit history
git_diff	Current diff
git_exec	Run any git command

Docker (4)

Tool	Description
docker_ps	List containers
docker_exec	Execute in container
docker_logs	Container logs
docker_run	Run new container

Dev Tools (3)

Tool	Description
npm_install	npm install
pip_install	pip install
run_tests	Run pytest/jest

---

Swarm Orchestrator

The swarm executes complex projects with parallel validation:

1. You submit a project: "Build a Python web scraper"
2. Project Manager decomposes it into tasks
3. Code Agents (parallel) write the code
4. Review Agents (parallel) validate each batch - checking syntax, docstrings, error handling
5. Verdict: PASS / WARNING / REVISE
6. Debug Agent fixes REVISE items
7. Test Agent runs integration tests
8. Results delivered

Parallel Validation (The Key Feature)

Unlike other systems that only run pytest after code is done, MSG runs Review Agents in parallel with Code Agents. While one agent is still writing code, another is already reviewing what was just completed. This catches issues immediately, not after hours of work.

Submit a Swarm Task

curl -X POST http://localhost:8765/api/v1/swarm/task \
  -H "Content-Type: application/json" \
  -d '{"description": "Build a calculator app", "files": ["calc.py", "test_calc.py"]}'

Check status:

curl http://localhost:8765/api/v1/swarm/task/{task_id}

---

Configuration

Edit config.yaml:

gateway:
  host: "0.0.0.0"
  port: 8765

security:
  allowed_directories:
    - "/home/yourname/projects"
  blocked_commands:
    - "rm -rf /"
  max_execution_time: 30

swarm:
  max_parallel_agents: 5
  review_strictness: "strict"

---

Security

• Path sandboxing: Tools can only access allowed directories
• Command blocklist: Dangerous commands are rejected
• Execution timeouts: No infinite hangs
• Output limits: Prevents memory exhaustion
• Optional auth: Token-based API authentication

---

Tech Stack

Component	Technology
MCP Server	mcp (FastMCP) Python SDK
Gateway	FastAPI + WebSockets
Process Mgmt	asyncio + subprocess
Browser	Playwright
Message Bus	asyncio Queue
Dashboard	FastAPI + Jinja2 + vanilla JS
Extension	Vanilla JS (content script)

---

Project Stats

• 34 Python files, 3,693 lines of code
• 33 MCP tools across 8 categories
• 5 agent types in the swarm (coder, reviewer, tester, debugger + orchestrator)
• 11 AI platforms supported via browser extension
• 6 dashboard pages with real-time WebSocket updates
• 100% syntax clean - all files pass py_compile

---

License

MIT - Use it, modify it, make money with it. Go get 'em.