Add thv vmcp serve and thv vmcp validate subcommands (#4900)

Create cmd/thv/app/vmcp.go with newVMCPCommand(), newVMCPServeCommand(),
and newVMCPValidateCommand() — thin wrappers that parse flags and delegate
to pkg/vmcp/cli/Serve and pkg/vmcp/cli/Validate respectively.

Register the command in NewRootCmd() and add "vmcp" to the
informationalCommands map so it bypasses container runtime preflight.
Regenerate CLI docs via task docs.

This is Phase 2 of RFC THV-0059, making thv vmcp serve and
thv vmcp validate available to users for the first time.

Closes #4883

Co-authored-by: taskbot <taskbot@users.noreply.github.com>

Author: yrobla

cmd/thv/app/commands.go

@@ -70,6 +70,7 @@ func NewRootCmd(enableUpdates bool) *cobra.Command {
 	rootCmd.AddCommand(newSecretCommand())
 	rootCmd.AddCommand(inspectorCommand())
 	rootCmd.AddCommand(newMCPCommand())
+	rootCmd.AddCommand(newVMCPCommand())
 	rootCmd.AddCommand(groupCmd)
 	rootCmd.AddCommand(skillCmd)
 	rootCmd.AddCommand(statusCmd)
@@ -100,14 +101,18 @@ func IsInformationalCommand(args []string) bool {
 
 	command := args[1]
 
-	// Commands that are entirely informational and don't need container runtime
+	// Commands that don't need container runtime or startup migrations.
+	// "vmcp" is safe here: telemetry/secret-scope migrations only affect thv run state,
+	// and EnsureDefaultGroupExists is called inside pkg/vmcp/cli/Serve when dynamic
+	// backend discovery is used (i.e. when no static backends are configured).
 	informationalCommands := map[string]bool{
 		"version":    true,
 		"search":     true,
 		"completion": true,
 		"registry":   true,
 		"mcp":        true,
 		"skill":      true,
+		"vmcp":       true,
 	}
 
 	return informationalCommands[command]

cmd/thv/app/vmcp.go

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package app
+
+import (
+	"github.com/spf13/cobra"
+
+	vmcpcli "github.com/stacklok/toolhive/pkg/vmcp/cli"
+)
+
+// newVMCPCommand returns the top-level "vmcp" Cobra command with subcommands attached.
+func newVMCPCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "vmcp",
+		Short: "Run and manage a Virtual MCP Server locally",
+		Long: `The vmcp command provides subcommands to run and validate a Virtual MCP
+Server (vMCP) locally without Kubernetes. A vMCP aggregates multiple MCP
+servers from a ToolHive group into a single unified endpoint.`,
+	}
+	cmd.AddCommand(newVMCPServeCommand())
+	cmd.AddCommand(newVMCPValidateCommand())
+	return cmd
+}
+
+// newVMCPServeCommand returns the "vmcp serve" subcommand.
+func newVMCPServeCommand() *cobra.Command {
+	var (
+		configPath  string
+		host        string
+		port        int
+		enableAudit bool
+	)
+	cmd := &cobra.Command{
+		Use:   "serve",
+		Short: "Start the Virtual MCP Server",
+		Long: `Start the Virtual MCP Server to aggregate and proxy multiple MCP servers.
+
+The server reads the configuration file specified by --config and starts
+listening for MCP client connections, aggregating tools, resources, and
+prompts from all configured backend MCP servers.`,
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return vmcpcli.Serve(cmd.Context(), vmcpcli.ServeConfig{
+				ConfigPath:  configPath,
+				Host:        host,
+				Port:        port,
+				EnableAudit: enableAudit,
+			})
+		},
+	}
+	cmd.Flags().StringVarP(&configPath, "config", "c", "", "Path to vMCP configuration file (required)")
+	cmd.Flags().StringVar(&host, "host", "127.0.0.1", "Host address to bind to")
+	cmd.Flags().IntVar(&port, "port", 4483, "Port to listen on")
+	cmd.Flags().BoolVar(&enableAudit, "enable-audit", false, "Enable audit logging with default configuration")
+	_ = cmd.MarkFlagRequired("config")
+	return cmd
+}
+
+// newVMCPValidateCommand returns the "vmcp validate" subcommand.
+func newVMCPValidateCommand() *cobra.Command {
+	var configPath string
+	cmd := &cobra.Command{
+		Use:   "validate",
+		Short: "Validate a vMCP configuration file",
+		Long: `Validate the vMCP configuration file for syntax and semantic errors.
+
+This command checks YAML syntax, required field presence, middleware
+configuration correctness, and backend configuration validity. Exits 0
+for valid configurations, non-zero with a descriptive error otherwise.`,
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return vmcpcli.Validate(cmd.Context(), vmcpcli.ValidateConfig{
+				ConfigPath: configPath,
+			})
+		},
+	}
+	cmd.Flags().StringVarP(&configPath, "config", "c", "", "Path to vMCP configuration file (required)")
+	_ = cmd.MarkFlagRequired("config")
+	return cmd
+}

