# Komodo MCP Server

A Model Context Protocol (MCP) server for [Komodo](https://komo.do/) Docker management.

## Features

- **Curated Tools**: High-level tools for common operations
- **Raw API Access**: Pass-through tool for 100% API coverage
- **API Docs Resource**: Built-in reference for AI agents

## Tools

| Tool | Description |
|------|-------------|
| `list_servers` | Lists all periphery servers |
| `list_deployments` | Lists deployments (containers) |
| `list_stacks` | Lists stacks (docker-compose) |
| `get_container_status` | Gets container details |
| `komodo_api_call` | Raw API pass-through |

## Resources

| Resource | Description |
|----------|-------------|
| `komodo://api-reference` | API documentation |

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `KOMODO_URL` | Yes | Komodo Core URL |
| `KOMODO_API_KEY` | Yes | API key |
| `KOMODO_API_SECRET` | Yes | API secret |

### Deploy with Docker Compose

```yaml
services:
  komodo-mcp:
    image: gitea.ext.ben.io/b3nw/komodo-mcp:latest
    environment:
      - KOMODO_URL=https://komodo.example.com
      - KOMODO_API_KEY=your-key
      - KOMODO_API_SECRET=your-secret
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
```

### Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/mcp` | POST | MCP protocol endpoint |
| `/health` | GET | Health check for Docker |

## Local Development

```bash
# Setup
cp .env.example .env
# Edit .env with your credentials

# Build and run
make build
make dev

# Test
make logs
make test-mcp
make stop
```

## Tech Stack

- Python 3.11+ / FastMCP / httpx
- Streamable HTTP transport / uvicorn
- Docker with multi-stage build