Ben
98dc6b7f50
All checks were successful
Build and Push Komodo MCP Docker Image / build (push) Successful in 18s
- 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
79 lines
3.9 KiB
Markdown
79 lines
3.9 KiB
Markdown
# 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
|