Documentation
¶
Overview ¶
Package cli provides the business logic for the vMCP serve, validate, and init commands. It is designed to be imported by both the standalone vmcp binary (cmd/vmcp/app) and the thv vmcp subcommand (cmd/thv/app).
Package cli provides the business logic for the vMCP serve and validate commands. It is designed to be imported by both the standalone vmcp binary (cmd/vmcp/app) and the thv vmcp subcommand (cmd/thv/app), keeping all server-initialization logic in one importable place.
Index ¶
- Constants
- func Init(ctx context.Context, cfg InitConfig) error
- func Serve(ctx context.Context, cfg ServeConfig) error
- func Validate(_ context.Context, cfg ValidateConfig) error
- type ContainerFactory
- type EmbeddingServiceManager
- type EmbeddingServiceManagerConfig
- type InitConfig
- type ServeConfig
- type ValidateConfig
Constants ¶
const ( // DefaultEmbeddingImage is the default HuggingFace Text Embeddings // Inference image used when ServeConfig.EmbeddingImage is empty. DefaultEmbeddingImage = "ghcr.io/huggingface/text-embeddings-inference:cpu-latest" // DefaultEmbeddingModel is the HuggingFace model used when EmbeddingModel is empty. DefaultEmbeddingModel = "BAAI/bge-small-en-v1.5" )
Variables ¶
This section is empty.
Functions ¶
func Init ¶
func Init(ctx context.Context, cfg InitConfig) error
Init discovers workloads in cfg.GroupName, renders a starter vMCP YAML config file with one backend entry per accessible workload, and writes the result to cfg.OutputPath or cfg.Writer.
Types ¶
type ContainerFactory ¶
type ContainerFactory interface {
// Create initialises a container runtime backed by the host daemon.
Create(ctx context.Context) (runtime.Runtime, error)
}
ContainerFactory is the minimal interface over *container.Factory that EmbeddingServiceManager requires. Defined here to allow mock injection in unit tests; in production callers pass container.NewFactory().
type EmbeddingServiceManager ¶
type EmbeddingServiceManager struct {
// contains filtered or unexported fields
}
EmbeddingServiceManager manages the lifecycle of a TEI container used by the Tier 2 semantic optimizer. It creates or reuses a container deterministically named after the model, health-polls with exponential backoff, and only stops the container if this instance started it.
On Docker the container is bound to a localhost port and the model cache is bind-mounted from the host. On Kubernetes the TEI pod is exposed via a ClusterIP Service named "mcp-<containerName>" and reached at http://mcp-<containerName>:<teiContainerPort>; the host bind-mount is skipped because Kubernetes ignores Docker permission profiles.
func NewEmbeddingServiceManager ¶
func NewEmbeddingServiceManager(factory ContainerFactory, cfg EmbeddingServiceManagerConfig) (*EmbeddingServiceManager, error)
NewEmbeddingServiceManager constructs an EmbeddingServiceManager from the given factory and config. Returns an error when factory is nil or cfg.Model is empty.
func (*EmbeddingServiceManager) Start ¶
func (m *EmbeddingServiceManager) Start(ctx context.Context) (string, error)
Start ensures the TEI container is running and returns its HTTP base URL. On Docker this is http://localhost:<port>; on Kubernetes it is http://<containerName>:<teiContainerPort>.
On first call it checks for an existing running container with the same name; if found, it returns that container's URL without starting a new one (idempotent reuse). If no container is running, Start deploys a new one, then polls its /health endpoint with exponential backoff until it responds 200 or ctx is cancelled.
Returns a non-nil error if the container cannot be started or the health check never succeeds within the context deadline.
func (*EmbeddingServiceManager) Stop ¶
func (m *EmbeddingServiceManager) Stop(ctx context.Context) error
Stop stops the TEI container if this EmbeddingServiceManager instance started it. If the container was already running when Start was called (reuse case), Stop is a no-op — the container belongs to whichever process created it.
type EmbeddingServiceManagerConfig ¶
type EmbeddingServiceManagerConfig struct {
// Model is the HuggingFace model name (e.g. "BAAI/bge-small-en-v1.5").
// Required; must be non-empty.
Model string
// Image is the TEI container image to run.
// Defaults to DefaultEmbeddingImage when empty.
Image string
}
EmbeddingServiceManagerConfig holds the parameters for constructing an EmbeddingServiceManager.
type InitConfig ¶
type InitConfig struct {
// GroupName is the ToolHive group whose workloads are enumerated.
GroupName string
// OutputPath is the file path to write the generated config.
// If empty or "-", content is written to Writer.
OutputPath string
// Writer is used when OutputPath is empty or "-".
// Defaults to os.Stdout when nil.
Writer io.Writer
// Discoverer resolves running workloads in the group.
// In production, callers pass a *pkg/workloads.DiscovererAdapter (CLI) or
// the Kubernetes discoverer from pkg/vmcp/workloads/k8s.go.
Discoverer workloads.Discoverer
}
InitConfig holds all parameters for the Init command. Discoverer is injected rather than constructed internally to enable unit testing.
type ServeConfig ¶
type ServeConfig struct {
// ConfigPath is the path to the vMCP YAML configuration file.
// When set, takes precedence over GroupRef.
ConfigPath string
// GroupRef is a ToolHive group name used for zero-config quick mode when
// ConfigPath is empty. A minimal in-memory config is generated from this value.
GroupRef string
// Host is the address the server binds to (e.g. "127.0.0.1").
Host string
// Port is the TCP port the server listens on.
Port int
// EnableAudit enables audit logging with default configuration when
// the loaded config does not already define an audit section.
EnableAudit bool
// Optimizer tier selection (Phase 4 — flag-driven).
// EnableOptimizer enables Tier 1 FTS5 keyword search (find_tool / call_tool).
EnableOptimizer bool
// EnableEmbedding enables Tier 2 TEI semantic search; implies EnableOptimizer.
EnableEmbedding bool
// EmbeddingModel is the HuggingFace model name for the managed TEI container.
// Defaults to "BAAI/bge-small-en-v1.5" when empty.
EmbeddingModel string
// EmbeddingImage is the TEI container image.
// Defaults to the CPU TEI image when empty.
EmbeddingImage string
}
ServeConfig holds all parameters needed to start the vMCP server. Populated by the caller from Cobra flag values or equivalent. At least one of ConfigPath or GroupRef must be non-empty; ConfigPath takes precedence when both are provided.
type ValidateConfig ¶
type ValidateConfig struct {
// ConfigPath is the path to the vMCP YAML configuration file to validate.
ConfigPath string
}
ValidateConfig holds parameters for the validate command.
Source Files
Directories