launcher

package
v0.4.18 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source
const (
	// DefaultIdleTimeout is the maximum duration a STDIO-backend connection can remain unused
	// before being removed from the session pool. Set to 6 hours to accommodate long-running
	// workflow tasks (e.g. ML training, large builds) that may not make MCP calls for extended
	// periods. Note: this is distinct from HTTP backend keepalive (config.DefaultKeepaliveInterval)
	// which keeps the remote session alive on the HTTP server side; STDIO connections run as local
	// child processes whose sessions are bounded only by this pool eviction window.
	DefaultIdleTimeout     = 6 * time.Hour
	DefaultCleanupInterval = 5 * time.Minute
	DefaultMaxErrorCount   = 10
)

Default configuration values

View Source
const AllowedMountRootsEnvVar = "MCP_GATEWAY_ALLOWED_MOUNT_ROOTS"

AllowedMountRootsEnvVar names the environment variable used by operators to override the trusted host mount roots. The value is a comma-separated list of "path" or "path:ro" / "path:rw" entries (defaults to read-only).

View Source
const (
	// DefaultHealthCheckInterval is the recommended periodic health check interval (spec §8).
	DefaultHealthCheckInterval = 30 * time.Second
)

Variables

View Source
var ErrServerNotFound = errors.New("server not found in config")

ErrServerNotFound is returned by getServerConfig when the requested server ID is not present in the gateway configuration.

Functions

func GetOrLaunch

func GetOrLaunch(l *Launcher, serverID string) (*mcp.Connection, error)

GetOrLaunch returns an existing connection or launches a new one

func GetOrLaunchForSession

func GetOrLaunchForSession(l *Launcher, serverID, sessionID string) (*mcp.Connection, error)

GetOrLaunchForSession returns a session-aware connection or launches a new one This is used for stateful stdio backends that require persistent connections

func LogConnectionError added in v0.3.26

func LogConnectionError(errCtx ConnectionErrorContext, err error)

LogConnectionError logs detailed diagnostics for a launcher connection failure, including command context, captured stderr, and actionable hints based on the error type and execution environment.

Types

type ConnectionErrorContext added in v0.3.26

type ConnectionErrorContext struct {
	ServerID           string
	SessionID          string
	Command            string
	Args               []string
	Env                map[string]string
	RunningInContainer bool
	IsDirectCommand    bool
	StartupTimeout     time.Duration
	StderrOutput       string
}

ConnectionErrorContext holds all context needed to produce a detailed connection failure diagnostic. Fields left at their zero values are omitted from the output.

type ConnectionKey

type ConnectionKey struct {
	BackendID string
	SessionID string
}

ConnectionKey uniquely identifies a connection by backend and session

func (ConnectionKey) String

func (k ConnectionKey) String() string

String returns a string representation of the connection key

type ConnectionMetadata

type ConnectionMetadata struct {
	Connection   *mcp.Connection
	CreatedAt    time.Time
	LastUsedAt   time.Time
	RequestCount int
	ErrorCount   int
	State        ConnectionState
}

ConnectionMetadata tracks information about a pooled connection

type ConnectionState

type ConnectionState string

ConnectionState represents the state of a pooled connection

const (
	ConnectionStateActive ConnectionState = "active"
	ConnectionStateIdle   ConnectionState = "idle"
	ConnectionStateClosed ConnectionState = "closed"
)

type HealthMonitor added in v0.2.12

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

HealthMonitor periodically checks backend server health and automatically restarts servers that are in an error state (MCP Gateway Specification §8).

func NewHealthMonitor added in v0.2.12

func NewHealthMonitor(l *Launcher, interval time.Duration) *HealthMonitor

NewHealthMonitor creates a health monitor for the given launcher.

func (*HealthMonitor) Start added in v0.2.12

func (hm *HealthMonitor) Start()

Start begins periodic health checks in a background goroutine.

func (*HealthMonitor) Stop added in v0.2.12

func (hm *HealthMonitor) Stop()

Stop signals the health monitor to stop and waits for it to finish.

type Launcher

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

Launcher manages backend MCP server connections

func New

func New(ctx context.Context, cfg *config.Config) *Launcher