cmd/thv/main.go

@@ -66,8 +66,13 @@ func main() {
 		// Renames bare system keys (BEARER_TOKEN_, REGISTRY_OAUTH_, etc.) to __thv_<scope>_ namespace
 		migration.CheckAndPerformSecretScopeMigration()
 
-		// Ensure default group exists (creates it for fresh installs, no-op otherwise)
-		migration.EnsureDefaultGroupExists()
+		// Ensure the default group exists on fresh installs so that commands
+		// which default to --group default (e.g. run, list) work without the
+		// user having to create the group manually.
+		if err := migration.EnsureDefaultGroupExists(); err != nil {
+			slog.Error("failed to ensure default group exists", "error", err)
+			os.Exit(1)
+		}
 	}
 
 	cmd := app.NewRootCmd(!app.IsCompletionCommand(os.Args))

docs/cli/thv.md

@@ -7,24 +7,22 @@ package migration
 import (
 	"context"
 	"log/slog"
-	"sync"
 
+	"github.com/stacklok/toolhive/pkg/container/runtime"
 	"github.com/stacklok/toolhive/pkg/groups"
 )
 
-// ensureDefaultGroupOnce ensures the default group check only runs once per process
-var ensureDefaultGroupOnce sync.Once
-
 // EnsureDefaultGroupExists ensures the default group exists, creating it if necessary.
 // This is called at application startup for fresh installs and is a no-op when
 // the group already exists (e.g. after a previous migration or existing setup).
-func EnsureDefaultGroupExists() {
-	ensureDefaultGroupOnce.Do(func() {
-		if err := ensureDefaultGroupExists(context.Background()); err != nil {
-			slog.Error("failed to ensure default group exists", "error", err)
-			return
-		}
-	})
+// In Kubernetes environments this is always a no-op: MCPGroup CRDs are
+// operator/user-managed resources and the caller's service account may not
+// have create permission on them.
+func EnsureDefaultGroupExists() error {
+	if runtime.IsKubernetesRuntime() {
+		return nil
+	}
+	return ensureDefaultGroupExists(context.Background())
 }
 
 func ensureDefaultGroupExists(ctx context.Context) error {

docs/cli/thv_vmcp.md

@@ -160,7 +160,7 @@ func (d *backendDiscoverer) Discover(ctx context.Context, groupRef string) (back
 		return nil, fmt.Errorf("failed to check if group exists: %w", err)
 	}
 	if !exists {
-		return nil, fmt.Errorf("group %s not found", groupRef)
+		return nil, fmt.Errorf("%w: %s", groups.ErrGroupNotFound, groupRef)
 	}
 
 	// Get all typedWorkloads in the group

docs/cli/thv_vmcp_serve.md

@@ -28,6 +28,7 @@ import (
 	"github.com/stacklok/toolhive/pkg/authserver/server/keys"
 	"github.com/stacklok/toolhive/pkg/container/runtime"
 	"github.com/stacklok/toolhive/pkg/groups"
+	"github.com/stacklok/toolhive/pkg/migration"
 	"github.com/stacklok/toolhive/pkg/telemetry"
 	"github.com/stacklok/toolhive/pkg/versions"
 	"github.com/stacklok/toolhive/pkg/vmcp"
@@ -418,8 +419,14 @@ func discoverBackends(
 			cfg.Group,
 		)
 	} else {
-		// Dynamic mode: discover backends at runtime from K8s API.
+		// Dynamic mode: discover backends at runtime from the active workload manager (K8s or local).
 		slog.Info("dynamic mode: initializing group manager for backend discovery")
+		// EnsureDefaultGroupExists is a no-op in Kubernetes (service account has no
+		// create permission on MCPGroup CRDs). If the group does not exist,
+		// Discover returns ErrGroupNotFound which is handled below.
+		if err := migration.EnsureDefaultGroupExists(); err != nil {
+			return nil, nil, nil, fmt.Errorf("failed to ensure default group exists: %w", err)
+		}
 		groupsManager, err := groups.NewManager()
 		if err != nil {
 			return nil, nil, nil, fmt.Errorf("failed to create groups manager: %w", err)
@@ -447,6 +454,13 @@ func runDiscovery(
 	slog.Info(fmt.Sprintf("Discovering backends in group: %s", groupRef))
 	backends, err := discoverer.Discover(ctx, groupRef)
 	if err != nil {
+		// In Kubernetes mode the MCPGroup CRD is operator/user-managed and may
+		// not exist yet. Treat a missing group as zero backends so vMCP can
+		// start and serve once backends are registered later.
+		if runtime.IsKubernetesRuntime() && errors.Is(err, groups.ErrGroupNotFound) {
+			slog.Warn(fmt.Sprintf("Group %s not found - vmcp will start but have no backends to proxy", groupRef))
+			return []vmcp.Backend{}, backendClient, outgoingRegistry, nil
+		}
 		return nil, nil, nil, fmt.Errorf("failed to discover backends: %w", err)
 	}