# Komodo MCP Server

An MCP (Model Context Protocol) server for interacting with the Komodo Client API, built with FastMCP.

## Overview

This MCP server provides a comprehensive interface to the Komodo API, allowing you to manage deployments, builds, stacks, servers, and execute commands through MCP-compatible clients. It exposes all major Komodo API operations as MCP tools.

## Features

- **Complete API Coverage**: Supports all Komodo API modules (auth, user, read, write, execute, terminal)
- **Type-Safe**: Built with Pydantic for request/response validation
- **Error Handling**: Comprehensive error handling with clear error messages
- **Flexible Configuration**: Supports client-provided configuration or environment variables
- **Docker Support**: Ready-to-use Docker containerization
- **FastMCP Integration**: Built on FastMCP for reliable MCP protocol handling

## Installation

### Prerequisites

- Python 3.12 or later
- Access to a Komodo instance
- Komodo API credentials (API key and secret)

### Install Dependencies

```bash
pip install -e .
```

Or install dependencies directly:

```bash
pip install fastmcp httpx pydantic python-dotenv
```

## Configuration

The server supports two configuration methods:

### Method 1: Client-Provided Configuration (Recommended)

Provide configuration during MCP server initialization. This is the preferred method as it keeps credentials out of environment variables.

**MCP Client Configuration Example:**

```json
{
  "mcpServers": {
    "komodo": {
      "command": "python",
      "args": ["-m", "komodo_mcp.main"],
      "initializationOptions": {
        "komodo_address": "https://komodo.example.com",
        "komodo_api_key": "your_api_key",
        "komodo_api_secret": "your_api_secret"
      }
    }
  }
}
```

**Alternative parameter names** (also supported):
- `address` instead of `komodo_address`
- `api_key` instead of `komodo_api_key`
- `api_secret` instead of `komodo_api_secret`

### Method 2: Environment Variables (Fallback)

If client-provided configuration is not available, the server will fall back to environment variables.

Create a `.env` file in the project root (or copy from `.env.example`):

```bash
cp .env.example .env
```

Edit `.env` with your Komodo credentials:

```env
KOMODO_ADDRESS=https://komodo.example.com
KOMODO_API_KEY=your_api_key_here
KOMODO_API_SECRET=your_api_secret_here
```

**Environment Variables:**

- `KOMODO_ADDRESS` (required): Base URL of your Komodo instance (e.g., `https://komodo.example.com`)
- `KOMODO_API_KEY` (required): Your Komodo API key
- `KOMODO_API_SECRET` (required): Your Komodo API secret

You can obtain API credentials from the Komodo UI Settings page.

**Configuration Priority:**
1. Client-provided initialization options (highest priority)
2. Environment variables (fallback)

## Usage

### Running the Server Locally

The server runs using stdio transport (standard for MCP):

```bash
python -m komodo_mcp.main
```

Or use the installed script:

```bash
komodo-mcp
```

### Running with Docker

#### Build the Docker Image

```bash
docker build -f docker/Dockerfile -t komodo-mcp .
```

#### Run the Container

**With environment variables:**

```bash
docker run -it --rm \
  -e KOMODO_ADDRESS=https://komodo.example.com \
  -e KOMODO_API_KEY=your_api_key \
  -e KOMODO_API_SECRET=your_api_secret \
  komodo-mcp
```

**With docker-compose:**

```bash
# Set environment variables in .env file or export them
export KOMODO_ADDRESS=https://komodo.example.com
export KOMODO_API_KEY=your_api_key
export KOMODO_API_SECRET=your_api_secret

docker-compose up
```

**With client-provided configuration:**

The Docker container can be used with client-provided configuration. Configure your MCP client to connect to the Docker container:

```json
{
  "mcpServers": {
    "komodo": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "komodo-mcp"
      ],
      "initializationOptions": {
        "komodo_address": "https://komodo.example.com",
        "komodo_api_key": "your_api_key",
        "komodo_api_secret": "your_api_secret"
      }
    }
  }
}
```

### MCP Client Configuration

**Local Installation:**

```json
{
  "mcpServers": {
    "komodo": {
      "command": "python",
      "args": ["-m", "komodo_mcp.main"],
      "initializationOptions": {
        "komodo_address": "https://komodo.example.com",
        "komodo_api_key": "your_api_key",
        "komodo_api_secret": "your_api_secret"
      }
    }
  }
}
```

**Docker Installation:**

```json
{
  "mcpServers": {
    "komodo": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "komodo-mcp"
      ],
      "initializationOptions": {
        "komodo_address": "https://komodo.example.com",
        "komodo_api_key": "your_api_key",
        "komodo_api_secret": "your_api_secret"
      }
    }
  }
}
```

## Available Tools

