# 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

```bash
npx cube-mcp
```

### Add to Claude Code

```bash
claude mcp add cube -- npx cube-mcp
```

## 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 |
| `kubectl_exec` | Run kubectl commands (server-side) |

### Apollo Environments

| Tool | Description |
|------|-------------|
| `list_environments` | List Apollo environments |
| `create_environment` | Create a new environment |
| `replicate_environment` | Clone an environment |
| `install_entity` | Install a Helm chart entity |
| `entity_health` | Get entity health status |
| `plan_details` | Get plan tasks, events, and error logs |

### Build & Publish

| 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 |

### 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 |

## Local Development

```bash
# Install dependencies
uv sync --dev

# 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.
