# MCP CLDKCTL - Model Context Protocol Server for Cloudeka CLI

## 🏠 Home Page

### Description
MCP CLDKCTL is a Model Context Protocol (MCP) server that provides seamless integration between AI assistants (Claude Desktop, Cursor) and Cloudeka's cloud infrastructure management platform. It transforms the cldkctl CLI functionality into AI-accessible tools, enabling natural language interaction with Kubernetes clusters, virtual machines, container registries, billing systems, and more.

### Key Benefits
- **🤖 AI-Native Interface**: Control your entire cloud infrastructure through natural language conversations
- **🔐 Smart Authentication**: Automatic token management with environment fallback (production → staging)
- **⚡ Persistent Caching**: JWT tokens cached locally for optimal performance
- **🔄 Auto-Reauthentication**: Seamless token renewal without manual intervention
- **🌍 Multi-Environment Support**: Easy switching between production and staging environments
- **📊 Complete API Coverage**: Access to all cldkctl endpoints as MCP tools

### Quick Preview Tools
- **Kubernetes Management**: Pods, deployments, services, configmaps, secrets
- **Virtual Machine Operations**: Create, manage, start/stop VMs
- **Container Registry**: Manage Docker registries and artifacts
- **Billing & Cost Management**: Monitor usage, view invoices, track expenses
- **Project & Organization**: User management, role assignments, project configuration
- **Notebook Management**: Create and manage Deka notebooks
- **Audit & Security**: View audit logs, manage tokens

---

## 1. Prerequisites and Setup

### Required Components
- **Python 3.8+** with pip or uv package manager
- **cldkctl Token**: Valid authentication token from Cloudeka platform
- **MCP-Compatible Client**: Claude Desktop, Cursor, or other MCP hosts
- **Network Access**: Connection to Cloudeka API endpoints

### Installation Options

#### Option A: From PyPI (Recommended)
```bash
# Using uvx (recommended)
uvx mcp-cldkctl-t

# Using pip
pip install mcp-cldkctl-t
```

#### Option B: From Source
```bash
git clone https://github.com/cloudeka/mcp-cldkctl.git
cd mcp-cldkctl
pip install -e .
# or
uv sync
```

### Environment Configuration

#### Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `CLDKCTL_TOKEN` | Yes | - | Your cldkctl token (starts with `cldkctl_`) |
| `CLDKCTL_BASE_URL` | No | `https://ai.cloudeka.id` | Base URL (auto-fallback to staging) |
| `CLDKCTL_DEFAULT_PROJECT_ID` | No | - | Default project ID for convenience |

#### Setup Examples

**Linux/macOS:**
```bash
export CLDKCTL_TOKEN="cldkctl_your_token_here"
export CLDKCTL_BASE_URL="https://ai.cloudeka.id"
export CLDKCTL_DEFAULT_PROJECT_ID="your_project_id"
```

**Windows:**
```cmd
set CLDKCTL_TOKEN=cldkctl_your_token_here
set CLDKCTL_BASE_URL=https://ai.cloudeka.id
set CLDKCTL_DEFAULT_PROJECT_ID=your_project_id
```

---

## 2. Integration with AI (Claude Desktop, Cursor)

### Claude Desktop Configuration

Add to your Claude Desktop configuration file:

```json
{
  "mcpServers": {
    "cldkctl": {
      "command": "uvx",
      "args": ["mcp-cldkctl-t@0.1.12"],
      "env": {
        "CLDKCTL_TOKEN": "cldkctl_4Lyn6i2vRslxqQi5d0SiNXN5XHyvGRzU",
        "CLDKCTL_BASE_URL": "https://staging.ai.cloudeka.id"
      }
    }
  }
}
```

### Cursor Configuration

