<p align="center">
  <img src="src/web/static/logo.svg" alt="Red Team MCP" width="120" height="120">
</p>

<h1 align="center">Red Team MCP</h1>

<p align="center">
  <strong>Assemble elite AI agent teams to tackle any challenge</strong>
</p>

<p align="center">
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-features">Features</a> •
  <a href="#-multi-agent-coordination">Multi-Agent</a> •
  <a href="#-mcp-integration">MCP Integration</a> •
  <a href="#-api-reference">API</a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/providers-68-red" alt="68 Providers">
  <img src="https://img.shields.io/badge/models-1500+-red" alt="1500+ Models">
  <img src="https://img.shields.io/badge/python-3.10+-blue" alt="Python 3.10+">
  <img src="https://img.shields.io/badge/license-AGPL--3.0-blue" alt="AGPL-3.0 License">
</p>

---

Red Team MCP is a multi-agent collaboration platform that connects to **68 providers and 1500+ models** via [models.dev](https://models.dev). Build specialized agent teams, coordinate complex workflows, and integrate seamlessly with VS Code and Claude Desktop through the Model Context Protocol (MCP).

## ✨ Features

<table>
<tr>
<td width="50%">

### 🎯 Universal Model Access

- **68 Providers**: Anthropic, OpenAI, Google, Groq, Mistral, DeepSeek, and 60+ more
- **1500+ Models**: Auto-synced from models.dev
- **Unified API**: One interface for all providers

</td>
<td width="50%">

### 🤖 Multi-Agent Collaboration

- **5 Coordination Modes**: Pipeline, Ensemble, Debate, Swarm, Hierarchical
- **Predefined Teams**: Writing, Marketing, Research, Technical, Executive
- **Custom Teams**: Build your own agent configurations

</td>
</tr>
<tr>
<td width="50%">

### 📡 MCP Integration

- **VS Code Ready**: Works with GitHub Copilot
- **Claude Desktop**: Native integration
- **Dynamic Tools**: All agents exposed as MCP tools

</td>
<td width="50%">

### 🚀 Production Ready

- **FastAPI Backend**: High-performance async API
- **Web Dashboard**: HTMX-powered admin interface
- **Cost Tracking**: Per-request usage analytics

</td>
</tr>
</table>

## 🚀 Quick Start

### Option A: Docker (Recommended)

```bash
git clone https://github.com/yourusername/red-team-mcp.git
cd red-team-mcp
cp .env.example .env
# Edit .env with your API keys

docker compose up -d
# Open http://localhost:8000/ui/
```

### Option B: Local Install

```bash
git clone https://github.com/yourusername/red-team-mcp.git
cd red-team-mcp
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

### Configure API Keys

```bash
cp .env.example .env
# Edit .env with your API keys
```

### Run

```bash
# Start the web server & dashboard
python main.py serve
# Open http://localhost:8000/ui/

# Or use the CLI
python main.py chat "What is machine learning?"

# Or start the MCP server
python main.py mcp
```

## 🤝 Multi-Agent Coordination

Red Team MCP excels at coordinating multiple AI agents on complex tasks. Choose from 5 coordination modes:

| Mode | Description | Best For |
|------|-------------|----------|
| **Pipeline** | Agents work sequentially, each building on the previous output | Document workflows, iterative refinement |
| **Ensemble** | Agents work in parallel, then synthesize results | Comprehensive analysis, multiple perspectives |
| **Debate** | Agents engage in back-and-forth argumentation | Critical thinking, finding flaws |
| **Swarm** | CrewAI-powered collaboration with delegation | Complex projects, dynamic task allocation |
| **Hierarchical** | Manager agent delegates to specialists | Large teams, structured workflows |

### Predefined Agent Teams

| Team | Agents | Default Mode |
|------|--------|--------------|
| **Writing Team** | Creative Writer, Editor, SEO Specialist | Pipeline |
| **Marketing Team** | Strategist, Brand Manager, Social Media | Hierarchical |
| **Research Team** | Researcher, Data Scientist, Analyst | Ensemble |
| **Technical Team** | Expert, Solutions Architect, Security | Debate |
| **Executive Team** | Strategy, Financial, Operations | Ensemble |

### Example: Multi-Agent Request

```bash
curl -X POST "http://localhost:8000/api/multi-agent" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Analyze the competitive landscape for AI startups",
    "coordination_mode": "ensemble",
    "agents": ["financial_analyst", "strategy_consultant", "technical_expert"]
  }'
