runner

package
v0.2.5 Latest Latest
Warning

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

 Go to latest Published: Aug 8, 2025 License: Apache-2.0 Imports: 37 Imported by: 1

Documentation

Overview

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

Variables

This section is empty.

Functions

func BuildFromProtocolSchemeWithName added in v0.2.3 

func BuildFromProtocolSchemeWithName(
	ctx context.Context,
	imageManager images.ImageManager,
	serverOrImage string,
	caCertPath string,
	imageName string,
	dryRun bool,
) (string, error)

BuildFromProtocolSchemeWithName checks if the serverOrImage string contains a protocol scheme (uvx://, npx://, or go://) and builds a Docker image for it if needed with a custom image name. If imageName is empty, a default name will be generated. If dryRun is true, returns the Dockerfile content instead of building the image. Returns the Docker image name (or Dockerfile content if dryRun) and any error encountered.

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 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://)

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"`

	// Group is the name of the group this workload belongs to, if any
	Group string `json:"group,omitempty" yaml:"group,omitempty"`

	// ToolsFilter is the list of tools to filter
	ToolsFilter []string `json:"tools_filter,omitempty" yaml:"tools_filter,omitempty"`

	// IgnoreConfig contains configuration for ignore processing
	IgnoreConfig *ignore.Config `json:"ignore_config,omitempty" yaml:"ignore_config,omitempty"`

	// MiddlewareConfigs contains the list of middleware to apply to the transport
	// and the configuration for each middleware.
	MiddlewareConfigs []types.MiddlewareConfig `json:"middleware_configs,omitempty" yaml:"middleware_configs,omitempty"`
}

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

func LoadState 

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

LoadState loads a run configuration from the state store

func NewRunConfig 

func NewRunConfig() *RunConfig

NewRunConfig creates a new RunConfig with default values

func ReadJSON 

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

ReadJSON deserializes the RunConfig from JSON read from the provided reader

func (*RunConfig) SaveState added in v0.2.4 

func (c *RunConfig) SaveState(ctx context.Context) error

SaveState saves the run configuration to the state store

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) WithMiddlewareConfig added in v0.2.4 

func (c *RunConfig) WithMiddlewareConfig(middlewareConfig []types.MiddlewareConfig) *RunConfig

WithMiddlewareConfig adds middleware configuration to the RunConfig

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) WithGroup added in v0.2.1 

func (b *RunConfigBuilder) WithGroup(groupName string) *RunConfigBuilder

WithGroup sets the group name for the workload

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) WithIgnoreConfig added in v0.2.1 

func (b *RunConfigBuilder) WithIgnoreConfig(ignoreConfig *ignore.Config) *RunConfigBuilder

WithIgnoreConfig sets the ignore configuration

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) WithMiddlewareConfig added in v0.2.4 

func (b *RunConfigBuilder) WithMiddlewareConfig(middlewareConfig []types.MiddlewareConfig) *RunConfigBuilder

WithMiddlewareConfig sets the middleware configuration

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, oidcIntrospectionURL, oidcClientID string, oidcClientSecret string,
	thvCABundle, jwksAuthTokenFile, resourceURL 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) WithToolsFilter added in v0.2.1 

func (b *RunConfigBuilder) WithToolsFilter(toolsFilter []string) *RunConfigBuilder

WithToolsFilter sets the tools filter

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 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

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.