Add thv build subcommand for building containers without running them (#1273)

Author: JAORMX

cmd/thv/app/build.go

@@ -0,0 +1,83 @@
+package app
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/stacklok/toolhive/pkg/container/images"
+	"github.com/stacklok/toolhive/pkg/logger"
+	"github.com/stacklok/toolhive/pkg/runner"
+)
+
+var buildCmd = &cobra.Command{
+	Use:   "build [flags] PROTOCOL",
+	Short: "Build a container for an MCP server without running it",
+	Long: `Build a container for an MCP server using a protocol scheme without running it.
+
+ToolHive supports building containers from protocol schemes:
+
+	$ thv build uvx://package-name
+	$ thv build npx://package-name
+	$ thv build go://package-name
+	$ thv build go://./local-path
+
+Automatically generates a container that can run the specified package
+using either uvx (Python with uv package manager), npx (Node.js),
+or go (Golang). For Go, you can also specify local paths starting
+with './' or '../' to build local Go projects.
+
+The container will be built and tagged locally, ready to be used with 'thv run'
+or other container tools. The built image name will be displayed upon successful completion.
+
+Examples:
+	$ thv build uvx://mcp-server-git
+	$ thv build --tag my-custom-name:latest npx://@modelcontextprotocol/server-filesystem
+	$ thv build go://./my-local-server`,
+	Args: cobra.ExactArgs(1),
+	RunE: buildCmdFunc,
+}
+
+var buildFlags BuildFlags
+
+// BuildFlags holds the configuration for building MCP server containers
+type BuildFlags struct {
+	Tag string
+}
+
+func init() {
+	// Add build flags
+	AddBuildFlags(buildCmd, &buildFlags)
+}
+
+// AddBuildFlags adds all the build flags to a command
+func AddBuildFlags(cmd *cobra.Command, config *BuildFlags) {
+	cmd.Flags().StringVarP(&config.Tag, "tag", "t", "", "Name and optionally a tag in the 'name:tag' format for the built image")
+}
+
+func buildCmdFunc(cmd *cobra.Command, args []string) error {
+	ctx := cmd.Context()
+	protocolScheme := args[0]
+
+	// Validate that this is a protocol scheme
+	if !runner.IsImageProtocolScheme(protocolScheme) {
+		return fmt.Errorf("invalid protocol scheme: %s. Supported schemes are: uvx://, npx://, go://", protocolScheme)
+	}
+
+	logger.Infof("Building container for protocol scheme: %s", protocolScheme)
+
+	// Create image manager for building
+	imageManager := images.NewImageManager(ctx)
+
+	// Build the image using the new protocol handler with custom name
+	imageName, err := runner.BuildFromProtocolSchemeWithName(ctx, imageManager, protocolScheme, "", buildFlags.Tag)
+	if err != nil {
+		return fmt.Errorf("failed to build container for %s: %v", protocolScheme, err)
+	}
+
+	logger.Infof("Successfully built container image: %s", imageName)
+	fmt.Printf("Container built successfully: %s\n", imageName)
+	fmt.Printf("You can now run it with: thv run %s\n", imageName)
+
+	return nil
+}

cmd/thv/app/commands.go

@@ -41,6 +41,7 @@ func NewRootCmd(enableUpdates bool) *cobra.Command {
 
 	// Add subcommands
 	rootCmd.AddCommand(runCmd)
+	rootCmd.AddCommand(buildCmd)
 	rootCmd.AddCommand(listCmd)
 	rootCmd.AddCommand(stopCmd)
 	rootCmd.AddCommand(rmCmd)

docs/cli/thv.md

@@ -8,6 +8,8 @@ import (
 	"strings"
 	"time"
 
+	nameref "github.com/google/go-containerregistry/pkg/name"
+
 	"github.com/stacklok/toolhive/pkg/certs"
 	"github.com/stacklok/toolhive/pkg/container/images"
 	"github.com/stacklok/toolhive/pkg/container/templates"
@@ -29,6 +31,20 @@ func HandleProtocolScheme(
 	imageManager images.ImageManager,
 	serverOrImage string,
 	caCertPath string,
+) (string, error) {
+	return BuildFromProtocolSchemeWithName(ctx, imageManager, serverOrImage, caCertPath, "")
+}
+
+// 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.
+// Returns the Docker image name to use and any error encountered.
+func BuildFromProtocolSchemeWithName(
+	ctx context.Context,
+	imageManager images.ImageManager,
+	serverOrImage string,
+	caCertPath string,
+	imageName string,
 ) (string, error) {
 	transportType, packageName, err := parseProtocolScheme(serverOrImage)
 	if err != nil {
@@ -40,7 +56,7 @@ func HandleProtocolScheme(
 		return "", err
 	}
 
-	return buildImageFromTemplate(ctx, imageManager, transportType, packageName, templateData)
+	return buildImageFromTemplateWithName(ctx, imageManager, transportType, packageName, templateData, imageName)
 }
 
 // parseProtocolScheme extracts the transport type and package name from the protocol scheme.
@@ -243,13 +259,15 @@ func generateImageName(transportType templates.TransportType, packageName string
 		tag))
 }
 
-// buildImageFromTemplate builds a Docker image from the template data.
-func buildImageFromTemplate(
+// buildImageFromTemplateWithName builds a Docker image from the template data with a custom image name.
+// If imageName is empty, a default name will be generated.
+func buildImageFromTemplateWithName(
 	ctx context.Context,
 	imageManager images.ImageManager,
 	transportType templates.TransportType,
 	packageName string,
 	templateData templates.TemplateData,
+	imageName string,
 ) (string, error) {
 
 	// Get the Dockerfile content
@@ -277,21 +295,33 @@ func buildImageFromTemplate(
 	}
 	defer caCertCleanup()
 
-	// Generate image name
-	imageName := generateImageName(transportType, packageName)
+	// Use provided image name or generate one
+	finalImageName := imageName
+	if finalImageName == "" {
+		finalImageName = generateImageName(transportType, packageName)
+	} else {
+		// Validate the provided image name using go-containerregistry
+		ref, err := nameref.ParseReference(finalImageName)
+		if err != nil {
+			return "", fmt.Errorf("invalid image name format '%s': %w", finalImageName, err)
+		}
+		// Use the normalized reference string
+		finalImageName = ref.String()
+		logger.Debugf("Using validated image name: %s", finalImageName)
+	}
 
 	// Log the build process
 	logger.Debugf("Building Docker image for %s package: %s", transportType, packageName)
 	logger.Debugf("Using Dockerfile:\n%s", dockerfileContent)
 
 	// Build the Docker image
 	logger.Infof("Building Docker image for %s package: %s", transportType, packageName)
-	if err := imageManager.BuildImage(ctx, buildCtx.Dir, imageName); err != nil {
+	if err := imageManager.BuildImage(ctx, buildCtx.Dir, finalImageName); err != nil {
 		return "", fmt.Errorf("failed to build Docker image: %w", err)
 	}
-	logger.Infof("Successfully built Docker image: %s", imageName)
+	logger.Infof("Successfully built Docker image: %s", finalImageName)
 
-	return imageName, nil
+	return finalImageName, nil
 }
 
 // Replace slashes with dashes to create a valid Docker image name. If there