server

package
v1.5.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 20, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package server provides the server registry for managing MCP servers. It acts as the coordination layer between configuration and supervision.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrServerExists     = errors.New("server already exists")
	ErrServerNotFound   = errors.New("server not found")
	ErrServerRunning    = errors.New("server is running")
	ErrServerNotRunning = errors.New("server is not running")
)

Errors returned by Registry operations.

Functions

This section is empty.

Types

type ManagedServer 

type ManagedServer struct {
	// Name is the unique identifier for this server.
	Name string

	// Config is the server configuration from servers.yaml.
	Config *config.ServerConfig

	// State is the current lifecycle state.
	State State

	// Process is the underlying supervised process (nil when stopped).
	Process *supervisor.ManagedProcess

	// Metadata
	CreatedAt    time.Time
	StartedAt    time.Time
	StoppedAt    time.Time
	RestartCount int
	LastError    error
}

ManagedServer represents an MCP server registered in the registry. It tracks configuration, state, and runtime metadata.

func (*ManagedServer) IsRunning 

func (s *ManagedServer) IsRunning() bool

IsRunning returns true if the server is in a running state.

func (*ManagedServer) IsStopped 

func (s *ManagedServer) IsStopped() bool

IsStopped returns true if the server is in a stopped state.

func (*ManagedServer) PID 

func (s *ManagedServer) PID() int

PID returns the process ID if running, or 0 if not.

func (*ManagedServer) Port 

func (s *ManagedServer) Port() int

Port returns the HTTP port this server is exposed on.

func (*ManagedServer) Status 

func (s *ManagedServer) Status() ServerStatus

Status returns a snapshot of the server's current state.

func (*ManagedServer) Transport 

func (s *ManagedServer) Transport() config.TransportType

Transport returns the transport type (stdio, http, sse).

func (*ManagedServer) Uptime 

func (s *ManagedServer) Uptime() time.Duration

Uptime returns how long the server has been running, or 0 if not running.

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry manages MCP server configurations and their lifecycle. It provides a thread-safe interface for adding, removing, starting, and stopping servers.

func NewRegistry 

func NewRegistry(sup *supervisor.Supervisor, logger *slog.Logger) *Registry

NewRegistry creates a new server registry with the given supervisor.

func (*Registry) Add 

func (r *Registry) Add(name string, cfg *config.ServerConfig) error

Add registers a new server configuration. The server is not started automatically; call Start() to start it.

func (*Registry) BlockStartup added in v1.4.5 

func (r *Registry) BlockStartup(name string, err error)

BlockStartup records a reconciliation conflict without changing config.

func (*Registry) Close added in v1.5.0 

func (r *Registry) Close()

Close stops event delivery and waits for queued events to drain. It is safe to call multiple times.

func (*Registry) Count 

func (r *Registry) Count() int

Count returns the number of registered servers.

func (*Registry) Get 

func (r *Registry) Get(name string) *ManagedServer

Get returns a server by name, or nil if not found.

func (*Registry) List 

func (r *Registry) List() []*ManagedServer

List returns all registered servers sorted by name.

func (*Registry) LoadFromConfig 

func (r *Registry) LoadFromConfig(cfg *config.Config) error

LoadFromConfig loads all servers from a configuration.

func (*Registry) Names 

func (r *Registry) Names() []string

Names returns all registered server names sorted alphabetically.

func (*Registry) Remove 

func (r *Registry) Remove(name string) error

Remove unregisters a server. The server must be stopped first.

func (*Registry) Restart 

func (r *Registry) Restart(name string) error

Restart stops and starts a server.

func (*Registry) SetEventHandler 

func (r *Registry) SetEventHandler(handler ServerEventHandler)

SetEventHandler registers a callback for server lifecycle events. Only one handler can be registered at a time; subsequent calls replace the previous handler. Pass nil to unregister the current handler. The handler is called asynchronously after state changes complete, and receives events in the order those state changes occurred.

func (*Registry) SetStartupGuard added in v1.4.5 

func (r *Registry) SetStartupGuard(guard func(string) error)

func (*Registry) Start 

