# Cube MCP Server - Developer Setup Guide

This guide will help you set up the Cube MCP server to interact with EdgescaleAI Cubes through Claude Code.

## Prerequisites

Before installing, ensure you have:

1. **Python 3.10+** installed
   ```bash
   python3 --version  # Should be 3.10 or higher
   ```

2. **Teleport client (tsh)** installed
   - Download from: https://goteleport.com/download/
   - Verify installation:
     ```bash
     tsh version
     ```

3. **kubectl** installed
   - Download from: https://kubernetes.io/docs/tasks/tools/
   - Verify installation:
     ```bash
     kubectl version --client
     ```

4. **Claude Code** installed
   - Install via: `npm install -g @anthropic-ai/claude-code`
   - Or see: https://claude.ai/code

---

## Installation

### Step 1: Install the Cube MCP package

```bash
pip3 install cube_mcp-0.1.0-py3-none-any.whl
```

### Step 2: Find the cube-mcp executable path

You need the **full path** to the actual executable (not a shim):

```bash
# Find where it's installed
which cube-mcp

# If using pyenv, get the actual path (not the shim)
# Example: /Users/yourname/.pyenv/versions/3.11.6/bin/cube-mcp
```

### Step 3: Add to Claude Code

Use the `claude mcp add` command with the full path:

```bash
claude mcp add cube -- /full/path/to/cube-mcp
```

For example:
```bash
claude mcp add cube -- /Users/yourname/.pyenv/versions/3.11.6/bin/cube-mcp
```

**For global availability** (recommended - works in all projects):

```bash
claude mcp add --scope user cube -- /full/path/to/cube-mcp
```

Scope options:
- `--scope user` - Available globally in all projects
- `--scope project` - Only available in current project
- `--scope local` - Default, stored in local config

### Step 4: Verify installation

```bash
claude mcp list
```

You should see `cube` in the list.

### Step 5: Restart Claude Code

Start a new conversation or restart Claude Code to use the tools.

---

## Usage

Once configured, you can interact with Cubes using natural language in Claude Code:

### List available Cubes
```
"What Cubes are available?"
"Show me the list of Cube clusters"
```

### Connect to a Cube
```
"Connect me to the staging-int Cube"
"Login to staging-pre-prod"
```

This will open your browser for Teleport SSO authentication.

### Check Cube status
```
"What's the status of the Cube?"
"Show me the node conditions"
```

---

## Available Commands

| Command | Description |
|---------|-------------|
| `cube_login` | Connect to a Cube cluster via Teleport SSO |
| `cube_list` | List all available Cube clusters |
| `cube_status` | Get status of the connected Cube node |

---

## Troubleshooting

### "cube-mcp: command not found"

Find the actual executable path:

```bash
# If using pyenv, find the real path
ls ~/.pyenv/versions/*/bin/cube-mcp

# Or check where pip installed it
pip3 show cube-mcp | grep Location
```

Use the full path when running `claude mcp add`.

### "tsh: command not found"

Install the Teleport client:
- macOS: `brew install teleport`
- Linux: See https://goteleport.com/download/
- Windows: Download from https://goteleport.com/download/

### "kubectl: command not found"

Install kubectl:
- macOS: `brew install kubectl`
- Linux: See https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/
- Windows: See https://kubernetes.io/docs/tasks/tools/install-kubectl-windows/

### MCP server not appearing in Claude Code

1. Verify it's registered: `claude mcp list`
2. Ensure you used the full path to the executable (not a shim)
3. Start a new conversation or restart Claude Code
4. Try removing and re-adding: `claude mcp remove cube` then `claude mcp add cube -- /path/to/cube-mcp`

### TLS Certificate errors

If you get certificate errors when connecting to a Cube:

```bash
kubectl config set-cluster <full-cluster-name> --insecure-skip-tls-verify=true
```

### Teleport authentication issues

Try logging in manually first:
```bash
tsh login --proxy=edgescaleai.teleport.sh
```

If this works but the MCP server doesn't, ensure your browser is set as the default for handling auth callbacks.

---

## Support

For issues or questions, contact the EdgescaleAI team.