New creates a new Launcher

func (*Launcher) Close

func (l *Launcher) Close()

Close closes all connections

func (*Launcher) GetServerState added in v0.2.11

func (l *Launcher) GetServerState(serverID string) ServerState

GetServerState returns the observed runtime state for a single server.

func (*Launcher) ServerIDs

func (l *Launcher) ServerIDs() []string

ServerIDs returns all configured server IDs

type MountPolicy added in v0.4.9

type MountPolicy struct {
	// Roots is the allowlist of host roots. An empty list denies all mounts.
	Roots []MountRoot
}

MountPolicy is the typed configuration boundary that determines which host paths a container-backed MCP server may bind-mount. It is owned by the launcher (the trusted component that starts backend processes) and is never derived from MCP server configuration.

func DefaultMountPolicy added in v0.4.9

func DefaultMountPolicy() MountPolicy

DefaultMountPolicy builds the default allowlist: the agent workspace (read-only) and the temporary directory root (read-write, used for gateway logs and large payload exchange). Operators may override the allowlist with AllowedMountRootsEnvVar.

func (MountPolicy) ValidateContainerArgs added in v0.4.9

func (p MountPolicy) ValidateContainerArgs(args []string) error

ValidateContainerArgs validates the container runtime arguments used to launch a backend MCP server. Every bind-mount declaration must satisfy the policy and no policy-bypassing runtime option may be present.

func (MountPolicy) ValidateMount added in v0.4.9

func (p MountPolicy) ValidateMount(spec string) error

ValidateMount checks a single "source:dest:mode" declaration against the policy.

type MountRoot added in v0.4.9

type MountRoot struct {
	// Path is the host directory root (canonicalized when the policy is built).
	Path string
	// Writable reports whether "rw" mounts are permitted under this root.
	Writable bool
}

MountRoot is a trusted host directory that container-backed MCP servers are permitted to mount from. Writable is an explicit, trusted policy decision: mounts under a root are forced read-only unless the root allows writes.

type PoolConfig

type PoolConfig struct {
	IdleTimeout     time.Duration
	CleanupInterval time.Duration
	MaxErrorCount   int
}

PoolConfig configures the connection pool

type ServerState added in v0.2.11

type ServerState struct {
	Status    string    // "running" | "stopped" | "error"
	StartedAt time.Time // zero value means never started
	LastError string    // most recent error message, if any
}

ServerState represents the observed runtime state of a backend server.

type SessionConnectionPool

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

SessionConnectionPool manages connections keyed by (backend, session)

func NewSessionConnectionPool

func NewSessionConnectionPool(ctx context.Context) *SessionConnectionPool

NewSessionConnectionPool creates a new connection pool with default config

func NewSessionConnectionPoolWithConfig

func NewSessionConnectionPoolWithConfig(ctx context.Context, config PoolConfig) *SessionConnectionPool

NewSessionConnectionPoolWithConfig creates a new connection pool with custom config

func (*SessionConnectionPool) Delete

func (p *SessionConnectionPool) Delete(backendID, sessionID string)

Delete removes a connection from the pool

func (*SessionConnectionPool) Get

func (p *SessionConnectionPool) Get(backendID, sessionID string) (*mcp.Connection, bool)

Get retrieves a connection from the pool

func (*SessionConnectionPool) GetMetadata

func (p *SessionConnectionPool) GetMetadata(backendID, sessionID string) (*ConnectionMetadata, bool)

GetMetadata returns metadata for a connection (for testing/monitoring)

func (*SessionConnectionPool) List

List returns all connection keys in the pool (for monitoring/debugging)

func (*SessionConnectionPool) RecordError

func (p *SessionConnectionPool) RecordError(backendID, sessionID string)

RecordError increments the error count for a connection

func (*SessionConnectionPool) Set

func (p *SessionConnectionPool) Set(backendID, sessionID string, conn *mcp.Connection)

Set adds or updates a connection in the pool

func (*SessionConnectionPool) Size

func (p *SessionConnectionPool) Size() int

Size returns the number of connections in the pool

func (*SessionConnectionPool) Stop

func (p *SessionConnectionPool) Stop()

Stop gracefully shuts down the connection pool

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL