muster CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when 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 and install
make build                        # Build local binary
go install                        # Install binary (use after every code change)

# 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 30000     # Run all scenarios

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