# Implementation Details

Technical documentation for the Komodo MCP Server.

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    MCP Client (AI Agent)                │
└─────────────────────────┬───────────────────────────────┘
                          │ HTTP (POST /mcp)
                          ▼
┌─────────────────────────────────────────────────────────┐
│              Docker Container (komodo-mcp)              │
│  ┌───────────────────────────────────────────────────┐  │
│  │              FastMCP + uvicorn (:8000)            │  │
│  └───────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────┐  │
│  │                  KomodoClient                     │  │
│  │            (httpx → Komodo Core API)              │  │
│  └─────────────────────────┬─────────────────────────┘  │
└─────────────────────────────┼───────────────────────────┘
                              │ HTTPS
                              ▼
                    ┌──────────────────┐
                    │   Komodo Core    │
                    │    (REST API)    │
                    └────────┬─────────┘
                             │
           ┌─────────────────┼─────────────────┐
           ▼                 ▼                 ▼
     ┌──────────┐      ┌──────────┐      ┌──────────┐
     │ Periphery│      │ Periphery│      │ Periphery│
     │ Server 1 │      │ Server 2 │      │ Server N │
     └──────────┘      └──────────┘      └──────────┘
```

## Components

### KomodoClient
- HTTP client using `httpx`
- Handles authentication via `X-Api-Key` and `X-Api-Secret` headers
- Methods: `read()`, `write()`, `execute()` mapping to API endpoints

### Transport Security
- `TransportSecuritySettings` validates Host headers
- Configurable via `MCP_ALLOWED_HOSTS`

### Tool Strategy

**Layer 1: Curated Tools**
- `list_servers()` - Server discovery
- `list_deployments()` - Container listing
- `list_stacks()` - Stack listing
- `get_container_status(deployment)` - Container details

**Layer 2: Raw Access**
- `komodo_api_call(endpoint, request_type, params)` - Any API operation

### API Docs Resource
- URI: `komodo://api-reference`
- Provides structured API documentation for AI agents

## Komodo API

All requests use:
- **Method**: POST
- **Paths**: `/read`, `/write`, `/execute`
- **Body**: `{"type": "RequestType", "params": {...}}`
- **Auth**: `X-Api-Key` + `X-Api-Secret` headers

Full docs: https://docs.rs/komodo_client/latest/komodo_client/api/index.html

## Build & Deploy

- **Build**: `uv` + multi-stage Docker
- **Registry**: Gitea Container Registry
- **Deploy**: Docker Compose