Skip to content

serve.md

Latest commit

 

History

History
336 lines (254 loc) · 8.41 KB

serve.md

File metadata and controls

336 lines (254 loc) · 8.41 KB
Raw

muster serve

Start the Muster control plane server.

Synopsis

muster serve [OPTIONS]

Description

The serve command starts the Muster control plane, which manages MCP servers, workflows, services, and provides the unified API for agent interactions. This is the core command that enables all other Muster functionality.

The aggregator server provides a unified MCP interface that other muster commands can connect to. Once started, you can use commands like muster list, muster create, muster start, etc. to interact with the running server.

Options

Server Configuration

  • --config-path (string): Custom configuration directory path
    • Default: ~/.config/muster
    • Directory should contain config.yaml and subdirectories: mcpservers/, workflows/, services/

Logging and Debugging

  • --debug: Enable debug-level logging and verbose output
    • Default: false
    • Provides detailed information about service startup and operations
  • --silent: Disable console log output (writer → io.Discard)
    • Default: false
    • Useful for programmatic usage or when console output needs to be suppressed
    • Does not silence OTLP. When OTLP is configured (via OTEL_EXPORTER_OTLP_* or OTEL_LOGS_EXPORTER), log records still flow to the collector. To disable OTLP, unset those env vars or set OTEL_SDK_DISABLED=true.

Security and Safety

  • --yolo: Disable denylist for destructive tool calls
    • Default: false
    • WARNING: Use with extreme caution. This removes safety restrictions on potentially destructive operations

Configuration

The serve command uses configuration from config.yaml in the configuration directory:

# Default configuration structure
server:
  port: 8080
  host: "0.0.0.0"
  timeout: "30s"

mcpServers:
  autoStart: true
  timeout: "30s"
  healthCheckInterval: "30s"

logging:
  level: "info"
  format: "text"

storage:
  dataDir: "~/.local/share/muster"
  tempDir: "/tmp"

# Component directories
directories:
  mcpservers: "mcpservers/"
  workflows: "workflows/"
  services: "services/"

Startup Sequence

When you run muster serve, the following initialization occurs:

  1. Configuration Loading

    • Loads configuration from the specified directory
    • Supports layered configuration (defaults + user + project)
    • Validates configuration structure

  2. Service Initialization

    • Sets up API service locator pattern
    • Initializes orchestrator for service lifecycle management
    • Registers all service adapters with the API layer

  3. Component Loading

    • Loads MCP server definitions from mcpservers/
    • Loads workflow definitions from workflows/
    • Loads service instances from services/

  4. Auto-Start Services

    • Starts all configured MCP servers with autoStart: true
    • Initializes the aggregator service for tool access
    • Starts any service instances marked for auto-start

  5. Server Ready

    • Begins accepting connections on the configured port
    • Provides unified MCP interface for client connections

Examples

Basic Usage

# Start with default settings
muster serve

# Logs will show startup progress:
# INFO: Setting up orchestrator for service management
# INFO: Loading MCP servers from ~/.config/muster/mcpservers/
# INFO: Services started. Press Ctrl+C to stop all services and exit.

Custom Configuration Directory

# Use custom configuration path
muster serve --config-path /etc/muster

# For development with local config
muster serve --config-path ./local-config

Debug Mode

# Start with debug logging
muster serve --debug

# Debug output includes:
# DEBUG: Loaded configuration from custom path: /etc/muster
# DEBUG: Initializing service registry
# DEBUG: Registering MCP server adapter
# DEBUG: Starting MCP server: kubernetes

Production Setup

# Production server configuration
muster serve \
  --config-path /etc/muster \
  --silent

# Recommended systemd service setup

Development Mode

# Development with debug output
muster serve \
  --debug \
  --config-path ./dev-config

Configuration File Structure

The configuration directory should be organized as follows:

/path/to/config/
├── config.yaml              # Main configuration
├── mcpservers/              # MCP server definitions
│   ├── kubernetes.yaml
│   ├── prometheus.yaml
│   └── github.yaml
├── workflows/               # Workflow definitions
│   ├── deploy-app.yaml
│   └── backup-db.yaml
└── services/                # Service instances
    ├── my-web-app.yaml
    └── prod-database.yaml

Environment Variables

Variable Description Default
MUSTER_CONFIG_PATH Override default configuration directory ~/.config/muster
MUSTER_DEBUG Enable debug mode false
MUSTER_LOG_LEVEL Set log level (debug|info|warn|error) info

Exit Codes

Code Meaning
0 Server shutdown cleanly
1 Configuration error or invalid arguments
2 Service initialization failed
3 Failed to start required services
130 Interrupted by signal (Ctrl+C)

Signals

The serve command handles the following signals for graceful shutdown:

  • SIGINT (Ctrl+C): Initiates graceful shutdown sequence
  • SIGTERM: Initiates graceful shutdown sequence

During shutdown:

  1. Stops accepting new connections
  2. Gracefully stops all running services
  3. Saves any pending state
  4. Exits cleanly

Troubleshooting

Configuration Errors

Error: Failed to load muster configuration

# Check configuration file exists and is valid YAML
ls -la ~/.config/muster/config.yaml
muster serve --debug  # Shows detailed error information

Error: Failed to initialize services

# Verify configuration directory structure
ls -la ~/.config/muster/
mkdir -p ~/.config/muster/{mcpservers,workflows,services}

MCP Server Issues

Error: MCP servers fail to start

# Check MCP server configurations
muster serve --debug

# Verify MCP server binaries are available
which mcp-kubernetes
which mcp-prometheus

Port Conflicts

Error: Address already in use

# Check what's using the port
netstat -tulpn | grep :8080
lsof -i :8080

# Edit config.yaml to use different port
# server:
#   port: 8081

Permission Issues

Error: Permission denied accessing configuration

# Check directory permissions
ls -la ~/.config/muster
chmod 755 ~/.config/muster
chmod 644 ~/.config/muster/config.yaml

# For system-wide configuration
sudo chown -R muster:muster /etc/muster

Service Dependencies

Error: Services fail to start due to dependencies

# Start without auto-start to debug
# Edit config.yaml:
# mcpServers:
#   autoStart: false

# Then start services individually using other commands
muster list mcpserver
muster start service <service-name>

Integration with Other Commands

After starting the server, you can use other Muster commands:

# In one terminal
muster serve

# In another terminal
muster list service           # List all services
muster create service my-app
muster agent --repl          # Interactive tool exploration
muster test --scenario basic-crud  # Run tests

IDE Integration

To connect Muster to your IDE (Cursor, VSCode, etc.):

# Start the server
muster serve

# In your IDE's MCP configuration, use:
muster agent --mcp-server

Related Commands

  • agent - Connect to the server interactively
  • list - List resources managed by the server
  • get - Get detailed resource information
  • create - Create new resources
  • test - Test server functionality

Advanced Usage

Custom Configuration Loading

# Single-path configuration (no layering)
muster serve --config-path /opt/muster/config

# Development with debug and custom path
muster serve --debug --config-path ./test-config

Security Considerations

# Production: Run without --yolo flag
muster serve --config-path /etc/muster

# Development: Use --yolo for testing only
muster serve --debug --yolo --config-path ./dev-config

Monitoring and Health Checks

The server exposes health and status information:

# Check server status (from another terminal)
curl http://localhost:8080/api/v1/status

# Monitor logs in real-time
muster serve --debug | tee muster.log