# MCP — Metacircular Control Plane

MCP is the orchestrator for the [Metacircular](https://metacircular.net)
platform. It manages container lifecycle, tracks what services run where,
and transfers files between the operator's workstation and managed nodes.

## Architecture

**CLI** (`mcp`) — thin client on the operator's workstation. Reads local
service definition files, pushes intent to agents, queries status.

**Agent** (`mcp-agent`) — per-node daemon. Manages containers via rootless
podman, stores a SQLite registry of desired/observed state, monitors for
drift, and alerts the operator.

## Quick Start

### Build

```bash
make all          # vet, lint, test, build
make mcp          # CLI only
make mcp-agent    # agent only
```

### Install the CLI

```bash
cp mcp ~/.local/bin/
mkdir -p ~/.config/mcp/services
```

Create `~/.config/mcp/mcp.toml`:

```toml
[services]
dir = "/home/<user>/.config/mcp/services"

[mcias]
server_url   = "https://mcias.metacircular.net:8443"
service_name = "mcp"

[auth]
token_path = "/home/<user>/.config/mcp/token"

[[nodes]]
name = "rift"
address = "100.95.252.120:9444"
```

### Authenticate

```bash
mcp login
```

### Check status

```bash
mcp status    # full picture: services, drift, events
mcp ps        # live container check with uptime
mcp list      # quick registry query
```

### Deploy a service

Write a service definition in `~/.config/mcp/services/<name>.toml`:

```toml
name = "myservice"
node = "rift"
active = true

[[components]]
name = "api"
image = "mcr.svc.mcp.metacircular.net:8443/myservice:v1.0.0"
network = "mcpnet"
user = "0:0"
restart = "unless-stopped"
ports = ["127.0.0.1:8443:8443"]
volumes = ["/srv/myservice:/srv/myservice"]
cmd = ["server", "--config", "/srv/myservice/myservice.toml"]
```

Then deploy:

```bash
mcp deploy myservice
```

## Commands

| Command | Description |
|---------|-------------|
| `mcp login` | Authenticate to MCIAS |
| `mcp deploy <service>[/<component>]` | Deploy from service definition |
| `mcp stop <service>` | Stop all components |
| `mcp start <service>` | Start all components |
| `mcp restart <service>` | Restart all components |
| `mcp list` | List services (registry) |
| `mcp ps` | Live container check |
| `mcp status [service]` | Full status with drift and events |
| `mcp sync` | Push all service definitions |
| `mcp adopt <service>` | Adopt running containers |
| `mcp service show <service>` | Print spec from agent |
| `mcp service edit <service>` | Edit definition in $EDITOR |
| `mcp service export <service>` | Export agent spec to file |
| `mcp push <file> <service> [path]` | Push file to node |
| `mcp pull <service> <path> [file]` | Pull file from node |
| `mcp node list` | List nodes |
| `mcp node add <name> <addr>` | Add a node |
| `mcp node remove <name>` | Remove a node |

## Documentation

- [ARCHITECTURE.md](ARCHITECTURE.md) — design specification
- [RUNBOOK.md](RUNBOOK.md) — operational procedures
- [PROJECT_PLAN_V1.md](PROJECT_PLAN_V1.md) — implementation plan
- [PROGRESS_V1.md](PROGRESS_V1.md) — progress and remaining work