Add to your Cursor settings (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "cldkctl": {
      "command": "uvx",
      "args": ["mcp-cldkctl-t@0.1.12"],
      "env": {
        "CLDKCTL_TOKEN": "your_cldkctl_token_here",
        "CLDKCTL_BASE_URL": "https://staging.ai.cloudeka.id"
      }
    }
  }
}
```

### Configuration Features
- **Automatic Token Loading**: Reads from environment variables or `mcp.json`
- **Environment Fallback**: Automatically switches to staging if production fails
- **Persistent Caching**: Stores authentication tokens locally
- **Cross-Platform Support**: Works on Windows, macOS, and Linux

---

## 3. Core Functions (Tools)

### Authentication & Environment Management

#### `auth`
Authenticate with your cldkctl token to get JWT access.
```python
auth(token="cldkctl_your_token_here", force_staging=False)
```

#### `switch_environment`
Switch between production and staging environments.
```python
switch_environment(environment="staging")  # or "production"
```

#### `status`
Check current authentication and environment status.
```python
status()
```

### Project & Organization Management

#### `project_list`
List all projects in your organization.
```python
project_list()
```

#### `project_detail`
Get detailed information about a specific project.
```python
project_detail(project_id="your_project_id")
```

#### `org_detail`
Get organization details and information.
```python
org_detail()
```

#### `org_members`
List all members in your organization.
```python
org_members()
```

### Kubernetes Management

#### `k8s_pods`
List Kubernetes pods in a namespace.
```python
k8s_pods(project_id="your_project_id", namespace="default")
```

#### `k8s_deployments`
List Kubernetes deployments.
```python
k8s_deployments(project_id="your_project_id", namespace="default")
```

#### `k8s_services`
List Kubernetes services.
```python
k8s_services(project_id="your_project_id", namespace="default")
```

#### `k8s_configmaps`
List Kubernetes configmaps.
```python
k8s_configmaps(project_id="your_project_id", namespace="default")
```

#### `k8s_secrets`
List Kubernetes secrets.
```python
k8s_secrets(project_id="your_project_id", namespace="default")
```

### Virtual Machine Management

#### `vm_list`
List all virtual machines.
```python
vm_list()
```

#### `vm_detail`
Get detailed information about a specific VM.
```python
vm_detail(vm_id="your_vm_id")
```

#### `vm_create`
Create a new virtual machine.
```python
vm_create(
    project_id="your_project_id",
    name="my-vm",
    flavor="flavor_id",
    image="image_id",
    network="network_id",
    storage="100GB"
)
```

#### `vm_turn_on` / `vm_turn_off`
Control VM power states.
```python
vm_turn_on(vm_id="your_vm_id")
vm_turn_off(vm_id="your_vm_id")
```

### Container Registry Management

#### `registry_list`
List container registries in a project.
```python
registry_list(project_id="your_project_id")
```

#### `registry_repositories`
List repositories in a registry.
```python
registry_repositories(registry_id="your_registry_id")
```

#### `registry_detail`
Get detailed registry information.
```python
registry_detail(registry_id="your_registry_id")
```

### Billing & Cost Management

#### `balance_detail`
Get project balance details.
```python
balance_detail(project_id="your_project_id")
```

#### `billing_daily_cost`
Get daily billing costs for a project.
```python
billing_daily_cost(project_id="your_project_id")
```

#### `billing_monthly_cost`
Get monthly billing costs for a project.
```python
billing_monthly_cost(project_id="your_project_id")
```

#### `billing_history`
Get billing history for a date range.
```python
billing_history(
    project_id="your_project_id",
    start="2024-01-01",
    end="2024-01-31"
)
```

#### `billing_invoice_sme`
List SME invoices.
```python
billing_invoice_sme()
```

### Notebook Management

#### `notebook_list`
List Deka notebooks in a project.
```python
notebook_list(project_id="your_project_id")
```

#### `notebook_create`
Create a new Deka notebook.
```python
notebook_create(
    project_id="your_project_id",
    name="my-notebook",
    namespace="default",
    image="image_id",
    cpu="2",
    memory="4GB",
    storage="50GB"
)
```

### Voucher & Token Management

#### `voucher_list`
List available vouchers.
```python
voucher_list()
```

#### `voucher_apply`
Apply a voucher code.
```python
voucher_apply(voucher_code="VOUCHER123")
```

#### `token_list`
List your cldkctl tokens.
```python
token_list()
```

#### `token_create`
Create a new cldkctl token.
```python
token_create(name="my-token", expiration_days=30)
```

### Audit & Security

#### `audit_logs`
Get audit logs.
```python
audit_logs()
```

### Advanced Kubernetes Operations

#### `k8s_pod_create`
Create a new Kubernetes pod.
```python
k8s_pod_create(
    project_id="your_project_id",
    namespace="default",
    spec={"apiVersion": "v1", "kind": "Pod", ...}
)
```

#### `k8s_pod_edit`
Edit an existing Kubernetes pod.
```python
k8s_pod_edit(
    project_id="your_project_id",
    namespace="default",
    name="pod-name",
    spec={"apiVersion": "v1", "kind": "Pod", ...}
)
```

#### `k8s_pod_delete`
Delete a Kubernetes pod.
```python
k8s_pod_delete(
    project_id="your_project_id",
    namespace="default",
    name="pod-name"
)
```

---

## 4. Local Testing and Development

### Running the Server Locally

#### Direct Execution
```bash
# Using uvx (recommended)
uvx mcp-cldkctl-t

