Add MCP optimizer implementation for semantic tool discovery

.gitignore

@@ -44,3 +44,12 @@ coverage*
 
 crd-helm-wrapper
 cmd/vmcp/__debug_bin*
+
+# Demo files
+examples/operator/virtual-mcps/vmcp_optimizer.yaml
+scripts/k8s_vmcp_optimizer_demo.sh
+examples/ingress/mcp-servers-ingress.yaml
+examples/vmcp-config-optimizer.yaml
+/vmcp
+thv-operator
+thv

BRANCH_SPLIT_SUMMARY.md

@@ -0,0 +1,82 @@
+# Branch Split Summary
+
+## Branches Created
+- `optimizer-enablers`: Infrastructure improvements and bugfixes (no optimizer code)
+- `optimizer-implementation`: Full optimizer implementation (includes all changes)
+
+## Files Removed from optimizer-enablers Branch
+✅ Already removed:
+- `cmd/thv-operator/pkg/optimizer/` (entire directory)
+- `pkg/vmcp/optimizer/` (entire directory)
+- `pkg/vmcp/server/adapter/optimizer_adapter.go`
+- `pkg/vmcp/server/adapter/optimizer_adapter_test.go`
+- `pkg/vmcp/server/optimizer_test.go`
+- `examples/vmcp-config-optimizer.yaml`
+- `test/e2e/thv-operator/virtualmcp/virtualmcp_optimizer_test.go`
+
+## Files That Need Manual Cleanup in optimizer-enablers Branch
+
+### 1. `pkg/vmcp/config/config.go`
+- Revert `OptimizerConfig` struct to simpler version from main
+- Keep the `Optimizer *OptimizerConfig` field in `Config` struct (exists in main)
+
+### 2. `pkg/vmcp/server/server.go`
+- Remove optimizer initialization code
+- Remove optimizer-related imports
+- Keep other improvements (tracing, health checks, etc.)
+
+### 3. `cmd/vmcp/app/commands.go`
+- Remove optimizer configuration parsing
+- Remove optimizer-related imports
+- Keep other CLI improvements
+
+### 4. `pkg/vmcp/router/default_router.go`
+- Remove `optim_*` prefix handling (if added)
+- Keep other router improvements
+
+### 5. `cmd/thv-operator/pkg/vmcpconfig/converter.go`
+- Remove `resolveEmbeddingService` function
+- Remove optimizer config conversion logic
+- Keep other converter improvements
+
+### 6. CRD Files
+- `deploy/charts/operator-crds/files/crds/toolhive.stacklok.dev_virtualmcpservers.yaml`
+- `deploy/charts/operator-crds/templates/toolhive.stacklok.dev_virtualmcpservers.yaml`
+- Revert optimizer config schema to simpler version from main
+
+### 7. `docs/operator/crd-api.md`
+- Remove optimizer config documentation (or revert to simpler version)
+
+### 8. `Taskfile.yml`
+- Remove `-tags="fts5"` build flags (optimizer-specific)
+- Remove `test-optimizer` task
+
+### 9. `go.mod` and `go.sum`
+- Remove optimizer-related dependencies (chromem-go, sqlite-vec, etc.)
+- Keep other dependency updates
+
+### 10. `cmd/vmcp/README.md`
+- Remove optimizer mentions from "In Progress" section
+
+## Files That Stay in Both Branches (Enabler Changes)
+- `pkg/vmcp/aggregator/default_aggregator.go` - OpenTelemetry tracing
+- `pkg/vmcp/discovery/manager.go` - Singleflight deduplication
+- `pkg/vmcp/health/checker.go` - Self-check prevention
+- `pkg/vmcp/health/checker_selfcheck_test.go` - New test file
+- `pkg/vmcp/health/checker_test.go` - Test updates
+- `pkg/vmcp/health/monitor.go` - Health monitor updates
+- `pkg/vmcp/health/monitor_test.go` - Test updates
+- `pkg/vmcp/client/client.go` - HTTP timeout fixes
+- `test/e2e/thv-operator/virtualmcp/helpers.go` - Test reliability fixes
+- `test/e2e/thv-operator/virtualmcp/virtualmcp_auth_discovery_test.go` - Test fixes
+- `test/integration/vmcp/helpers/helpers_test.go` - Test updates
+- `.gitignore` - Debug binary patterns
+- `.golangci.yml` - Scripts exclusion
+- `codecov.yaml` - Test coverage exclusions
+- `deploy/charts/operator-crds/Chart.yaml` - Version bump
+- `deploy/charts/operator-crds/README.md` - Version update
+
+## Next Steps
+1. Manually edit the files listed above in `optimizer-enablers` branch
+2. Test that `optimizer-enablers` branch compiles and works without optimizer
+3. Verify `optimizer-implementation` branch has all changes intact

