# CLAUDE.md

## Project Overview

MCP (Metacircular Control Plane) is the orchestrator for the Metacircular platform. It manages container lifecycle, tracks what services run where, and transfers files between the operator's workstation and managed nodes.

## Architecture

MCP has two components:
- **CLI** (`mcp`) — thin client on the operator's workstation. Reads local service definition files, pushes intent to agents, queries status. No database.
- **Agent** (`mcp-agent`) — smart per-node daemon. Manages containers via podman, stores the registry (SQLite), monitors for drift, alerts the operator.

Services have one or more components (containers). Container naming: `<service>-<component>`.

## v2 Development (Multi-Node)

MCP v2 extends the single-node agent model to a multi-node fleet with a central master process. See the root repo's `docs/phase-e-plan.md` and `docs/architecture-v2.md` for the full design.

**Current state:**
- **svc** is operational as an edge node (manages mc-proxy routing only, no containers)
- **rift** runs the agent with full container management
- **orion** is provisioned but offline for maintenance

**Key v2 concepts (in development):**
- **mcp-master** — central orchestrator on rift. Accepts CLI commands, dispatches to agents, maintains node registry, coordinates edge routing.
- **Agent self-registration** — agents register with the master on startup (name, role, address, arch). No static node config required after bootstrap.
- **Tier-based placement** — `tier = "core"` runs on the master node, `tier = "worker"` (default) is auto-placed on a worker with capacity, `node = "<name>"` overrides for pinned services.
- **Edge routing** — `public = true` on routes declares intent; the master assigns the route to an edge node (currently svc).

## Build Commands

```bash
make all          # vet → lint → test → build both binaries
make build        # go build ./...
make test         # go test ./...
make vet          # go vet ./...
make lint         # golangci-lint run ./...
make proto        # regenerate gRPC code from .proto files
make proto-lint   # buf lint + buf breaking
make mcp          # build CLI binary
make mcp-agent    # build agent binary
make clean        # remove binaries
```

Run a single test: `go test ./internal/registry/ -run TestComponentCRUD`

## Project Structure

- `cmd/mcp/` — CLI entry point
- `cmd/mcp-agent/` — Agent entry point
- `internal/agent/` — Agent core (deploy, lifecycle, sync, adopt, status, files, edge_rpc, dns, proxy, certs)
- `internal/runtime/` — Container runtime abstraction (podman)
- `internal/registry/` — SQLite registry (services, components, events)
- `internal/monitor/` — Monitoring subsystem (watch loop, alerting)
- `internal/servicedef/` — Service definition file parsing (TOML)
- `internal/auth/` — MCIAS integration (token validation, interceptor)
- `internal/config/` — Configuration loading (CLI + agent)
- `proto/mcp/v1/` — Proto definitions
- `gen/mcp/v1/` — Generated Go gRPC code

## Critical Rules

1. Agent is gRPC-only (no REST). This is a deliberate exception to the platform's REST+gRPC parity rule.
2. Container naming convention: `<service>-<component>` (e.g., `metacrypt-api`, `metacrypt-web`).
3. File operations are scoped to `/srv/<service>/`. Path traversal is rejected.
4. Alert commands use exec-style invocation (argv array, no shell). Never use `sh -c`.
5. The agent binds to the overlay interface only, not all interfaces. It does NOT sit behind MC-Proxy.
6. Every RPC is audit-logged at info level (method, caller, timestamp).
7. `active: true/false` in service definitions controls desired state. `mcp stop/start` update the file.

## Module Path

`git.wntrmute.dev/mc/mcp`