# Direct Python execution
python -m mcp_cldkctl.server

# Using the installed script
mcp-cldkctl-t
```

### Development Setup

#### Install Development Dependencies
```bash
pip install -e ".[dev]"
# or
uv sync --dev
```

#### Available Test Files
- `test_auth.py` - Basic authentication tests
- `test_production_auth.py` - Production environment auth tests
- `test_staging_auth.py` - Staging environment auth tests
- `test_api_endpoint.py` - API endpoint tests
- `test_package.py` - Package functionality tests

#### Running Tests
```bash
# Run all tests
pytest

# Run specific test file
pytest test_auth.py

# Run with verbose output
pytest -v

# Run with coverage
pytest --cov=mcp_cldkctl
```

### Debugging Tools

#### Debug Authentication
```bash
python debug_auth.py
```

#### Debug Environment Switching
```bash
python debug_production_vs_staging.py
```

#### Debug API Endpoints
```bash
python debug_tools.py
```

### Building and Publishing

#### Build Package
```bash
python build_and_publish.py
```

#### Manual Build
```bash
# Build wheel
python -m build

# Build source distribution
python setup.py sdist bdist_wheel
```

---

## 5. Architecture Overview

### System Components

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │    │   MCP Server     │    │  Cloudeka API   │
│  (Claude/Cursor)│◄──►│  (mcp-cldkctl)   │◄──►│  (ai.cloudeka.id)│
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │   Local Cache    │
                       │  (~/.cldkctl/)   │
                       └──────────────────┘
```

### Data Flow

1. **MCP Client Request**: AI assistant sends tool call request
2. **MCP Server Processing**: Server validates and processes the request
3. **Authentication Check**: Verify JWT token or re-authenticate if needed
4. **API Call**: Make authenticated request to Cloudeka API
5. **Response Processing**: Format and return response to client
6. **Caching**: Store authentication tokens locally

### Authentication Flow

```
┌─────────────┐    ┌──────────────┐    ┌─────────────┐    ┌─────────────┐
│   cldkctl   │───►│   JWT Token  │───►│   API Call  │───►│   Response  │
│   Token     │    │   (24h exp)  │    │             │    │             │
└─────────────┘    └──────────────┘    └─────────────┘    └─────────────┘
                          │
                          ▼
                   ┌──────────────┐
                   │ Local Cache  │
                   │ (~/.cldkctl) │
                   └──────────────┘
```

### Environment Fallback Mechanism

```
┌─────────────────┐
│ Try Production  │
│ (ai.cloudeka.id)│
└─────────┬───────┘
          │
          ▼
┌─────────────────┐
│ Database Error? │
│ (cldkctl_tokens)│
└─────────┬───────┘
          │ Yes
          ▼
┌─────────────────┐
│ Try Staging     │
│ (staging.ai...) │
└─────────┬───────┘
          │
          ▼
┌─────────────────┐
│ Cache Working   │
│ Environment     │
└─────────────────┘
```

### File Structure