Taskfile.yml

@@ -176,6 +176,11 @@ tasks:
     desc: Run all tests (unit and e2e)
     deps: [test, test-e2e]
 
+  test-optimizer:
+    desc: Run optimizer integration tests with sqlite-vec
+    cmds:
+      - ./scripts/test-optimizer-with-sqlite-vec.sh
+
   build:
     desc: Build the binary
     deps: [gen]
@@ -219,12 +224,12 @@ tasks:
     cmds:
       - cmd: mkdir -p bin
         platforms: [linux, darwin]
-      - cmd: go build -ldflags "-s -w -X github.com/stacklok/toolhive/pkg/versions.Version={{.VERSION}} -X github.com/stacklok/toolhive/pkg/versions.Commit={{.COMMIT}} -X github.com/stacklok/toolhive/pkg/versions.BuildDate={{.BUILD_DATE}}" -o bin/vmcp ./cmd/vmcp
+      - cmd: go build -tags="fts5" -ldflags "-s -w -X github.com/stacklok/toolhive/pkg/versions.Version={{.VERSION}} -X github.com/stacklok/toolhive/pkg/versions.Commit={{.COMMIT}} -X github.com/stacklok/toolhive/pkg/versions.BuildDate={{.BUILD_DATE}}" -o bin/vmcp ./cmd/vmcp
         platforms: [linux, darwin]
       - cmd: cmd.exe /c mkdir bin
         platforms: [windows]
         ignore_error: true
-      - cmd: go build -ldflags "-s -w -X github.com/stacklok/toolhive/pkg/versions.Version={{.VERSION}} -X github.com/stacklok/toolhive/pkg/versions.Commit={{.COMMIT}} -X github.com/stacklok/toolhive/pkg/versions.BuildDate={{.BUILD_DATE}}" -o bin/vmcp.exe ./cmd/vmcp
+      - cmd: go build -tags="fts5" -ldflags "-s -w -X github.com/stacklok/toolhive/pkg/versions.Version={{.VERSION}} -X github.com/stacklok/toolhive/pkg/versions.Commit={{.COMMIT}} -X github.com/stacklok/toolhive/pkg/versions.BuildDate={{.BUILD_DATE}}" -o bin/vmcp.exe ./cmd/vmcp
         platforms: [windows]
 
   install-vmcp:
@@ -236,7 +241,7 @@ tasks:
         sh: git rev-parse --short HEAD || echo "unknown"
       BUILD_DATE: '{{dateInZone "2006-01-02T15:04:05Z" (now) "UTC"}}'
     cmds:
-      - go install -ldflags "-s -w -X github.com/stacklok/toolhive/pkg/versions.Version={{.VERSION}} -X github.com/stacklok/toolhive/pkg/versions.Commit={{.COMMIT}} -X github.com/stacklok/toolhive/pkg/versions.BuildDate={{.BUILD_DATE}}" -v ./cmd/vmcp
+      - go install -tags="fts5" -ldflags "-s -w -X github.com/stacklok/toolhive/pkg/versions.Version={{.VERSION}} -X github.com/stacklok/toolhive/pkg/versions.Commit={{.COMMIT}} -X github.com/stacklok/toolhive/pkg/versions.BuildDate={{.BUILD_DATE}}" -v ./cmd/vmcp
 
   all:
     desc: Run linting, tests, and build

