# Master MCP Orchestrator

A central MCP server that connects to multiple MCP servers and intelligently routes user queries to the appropriate MCP tools, then aggregates and returns responses.

## 🚀 Quick Start (Interactive CLI)

The easiest way to get started is with our interactive CLI:

```bash
python src/cli.py
```

The CLI will guide you through:
- API key setup
- MCP server discovery
- MCP selection
- Interactive query interface

See [CLI_QUICKSTART.md](CLI_QUICKSTART.md) for detailed instructions.

## Features

- 🔌 **Multi-MCP Connection**: Connect to multiple MCP servers simultaneously
- 🤖 **AI-Powered Routing**: Uses LLM to intelligently route queries (default)
- 🧠 **Intelligent Routing**: Analyzes queries to determine which MCP(s) to call
- 🔍 **Tool Discovery**: Automatically discovers available tools from connected MCPs
- 📊 **Response Aggregation**: Combines responses from multiple MCPs when needed
- ⚡ **Async Execution**: Parallel execution for faster responses
- 🎯 **Query Analysis**: Understands query intent to route to correct MCPs
- 🔄 **Fallback Support**: Automatically falls back to rule-based routing if AI fails

## Architecture

```
User Query
    │
    ▼
┌─────────────────────┐
│  Master MCP Server  │
│  ┌───────────────┐  │
│  │ Query Analyzer│  │
│  └───────┬───────┘  │
│          │          │
│          ▼          │
│  ┌───────────────┐  │
│  │ MCP Router    │  │
│  └───────┬───────┘  │
│          │          │
└──────────┼──────────┘
           │
    ┌──────┴──────┐
    │             │
    ▼             ▼
┌─────────┐  ┌─────────┐
│ MCP #1  │  │ MCP #2  │
│ Router  │  │ Coding  │
└────┬────┘  └────┬────┘
     │            │
     └─────┬──────┘
           │
           ▼
    ┌──────────┐
    │ Response │
    │ Aggregator│
    └─────┬────┘
          │
          ▼
    User Response
```

## Installation

```bash
cd master-mcp
pip install -r requirements.txt
```

### AI Routing Setup (Optional)

The Master MCP works **out-of-the-box without API keys** using rule-based routing.

For enhanced AI-powered routing, set an API key:

```bash
# Option 1: OpenAI (default)
export OPENAI_API_KEY=your_key_here

# Option 2: Anthropic
export ANTHROPIC_API_KEY=your_key_here
export MASTER_MCP_AI_PROVIDER=anthropic
export MASTER_MCP_AI_MODEL=claude-3-5-haiku
```

**Routing Modes:**

| Mode | API Key Required | Speed | Intelligence |
|------|-----------------|-------|--------------|
| **Rule-based** (default) | ❌ No | ⚡ Fast | Good |
| **AI-powered** | ✅ Yes | 🔄 +200ms | Excellent |

To disable AI routing even if API key is set:

```bash
export MASTER_MCP_USE_AI=false
```

## Configuration

Create a `config.json` file to register MCP servers:

```json
{
  "mcp_servers": {
    "mcp-router": {
      "command": "python3",
      "args": ["/path/to/mcp-router/src/mcp_server.py"],
      "env": {}
    },
    "mcp-coding-agent": {
      "command": "python3",
      "args": ["/path/to/mcp-coding-agent/src/main.py"],
      "env": {}
    }
  }
}
```

## Usage

### As MCP Server (Cursor Integration) - **Recommended**

The Master MCP is now integrated with Cursor! See [CURSOR_SETUP.md](CURSOR_SETUP.md) for detailed instructions.

**Quick Start:**

1. The Master MCP has been added to your `~/.cursor/mcp.json`
2. Restart Cursor
3. Use it:
   ```
   @master-mcp query_mcp "What model should I use for debugging?"
   @master-mcp list_mcps
   ```

**Benefits:**
- 🎯 Auto-discovers all your existing MCPs
- 🤖 Intelligent query routing (AI or rule-based)
- 📊 Aggregates responses from multiple MCPs
- 🔌 Works out-of-the-box (no API key required for rule-based routing)

### Standalone MCP Server

Add to any MCP client's configuration:

```json
{
  "version": "1.0",
  "mcpServers": {
    "master-mcp": {
      "command": "python3",
      "args": ["/path/to/master-mcp/src/master_mcp_server.py"],
      "env": {
        "MASTER_MCP_USE_AI": "true"
      }
    }
  }
}
```

### CLI Usage

```bash
python src/master_mcp_server.py --query "What model should I use for debugging?"
```

## How It Works

1. **Query Analysis**: Analyzes user query to determine intent
2. **MCP Selection**: Selects appropriate MCP(s) based on query
3. **Tool Selection**: Chooses the right tool(s) from selected MCPs
4. **Execution**: Calls MCP tools (in parallel when possible)
5. **Aggregation**: Combines responses into a unified result
6. **Response**: Returns formatted response to user