mcp/CLAUDE.md

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

Build Commands

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)
• 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