Kyle Isom
08b3e2a472
All import paths updated to git.wntrmute.dev/mc/. Bumps mcdsl to v1.2.0, mc-proxy to v1.1.0. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
59 lines
2.6 KiB
Markdown
59 lines
2.6 KiB
Markdown
# 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
|
|
|
|
```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)
|
|
- `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`
|