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)

Workflow Tool Naming

• Internal/API layer: action_<workflow-name>
• Exposed to users: workflow_<workflow-name> (aggregator maps between them)

Entry Points

• muster serve → app.NewApplication() → initializes all services, starts aggregator
• muster agent → REPL, MCP server, or monitoring modes
• muster test → BDD scenario test runner

Conventions

• Go version: 1.26.0 (toolchain 1.27.2)
• Error handling: Wrap with fmt.Errorf("context: %w", err)
• File size: Keep under 400 lines, refactor larger files
• Package docs: Every package must have a doc.go
• Test coverage: 80% minimum for new code
• No flaky tests: Never use time.Sleep in tests. Never use timers to fix race conditions.
• Schema: Don't edit schema.json manually — generated via muster test --generate-schema
• BDD scenarios are truth: If a scenario fails, fix the code, not the scenario
• Tool naming: <prefix>_<category>_<action> (e.g., x_kubernetes_list_pods)
• Exit codes: 0=success, 1=error, 2=auth required, 3=auth failed

Releases

• The squash title of a merged pull request decides its release version. Never mark a commit or pull request title breaking (fix(aggregator)!:) and never add a BREAKING heading to the CHANGELOG unless a maintainer asked for a major release in that conversation: the release automation cuts the major from the title within seconds. Describe a behaviour change in the CHANGELOG entry and ask whether it warrants a major before merging.
• Debugging a failing scenario, a CI-only failure or a race report: docs/contributing/debugging.md.

Config Locations

• Default: ~/.config/muster/config.yaml
• Project: ./.muster/config.yaml
• Custom: --config-path flag
• Entity definitions: {configPath}/{workflows,mcpservers}/