runner

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 23, 2025 License: Apache-2.0 Imports: 34 Imported by: 1

Documentation

Overview

Package runner provides functionality for running MCP servers

Package runner provides functionality for running MCP servers

Package runner provides functionality for running MCP servers

Index

Constants

View Source 
const (
	UVXScheme = "uvx://"
	NPXScheme = "npx://"
	GOScheme  = "go://"
)

Protocol schemes

View Source 
const DefaultAppName = "toolhive"

DefaultAppName is the default application name used for state storage

Variables

This section is empty.

Functions

func CleanupTempPermissionProfile added in v0.0.48 

func CleanupTempPermissionProfile(permissionProfilePath string) error

CleanupTempPermissionProfile removes a temporary permission profile file if it was created by toolhive

func CreatePermissionProfileFile added in v0.0.48 

func CreatePermissionProfileFile(serverName string, permProfile *permissions.Profile) (string, error)

CreatePermissionProfileFile creates a temporary file with the permission profile

func DeleteSavedConfig 

func DeleteSavedConfig(ctx context.Context, name string) error

DeleteSavedConfig deletes a saved run configuration

func HandleProtocolScheme added in v0.0.33 

func HandleProtocolScheme(
	ctx context.Context,
	imageManager images.ImageManager,
	serverOrImage string,
	caCertPath string,
) (string, error)