```
mcp-cldkctl/
├── mcp_cldkctl/
│   ├── __init__.py          # Package initialization, token loading
│   ├── __main__.py          # CLI entry point
│   ├── server.py            # Main MCP server implementation
│   └── tool_param_map.py    # Tool definitions and API mappings
├── pyproject.toml           # Package configuration
├── README.md               # Package documentation
└── build_and_publish.py    # Build and deployment script
```

### Key Features

#### Smart Token Management
- **Automatic Loading**: Reads from environment variables, `mcp.json`, or cache
- **Persistent Storage**: Caches JWT tokens locally with expiration tracking
- **Auto-Reauthentication**: Seamlessly renews expired tokens
- **Environment Persistence**: Remembers working environment (production/staging)

#### Tool Generation
- **Dynamic Tool Creation**: Generates MCP tools from `TOOL_PARAM_MAP`
- **Parameter Validation**: Validates required and optional parameters
- **Type Mapping**: Converts API types to JSON schema types
- **Error Handling**: Comprehensive error handling and reporting

#### API Integration
- **RESTful Interface**: Full REST API coverage for all cldkctl endpoints
- **Method Support**: GET, POST, PUT, PATCH, DELETE operations
- **Path Parameters**: Dynamic URL parameter substitution
- **Query/Body Handling**: Automatic parameter routing based on HTTP method

### Security Considerations

- **Token Encryption**: JWT tokens stored with base64 encoding
- **Local Storage**: Authentication data stored in user's home directory
- **Environment Isolation**: Separate configurations for production/staging
- **Automatic Cleanup**: Expired tokens automatically removed from cache

### Performance Optimizations

- **Connection Pooling**: Reuses HTTP connections for better performance
- **Caching Strategy**: 24-hour JWT token caching reduces authentication overhead
- **Lazy Loading**: Tools loaded only when needed
- **Error Recovery**: Automatic retry mechanisms for transient failures

## 5. API Testing Summary

