# pi-controller-mcp

MCP (Model Context Protocol) server for managing Raspberry Pi K3s clusters via AI assistants like Claude Code.

## Features

- 🎯 **26 AI Tools** for complete cluster lifecycle management
- 📊 **7 Resources** providing real-time cluster context
- 🔐 **Secure Authentication** with JWT and API keys
- 🛡️ **RBAC Integration** respecting viewer/operator/admin roles
- 🔌 **GPIO Control** for hardware management
- 📦 **Zero Configuration** works out of the box with npx

## Quick Start

### 1. Configure Claude Code

Add to your `~/.config/claude-code/mcp.json` (or project `.mcp.json`):

```json
{
  "mcpServers": {
    "pi-controller": {
      "command": "npx",
      "args": ["-y", "pi-controller-mcp"],
      "env": {
        "PI_CONTROLLER_URL": "https://pi-controller.local:8080",
        "PI_CONTROLLER_USERNAME": "admin",
        "PI_CONTROLLER_PASSWORD": "your-password"
      }
    }
  }
}
```

### 2. Start Using with AI

```
User: "Create a 3-node K3s cluster called 'homelab'"

Claude: I'll help you create a cluster...
[Uses create_cluster tool]
[Uses discover_nodes tool]
[Uses provision_cluster tool]
```

## Available Tools

### Cluster Management
- `create_cluster` - Create cluster definition
- `list_clusters` - List all clusters
- `get_cluster_status` - Get detailed cluster status
- `provision_cluster` - Provision K3s on nodes
- `scale_cluster` - Scale cluster nodes
- `delete_cluster` - Delete cluster

### Node Management
- `discover_nodes` - List discovered Raspberry Pi nodes
- `get_node_info` - Get node details and hardware info
- `register_node` - Manually register a node
- `provision_node` - Provision K3s on single node
- `deprovision_node` - Remove K3s from node

### GPIO Control
- `list_gpio_devices` - List all GPIO devices
- `create_gpio_device` - Register GPIO device
- `read_gpio_pin` - Read pin value
- `write_gpio_pin` - Write to pin (HIGH/LOW)
- `reserve_gpio_pin` - Reserve pin for exclusive use
- `release_gpio_pin` - Release reservation
- `get_gpio_readings` - Get historical readings
- `delete_gpio_device` - Remove GPIO device

### Deployment
- `deploy_pod` - Deploy Kubernetes pod
- `get_pod` - Get pod information
- `delete_pod` - Delete pod

### Certificate Authority
- `initialize_ca` - Initialize CA
- `issue_certificate` - Issue new certificate
- `list_certificates` - List all certificates
- `revoke_certificate` - Revoke certificate

## Available Resources

Resources provide AI with real-time context about your clusters:

- `cluster://{cluster_id}/status` - Cluster health and metrics
- `cluster://{cluster_id}/nodes` - Node list with status
- `node://{node_id}/info` - Hardware specs and capabilities
- `node://{node_id}/metrics` - CPU, memory, temperature
- `node://{node_id}/gpio` - GPIO devices on node
- `gpio://{gpio_id}/state` - Current pin state
- `system://health` - Overall system health

## Configuration

### Environment Variables

| Variable | Required | Description | Default |
|----------|----------|-------------|---------|
| `PI_CONTROLLER_URL` | ✅ | Pi-controller API URL | - |
| `PI_CONTROLLER_API_KEY` | ⚠️* | API key for auth | - |
| `PI_CONTROLLER_USERNAME` | ⚠️* | Username for auth | - |
| `PI_CONTROLLER_PASSWORD` | ⚠️* | Password for auth | - |
| `PI_CONTROLLER_TLS_VERIFY` | ❌ | Verify TLS certs | `true` |
| `PI_CONTROLLER_TLS_CA_CERT` | ❌ | Path to CA cert | - |
| `PI_CONTROLLER_TIMEOUT` | ❌ | Request timeout (ms) | `30000` |
| `LOG_LEVEL` | ❌ | Logging level | `info` |

*Either API key or username/password required

### Authentication Methods

**Method 1: API Key (Recommended)**
```json
{
  "env": {
    "PI_CONTROLLER_URL": "https://pi-controller.local:8080",
    "PI_CONTROLLER_API_KEY": "your-api-key"
  }
}
```