### Authentication

- `komodo_login`: Login to Komodo and obtain authentication token

### User Management

- `komodo_list_api_keys`: List all API keys for the current user
- `komodo_create_api_key`: Create a new API key
- `komodo_delete_api_key`: Delete an API key

### Read Operations

- `komodo_get_deployment`: Get detailed information about a deployment
- `komodo_list_deployments`: List all deployments
- `komodo_get_build`: Get detailed information about a build
- `komodo_list_builds`: List all builds
- `komodo_get_stack`: Get detailed information about a stack
- `komodo_list_stacks`: List all stacks
- `komodo_get_server`: Get detailed information about a server
- `komodo_list_servers`: List all servers

### Write Operations

- `komodo_create_deployment`: Create a new deployment
- `komodo_update_deployment`: Update an existing deployment
- `komodo_delete_deployment`: Delete a deployment
- `komodo_create_build`: Create a new build
- `komodo_update_build`: Update an existing build
- `komodo_delete_build`: Delete a build
- `komodo_create_stack`: Create a new stack
- `komodo_update_stack`: Update an existing stack
- `komodo_delete_stack`: Delete a stack
- `komodo_create_server`: Create a new server
- `komodo_update_server`: Update an existing server
- `komodo_delete_server`: Delete a server

### Execute Operations

- `komodo_run_build`: Execute/run a build
- `komodo_run_deployment`: Execute/run a deployment
- `komodo_stop_build`: Stop a running build
- `komodo_stop_deployment`: Stop a running deployment

### Terminal Operations

- `komodo_execute_command`: Execute a command on a server via terminal

## Examples

### List All Deployments

```python
# Using an MCP client
result = await client.call_tool("komodo_list_deployments")
print(result)
```

### Create a Deployment

```python
config = {
    "name": "my-deployment",
    "build": "build-id-here",
    # ... other deployment config
}
result = await client.call_tool("komodo_create_deployment", {"config": config})
print(result)
```

### Run a Build

```python
result = await client.call_tool("komodo_run_build", {
    "build": "build-id-here",
    "options": {
        "environment": "production"
    }
})
print(result)
```

### Execute a Command on a Server

```python
result = await client.call_tool("komodo_execute_command", {
    "server": "server-id-here",
    "command": "docker ps",
    "options": {
        "timeout": 30
    }
})
print(result)
```

## Error Handling

The server provides comprehensive error handling:

- **KomodoConfigError**: Raised when configuration is invalid or missing
- **KomodoAPIError**: Raised when Komodo API returns an error (includes error message and traceback)
- **KomodoConnectionError**: Raised when connection to Komodo API fails

All errors are properly formatted and include helpful error messages.

## Development

### Project Structure

```
komodo-mcp/
├── src/
│   └── komodo_mcp/
│       ├── __init__.py
│       ├── main.py              # Entry point
│       ├── server.py            # FastMCP server with all tools
│       ├── client.py            # Komodo HTTP client
│       ├── config.py            # Configuration management
│       ├── errors.py            # Custom exceptions
│       ├── models.py            # Pydantic models
│       └── tools/               # Tool modules
│           ├── __init__.py
│           ├── auth.py
│           ├── user.py
│           ├── read.py
│           ├── write.py
│           ├── execute.py
│           └── terminal.py
├── tests/                       # Test files
│   └── __init__.py
├── docker/
│   └── Dockerfile               # Docker image definition
├── docker-compose.yml           # Docker Compose configuration
├── .dockerignore                # Docker ignore patterns
├── pyproject.toml               # Project configuration
├── .env.example                  # Environment variable template
├── .gitignore
└── README.md
```

### Running Tests

```bash
pytest
```

### Docker Development

For development with Docker, you can mount the source code:

```yaml
# In docker-compose.yml, uncomment the volumes section:
volumes:
  - ./src:/app/src:ro
```

Then rebuild and run:

```bash
docker-compose up --build
```

## Docker Details

### Image Size Optimization

The Docker image uses Python 3.12-slim for a smaller footprint. The image includes:
- Python 3.12 runtime
- Project dependencies
- Non-root user for security
- Optimized layer caching

### Security Considerations

- Runs as non-root user (`komodo`)
- No unnecessary packages installed
- Environment variables can be provided at runtime
- Supports client-provided configuration (no secrets in image)

### MCP Protocol Support

MCP servers use stdio transport, so:
- No ports need to be exposed
- Communication happens via stdin/stdout
- Works seamlessly with Docker's stdio support

## License

This project is licensed under the same license as the Komodo Client API.

## References

- [Komodo Client API Documentation](https://docs.rs/komodo_client/latest/komodo_client/api/index.html)
- [FastMCP Documentation](https://gofastmcp.com/)