# Multi-Agent MCP Network

A production-ready **Model Context Protocol (MCP)** server that exposes multiple specialized AI agents through a unified interface. Each agent is an expert in its domain and they collaborate through an intelligent orchestrator.

## Architecture

```
                    ┌─────────────────────┐
                    │   Client / MCP Host  │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │  REST API (Express)  │
                    │  MCP Server (SDK)   │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │    Orchestrator     │
                    │  ┌─────┴─────┐     │
                    │  │ Router    │     │
                    │  │ Workflow  │     │
                    │  └─────┬─────┘     │
                    └──────────┬──────────┘
                               │
          ┌────────────────────┼────────────────────┐
          ▼        ▼           ▼          ▼         ▼
       ┌────┐  ┌────┐     ┌────┐     ┌────┐    ┌────┐
       │CEO │  │CTO │ ... │Mktg│     │ QA │    │ ...│
       └────┘  └────┘     └────┘     └────┘    └────┘
          │        │          │          │
          └────────┴──────────┴──────────┘
                               │
                    ┌──────────▼──────────┐
                    │  Memory Layer       │
                    │  PostgreSQL + Qdrant│
                    └─────────────────────┘
```

## Agents

| Agent | Role | Expertise |
|-------|------|-----------|
| CEO   | Business Strategy | Market analysis, product roadmap, pricing, investment, startup advice |
| CTO   | Technology | Software architecture, backend, frontend, databases, AI/ML, DevOps, cloud |
| Designer | Design | UI/UX, brand identity, logos, color palettes, design systems |
| Sales | Revenue | Lead generation, cold emails, CRM, sales funnels, outreach |
| Marketing | Growth | SEO, content, ads, social media, email campaigns, competitor analysis |
| QA | Quality | Code review, bug finding, testing, security, performance |

## Tech Stack

- **Runtime:** Node.js 20+, TypeScript
- **Framework:** Express, FastMCP SDK (`@modelcontextprotocol/sdk`)
- **Databases:** PostgreSQL (pgvector), Qdrant (vector), Redis (cache)
- **AI:** OpenAI, Anthropic Claude, Google Gemini
- **Infrastructure:** Docker, Docker Compose

## Quick Start

### Prerequisites

- Node.js 20+
- Docker & Docker Compose
- At least one AI provider API key (OpenAI, Anthropic, or Gemini)

### 1. Clone & Install

```bash
cd multi-agent-mcp
npm install
```

### 2. Configure Environment

```bash
cp .env.example .env
```

Edit `.env` and add your API keys:

```env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...
API_KEY=sk-mcp-your-secret-key
JWT_SECRET=your-random-secret
```

### 3. Start Infrastructure

```bash
docker compose up -d postgres qdrant redis
```

### 4. Run Database Migrations

```bash
npm run db:migrate
```

### 5. Start the Server

**Development mode:**
```bash
npm run dev
```

**Production mode:**
```bash
npm run build
npm start
```

### 6. Start MCP Server (for MCP clients)

```bash
npm run mcp
```

## API Endpoints

All endpoints require `x-api-key` header matching your `API_KEY` env var.

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/chat` | Send query to orchestrator (auto-routes to agents) |
| POST | `/agent/ceo` | Ask CEO directly |
| POST | `/agent/cto` | Ask CTO directly |
| POST | `/agent/designer` | Ask Designer directly |
| POST | `/agent/sales` | Ask Sales directly |
| POST | `/agent/marketing` | Ask Marketing directly |
| POST | `/agent/qa` | Ask QA directly |
| POST | `/memory` | Save or search memory |
| GET | `/projects` | List all projects |
| GET | `/projects/:id` | Get project details |
| GET | `/tasks` | List tasks |
| GET | `/health` | Health check |

### Chat Example

```bash
curl -X POST http://localhost:3001/chat \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-mcp-your-secret-key" \
  -d '{"query": "I want to launch an AI SaaS for small businesses"}'
```

## MCP Tools

When running as an MCP server (via `npm run mcp`), the following tools are exposed:

| Tool | Description |
|------|-------------|
| `ask_ceo` | Business strategy advice |
| `ask_cto` | Technical architecture guidance |
| `ask_designer` | UI/UX and brand design |
| `ask_sales` | Sales and lead generation |
| `ask_marketing` | Marketing and growth |
| `ask_qa` | Code review and quality |
| `ask_all_agents` | Multi-agent collaboration |
| `create_project` | Create a new project |
| `save_memory` | Store long-term memory |
| `load_memory` | Retrieve memories |
| `search_documents` | Semantic document search |
| `generate_strategy` | Business strategy generation |
| `generate_ui` | UI design generation |
| `generate_architecture` | System architecture design |
| `generate_marketing_plan` | Marketing plan generation |
| `generate_sales_plan` | Sales plan generation |
| `review_project` | Full project review |

## Docker Deployment

Start everything with one command:

```bash
docker compose up --build
```

This starts:
- `app` - The Multi-Agent MCP server
- `postgres` - PostgreSQL with pgvector
- `qdrant` - Vector database for embeddings
- `redis` - Cache layer

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `API_KEY` | Yes | API authentication key |
| `JWT_SECRET` | Yes | JWT signing secret |
| `OPENAI_API_KEY` | No* | OpenAI API key |
| `ANTHROPIC_API_KEY` | No* | Anthropic API key |
| `GEMINI_API_KEY` | No* | Google Gemini API key |
| `DATABASE_URL` | No | PostgreSQL connection string |
| `QDRANT_URL` | No | Qdrant endpoint |
| `REDIS_URL` | No | Redis connection string |

*At least one AI provider API key is required.

## Project Structure

```
src/
├── agents/          # Agent implementations
│   ├── BaseAgent.ts # Abstract base class
│   ├── CEOAgent.ts
│   ├── CTOAgent.ts
│   ├── DesignerAgent.ts
│   ├── SalesAgent.ts
│   ├── MarketingAgent.ts
│   └── QAAgent.ts
├── orchestrator/    # Routing & workflow
│   ├── Router.ts    # Intent detection, agent selection
│   └── Workflow.ts  # Multi-agent execution, response merging
├── memory/          # Persistence layer
│   ├── postgres.ts  # PostgreSQL client
│   ├── qdrant.ts    # Qdrant vector client
│   ├── logger.ts    # Winston logger
│   └── migrate.ts   # DB migration runner
├── tools/           # MCP server
│   └── server.ts    # FastMCP SDK server with tool registration
├── config/          # Configuration
│   └── index.ts     # Env var loading
├── types/           # TypeScript types
│   └── index.ts     # All type definitions
└── index.ts         # Express REST API entry point
```

## Adding a New Agent

1. Create `src/agents/YourAgent.ts` extending `BaseAgent`
2. Add your agent role to `AgentRole` enum in `src/types/index.ts`
3. Add a system prompt in `SYSTEM_PROMPTS` in `src/types/index.ts`
4. Register the agent in `Router.ts` constructor
5. Add MCP tool in `src/tools/server.ts`
6. Add REST endpoint in `src/index.ts`
7. Add SQL seed in `sql/schema.sql`

## License

MIT