# Multi-MCP Server

A distributed Model Context Protocol (MCP) server setup featuring multiple independent MCP servers and a master aggregator server. This project demonstrates how to build and orchestrate MCP-based services for tool calling and result aggregation.

## 🚀 Features

- **Multiple MCP Servers**: Three specialized MCP servers running on separate ports
  - Server 1: Greeting service
  - Server 2: Mathematical operations
  - Server 3: Text manipulation
- **Master Aggregator**: A central MCP server that orchestrates calls to all three servers
- **HTTP Transport**: Stateless HTTP-based communication using JSON-RPC 2.0
- **Async Support**: Fully asynchronous implementation for high performance
- **Easy Deployment**: Simple setup with virtual environment and uvicorn

## 📋 Prerequisites

- Python 3.8+
- Virtual environment (recommended)

## 🛠️ Installation

1. **Clone the repository** (if applicable) or navigate to the project directory:
   ```bash
   cd /path/to/Multi-MCPServer
   ```

2. **Create and activate a virtual environment**:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

## 🏃‍♂️ Running the Servers

### Start Individual MCP Servers

Run each server in separate terminals or background processes:

```bash
# Server 1 (Port 8001)
PORT=8001 uvicorn mcp_server1:app --host 0.0.0.0 --port 8001

# Server 2 (Port 8002)
PORT=8002 uvicorn mcp_server2:app --host 0.0.0.0 --port 8002

# Server 3 (Port 8003)
PORT=8003 uvicorn mcp_server3:app --host 0.0.0.0 --port 8003
```

### Start Master Aggregator Server

```bash
uvicorn master_mcp:app --host 0.0.0.0 --port 8000
```

## 📖 Usage

### Available Tools

#### Server 1 Tools
- **greet(name: str)**: Returns a personalized greeting message

#### Server 2 Tools
- **add(a: float, b: float)**: Returns the sum of two numbers

#### Server 3 Tools
- **reverse_text(text: str)**: Returns the reversed text

#### Master Server Tools
- **aggregate_results(input_text: str)**: Calls all three servers and aggregates their results

### Example API Calls

#### Direct Server Calls
```bash
# Greet
curl -X POST http://localhost:8001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "greet", "arguments": {"name": "World"}}, "id": 1}'

# Add numbers
curl -X POST http://localhost:8002/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "add", "arguments": {"a": 10, "b": 20}}, "id": 1}'

# Reverse text
curl -X POST http://localhost:8003/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "reverse_text", "arguments": {"text": "hello"}}, "id": 1}'
```

#### Aggregated Results
```bash
# Aggregate all results
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "aggregate_results", "arguments": {"input_text": "test"}}, "id": 1}'
```

Response:
```json
{
  "greet_result": "Hello, test! — from MCP Server 1",
  "add_result": "30.0",
  "reverse_text_result": "tset"
}
```

## 🏗️ Architecture

```
┌─────────────────┐    ┌─────────────────┐
│   Master MCP    │────│   Server 1      │
│   (Port 8000)   │    │   (Port 8001)   │
└─────────────────┘    └─────────────────┘
         │                       │
         └───────────────────────┼───────────────────────┐
                                 │                       │
                    ┌─────────────────┐    ┌─────────────────┐
                    │   Server 2      │    │   Server 3      │
                    │   (Port 8002)   │    │   (Port 8003)   │
                    └─────────────────┘    └─────────────────┘
```

- **Master Server**: Orchestrates calls to individual servers
- **Individual Servers**: Specialized MCP servers with unique tools
- **HTTP Transport**: All communication uses HTTP with JSON-RPC 2.0 over Server-Sent Events

## 🔧 Configuration

- **Ports**: Configurable via `PORT` environment variable (defaults: 8001, 8002, 8003)
- **Host**: Default `0.0.0.0` for external access
- **Transport Security**: Configurable via `TransportSecuritySettings`

## 🧪 Testing

Run the servers and use the provided curl examples to test functionality.

## 📦 Dependencies

- `fastmcp`: MCP server framework
- `httpx`: Async HTTP client
- `uvicorn`: ASGI server
- `fastapi`: Web framework

See `requirements.txt` for full list.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🆘 Troubleshooting

### Common Issues

1. **Port already in use**: Change the PORT environment variable
2. **Connection refused**: Ensure all servers are running
3. **JSON parsing errors**: Check request format matches JSON-RPC 2.0 specification

### Logs

Check server logs for detailed error information. Enable debug logging by setting `LOG_LEVEL=DEBUG`.

## 📚 Additional Resources

- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [FastMCP Documentation](https://github.com/modelcontextprotocol/python-sdk)
- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)</content>
<parameter name="filePath">/Users/arvindacharya/Desktop/Quadra-Projects/MCP/Multi-MCPServer/README.md