**Method 2: Username/Password**
```json
{
  "env": {
    "PI_CONTROLLER_URL": "https://pi-controller.local:8080",
    "PI_CONTROLLER_USERNAME": "admin",
    "PI_CONTROLLER_PASSWORD": "secure-password"
  }
}
```

## Examples

### Create and Provision Cluster

```
User: "Create a K3s cluster with 1 master and 2 workers"

AI uses:
1. create_cluster → Creates cluster definition
2. discover_nodes → Finds available Pi nodes
3. provision_cluster → Installs K3s on selected nodes
4. cluster://{id}/status → Monitors provisioning progress
```

### Control GPIO Hardware

```
User: "Turn on the LED on GPIO pin 18"

AI uses:
1. discover_nodes → Finds the right node
2. list_gpio_devices → Locates GPIO device on pin 18
3. write_gpio_pin → Sets pin value to HIGH (1)
4. gpio://{id}/state → Confirms new state
```

### Deploy Application

```
User: "Deploy nginx on the homelab cluster"

AI uses:
1. list_clusters → Finds homelab cluster
2. deploy_pod → Creates nginx pod
3. get_pod → Verifies deployment
```

## Development

### Setup

```bash
git clone https://github.com/dsyorkd/pi-controller-mcp.git
cd pi-controller-mcp
npm install
```

### Run in Development

```bash
# Copy environment template
cp .env.example .env

# Edit .env with your pi-controller URL and credentials
nano .env

# Start in watch mode
npm run dev
```

### Build

```bash
npm run build
```

### Test

```bash
# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests (requires running pi-controller)
npm run test:integration
```

## Architecture

```
pi-controller-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── config.ts             # Configuration loader
│   ├── client/
│   │   ├── pi-controller-client.ts  # REST API client
│   │   └── auth.ts           # Authentication
│   ├── tools/
│   │   ├── cluster.ts        # Cluster tools
│   │   ├── node.ts           # Node tools
│   │   ├── gpio.ts           # GPIO tools
│   │   ├── deployment.ts     # Deployment tools
│   │   └── ca.ts             # CA tools
│   ├── resources/
│   │   ├── cluster-status.ts # Cluster resources
│   │   ├── node-info.ts      # Node resources
│   │   ├── gpio-state.ts     # GPIO resources
│   │   └── metrics.ts        # Metrics resources
│   └── types/
│       └── pi-controller.ts  # Type definitions
```

## Troubleshooting

### Connection Issues

**Error:** `Cannot connect to pi-controller`

**Solutions:**
1. Verify `PI_CONTROLLER_URL` is correct
2. Check pi-controller is running: `curl ${PI_CONTROLLER_URL}/health`
3. Verify network connectivity
4. Check TLS certificate if using HTTPS

### Authentication Issues

**Error:** `Authentication failed`

**Solutions:**
1. Verify credentials in `.mcp.json` or `.env`
2. Check user has required RBAC role
3. For API key: Ensure key is valid and not expired
4. For username/password: Verify credentials are correct

### Permission Issues

**Error:** `Forbidden: insufficient permissions`

**Solutions:**
1. Tools require different RBAC roles:
   - Read operations: `viewer` role
   - Write operations: `operator` role
   - Lifecycle operations: `admin` role
2. Check user role: See pi-controller documentation

## Contributing

1. Fork the repository
2. Create feature branch: `git checkout -b feature/amazing-feature`
3. Commit changes: `git commit -m 'Add amazing feature'`
4. Push to branch: `git push origin feature/amazing-feature`
5. Open Pull Request

See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.

## Related Projects

- **[pi-controller](https://github.com/dsyorkd/pi-controller)** - Main control plane
- **[kubes-aura](https://github.com/dsyorkd/kubes-aura)** - Web UI
- **pi-agent** - Node agent (part of pi-controller)

## License

MIT License - see [LICENSE](LICENSE) file for details

## Support

- 📖 [Documentation](https://docs.pi-controller.io)
- 🐛 [Issue Tracker](https://github.com/dsyorkd/pi-controller-mcp/issues)
- 💬 [Discussions](https://github.com/dsyorkd/pi-controller-mcp/discussions)

---

Built with ❤️ for the Raspberry Pi and AI community