func (r *Registry) Start(name string) error

Start begins running a server.

func (*Registry) StartAll 

func (r *Registry) StartAll(ctx context.Context) error

StartAll starts all servers that have autostart enabled.

Best-effort by default: advisory (Required=false) failures are logged + joined but do not fail the whole operation from the caller's perspective (caller decides). When a server has Autostart=true AND Required=true and its start fails, StartAll returns a *RequiredStartupError that wraps the joined error plus the list of required failures — daemon startup should treat this as fatal.

func (*Registry) Status 

func (r *Registry) Status() RegistryStatus

Status returns a snapshot of the current registry state.

func (*Registry) Stop 

func (r *Registry) Stop(name string) error

Stop halts a running server.

func (*Registry) StopAll 

func (r *Registry) StopAll(ctx context.Context) error

StopAll stops all running servers.

type RegistryStatus 

type RegistryStatus struct {
	TotalServers   int            `json:"total_servers"`
	RunningServers int            `json:"running_servers"`
	StoppedServers int            `json:"stopped_servers"`
	FailedServers  int            `json:"failed_servers"`
	Servers        []ServerStatus `json:"servers"`
}

RegistryStatus contains aggregate information about the registry.

type RequiredStartupError 

type RequiredStartupError struct {
	Failures []string // server names that failed required startup
	Joined   error    // underlying joined start errors (all startup errors)
}

RequiredStartupError is returned by StartAll when one or more servers with Autostart=true AND Required=true failed to start. Callers can differentiate this from advisory best-effort errors via errors.As so that daemon startup can exit non-zero only for the required failures.

func (*RequiredStartupError) Error 

func (e *RequiredStartupError) Error() string

func (*RequiredStartupError) Unwrap 

func (e *RequiredStartupError) Unwrap() error

type ServerEvent 

type ServerEvent struct {
	Type   ServerEventType
	Name   string
	Server *ManagedServer
}

ServerEvent contains information about a server lifecycle change. Events are fired asynchronously after the corresponding operation completes, and are delivered to the handler in the order the operations occurred.

type ServerEventHandler 

type ServerEventHandler func(event ServerEvent)

ServerEventHandler is called when server lifecycle events occur.

Handlers must be non-blocking and must not call back into the registry. Events are delivered sequentially by a single goroutine, so a slow handler delays every subsequent event; delivery is bounded by handlerTimeout, after which the handler is abandoned and ordering is no longer guaranteed for it.

type ServerEventType 

type ServerEventType int

ServerEventType indicates the type of server lifecycle event. 

const (
	// EventServerStarted fires when a server has successfully started.
	EventServerStarted ServerEventType = iota
	// EventServerStopped fires when a server has been stopped.
	EventServerStopped
)

type ServerStatus 

type ServerStatus struct {
	Name         string               `json:"name"`
	State        State                `json:"state"`
	Port         int                  `json:"port"`
	Transport    config.TransportType `json:"transport"`
	PID          int                  `json:"pid,omitempty"`
	Uptime       time.Duration        `json:"uptime,omitempty"`
	RestartCount int                  `json:"restart_count"`
	LastError    string               `json:"last_error,omitempty"`
	Autostart    bool                 `json:"autostart"`
	// Required reflects the config.ServerConfig.Required flag. External
	// tools such as OCA doctor use this combined with State to surface
	// required-but-not-running servers as errors (rather than warnings).
	Required bool `json:"required"`
}

ServerStatus is a JSON-serializable snapshot of server state.

type State 

type State string

State represents the lifecycle state of a managed server. 

const (
	// StateStopped indicates the server is not running.
	StateStopped State = "stopped"
	// StateStarting indicates the server is starting up.
	StateStarting State = "starting"
	// StateRunning indicates the server is running normally.
	StateRunning State = "running"
	// StateStopping indicates the server is shutting down.
	StateStopping State = "stopping"
	// StateCrashed indicates the server exited unexpectedly.
	StateCrashed State = "crashed"
	// StateFailed indicates the server failed to start or exceeded restart limits.
	StateFailed State = "failed"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.