Files

Build and Push Komodo MCP Docker Image / build (push) Successful in 42s

Details

feat: add /health endpoint and switch to fastmcp 2.0

- Switch from mcp package to fastmcp>=2.0 for Streamable HTTP support
  - Fixes 405 Method Not Allowed for MCP clients like Gemini CLI
  - MCP endpoint now at /mcp (POST) instead of /sse (GET)
  - Removes MCP_ALLOWED_HOSTS (handled at reverse proxy level)

- Add /health endpoint for Docker health checks
  - Returns {"status": "ok"} (200) or {"status": "degraded"} (503)
  - Enables health checks without transport security issues

- Add curl to Docker image for health checks
- Add healthcheck config to docker-compose files
- Add test-health and test-mcp Makefile targets
- Update documentation

2025-12-21 05:10:18 +00:00

3.9 KiB

Raw Permalink Blame History

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

3.9 KiB Raw Permalink Blame History