# cube-mcp

MCP server for EdgescaleAI Cube management and Apollo deployments.

## Architecture

**cube-agent** runs locally as an MCP server (via `npx cube-mcp`). It handles authentication, Docker builds, Helm chart packaging, and app proxy tunnels. Server-side operations (Kubernetes, Teleport, Apollo) are proxied to **cube-cloud**, a FastAPI backend hosted on AWS ECS.

```
Claude Code  <-->  cube-agent (local MCP)  <-->  cube-cloud (ECS)  <-->  Teleport / Apollo / K8s
```

## Install

Requires [uv](https://docs.astral.sh/uv/) (or [pipx](https://pipx.pypa.io/)).

```bash
# Add to Claude Code
claude mcp add cube -- npx cube-mcp
```

Or run directly:

```bash
npx cube-mcp    # via Node (calls uvx under the hood)
uvx cube-mcp    # via uv directly
```

## Getting Started

```
You: "Log me in"             → agent_login_browser (opens browser for Cognito login)
You: "Connect to staging"    → cube_cluster_login (merges kubeconfig)
You: "Show Cube status"      → cube_status
```

## Tools

### Auth

| Tool | Description |
|------|-------------|
| `agent_login_browser` | Log in via browser (Cognito) |
| `agent_login` | Log in with an API key |
| `agent_logout` | Remove stored API key |
| `agent_status` | Check auth and connectivity |

### Kubernetes

| Tool | Description |
|------|-------------|
| `cube_list` | List available Cube clusters |
| `cube_status` | Get node status for a cluster |
| `cube_cluster_login` | Get kubeconfig for a cluster (merges into ~/.kube/config) |
| `kubectl_exec` | Run kubectl commands (server-side) |

### Apps

| Tool | Description |
|------|-------------|
| `app_list` | List Teleport apps |
| `app_proxy` | Start local proxy tunnel to an app |
| `app_proxy_stop` | Stop running proxies |
| `app_proxy_status` | Show proxy status |

### Build & Registry

| Tool | Description |
|------|-------------|
| `build_and_publish_to_apollo` | Build Docker image, package chart, push to ACR, publish manifest |
| `acr_get_token` | Get Apollo Container Registry token |
| `apollo_publish_manifest` | Publish a manifest YAML |

### Apollo Environments

| Tool | Description |
|------|-------------|
| `list_environments` | List/search Apollo environments |
| `create_environment` | Create a new environment with control plane |
| `replicate_environment` | Clone modules, entities, configs, and secrets |
| `delete_environment` | Delete an environment |
| `install_entity` | Install a Helm chart entity |
| `uninstall_entity` | Uninstall an entity |
| `entity_health` | Get entity health and activity status |
| `plan_details` | Get plan tasks, events, and error logs |
| `update_entity_config` | Update entity config overrides |
| `enforce_entity_config` | Force re-apply entity configuration |
| `reset_environment_agents` | Reset environment agents |

### Apollo Modules

| Tool | Description |
|------|-------------|
| `install_module` | Install a module on an environment |
| `uninstall_module` | Uninstall a module |
| `list_modules` | List modules in an environment |
| `update_module_variables` | Update module variables |

### Apollo Secrets

| Tool | Description |
|------|-------------|
| `create_secret` | Create a secret on an environment |
| `update_secret` | Update a secret value |

### Apollo Products & Release Channels

| Tool | Description |
|------|-------------|
| `list_products` | List available products |
| `compare_product_versions` | Compare versions of a product |
| `list_release_channels` | List release channels |
| `get_product_releases` | Get releases for a product |
| `add_product_to_release_channel` | Add a product to a release channel |
| `remove_product_from_release_channel` | Remove a product from a release channel |
| `set_label_on_product` | Set a label on a product |
| `remove_label_from_product` | Remove a label from a product |

### Apollo Change Requests

| Tool | Description |
|------|-------------|
| `list_change_requests` | List pending change requests |
| `review_change_request` | Approve or reject a change request |

## Local Development

```bash
# Install dependencies
uv sync --extra dev
uv pip install -e packages/cube-common -e packages/cube-cloud -e packages/cube-agent

# Run tests
uv run pytest packages/ -v

# Run cube-agent locally (for debugging)
uv run cube-agent
```

To test with Claude Code, point the MCP server at your local code:

```bash
claude mcp add cube-local -- uv run --directory /path/to/cube-mcp cube-agent
```

Reload after changes with `/mcp` in Claude Code.

## Contributing

1. Create a branch
2. Make changes
3. Run `uv run pytest packages/ -v`
4. Push and open a PR — tests run automatically
5. Merge to main — auto-publishes to PyPI and npm, auto-deploys to ECS

## Admin

See [docs/admin.md](docs/admin.md) for user management, RBAC, and profile configuration.
