# MSG - MCP 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

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

Optional (for browser tools):
```bash
pip install playwright
playwright install chromium
```

### 2. Run MSG

```bash
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:
```bash
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)
```javascript
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

```bash
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:
```bash
curl http://localhost:8765/api/v1/swarm/task/{task_id}
```

---

## Configuration

Edit `config.yaml`:

```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.