komodo-mcp-custom/IMPLEMENTATION.md

Implementation Details

Technical documentation for the Komodo MCP Server.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    MCP Client (AI Agent)                │
└─────────────────────────┬───────────────────────────────┘
                          │ SSE
                          ▼
┌─────────────────────────────────────────────────────────┐
│              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