Add option to skip Virtual MCP CRDs installation

[amirejaz]

Add Feature Flags for Controller Groups and Optional Virtual MCP CRD Installation

Summary

This PR implements feature flags to enable/disable controller groups in the ToolHive operator and adds the ability to skip installing Virtual MCP CRDs. This allows users to deploy a minimal operator configuration when they only need core MCP server management features.

Related Issues

• Closes Add optional installation flag for Virtual MCP CRDs in operator-crds Helm chart #2709 - Allow skipping Virtual MCP CRD installation
• Closes Provide feature flags for enabling/disabling controllers #2564 - Add feature flags to enable/disable controllers

Changes

1. Feature Flags Implementation

Added three environment variable flags to control controller groups:

• ENABLE_SERVER (default: true)

  • Controls: MCPServer, MCPExternalAuthConfig, MCPRemoteProxy, and ToolConfig controllers
  • When disabled: Skips all server-related controllers and field indexing

• ENABLE_REGISTRY (default: true)

  • Controls: MCPRegistry controller
  • When disabled: Skips MCPRegistry controller
  • Also affects MCPServer image validation mode (registry-enforcing vs always-allow)

• ENABLE_AGGREGATION (default: true)

  • Controls: VirtualMCPServer, MCPGroup controllers and their webhooks
  • Dependency: Requires ENABLE_SERVER=true (validated with warning log)
  • When disabled: Skips Virtual MCP aggregation features

2. Optional Virtual MCP CRD Installation

Added crds.install.virtualMCP option to the toolhive-operator-crds Helm chart:

• When set to false: Skips installing VirtualMCPServer and VirtualMCPCompositeToolDefinition CRDs
• Saves approximately 54KB of CRDs
• Users should also set ENABLE_AGGREGATION=false in the operator to prevent controller errors

3. Code Refactoring

Refactored setupControllersAndWebhooks function into smaller, focused functions:

• setupServerControllers() - Sets up server-related controllers
• setupRegistryController() - Sets up registry controller
• setupAggregationControllers() - Sets up aggregation controllers and webhooks

This improves maintainability and makes the code easier to test.

4. Image Validation Logic

Fixed image validation mode selection:

• When ENABLE_REGISTRY=true: MCPServer uses ImageValidationRegistryEnforcing
• When ENABLE_REGISTRY=false: MCPServer uses ImageValidationAlwaysAllow
• Previously, this was set incorrectly after controller setup

Usage Examples

Minimal Deployment (Core Server Management Only)

# Skip Virtual MCP CRDs
helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds \
  --set crds.install.virtualMCP=false

# Disable registry and aggregation features
helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator \
  -n toolhive-system --create-namespace \
  --set operator.env.ENABLE_REGISTRY=false \
  --set operator.env.ENABLE_AGGREGATION=false

Registry-Only Deployment

# Enable only server and registry features
helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator \
  -n toolhive-system --create-namespace \
  --set operator.env.ENABLE_AGGREGATION=false

Backward Compatibility

• All feature flags default to true when not set
• Existing deployments continue to work without any changes
• CRD installation defaults to true (installs all CRDs)

Documentation

• Updated operator-crds/README.md with feature flags documentation
• Updated operator/values.yaml with feature flag comments
• Added usage examples and dependency information

Testing

• ✅ Code compiles successfully
• ✅ All linting checks pass
• ✅ Functionality verified with feature flags enabled/disabled

[JAORMX]

Let's also add an environment variable to disable the controllers if this is enabled.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 36 lines in your changes missing coverage. Please review.
✅ Project coverage is 55.61%. Comparing base (a46eadb) to head (98dc7e4).

Files with missing lines	Patch %	Lines
cmd/thv-operator/main.go	0.00%	36 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2729      +/-   ##
==========================================
- Coverage   55.67%   55.61%   -0.06%     
==========================================
  Files         314      314              
  Lines       30486    30520      +34     
==========================================
+ Hits        16972    16974       +2     
- Misses      12025    12057      +32     
  Partials     1489     1489              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.