mcpserver

Documentation

Index

• Constants
• type Option
  • func WithAuthRequiredHook(fn func(*api.MCPServer, *mcpserver.AuthRequiredError)) Option
• type Service
  • func NewService(definition *api.MCPServer, opts ...Option) (*Service, error)
  • func (s *Service) CheckHealth(ctx context.Context) (services.HealthStatus, error)
  • func (s *Service) ConfigurationChanged(newConfig interface{}) bool
  • func (s *Service) GetConfiguration() interface{}
  • func (s *Service) GetConsecutiveFailures() int
  • func (s *Service) GetHealthCheckInterval() time.Duration
  • func (s *Service) GetLastAttempt() *time.Time
  • func (s *Service) GetLogContext() string
  • func (s *Service) GetMCPClient() interface{}
  • func (s *Service) GetNextRetryAfter() *time.Time
  • func (s *Service) GetServiceData() map[string]interface{}
  • func (s *Service) GetServiceType() string
  • func (s *Service) IsClientReady() bool
  • func (s *Service) IsHealthy() bool
  • func (s *Service) IsRunning() bool
  • func (s *Service) IsUnreachable() bool
  • func (s *Service) LogDebug(format string, args ...interface{})
  • func (s *Service) LogError(err error, format string, args ...interface{})
  • func (s *Service) LogInfo(format string, args ...interface{})
  • func (s *Service) LogWarn(format string, args ...interface{})
  • func (s *Service) Restart(ctx context.Context) error
  • func (s *Service) Start(ctx context.Context) error
  • func (s *Service) Stop(ctx context.Context) error
  • func (s *Service) UpdateConfiguration(newConfig interface{}) error
  • func (s *Service) ValidateConfiguration() error

Constants

const (
	// InitialBackoff is the initial retry interval after first failure (30 seconds)
	InitialBackoff = 30 * time.Second
	// MaxBackoff is the maximum retry interval (30 minutes)
	MaxBackoff = 30 * time.Minute
	// BackoffMultiplier is the factor by which backoff increases on each failure
	BackoffMultiplier = 2.0
)

Exponential backoff configuration for unreachable servers.

const DefaultRemoteTimeout = 30

DefaultRemoteTimeout is the default connection timeout in seconds for remote MCP servers. This value must be kept in sync with the kubebuilder:default annotation in MCPServerSpec.Timeout (see pkg/apis/muster/v1alpha1/mcpserver_types.go).

const RestartGracePeriod = 200 * time.Millisecond

RestartGracePeriod is the pause between stop and start during a restart. This allows time for: - Subprocess cleanup and port release for stdio servers - Connection draining for remote HTTP/SSE servers - Upstream load balancers to detect the disconnect

const UnreachableThreshold = 3

UnreachableThreshold is the number of consecutive failures before marking a server as unreachable.

Types

type Option

type Option func(*Service)

Option configures a Service at construction time.

func WithAuthRequiredHook

func WithAuthRequiredHook(fn func(*api.MCPServer, *mcpserver.AuthRequiredError)) Option

WithAuthRequiredHook registers a function that Start calls synchronously when it encounters a 401, before UpdateState(StateAuthRequired) publishes the state-change event. Work done inside the hook (e.g. registering the server in the aggregator) is therefore visible to all subscribers before the event reaches them.

The hook receives the service's current definition rather than a creation-time snapshot, so registrations reflect configuration updates applied before a restart.

type Service

type Service struct {
	*services.BaseService
	// contains filtered or unexported fields
}

Service implements the Service interface for MCP server management The MCP client now handles both process management AND MCP communication

func NewService

func NewService(definition *api.MCPServer, opts ...Option) (*Service, error)

NewService creates a new MCP server service

func (*Service) CheckHealth

func (s *Service) CheckHealth(ctx context.Context) (services.HealthStatus, error)

CheckHealth implements HealthChecker using MCP protocol

func (*Service) ConfigurationChanged

func (s *Service) ConfigurationChanged(newConfig interface{}) bool