| Group            | Tool Name / Action         | Endpoint (from note.txt)                                         | Result / Notes                                 | Status   |
|------------------|---------------------------|------------------------------------------------------------------|------------------------------------------------|----------|
| **User & Profile** | Auth (token)              | /core/cldkctl/auth                                               | Success, valid JWT                             | ✅        |
|                  | Login                     | /core/user/login                                                 | 400 Bad Request (no backend handler)           | ❌        |
|                  | ProfileDetail             | /core/user/profile                                               | Success                                        | ✅        |
|                  | UpdateProfile             | /core/user/organization/profile/member/:user_id                  | 400 Bad Request (invalid user)                 | ❌        |
|                  | ChangePassword            | /core/user/change-password                                       | 400 Bad Request (invalid password)             | ❌        |
| **Project**      | ProjectList               | /core/user/organization/projects/byOrg                           | Success (1 project found)                      | ✅        |
|                  | ProjectDetail             | /core/user/project/detail/:project_id                            | Success                                        | ✅        |
|                  | UpdateProject             | /core/user/projects/:project_id                                  | 400 Bad Request                                | ❌        |
|                  | CheckBeforeDeleteProject  | /core/user/checking/projects/:project_id                         | Success                                        | ✅        |
|                  | DeleteProject             | /core/user/projects/:project_id                                  | Not tested (no delete performed)               | -        |
|                  | ProjectRQuotaPost         | /mid/billing/projectdekagpu/quota/:project_id                    | Not tested                                     | -        |
|                  | ProjectRQuotaPre          | /mid/billing/projectflavorgpu/project/:project_id                | Not tested                                     | -        |
| **Balance & Billing** | BalanceDetail         | /core/balance/accumulated/:project_id                            | Success (all balances 0)                       | ✅        |
|                  | PaymentHistory            | /core/payment/history                                            | Not tested                                     | -        |
|                  | BillingDailyCost          | /core/billing/v2/daily-cost/:project_id                          | Not tested                                     | -        |
|                  | BillingMonthlyCostTotalBilled | /core/billing/monthly-cost/total-billed/:project_id           | Not tested                                     | -        |
|                  | BillingHistoryDetail      | /core/billing/v2/history                                         | Success (empty)                                | ✅        |
|                  | BillingInvoiceEnterprise  | /core/billing/invoice/:project_id                                | Success (empty)                                | ✅        |
| **VM**           | GetVm                     | /core/virtual-machine/list/all                                   | 400 Bad Request (Python client/tool), CLI works| ❌/✅     |
|                  | VmDetail                  | /core/virtual-machine/detail-vm                                  | Not tested (no VM ID)                          | -        |
|                  | CreateVm                  | /core/virtual-machine                                            | Not tested                                     | -        |
|                  | DeleteVm                  | /core/virtual-machine/delete                                     | Not tested                                     | -        |
| **Organization** | OrgDetail                 | /core/user/organization                                          | Success                                        | ✅        |
|                  | OrgMemberList             | /core/user/organization/member                                   | Success (1 member: you)                        | ✅        |
|                  | OrgRoleList               | /core/user/organization/role                                     | Success (Owner, Member)                        | ✅        |
|                  | OrgMemberAdd/Edit/Delete  | /core/user/organization/member                                   | 400 Bad Request or restricted                  | ❌        |
|                  | OrgMemberActivate         | /core/user/manageuser/active/:user_id                            | Success                                        | ✅        |
|                  | OrgMemberDeactivate       | /core/user/manageuser/deactive/:user_id                          | No result (restricted)                         | ❌        |
|                  | OrgMemberResendInvitation | /core/superadmin/manageuser/resend-verified/:user_id             | 400 Bad Request                                | ❌        |
| **Kubernetes**   | KubeDashboard             | /core/user/projects/:project_id/vcluster/dashboard               | API Error                                      | ❌        |
|                  | Kubeconfig                | /core/user/projects/:project_id/vcluster/kubeconfig              | 400 Bad Request                                | ❌        |
|                  | GetPod                    | /core/pods                                                       | Success (1 pod: coredns)                       | ✅        |
|                  | GetDeployment             | /core/deployment                                                 | Success (1 deployment: coredns)                | ✅        |
|                  | GetService                | /core/kubernetes/services                                        | Success (3 services)                           | ✅        |
|                  | GetNamespace              | /core/user/projects/:project_id/vcluster/namespaces              | Success (3 namespaces)                         | ✅        |
|                  | GetConfigMap              | /core/kubernetes/configmaps                                      | Success (multiple configmaps)                  | ✅        |
|                  | GetSecret                 | /core/kubernetes/secrets                                         | Success (1 secret)                             | ✅        |
| **Registry**     | RegistryList              | /core/dekaregistry/v2/registry                                   | 400 Bad Request (no registry)                  | ❌        |
|                  | RegistryDetail/Overview   | /core/dekaregistry/v2/registry/:registry_id                      | 400 Bad Request (invalid registry ID)          | ❌        |
|                  | RegistryMemberList/Add    | /core/dekaregistry/v2/member/:registry_id                        | 400 Bad Request (invalid registry ID)          | ❌        |
| **Notebook**     | NotebookList              | /core/deka-notebook                                              | Success (empty)                                | ✅        |
|                  | NotebookCreate            | /core/deka-notebook                                              | 400 Bad Request (invalid image/spec)           | ❌        |
| **Voucher**      | VoucherClaimedList        | /core/user/voucher-credit/claimed                                | Success (empty)                                | ✅        |
|                  | VoucherTrialClaimedList   | /core/user/voucher/claimed                                       | Success (empty)                                | ✅        |
|                  | VoucherClaim              | /core/user/voucher-credit/claim                                  | Requires claim data                            | ❌        |
| **Audit**        | AuditLog                  | /core/api/v1.1/user/activity/sp/get-auditlog                     | 404 Not Found                                  | ❌        |
| **Superadmin**   | SuperadminBalanceDetail   | /core/superadmin/balance/accumulated/:organization_id/:project_id| Success (all balances 0)                       | ✅        |
|                  | SuperadminBillingInvoiceEnterprise | /core/superadmin/invoice/:organization_id/:project_id     | Success (empty)                                | ✅        |
|                  | SuperadminProjectDetail   | /core/user/project/detail/:project_id                            | Success                                        | ✅        |
