muster: Instructions file for Codex

AGENTS.md

This file provides guidance to coding agents working with code in this repository.

What is Muster

Muster is a universal control plane and meta-MCP (Model Context Protocol) server aggregator for platform engineers and AI agents. It manages multiple backend MCP servers, provides intelligent tool discovery/filtering, includes a mcp-native workflow engine, and exposes its own functionality through mcp tools as well.

Build & Development Commands

# Build
go build -o ./muster .         # Build the worktree-local binary (gitignored); rebuild after every code change
./muster ...                    # Run it from the worktree; do not `go install` (overwrites the shared ~/.go/bin/muster)

# Testing
make test                         # Unit tests with race detector
./muster test --scenario <name> --verbose         # Run a single BDD scenario
./muster test --scenario <name> --verbose --debug # With debug output
./muster test --parallel 50 --base-port 20000     # Run all scenarios (never 30000-32767: kind NodePorts)

# Code quality (run before every commit)
goimports -w . && go fmt ./...    # Format code
make lint                         # golangci-lint with gosec and goconst
make vet                          # go vet

# Helm
make helm-lint                    # Lint Helm chart

Architecture

Service Locator Pattern (mandatory)

All inter-package communication goes through internal/api. This is the most critical architectural rule:

• internal/api defines handler interfaces in handlers.go and depends on no other internal package
• Each service package creates an api_adapter.go implementing the handler interface
• Adapters register themselves via api.RegisterXxx() functions
• Consumers retrieve handlers via api.GetXxx() — never import service packages directly
• Anti-pattern: Never import workflow or mcpserver packages directly

Key Packages

• cmd/ — CLI commands (serve, agent, auth, test, create, get, list)
• internal/api/ — Central service locator with handler interfaces and type definitions
• internal/app/ — Application bootstrap, lifecycle, config loading, service registration
• internal/aggregator/ — MCP server aggregation, registry, transports (SSE, stdio, streamable-http)
• internal/agent/ — MCP client, interactive REPL, MCP server mode for AI assistants
• internal/mcpserver/ — MCP server process management and health checking
• internal/workflow/ — Workflow definitions, execution engine, templating
• internal/orchestrator/ — Service lifecycle orchestration and state machine
• internal/testing/ — BDD test framework, scenarios in scenarios/*.yaml
• pkg/ — Public packages (Kubernetes APIs, auth, logging, OAuth)