cmd/thv-operator/controllers/mcpserver_controller.go

@@ -1137,12 +1137,13 @@ func (r *MCPServerReconciler) deploymentForMCPServer(
 				Spec: corev1.PodSpec{
 					ServiceAccountName: ctrlutil.ProxyRunnerServiceAccountName(m.Name),
 					Containers: []corev1.Container{{
-						Image:        getToolhiveRunnerImage(),
-						Name:         "toolhive",
-						Args:         args,
-						Env:          env,
-						VolumeMounts: volumeMounts,
-						Resources:    resources,
+						Image:           getToolhiveRunnerImage(),
+						Name:            "toolhive",
+						ImagePullPolicy: getImagePullPolicyForToolhiveRunner(),
+						Args:            args,
+						Env:             env,
+						VolumeMounts:    volumeMounts,
+						Resources:       resources,
 						Ports: []corev1.ContainerPort{{
 							ContainerPort: m.GetProxyPort(),
 							Name:          "http",
@@ -1700,6 +1701,19 @@ func getToolhiveRunnerImage() string {
 	return image
 }
 
+// getImagePullPolicyForToolhiveRunner returns the appropriate imagePullPolicy for the toolhive runner container.
+// If the image is a local image (starts with "kind.local/" or "localhost/"), use Never.
+// Otherwise, use IfNotPresent to allow pulling when needed but avoid unnecessary pulls.
+func getImagePullPolicyForToolhiveRunner() corev1.PullPolicy {
+	image := getToolhiveRunnerImage()
+	// Check if it's a local image that should use Never
+	if strings.HasPrefix(image, "kind.local/") || strings.HasPrefix(image, "localhost/") {
+		return corev1.PullNever
+	}
+	// For other images, use IfNotPresent to allow pulling when needed
+	return corev1.PullIfNotPresent
+}
+
 // handleExternalAuthConfig validates and tracks the hash of the referenced MCPExternalAuthConfig.
 // It updates the MCPServer status when the external auth configuration changes.
 func (r *MCPServerReconciler) handleExternalAuthConfig(ctx context.Context, m *mcpv1alpha1.MCPServer) error {

cmd/thv-operator/pkg/vmcpconfig/converter.go

@@ -135,18 +135,24 @@ func (c *Converter) Convert(
 	// are handled by kubebuilder annotations in pkg/telemetry/config.go and applied by the API server.
 	config.Telemetry = spectoconfig.NormalizeTelemetryConfig(vmcp.Spec.Config.Telemetry, vmcp.Name)
 
+	// Convert audit config
+	c.convertAuditConfig(config, vmcp)
+
+	// Apply operational defaults (fills missing values)
+	config.EnsureOperationalDefaults()
+
+	return config, nil
+}
+
+// convertAuditConfig converts audit configuration from CRD to vmcp config.
+func (*Converter) convertAuditConfig(config *vmcpconfig.Config, vmcp *mcpv1alpha1.VirtualMCPServer) {
 	if vmcp.Spec.Config.Audit != nil && vmcp.Spec.Config.Audit.Enabled {
 		config.Audit = vmcp.Spec.Config.Audit
 	}
 
 	if config.Audit != nil && config.Audit.Component == "" {
 		config.Audit.Component = vmcp.Name
 	}
-
-	// Apply operational defaults (fills missing values)
-	config.EnsureOperationalDefaults()
-
-	return config, nil
 }
 
 // convertIncomingAuth converts IncomingAuthConfig from CRD to vmcp config.

cmd/vmcp/README.md

@@ -6,7 +6,7 @@ The Virtual MCP Server (vmcp) is a standalone binary that aggregates multiple MC
 
 ## Features
 
-### Implemented (Phase 1)
+### Implemented
 - ✅ **Group-Based Backend Management**: Automatic workload discovery from ToolHive groups
 - ✅ **Tool Aggregation**: Combines tools from multiple MCP servers with conflict resolution (prefix, priority, manual)
 - ✅ **Resource & Prompt Aggregation**: Unified access to resources and prompts from all backends
@@ -16,12 +16,14 @@ The Virtual MCP Server (vmcp) is a standalone binary that aggregates multiple MC
 - ✅ **Health Endpoints**: `/health` and `/ping` for service monitoring
 - ✅ **Configuration Validation**: `vmcp validate` command for config verification
 - ✅ **Observability**: OpenTelemetry metrics and traces for backend operations and workflow executions
+- ✅ **Composite Tools**: Multi-step workflows with elicitation support
 
 ### In Progress
 - 🚧 **Incoming Authentication** (Issue #165): OIDC, local, anonymous authentication
 - 🚧 **Outgoing Authentication** (Issue #160): RFC 8693 token exchange for backend API access
 - 🚧 **Token Caching**: Memory and Redis cache providers
 - 🚧 **Health Monitoring** (Issue #166): Circuit breakers, backend health checks
+- 🚧 **Optimizer** Support the MCP optimizer in vMCP for context optimization on large toolsets.
 
 ### Future (Phase 2+)
 - 📋 **Authorization**: Cedar policy-based access control

cmd/vmcp/app/commands.go

@@ -28,7 +28,7 @@ import (
 	"github.com/stacklok/toolhive/pkg/vmcp/discovery"
 	"github.com/stacklok/toolhive/pkg/vmcp/health"
 	"github.com/stacklok/toolhive/pkg/vmcp/k8s"
-	"github.com/stacklok/toolhive/pkg/vmcp/optimizer"
+	vmcpoptimizer "github.com/stacklok/toolhive/pkg/vmcp/optimizer"
 	vmcprouter "github.com/stacklok/toolhive/pkg/vmcp/router"
 	vmcpserver "github.com/stacklok/toolhive/pkg/vmcp/server"
 	vmcpstatus "github.com/stacklok/toolhive/pkg/vmcp/status"
@@ -446,9 +446,28 @@ func runServe(cmd *cobra.Command, _ []string) error {
 		StatusReporter:      statusReporter,
 	}
 
-	if cfg.Optimizer != nil {
-		// TODO: update this with the real optimizer.
-		serverCfg.OptimizerFactory = optimizer.NewDummyOptimizer
+	// Configure optimizer if enabled in YAML config
+	if cfg.Optimizer != nil && cfg.Optimizer.Enabled {
+		logger.Info("🔬 Optimizer enabled via configuration (chromem-go)")
+		serverCfg.OptimizerFactory = vmcpoptimizer.NewEmbeddingOptimizer
+		serverCfg.OptimizerConfig = cfg.Optimizer
+		persistInfo := "in-memory"
+		if cfg.Optimizer.PersistPath != "" {
+			persistInfo = cfg.Optimizer.PersistPath
+		}
+		// FTS5 is always enabled with configurable semantic/BM25 ratio
+		ratio := 70 // Default (70%)
+		if cfg.Optimizer.HybridSearchRatio != nil {
+			ratio = *cfg.Optimizer.HybridSearchRatio
+		}
+		searchMode := fmt.Sprintf("hybrid (%d%% semantic, %d%% BM25)",
+			ratio,
+			100-ratio)
+		logger.Infof("Optimizer configured: backend=%s, dimension=%d, persistence=%s, search=%s",
+			cfg.Optimizer.EmbeddingBackend,
+			cfg.Optimizer.EmbeddingDimension,
+			persistInfo,
+			searchMode)
 	}
 
 	// Convert composite tool configurations to workflow definitions

deploy/charts/operator-crds/files/crds/toolhive.stacklok.dev_virtualmcpservers.yaml

@@ -677,17 +677,76 @@ spec:
                   optimizer:
                     description: |-
                       Optimizer configures the MCP optimizer for context optimization on large toolsets.
-                      When enabled, vMCP exposes only find_tool and call_tool operations to clients
+                      When enabled, vMCP exposes optim_find_tool and optim_call_tool operations to clients
                       instead of all backend tools directly. This reduces token usage by allowing
                       LLMs to discover relevant tools on demand rather than receiving all tool definitions.
                     properties:
-                      embeddingService:
+                      embeddingBackend:
                         description: |-
-                          EmbeddingService is the name of a Kubernetes Service that provides the embedding service
-                          for semantic tool discovery. The service must implement the optimizer embedding API.
+                          EmbeddingBackend specifies the embedding provider: "ollama", "vllm", "unified", or "openai".
+                          - "ollama": Uses local Ollama HTTP API for embeddings
+                          - "vllm": Uses vLLM OpenAI-compatible API (recommended for production Kubernetes deployments)
+                          - "unified": Uses generic OpenAI-compatible API (works with both vLLM and OpenAI)
+                          - "openai": Uses OpenAI-compatible API
+                        enum:
+                        - ollama
+                        - vllm
+                        - unified
+                        - openai
+                        type: string
+                      embeddingDimension:
+                        description: |-
+                          EmbeddingDimension is the dimension of the embedding vectors.
+                          Common values:
+                          - 384: all-MiniLM-L6-v2, nomic-embed-text
+                          - 768: BAAI/bge-small-en-v1.5
+                          - 1536: OpenAI text-embedding-3-small
+                        minimum: 1
+                        type: integer
+                      embeddingModel:
+                        description: |-
+                          EmbeddingModel is the model name to use for embeddings.
+                          Required when EmbeddingBackend is "ollama" or "openai-compatible".
+                          Examples:
+                          - Ollama: "nomic-embed-text", "all-minilm"
+                          - vLLM: "BAAI/bge-small-en-v1.5"
+                          - OpenAI: "text-embedding-3-small"
+                        type: string
+                      embeddingURL:
+                        description: |-
+                          EmbeddingURL is the base URL for the embedding service (Ollama or OpenAI-compatible API).
+                          Required when EmbeddingBackend is "ollama" or "openai-compatible".
+                          Examples:
+                          - Ollama: "http://localhost:11434"
+                          - vLLM: "http://vllm-service:8000/v1"
+                          - OpenAI: "https://api.openai.com/v1"
+                        type: string
+                      enabled:
+                        description: |-
+                          Enabled determines whether the optimizer is active.
+                          When true, vMCP exposes optim_find_tool and optim_call_tool instead of all backend tools.
+                        type: boolean
+                      ftsDBPath:
+                        description: |-
+                          FTSDBPath is the path to the SQLite FTS5 database for BM25 text search.
+                          If empty, defaults to ":memory:" for in-memory FTS5, or "{PersistPath}/fts.db" if PersistPath is set.
+                          Hybrid search (semantic + BM25) is always enabled.
+                        type: string
+                      hybridSearchRatio:
+                        description: |-
+                          HybridSearchRatio controls the mix of semantic vs BM25 results in hybrid search.
+                          Value range: 0 (all BM25) to 100 (all semantic), representing percentage.
+                          Default: 70 (70% semantic, 30% BM25)
+                          Only used when FTSDBPath is set.
+                        maximum: 100
+                        minimum: 0
+                        type: integer
+                      persistPath:
+                        description: |-
+                          PersistPath is the optional filesystem path for persisting the chromem-go database.
+                          If empty, the database will be in-memory only (ephemeral).
+                          When set, tool metadata and embeddings are persisted to disk for faster restarts.
                         type: string
-                    required:
-                    - embeddingService
                     type: object
                   outgoingAuth:
                     description: |-