ConfigurationChanged returns true if the new configuration differs from the current one in a way that requires a restart. Description changes are excluded because they are metadata-only and do not affect runtime behavior.

Concurrency: must be called from the reconciler goroutine only; concurrent access to s.definition is not synchronized.

func (*Service) GetConfiguration

func (s *Service) GetConfiguration() interface{}

GetConfiguration returns the MCP server configuration

func (*Service) GetConsecutiveFailures

func (s *Service) GetConsecutiveFailures() int

GetConsecutiveFailures returns the number of consecutive connection failures. Thread-safe.

func (*Service) GetHealthCheckInterval

func (s *Service) GetHealthCheckInterval() time.Duration

GetHealthCheckInterval implements HealthChecker

func (*Service) GetLastAttempt

func (s *Service) GetLastAttempt() *time.Time

GetLastAttempt returns the time of the last connection attempt. This value is preserved after successful connections for diagnostic purposes. Thread-safe.

func (*Service) GetLogContext

func (s *Service) GetLogContext() string

GetLogContext returns the logging context for this service

func (*Service) GetMCPClient

func (s *Service) GetMCPClient() interface{}

GetMCPClient returns the MCP client for this service (used by aggregator) This is now much simpler since the client IS the process manager

func (*Service) GetNextRetryAfter

func (s *Service) GetNextRetryAfter() *time.Time

GetNextRetryAfter returns the time after which the next retry should be attempted. Returns nil if no retry is scheduled (either never failed or after successful connection). Thread-safe.

func (*Service) GetServiceData

func (s *Service) GetServiceData() map[string]interface{}

GetServiceData implements ServiceDataProvider

func (*Service) GetServiceType

func (s *Service) GetServiceType() string

GetServiceType returns the service type

func (*Service) IsClientReady

func (s *Service) IsClientReady() bool

IsClientReady returns whether the MCP client is initialized and ready

func (*Service) IsHealthy

func (s *Service) IsHealthy() bool

IsHealthy checks if the MCP server is healthy

func (*Service) IsRunning

func (s *Service) IsRunning() bool

IsRunning checks if the MCP server is running (or connected for remote servers)

func (*Service) IsUnreachable

func (s *Service) IsUnreachable() bool

IsUnreachable returns true if the server is in the unreachable state.

func (*Service) LogDebug

func (s *Service) LogDebug(format string, args ...interface{})

LogDebug logs a debug message with service context

func (*Service) LogError

func (s *Service) LogError(err error, format string, args ...interface{})

LogError logs an error message with service context

func (*Service) LogInfo

func (s *Service) LogInfo(format string, args ...interface{})

LogInfo logs an info message with service context

func (*Service) LogWarn

func (s *Service) LogWarn(format string, args ...interface{})

LogWarn logs a warning message with service context

func (*Service) Restart

func (s *Service) Restart(ctx context.Context) error

Restart restarts the MCP server service. This method performs a graceful restart by stopping the service first (if running), waiting a brief grace period, and then starting it again.

func (*Service) Start

func (s *Service) Start(ctx context.Context) error

Start starts the MCP server service by creating and initializing the MCP client The client handles both process startup and MCP protocol initialization

If the server requires OAuth authentication, this method will return an AuthRequiredError containing the OAuth information. The caller should handle this by registering the server in auth_required state with a synthetic tool.

For remote servers, this method tracks consecutive connection failures and transitions to StateUnreachable after UnreachableThreshold failures.

func (*Service) Stop

func (s *Service) Stop(ctx context.Context) error

Stop stops the MCP server service by closing the MCP client The client handles both MCP protocol cleanup and process termination

func (*Service) UpdateConfiguration

func (s *Service) UpdateConfiguration(newConfig interface{}) error

UpdateConfiguration updates the MCP server configuration.

Concurrency: must be called from the reconciler goroutine only; concurrent access to s.definition is not synchronized.

func (*Service) ValidateConfiguration

func (s *Service) ValidateConfiguration() error

ValidateConfiguration validates the MCP server configuration