Metadata-Version: 2.4
Name: cube-mcp
Version: 0.3.26
Summary: MCP server for EdgescaleAI Cube operations
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

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

```
┌──────────────────────────────────────────────────────────────────────────────┐
│  LOCAL (developer machine)                                                   │
│                                                                              │
│  ┌─────────────┐    MCP JSON-RPC     ┌──────────────────────────────────┐   │
│  │ Claude Code  │◄──────────────────►│  cube-agent (MCP server)         │   │
│  └─────────────┘                     │                                  │   │
│                                      │  Local tools:                    │   │
│                                      │   • agent_login_browser          │   │
│                                      │   • agent_login / logout         │   │
│                                      │   • agent_status                 │   │
│                                      │   • cube_cluster_login           │   │
│                                      │   • build_and_publish_to_apollo  │   │
│                                      │   • app_proxy / stop / status    │   │
│                                      │                                  │   │
│                                      │  Remote tools:                   │   │
│                                      │   (proxied to cube-cloud ──────) │   │
│                                      └────────┬──────────┬──────────────┘   │
│                                               │          │                   │
│   ~/.kube/config ◄── kubeconfig merge         │          │ WebSocket         │
│   ~/.cube-agent/  ◄── API key storage         │          │ /tunnel           │
│   localhost:PORT  ◄── app proxy listener      │          │                   │
└───────────────────────────────────────────────┼──────────┼───────────────────┘
                                                │          │
                               HTTPS + Bearer   │          │  TCP-over-WS
                               POST /mcp/        │          │  relay
                                                │          │
┌───────────────────────────────────────────────┼──────────┼───────────────────┐
│  CLOUD (AWS ECS)                              │          │                   │
│                                               ▼          ▼                   │
│  ┌────────────────────────────────────────────────────────────────────────┐  │
│  │  cube-cloud (FastAPI)                                                  │  │
│  │                                                                        │  │
│  │  ┌─────────────────────┐     ┌──────────────────────────────────────┐ │  │
│  │  │  Auth Middleware     │     │  RBAC (Cognito + Profiles)          │ │  │
│  │  │  • Validate API key  │────►│  • Cognito group → profile          │ │  │
│  │  │    (DynamoDB lookup)│     │  • Profile → Apollo credentials     │ │  │
│  │  │  • Attach profile   │     │    (AWS Secrets Manager)            │ │  │
│  │  └─────────────────────┘     └──────────────────────────────────────┘ │  │
│  │                                                                        │  │
│  │  Cloud tools (RBAC-gated):                                            │  │
│  │   Kubernetes        Apollo Environments    Apollo Products            │  │
│  │   • cube_list       • list_environments    • list_products            │  │
│  │   • cube_status     • create_environment   • compare_product_versions │  │
│  │   • kubectl_exec    • replicate_environment• list_release_channels    │  │
│  │   • app_list        • delete_environment   • get_product_releases     │  │
│  │                     • install/uninstall_    • add/remove_product_     │  │
│  │   Modules             entity                 to_release_channel       │  │
│  │   • list_modules    • entity_health        • set/remove_label         │  │
│  │   • install_module  • plan_details                                    │  │
│  │   • uninstall_module• update/enforce_      Change Requests            │  │
│  │   • update_module_    entity_config        • list_change_requests     │  │
│  │     variables       • reset_env_agents     • review_change_request    │  │
│  │                                                                        │  │
│  │   Secrets           Registry                                          │  │
│  │   • create_secret   • acr_get_token                                   │  │
│  │   • update_secret   • apollo_publish_manifest                         │  │
│  └────────────────────────┬───────────────────────────┬──────────────────┘  │
│                           │                           │                      │
│  ┌────────────────────────┴────────────────┐          │                      │
│  │  tbot sidecar (Teleport credentials)    │          │                      │
│  │  • IAM join method (Fargate identity)   │          │                      │
│  │  • identity/  → tsh commands            │          │                      │
│  │  • kube/{cluster}/ → kubeconfigs        │          │                      │
│  │  • app-{name}/ → app TLS certs          │          │                      │
│  └──────────┬─────────────────────────────┘          │                      │
│             │                                         │                      │
└─────────────┼─────────────────────────────────────────┼──────────────────────┘
              │                                         │
              │ tsh/tctl (short-lived certs)            │ GraphQL (OAuth2)
              ▼                                         ▼
┌──────────────────────────┐            ┌──────────────────────────────────┐
│  Teleport                │            │  Apollo                          │
│  edgescaleai.teleport.sh │            │  edgescaleai.palantirapollo.com  │
│                          │            │                                  │
│  • Kube clusters         │            │  • Environments & Modules        │
│  • App proxies           │            │  • Entities (Helm charts)        │
│  • SSH access            │            │  • Products & Release Channels   │
│  • Identity & TLS certs  │            │  • Change Requests               │
└──────────────────────────┘            │  • ACR (Docker + Helm registry)  │
                                        └──────────────────────────────────┘
```

### How it works

1. **Local tools** run directly on the developer's machine inside `cube-agent`. These handle authentication (Cognito browser login, API key storage), Docker builds, Helm chart packaging, kubeconfig merging, and app proxy tunnels.

2. **Cloud tools** are proxied from `cube-agent` to `cube-cloud` (FastAPI on AWS ECS) via MCP Streamable HTTP. Every request is authenticated with a Bearer API key validated against DynamoDB.

3. **RBAC** maps Cognito user groups to profiles. Each profile resolves to Apollo OAuth2 credentials stored in AWS Secrets Manager, scoping what the user can access.

4. **Teleport** access is provided by a `tbot` sidecar running alongside `cube-cloud` in the same ECS task. It uses IAM join to obtain short-lived certificates for Kubernetes clusters and app proxies — no `tsh` is needed on the developer's machine.

5. **Apollo** operations (environments, modules, entities, products, releases, change requests) go through a GraphQL API authenticated with per-profile OAuth2 client credentials.

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