HandleProtocolScheme checks if the serverOrImage string contains a protocol scheme (uvx://, npx://, or go://) and builds a Docker image for it if needed. Returns the Docker image name to use and any error encountered.

func IsImageProtocolScheme added in v0.0.35 

func IsImageProtocolScheme(serverOrImage string) bool

IsImageProtocolScheme checks if the serverOrImage string contains a protocol scheme (uvx://, npx://, or go://)

func ListSavedConfigs 

func ListSavedConfigs(ctx context.Context) ([]string, error)

ListSavedConfigs lists all saved run configurations

Types

type CLIEnvVarValidator added in v0.1.0 

type CLIEnvVarValidator struct{}

CLIEnvVarValidator implements the EnvVarValidator interface for CLI usage. If any missing, mandatory variables are found, this code will prompt the user to supply them through stdin.

func (*CLIEnvVarValidator) Validate added in v0.1.0 

func (*CLIEnvVarValidator) Validate(
	ctx context.Context,
	metadata *registry.ImageMetadata,
	runConfig *RunConfig,
	suppliedEnvVars []string,
) ([]string, error)

Validate checks that all required environment variables and secrets are provided and returns the processed environment variables to be set.

type DetachedEnvVarValidator added in v0.1.0 

type DetachedEnvVarValidator struct{}

DetachedEnvVarValidator implements the EnvVarValidator interface for scenarios where the user cannot be prompted for input. Any missing, mandatory variables will result in an error being returned.

func (*DetachedEnvVarValidator) Validate added in v0.1.0 

func (*DetachedEnvVarValidator) Validate(
	_ context.Context,
	metadata *registry.ImageMetadata,
	runConfig *RunConfig,
	suppliedEnvVars []string,
) ([]string, error)

Validate checks that all required environment variables and secrets are provided and returns the processed environment variables to be set.

type EnvVarValidator added in v0.1.0 

type EnvVarValidator interface {
	// Validate checks that all required environment variables and secrets are provided
	// and returns the processed environment variables to be set.
	Validate(
		ctx context.Context,
		metadata *registry.ImageMetadata,
		runConfig *RunConfig,
		suppliedEnvVars []string,
	) ([]string, error)
}

EnvVarValidator defines the interface for checking that the expected environment variables and secrets have been supplied when creating a workload. This is implemented as a strategy pattern since the handling is different for the CLI vs the API and k8s.

type RunConfig 

type RunConfig struct {
	// Image is the Docker image to run
	Image string `json:"image" yaml:"image"`

	// CmdArgs are the arguments to pass to the container
	CmdArgs []string `json:"cmd_args,omitempty" yaml:"cmd_args,omitempty"`

	// Name is the name of the MCP server
	Name string `json:"name" yaml:"name"`

	// ContainerName is the name of the container
	ContainerName string `json:"container_name" yaml:"container_name"`

	// BaseName is the base name used for the container (without prefixes)
	BaseName string `json:"base_name" yaml:"base_name"`

	// Transport is the transport mode (stdio, sse, or streamable-http)
	Transport types.TransportType `json:"transport" yaml:"transport"`

	// Host is the host for the HTTP proxy
	Host string `json:"host" yaml:"host"`

	// Port is the port for the HTTP proxy to listen on (host port)
	Port int `json:"port" yaml:"port"`

	// TargetPort is the port for the container to expose (only applicable to SSE transport)
	TargetPort int `json:"target_port,omitempty" yaml:"target_port,omitempty"`

	// TargetHost is the host to forward traffic to (only applicable to SSE transport)
	TargetHost string `json:"target_host,omitempty" yaml:"target_host,omitempty"`

	// PermissionProfileNameOrPath is the name or path of the permission profile
	PermissionProfileNameOrPath string `json:"permission_profile_name_or_path,omitempty" yaml:"permission_profile_name_or_path,omitempty"` //nolint:lll

	// PermissionProfile is the permission profile to use
	PermissionProfile *permissions.Profile `json:"permission_profile" yaml:"permission_profile"`

	// EnvVars are the parsed environment variables as key-value pairs
	EnvVars map[string]string `json:"env_vars,omitempty" yaml:"env_vars,omitempty"`

	// Debug indicates whether debug mode is enabled
	Debug bool `json:"debug,omitempty" yaml:"debug,omitempty"`

	// Volumes are the directory mounts to pass to the container
	// Format: "host-path:container-path[:ro]"
	Volumes []string `json:"volumes,omitempty" yaml:"volumes,omitempty"`

	// ContainerLabels are the labels to apply to the container
	ContainerLabels map[string]string `json:"container_labels,omitempty" yaml:"container_labels,omitempty"`

	// OIDCConfig contains OIDC configuration
	OIDCConfig *auth.TokenValidatorConfig `json:"oidc_config,omitempty" yaml:"oidc_config,omitempty"`

	// AuthzConfig contains the authorization configuration
	AuthzConfig *authz.Config `json:"authz_config,omitempty" yaml:"authz_config,omitempty"`

	// AuthzConfigPath is the path to the authorization configuration file
	AuthzConfigPath string `json:"authz_config_path,omitempty" yaml:"authz_config_path,omitempty"`

	// AuditConfig contains the audit logging configuration
	AuditConfig *audit.Config `json:"audit_config,omitempty" yaml:"audit_config,omitempty"`

	// AuditConfigPath is the path to the audit configuration file
	AuditConfigPath string `json:"audit_config_path,omitempty" yaml:"audit_config_path,omitempty"`

	// TelemetryConfig contains the OpenTelemetry configuration
	TelemetryConfig *telemetry.Config `json:"telemetry_config,omitempty" yaml:"telemetry_config,omitempty"`

	// Secrets are the secret parameters to pass to the container
	// Format: "<secret name>,target=<target environment variable>"
	Secrets []string `json:"secrets,omitempty" yaml:"secrets,omitempty"`

	// K8sPodTemplatePatch is a JSON string to patch the Kubernetes pod template
	// Only applicable when using Kubernetes runtime
	K8sPodTemplatePatch string `json:"k8s_pod_template_patch,omitempty" yaml:"k8s_pod_template_patch,omitempty"`

	// Deployer is the container runtime to use (not serialized)
	Deployer rt.Deployer `json:"-" yaml:"-"`

	// IsolateNetwork indicates whether to isolate the network for the container
	IsolateNetwork bool `json:"isolate_network,omitempty" yaml:"isolate_network,omitempty"`

	// ProxyMode is the proxy mode for stdio transport ("sse" or "streamable-http")
	ProxyMode types.ProxyMode `json:"proxy_mode,omitempty" yaml:"proxy_mode,omitempty"`

	// ThvCABundle is the path to the CA certificate bundle for ToolHive HTTP operations
	ThvCABundle string `json:"thv_ca_bundle,omitempty" yaml:"thv_ca_bundle,omitempty"`

	// JWKSAuthTokenFile is the path to file containing auth token for JWKS/OIDC requests
	JWKSAuthTokenFile string `json:"jwks_auth_token_file,omitempty" yaml:"jwks_auth_token_file,omitempty"`

	// JWKSAllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses
	JWKSAllowPrivateIP bool `json:"jwks_allow_private_ip,omitempty" yaml:"jwks_allow_private_ip,omitempty"`
}

RunConfig contains all the configuration needed to run an MCP server It is serializable to JSON and YAML

func NewRunConfig 

func NewRunConfig() *RunConfig

NewRunConfig creates a new RunConfig with default values

func NewRunConfigFromFlags 

func NewRunConfigFromFlags(
	ctx context.Context,
	runtime rt.Deployer,
	cmdArgs []string,
	name string,
	imageURL string,
	imageMetadata *registry.ImageMetadata,
	host string,
	debug bool,
	volumes []string,
	secretsList []string,
	authzConfigPath string,
	auditConfigPath string,
	enableAudit bool,
	permissionProfile string,
	targetHost string,
	mcpTransport string,
	port int,
	targetPort int,
	envVars []string,
	runLabels []string,
	oidcIssuer string,
	oidcAudience string,
	oidcJwksURL string,
	oidcClientID string,
	oidcAllowOpaqueTokens bool,
	otelEndpoint string,
	otelServiceName string,
	otelSamplingRate float64,
	otelHeaders []string,
	otelInsecure bool,
	otelEnablePrometheusMetricsPath bool,
	otelEnvironmentVariables []string,
	isolateNetwork bool,
	k8sPodPatch string,
	thvCABundle string,
	jwksAuthTokenFile string,
	jwksAllowPrivateIP bool,
	envVarValidator EnvVarValidator,
	proxyMode types.ProxyMode,
) (*RunConfig, error)

NewRunConfigFromFlags creates a new RunConfig with values from command-line flags

func ReadJSON 

func ReadJSON(r io.Reader) (*RunConfig, error)

ReadJSON deserializes the RunConfig from JSON read from the provided reader

func (*RunConfig) ValidateSecrets added in v0.1.8 

func (c *RunConfig) ValidateSecrets(ctx context.Context, secretManager secrets.Provider) error

ValidateSecrets checks if the secrets can be parsed and are valid

func (*RunConfig) WithAudit added in v0.0.40 

func (c *RunConfig) WithAudit(config *audit.Config) *RunConfig

WithAudit adds audit configuration to the RunConfig

func (*RunConfig) WithAuthz 

func (c *RunConfig) WithAuthz(config *authz.Config) *RunConfig

WithAuthz adds authorization configuration to the RunConfig

func (*RunConfig) WithContainerName 

func (c *RunConfig) WithContainerName() *RunConfig

WithContainerName generates container name if not already set

func (*RunConfig) WithEnvironmentVariables 

func (c *RunConfig) WithEnvironmentVariables(envVarStrings []string) (*RunConfig, error)

WithEnvironmentVariables parses and sets environment variables

func (*RunConfig) WithPorts 

func (c *RunConfig) WithPorts(proxyPort, targetPort int) (*RunConfig, error)

WithPorts configures the host and target ports

func (*RunConfig) WithSecrets 

func (c *RunConfig) WithSecrets(ctx context.Context, secretManager secrets.Provider) (*RunConfig, error)

WithSecrets processes secrets and adds them to environment variables

func (*RunConfig) WithStandardLabels 

func (c *RunConfig) WithStandardLabels() *RunConfig

WithStandardLabels adds standard labels to the container

func (*RunConfig) WithTransport 

func (c *RunConfig) WithTransport(t string) (*RunConfig, error)

WithTransport parses and sets the transport type

func (*RunConfig) WriteJSON 

func (c *RunConfig) WriteJSON(w io.Writer) error

WriteJSON serializes the RunConfig to JSON and writes it to the provided writer

type RunConfigBuilder added in v0.1.6 

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

RunConfigBuilder provides a fluent interface for building RunConfig instances

func NewRunConfigBuilder added in v0.1.6 

func NewRunConfigBuilder() *RunConfigBuilder

NewRunConfigBuilder creates a new RunConfigBuilder with default values

func (*RunConfigBuilder) Build added in v0.1.6 

func (b *RunConfigBuilder) Build(ctx context.Context, imageMetadata *registry.ImageMetadata,
	envVars []string, envVarValidator EnvVarValidator) (*RunConfig, error)

Build creates the final RunConfig instance with validation and processing

func (*RunConfigBuilder) WithAuditConfigPath added in v0.1.6 

func (b *RunConfigBuilder) WithAuditConfigPath(path string) *RunConfigBuilder

WithAuditConfigPath sets the audit config path

func (*RunConfigBuilder) WithAuditEnabled added in v0.1.6 

func (b *RunConfigBuilder) WithAuditEnabled(enableAudit bool, auditConfigPath string) *RunConfigBuilder

WithAuditEnabled configures audit settings

func (*RunConfigBuilder) WithAuthzConfigPath added in v0.1.6 

func (b *RunConfigBuilder) WithAuthzConfigPath(path string) *RunConfigBuilder

WithAuthzConfigPath sets the authorization config path

func (*RunConfigBuilder) WithCmdArgs added in v0.1.6 

func (b *RunConfigBuilder) WithCmdArgs(args []string) *RunConfigBuilder

WithCmdArgs sets the command arguments

func (*RunConfigBuilder) WithDebug added in v0.1.6 

func (b *RunConfigBuilder) WithDebug(debug bool) *RunConfigBuilder

WithDebug sets debug mode

func (*RunConfigBuilder) WithHost added in v0.1.6 

func (b *RunConfigBuilder) WithHost(host string) *RunConfigBuilder

WithHost sets the host (applies default if empty)

func (*RunConfigBuilder) WithImage added in v0.1.6 

func (b *RunConfigBuilder) WithImage(image string) *RunConfigBuilder

WithImage sets the Docker image

func (*RunConfigBuilder) WithK8sPodPatch added in v0.1.6 

func (b *RunConfigBuilder) WithK8sPodPatch(patch string) *RunConfigBuilder

WithK8sPodPatch sets the Kubernetes pod template patch

func (*RunConfigBuilder) WithLabels added in v0.1.9 

func (b *RunConfigBuilder) WithLabels(labelStrings []string) *RunConfigBuilder

WithLabels sets custom labels from command-line flags

func (*RunConfigBuilder) WithName added in v0.1.6 

func (b *RunConfigBuilder) WithName(name string) *RunConfigBuilder

WithName sets the MCP server name

func (*RunConfigBuilder) WithNetworkIsolation added in v0.1.6 

func (b *RunConfigBuilder) WithNetworkIsolation(isolate bool) *RunConfigBuilder

WithNetworkIsolation sets network isolation

func (*RunConfigBuilder) WithOIDCConfig added in v0.1.6 

func (b *RunConfigBuilder) WithOIDCConfig(
	oidcIssuer, oidcAudience, oidcJwksURL, oidcClientID string,
	oidcAllowOpaqueTokens bool,
	thvCABundle, jwksAuthTokenFile string,
	jwksAllowPrivateIP bool,
) *RunConfigBuilder

WithOIDCConfig configures OIDC settings

func (*RunConfigBuilder) WithPermissionProfile added in v0.1.6 

func (b *RunConfigBuilder) WithPermissionProfile(profile *permissions.Profile) *RunConfigBuilder

WithPermissionProfile sets the permission profile directly. If called multiple times or mixed with WithPermissionProfile, the last call takes precedence.

func (*RunConfigBuilder) WithPermissionProfileNameOrPath added in v0.1.6 

func (b *RunConfigBuilder) WithPermissionProfileNameOrPath(profile string) *RunConfigBuilder

WithPermissionProfileNameOrPath sets the permission profile name or path. If called multiple times or mixed with WithPermissionProfile, the last call takes precedence.

func (*RunConfigBuilder) WithProxyMode added in v0.1.6 

func (b *RunConfigBuilder) WithProxyMode(mode types.ProxyMode) *RunConfigBuilder

WithProxyMode sets the proxy mode

func (*RunConfigBuilder) WithRuntime added in v0.1.6 

func (b *RunConfigBuilder) WithRuntime(deployer rt.Deployer) *RunConfigBuilder

WithRuntime sets the container runtime

func (*RunConfigBuilder) WithSecrets added in v0.1.6 

func (b *RunConfigBuilder) WithSecrets(secrets []string) *RunConfigBuilder

WithSecrets sets the secrets list

func (*RunConfigBuilder) WithTargetHost added in v0.1.6 

func (b *RunConfigBuilder) WithTargetHost(targetHost string) *RunConfigBuilder

WithTargetHost sets the target host (applies default if empty)

func (*RunConfigBuilder) WithTelemetryConfig added in v0.1.6 

func (b *RunConfigBuilder) WithTelemetryConfig(otelEndpoint string, otelEnablePrometheusMetricsPath bool,
	otelServiceName string, otelSamplingRate float64, otelHeaders []string, otelInsecure bool,
	otelEnvironmentVariables []string) *RunConfigBuilder

WithTelemetryConfig configures telemetry settings

func (*RunConfigBuilder) WithTransportAndPorts added in v0.1.6 

func (b *RunConfigBuilder) WithTransportAndPorts(mcpTransport string, port, targetPort int) *RunConfigBuilder

WithTransportAndPorts sets transport and port configuration

func (*RunConfigBuilder) WithVolumes added in v0.1.6 

func (b *RunConfigBuilder) WithVolumes(volumes []string) *RunConfigBuilder

WithVolumes sets the volume mounts

type Runner 

type Runner struct {
	// Config is the configuration for the runner
	Config *RunConfig
	// contains filtered or unexported fields
}

Runner is responsible for running an MCP server with the provided configuration

func LoadState 

func LoadState(ctx context.Context, name string) (*Runner, error)

LoadState loads the runner configuration from the state store This is a static method that returns a new Runner instance

func NewRunner 

func NewRunner(runConfig *RunConfig) *Runner

NewRunner creates a new Runner with the provided configuration

func (*Runner) Cleanup added in v0.0.47 

func (r *Runner) Cleanup(ctx context.Context) error

Cleanup performs cleanup operations for the runner, including shutting down telemetry.

func (*Runner) Run 

func (r *Runner) Run(ctx context.Context) error

Run runs the MCP server with the provided configuration

func (*Runner) SaveState 

func (r *Runner) SaveState(ctx context.Context) error

SaveState saves the runner configuration to the state store

Source Files

View all Source files

Directories

Path Synopsis
Package retriever contains logic for fetching or building MCP servers.
 Package retriever contains logic for fetching or building MCP servers.

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.