```

## 📡 MCP Integration

Red Team MCP provides a Model Context Protocol server for seamless integration with AI assistants.

### VS Code Setup

Create `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "red-team-mcp": {
      "command": "python",
      "args": ["-m", "src.mcp_server_dynamic"],
      "cwd": "/path/to/red-team-mcp"
    }
  }
}
```

### Claude Desktop Setup

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "red-team-mcp": {
      "command": "python",
      "args": ["/path/to/red-team-mcp/main.py", "mcp"]
    }
  }
}
```

### Available MCP Tools

| Tool | Description |
|------|-------------|
| `list_agents` | List all available agents |
| `list_teams` | List all predefined teams |
| `chat` | Chat with a specific agent |
| `run_team` | Execute a team on a task |
| `coordinate` | Run multi-agent coordination |
| `brainstorm` | Generate multiple perspectives |

## 📖 API Reference

### Chat Endpoint

```http
POST /api/chat
Content-Type: application/json

{
  "agent_id": "creative_writer",
  "message": "Write a tagline for an AI product",
  "temperature": 0.8,
  "max_tokens": 500
}
```

### Multi-Agent Endpoint

```http
POST /api/multi-agent
Content-Type: application/json

{
  "query": "Develop a go-to-market strategy",
  "coordination_mode": "hierarchical",
  "agents": ["marketing_strategist", "sales_analyst"],
  "rebuttal_limit": 3
}
```

### Run Team Endpoint

```http
POST /api/team/{team_id}/run
Content-Type: application/json

{
  "query": "Create a blog post about AI trends",
  "coordination_mode": "pipeline"
}
```

### Additional Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/agents` | GET | List all agents |
| `/api/teams` | GET | List all teams |
| `/api/models` | GET | List available models |
| `/health` | GET | Health check |
| `/ws/chat` | WS | WebSocket streaming |

## 🏗️ Architecture

```
red-team-mcp/
├── main.py                    # CLI entry point
├── config/config.yaml         # Configuration
├── src/
│   ├── api/                   # FastAPI application
│   │   ├── app.py            # App factory
│   │   ├── endpoints.py      # REST endpoints
│   │   └── websockets.py     # WebSocket handlers
│   ├── agents/               # Agent implementations
│   │   ├── configurable_agent.py
│   │   └── coordinator.py    # Multi-agent coordination
│   ├── web/                  # Dashboard UI
│   │   ├── routes.py
│   │   └── templates/        # HTMX templates
│   ├── providers/            # 68 provider implementations
│   ├── config.py             # Configuration management
│   ├── models.py             # Model selector
│   ├── db.py                 # SQLite persistence
│   └── mcp_server_dynamic.py # MCP server
└── mcp_servers/              # Generated MCP servers
```

## ⚙️ Configuration

### Environment Variables

```bash
# Core providers
ANTHROPIC_API_KEY=your_key
OPENAI_API_KEY=your_key
GOOGLE_API_KEY=your_key
GROQ_API_KEY=your_key
DEEPSEEK_API_KEY=your_key

# And 60+ more providers supported!
```

### config.yaml

```yaml
api:
  host: "0.0.0.0"
  port: 8000
  rate_limit: "100/minute"

models:
  default: "claude-sonnet-4-20250514"

agents:
  predefined:
    - id: my_custom_agent
      name: Custom Agent
      model_id: gpt-4o
      provider: openai
      role: Specialist
      goal: Help with specific tasks
```

## 🧪 Development

```bash
# Run tests
python -m pytest tests/ -v

# Run with hot reload
python main.py serve --reload

# Generate MCP servers
python main.py generate-mcp --all
```

## 📊 Web Dashboard

Access the admin dashboard at `http://localhost:8000/ui/` to:

- 💬 **Chat** with any agent interactively
- 👥 **Manage Teams** and agent configurations
- 📈 **View Statistics** on usage and costs
- ⚙️ **Configure** providers and settings
- 📤 **Export** configurations

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing`)
3. Add tests for new functionality
4. Ensure all tests pass (`python -m pytest`)
5. Submit a pull request

## 📄 License

AGPL-3.0 License - see [LICENSE](LICENSE) for details.

## 🙏 Acknowledgments

- [models.dev](https://models.dev) - Comprehensive model database
- [CrewAI](https://crewai.com) - Agent orchestration framework
- [FastAPI](https://fastapi.tiangolo.com) - High-performance web framework
- All 68 AI providers making their models accessible

---

<p align="center">
  <strong>Ready to assemble your AI team?</strong><br>
  <a href="#-quick-start">Get Started →</a>
</p>