Ben
72a53a64ed
- KomodoClient for Komodo Core API - MCP tools: list_servers, list_deployments, list_stacks, get_container_status - Raw API pass-through: komodo_api_call - API documentation resource: komodo://api-reference - Docker multi-stage build with uv
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) │
|
|
└─────────────────────────┬───────────────────────────────┘
|
|
│ 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
|