Merge branch 'main' into use-status-file-for-pids

Author: dmjb

.github/workflows/run-on-main-charts.yml

@@ -7,10 +7,6 @@ on:
     branches: [ main ]
     paths:
       - deploy/charts/**
-    paths-ignore:
-      - deploy/charts/**/CONTRIBUTING.md
-      - deploy/charts/**/ci/**
-      - deploy/charts/**/CLAUDE.md
 
 jobs:
   publish-charts:

.github/workflows/run-on-pr-charts.yml

@@ -8,10 +8,6 @@ on:
   pull_request:
     paths:
       - deploy/charts/**
-    paths-ignore:
-      - deploy/charts/**/CONTRIBUTING.md
-      - deploy/charts/**/ci/**
-      - deploy/charts/**/CLAUDE.md
 
 jobs:
   spellcheck:

CLAUDE.md

@@ -10,7 +10,7 @@ ToolHive is a lightweight, secure manager for MCP (Model Context Protocol: https
 - **Kubernetes Operator (`thv-operator`)**: Manages MCP servers in Kubernetes clusters
 - **Proxy Runner (`thv-proxyrunner`)**: Handles proxy functionality for MCP server communication
 
-The application acts as a thin client for Docker/Podman Unix socket API, providing container-based isolation for running MCP servers securely. It also builds on top of the MCP Specification: https://modelcontextprotocol.io/specification.
+The application acts as a thin client for Docker/Podman/Colima Unix socket API, providing container-based isolation for running MCP servers securely. It also builds on top of the MCP Specification: https://modelcontextprotocol.io/specification.
 
 ## Build and Development Commands
 
@@ -90,7 +90,7 @@ The test framework uses Ginkgo and Gomega for BDD-style testing.
 
 ### Key Design Patterns
 
-- **Factory Pattern**: Used extensively for creating runtime-specific implementations (Docker vs Kubernetes)
+- **Factory Pattern**: Used extensively for creating runtime-specific implementations (Docker/Colima/Podman vs Kubernetes)
 - **Interface Segregation**: Clean abstractions for container runtimes, transports, and storage
 - **Middleware Pattern**: HTTP middleware for auth, authz, telemetry
 - **Observer Pattern**: Event system for audit logging
@@ -131,6 +131,16 @@ The project uses `go.uber.org/mock` for generating mocks. Mock files are located
 - Supports environment variable overrides
 - Client configuration stored in `~/.toolhive/` or equivalent
 
+### Container Runtime Configuration
+
+ToolHive automatically detects available container runtimes in the following order: Podman, Colima, Docker. You can override the default socket paths using environment variables:
+
+- `TOOLHIVE_PODMAN_SOCKET`: Custom Podman socket path
+- `TOOLHIVE_COLIMA_SOCKET`: Custom Colima socket path (default: `~/.colima/default/docker.sock`)
+- `TOOLHIVE_DOCKER_SOCKET`: Custom Docker socket path
+
+**Colima Support**: Colima is fully supported as a Docker-compatible runtime. ToolHive will automatically detect Colima installations on macOS and Linux systems.
+
 ## Development Guidelines
 
 ### Code Organization
@@ -176,7 +186,7 @@ When working on the Kubernetes operator:
 
 ### Working with Containers
 
-The container abstraction supports both Docker and Kubernetes runtimes. When adding container functionality:
+The container abstraction supports Docker, Colima, Podman, and Kubernetes runtimes. When adding container functionality:
 - Implement the interface in `pkg/container/runtime/types.go`
 - Add runtime-specific implementations in appropriate subdirectories
 - Use factory pattern for runtime selection

cmd/thv-operator/api/v1alpha1/mcpserver_types.go

@@ -16,6 +16,13 @@ type MCPServerSpec struct {
 	// +kubebuilder:default=stdio
 	Transport string `json:"transport,omitempty"`
 
+	// ProxyMode is the proxy mode for stdio transport (sse or streamable-http)
+	// This setting is only used when Transport is "stdio"
+	// +kubebuilder:validation:Enum=sse;streamable-http
+	// +kubebuilder:default=sse
+	// +optional
+	ProxyMode string `json:"proxyMode,omitempty"`
+
 	// Port is the port to expose the MCP server on
 	// +kubebuilder:validation:Minimum=1
 	// +kubebuilder:validation:Maximum=65535

cmd/thv-operator/controllers/mcpserver_controller.go

@@ -71,13 +71,21 @@ var defaultRBACRules = []rbacv1.PolicyRule{
 		Resources: []string{"pods/attach"},
 		Verbs:     []string{"create", "get"},
 	},
+	{
+		APIGroups: []string{""},
+		Resources: []string{"configmaps"},
+		Verbs:     []string{"get", "list", "watch"},
+	},
 }
 
 var ctxLogger = log.FromContext(context.Background())
 
 // mcpContainerName is the name of the mcp container used in pod templates
 const mcpContainerName = "mcp"
 
+// trueValue is the string value "true" used for environment variable comparisons
+const trueValue = "true"
+
 // Authorization ConfigMap label constants
 const (
 	// authzLabelKey is the label key for authorization configuration type
@@ -463,38 +471,51 @@ func (r *MCPServerReconciler) deploymentForMCPServer(ctx context.Context, m *mcp
 
 	// Prepare container args
 	args := []string{"run", "--foreground=true"}
-	args = append(args, fmt.Sprintf("--proxy-port=%d", m.Spec.Port))
-	args = append(args, fmt.Sprintf("--name=%s", m.Name))
-	args = append(args, fmt.Sprintf("--transport=%s", m.Spec.Transport))
-	args = append(args, fmt.Sprintf("--host=%s", getProxyHost()))
 
-	if m.Spec.TargetPort != 0 {
-		args = append(args, fmt.Sprintf("--target-port=%d", m.Spec.TargetPort))
-	}
-
-	// Generate pod template patch for secrets and merge with user-provided patch
-
-	finalPodTemplateSpec := NewMCPServerPodTemplateSpecBuilder(m.Spec.PodTemplateSpec).
-		WithServiceAccount(m.Spec.ServiceAccount).
-		WithSecrets(m.Spec.Secrets).
-		Build()
-	// Add pod template patch if we have one
-	if finalPodTemplateSpec != nil {
-		podTemplatePatch, err := json.Marshal(finalPodTemplateSpec)
-		if err != nil {
-			logger.Errorf("Failed to marshal pod template spec: %v", err)
-		} else {
-			args = append(args, fmt.Sprintf("--k8s-pod-patch=%s", string(podTemplatePatch)))
+	// Check if global ConfigMap mode is enabled via environment variable
+	useConfigMap := os.Getenv("TOOLHIVE_USE_CONFIGMAP") == trueValue
+	if useConfigMap {
+		// Use the operator-created ConfigMap (format: {name}-runconfig)
+		configMapName := fmt.Sprintf("%s-runconfig", m.Name)
+		configMapRef := fmt.Sprintf("%s/%s", m.Namespace, configMapName)
+		args = append(args, fmt.Sprintf("--from-configmap=%s", configMapRef))
+	} else {
+		// Use individual configuration flags (existing behavior)
+		args = append(args, fmt.Sprintf("--proxy-port=%d", m.Spec.Port))
+		args = append(args, fmt.Sprintf("--name=%s", m.Name))
+		args = append(args, fmt.Sprintf("--transport=%s", m.Spec.Transport))
+		args = append(args, fmt.Sprintf("--host=%s", getProxyHost()))
+		if m.Spec.TargetPort != 0 {
+			args = append(args, fmt.Sprintf("--target-port=%d", m.Spec.TargetPort))
+		}
+	}
+
+	// Add pod template patch and permission profile only if not using ConfigMap
+	// When using ConfigMap, these are included in the runconfig.json
+	if !useConfigMap {
+		// Generate pod template patch for secrets and merge with user-provided patch
+		finalPodTemplateSpec := NewMCPServerPodTemplateSpecBuilder(m.Spec.PodTemplateSpec).
+			WithServiceAccount(m.Spec.ServiceAccount).
+			WithSecrets(m.Spec.Secrets).
+			Build()
+		// Add pod template patch if we have one
+		if finalPodTemplateSpec != nil {
+			podTemplatePatch, err := json.Marshal(finalPodTemplateSpec)
+			if err != nil {
+				logger.Errorf("Failed to marshal pod template spec: %v", err)
+			} else {
+				args = append(args, fmt.Sprintf("--k8s-pod-patch=%s", string(podTemplatePatch)))
+			}
 		}
-	}
 
-	// Add permission profile args
-	if m.Spec.PermissionProfile != nil {
-		switch m.Spec.PermissionProfile.Type {
-		case mcpv1alpha1.PermissionProfileTypeBuiltin:
-			args = append(args, fmt.Sprintf("--permission-profile=%s", m.Spec.PermissionProfile.Name))
-		case mcpv1alpha1.PermissionProfileTypeConfigMap:
-			args = append(args, fmt.Sprintf("--permission-profile-path=/etc/toolhive/profiles/%s", m.Spec.PermissionProfile.Key))
+		// Add permission profile args
+		if m.Spec.PermissionProfile != nil {
+			switch m.Spec.PermissionProfile.Type {
+			case mcpv1alpha1.PermissionProfileTypeBuiltin:
+				args = append(args, fmt.Sprintf("--permission-profile=%s", m.Spec.PermissionProfile.Name))
+			case mcpv1alpha1.PermissionProfileTypeConfigMap:
+				args = append(args, fmt.Sprintf("--permission-profile-path=/etc/toolhive/profiles/%s", m.Spec.PermissionProfile.Key))
+			}
 		}
 	}
 
@@ -526,15 +547,18 @@ func (r *MCPServerReconciler) deploymentForMCPServer(ctx context.Context, m *mcp
 		args = append(args, "--enable-audit")
 	}
 
-	// Add environment variables as --env flags for the MCP server
-	for _, e := range m.Spec.Env {
-		args = append(args, fmt.Sprintf("--env=%s=%s", e.Name, e.Value))
-	}
+	// Add environment variables and tools filter only if not using ConfigMap
+	if !useConfigMap {
+		// Add environment variables as --env flags for the MCP server
+		for _, e := range m.Spec.Env {
+			args = append(args, fmt.Sprintf("--env=%s=%s", e.Name, e.Value))
+		}
 
-	// Add tools filter args
-	if len(m.Spec.ToolsFilter) > 0 {
-		slices.Sort(m.Spec.ToolsFilter)
-		args = append(args, fmt.Sprintf("--tools=%s", strings.Join(m.Spec.ToolsFilter, ",")))
+		// Add tools filter args
+		if len(m.Spec.ToolsFilter) > 0 {
+			slices.Sort(m.Spec.ToolsFilter)
+			args = append(args, fmt.Sprintf("--tools=%s", strings.Join(m.Spec.ToolsFilter, ",")))
+		}
 	}
 
 	// Add OpenTelemetry configuration args
@@ -550,11 +574,13 @@ func (r *MCPServerReconciler) deploymentForMCPServer(ctx context.Context, m *mcp
 		}
 	}
 
-	// Add the image
+	// Always add the image as it's required by proxy runner command signature
+	// When using ConfigMap, the image from ConfigMap takes precedence, but we still need
+	// to provide this as a positional argument to satisfy the command requirements
 	args = append(args, m.Spec.Image)
 
-	// Add additional args
-	if len(m.Spec.Args) > 0 {
+	// Add additional args only if not using ConfigMap
+	if !useConfigMap && len(m.Spec.Args) > 0 {
 		args = append(args, "--")
 		args = append(args, m.Spec.Args...)
 	}

cmd/thv-operator/controllers/mcpserver_runconfig.go

@@ -216,19 +216,38 @@ func (*MCPServerReconciler) createRunConfigFromMCPServer(m *mcpv1alpha1.MCPServe
 		}
 	}
 
-	// Use the RunConfigBuilder for operator context with full builder pattern
-	config, err := runner.NewOperatorRunConfigBuilder().
+	// Set proxy mode, defaulting to "sse" if not specified
+	proxyMode := m.Spec.ProxyMode
+	if proxyMode == "" {
+		proxyMode = "sse" // Default to SSE for backward compatibility
+	}
+
+	builder := runner.NewOperatorRunConfigBuilder().
 		WithName(m.Name).
 		WithImage(m.Spec.Image).
 		WithCmdArgs(m.Spec.Args).
 		WithTransportAndPorts(m.Spec.Transport, port, int(m.Spec.TargetPort)).
+		WithProxyMode(transporttypes.ProxyMode(proxyMode)).
 		WithHost(proxyHost).
 		WithToolsFilter(m.Spec.ToolsFilter).
 		WithEnvVars(envVars).
 		WithVolumes(volumes).
 		WithSecrets(secrets).
-		WithK8sPodPatch(k8sPodPatch).
-		BuildForOperator()
+		WithK8sPodPatch(k8sPodPatch)
+
+	// Add permission profile if specified
+	if m.Spec.PermissionProfile != nil {
+		switch m.Spec.PermissionProfile.Type {
+		case mcpv1alpha1.PermissionProfileTypeBuiltin:
+			builder = builder.WithPermissionProfileNameOrPath(m.Spec.PermissionProfile.Name)
+		case mcpv1alpha1.PermissionProfileTypeConfigMap:
+			// For ConfigMap-based permission profiles, we store the path
+			builder = builder.WithPermissionProfileNameOrPath(fmt.Sprintf("/etc/toolhive/profiles/%s", m.Spec.PermissionProfile.Key))
+		}
+	}
+
+	// Use the RunConfigBuilder for operator context with full builder pattern
+	config, err := builder.BuildForOperator()
 
 	if err != nil {
 		return nil, err

cmd/thv-operator/controllers/mcpserver_runconfig_test.go

@@ -20,6 +20,13 @@ import (
 	transporttypes "github.com/stacklok/toolhive/pkg/transport/types"
 )
 
+const (
+	testImage               = "test-image:latest"
+	stdioTransport          = "stdio"
+	sseProxyMode            = "sse"
+	streamableHTTPProxyMode = "streamable-http"
+)
+
 func createRunConfigTestScheme() *runtime.Scheme {
 	testScheme := runtime.NewScheme()
 	_ = corev1.AddToScheme(testScheme)
@@ -35,7 +42,7 @@ func createTestMCPServerWithConfig(name, namespace, image string, envVars []mcpv
 		},
 		Spec: mcpv1alpha1.MCPServerSpec{
 			Image:     image,
-			Transport: "stdio",
+			Transport: stdioTransport,
 			Port:      8080,
 			Env:       envVars,
 		},
@@ -58,8 +65,8 @@ func TestCreateRunConfigFromMCPServer(t *testing.T) {
 					Namespace: "test-ns",
 				},
 				Spec: mcpv1alpha1.MCPServerSpec{
-					Image:     "test-image:latest",
-					Transport: "stdio",
+					Image:     testImage,
+					Transport: stdioTransport,
 					Port:      8080,
 				},
 			},
@@ -142,6 +149,50 @@ func TestCreateRunConfigFromMCPServer(t *testing.T) {
 					config.Secrets[1] == "secret2,target=key2"
 			},
 		},
+		{
+			name: "proxy mode specified",
+			mcpServer: &mcpv1alpha1.MCPServer{
+				ObjectMeta: metav1.ObjectMeta{
+					Name:      "proxy-mode-server",
+					Namespace: "test-ns",
+				},
+				Spec: mcpv1alpha1.MCPServerSpec{
+					Image:     testImage,
+					Transport: stdioTransport,
+					Port:      8080,
+					ProxyMode: streamableHTTPProxyMode,
+				},
+			},
+			expected: func(config *runner.RunConfig) bool {
+				return config.Name == "proxy-mode-server" &&
+					config.Image == testImage &&
+					config.Transport == stdioTransport &&
+					config.Port == 8080 &&
+					config.ProxyMode == streamableHTTPProxyMode
+			},
+		},
+		{
+			name: "proxy mode defaults to sse when not specified",
+			mcpServer: &mcpv1alpha1.MCPServer{
+				ObjectMeta: metav1.ObjectMeta{
+					Name:      "default-proxy-mode-server",
+					Namespace: "test-ns",
+				},
+				Spec: mcpv1alpha1.MCPServerSpec{
+					Image:     testImage,
+					Transport: stdioTransport,
+					Port:      8080,
+					// ProxyMode not specified
+				},
+			},
+			expected: func(config *runner.RunConfig) bool {
+				return config.Name == "default-proxy-mode-server" &&
+					config.Image == testImage &&
+					config.Transport == stdioTransport &&
+					config.Port == 8080 &&
+					config.ProxyMode == sseProxyMode // Should default to sse
+			},
+		},
 		{
 			name: "comprehensive test with all fields",
 			mcpServer: &mcpv1alpha1.MCPServer{
@@ -154,6 +205,7 @@ func TestCreateRunConfigFromMCPServer(t *testing.T) {
 					Transport:   "streamable-http",
 					Port:        9090,
 					TargetPort:  8080,
+					ProxyMode:   "streamable-http",
 					Args:        []string{"--comprehensive", "--test"},
 					ToolsFilter: []string{"tool1", "tool2"},
 					Env: []mcpv1alpha1.EnvVar{
@@ -177,6 +229,7 @@ func TestCreateRunConfigFromMCPServer(t *testing.T) {
 					config.Transport == "streamable-http" &&
 					config.Port == 9090 &&
 					config.TargetPort == 8080 &&
+					config.ProxyMode == streamableHTTPProxyMode &&
 					len(config.CmdArgs) == 2 &&
 					config.CmdArgs[0] == "--comprehensive" &&
 					len(config.ToolsFilter) == 2 &&
@@ -1024,6 +1077,20 @@ func TestMCPServerModificationScenarios(t *testing.T) {
 				"Secrets": []string{"secret1,target=CUSTOM_ENV1", "secret2,target=key2"},
 			},
 		},
+		{
+			name: "Proxy mode change",
+			initialServer: func() *mcpv1alpha1.MCPServer {
+				server := createTestMCPServerWithConfig("proxy-test", "default", "test:v1", nil)
+				server.Spec.ProxyMode = sseProxyMode
+				return server
+			},
+			modifyServer: func(server *mcpv1alpha1.MCPServer) {
+				server.Spec.ProxyMode = streamableHTTPProxyMode
+			},
+			expectedChanges: map[string]interface{}{
+				"ProxyMode": transporttypes.ProxyModeStreamableHTTP,
+			},
+		},
 	}
 
 	for _, tt := range tests {