# MCP API Gateway

A unified local API gateway with caching, rate limiting, and full MCP (Model Context Protocol) compatibility.

![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Status](https://img.shields.io/badge/status-active-brightgreen)

## Features

- **🔌 Unified API Aggregation** - Manage multiple API endpoints through a single gateway
- **💾 Multi-Strategy Caching** - LRU, LFU, FIFO, and TTL cache eviction policies
- **⚡ Rate Limiting** - Token bucket and sliding window algorithms
- **🔗 MCP Protocol** - Full Model Context Protocol support for AI agent integration
- **📊 Observability** - Built-in statistics and metrics
- **🔄 Retry Logic** - Automatic retry with exponential backoff

## Installation

```bash
# Clone the repository
git clone https://github.com/bandageok/mcp-api-gateway.git
cd mcp-api-gateway

# Install dependencies
pip install -r requirements.txt

# Or install directly
pip install aiohttp pyyaml
```

## Quick Start

### 1. Create a Configuration File

```bash
python gateway.py --create-config
```

This creates a `config.yaml` with sample endpoints:

```yaml
host: localhost
port: 8080
cache:
  enabled: true
  max_size: 1000
  ttl: 300
  strategy: lru
rate_limit:
  enabled: true
  requests_per_minute: 60
apis:
  - name: github-api
    url: https://api.github.com
    method: GET
```

### 2. Run the Gateway

```bash
# With config file
python gateway.py -c config.yaml

# Or with command line arguments
python gateway.py --host 0.0.0.0 --port 8080
```

### 3. Use the Gateway

```bash
# Call an API endpoint
curl http://localhost:8080/api/github-api/users/bandageok

# Check health
curl http://localhost:8080/health

# Get statistics
curl http://localhost:8080/stats

# Clear cache
curl -X DELETE http://localhost:8080/cache/clear

# Get configuration
curl http://localhost:8080/config
```

## MCP Protocol Integration

The gateway provides full MCP protocol support for AI agents:

### MCP Tools

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "github-api",
        "description": "Call GET https://api.github.com",
        "inputSchema": {
          "type": "object",
          "properties": {
            "params": {"type": "object"},
            "data": {"type": "object"}
          }
        }
      }
    ]
  }
}
```

### Call a Tool

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "github-api",
    "arguments": {
      "params": {"path": "/users/bandageok"}
    }
  }
}
```

### MCP Resources

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/list",
  "params": {}
}
```

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `host` | string | localhost | Host to bind to |
| `port` | int | 8080 | Port to bind to |
| `debug` | bool | false | Enable debug mode |
| `log_level` | string | INFO | Logging level |
| `cache.enabled` | bool | true | Enable caching |
| `cache.max_size` | int | 1000 | Maximum cache entries |
| `cache.ttl` | int | 300 | Cache TTL in seconds |
| `cache.strategy` | string | lru | Cache strategy (lru/lfu/fifo/ttl) |
| `rate_limit.enabled` | bool | true | Enable rate limiting |
| `rate_limit.requests_per_minute` | int | 60 | Rate limit threshold |

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | Health check |
| `/health` | GET | Detailed health status |
| `/stats` | GET | Gateway statistics |
| `/config` | GET | Current configuration |
| `/cache/clear` | DELETE | Clear the cache |
| `/api/{name}` | * | Proxy to configured API |
| `/mcp` | POST | MCP protocol endpoint |

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      MCP API Gateway                         │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐    ┌─────────────┐    ┌───────────────┐  │
│  │   Cache     │    │Rate Limiter │    │  MCP Handler  │  │
│  │  (LRU/LFU)  │    │   (Token)   │    │               │  │
│  └─────────────┘    └─────────────┘    └───────────────┘  │
├─────────────────────────────────────────────────────────────┤
│                     API Client Pool                          │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ GitHub   │  │ Weather  │  │  Stocks  │  │  Custom  │  │
│  │    API   │  │    API   │  │    API   │  │    API   │  │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
└─────────────────────────────────────────────────────────────┘
```

## Use Cases

### 1. AI Agent Integration

Connect AI agents to external APIs through MCP:

```python
import requests

# Initialize MCP
response = requests.post("http://localhost:8080/mcp", json={
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {}
})

# List available tools
response = requests.post("http://localhost:8080/mcp", json={
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
})
```

### 2. API Rate Limiting

Protect external APIs from being overwhelmed:

```yaml
rate_limit:
  enabled: true
  requests_per_minute: 60  # Max 60 requests per minute
```

### 3. Response Caching

Cache expensive API responses:

```yaml
cache:
  enabled: true
  max_size: 1000
  ttl: 300  # Cache for 5 minutes
  strategy: lru  # Evict least recently used
```

## Examples

### Python Client

```python
import aiohttp
import asyncio

async def call_gateway():
    async with aiohttp.ClientSession() as session:
        # Call an API
        async with session.get("http://localhost:8080/api/github-api/users/bandageok") as resp:
            data = await resp.json()
            print(data)
        
        # Check stats
        async with session.get("http://localhost:8080/stats") as resp:
            stats = await resp.json()
            print(f"Cache hit rate: {stats['cache_hit_rate']}")

asyncio.run(call_gateway())
```

### Add Custom API Endpoint

```yaml
apis:
  - name: my-api
    url: https://api.example.com
    method: GET
    headers:
      Authorization: Bearer YOUR_TOKEN
    timeout: 30
    retry_count: 3
```

## Performance

- **Throughput**: ~1000 requests/second (with caching)
- **Latency**: <10ms overhead (cache hit), <100ms overhead (cache miss)
- **Memory**: ~50MB base + cache size

## License

MIT License - See [LICENSE](LICENSE) for details.

## Author

- **BandageOK** - [GitHub](https://github.com/bandageok)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

⭐ Star us on GitHub if you find this useful!