Add ToolConfig CRD for tool filtering and renaming (#1814)

Allows MCPServers to reference reusable tool configurations for
filtering (allow-list) and renaming tools with custom descriptions.
Uses hash-based change detection to trigger reconciliation.

---------

Signed-off-by: Juan Antonio Osorio <[email protected]>

Author: JAORMX

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

@@ -88,9 +88,17 @@ type MCPServerSpec struct {
 	Audit *AuditConfig `json:"audit,omitempty"`
 
 	// ToolsFilter is the filter on tools applied to the MCP server
+	// Deprecated: Use ToolConfigRef instead
 	// +optional
 	ToolsFilter []string `json:"tools,omitempty"`
 
+	// ToolConfigRef references a MCPToolConfig resource for tool filtering and renaming.
+	// The referenced MCPToolConfig must exist in the same namespace as this MCPServer.
+	// Cross-namespace references are not supported for security and isolation reasons.
+	// If specified, this takes precedence over the inline ToolsFilter field.
+	// +optional
+	ToolConfigRef *ToolConfigRef `json:"toolConfigRef,omitempty"`
+
 	// Telemetry defines observability configuration for the MCP server
 	// +optional
 	Telemetry *TelemetryConfig `json:"telemetry,omitempty"`
@@ -440,6 +448,14 @@ type ConfigMapAuthzRef struct {
 	Key string `json:"key,omitempty"`
 }
 
+// ToolConfigRef defines a reference to a MCPToolConfig resource.
+// The referenced MCPToolConfig must be in the same namespace as the MCPServer.
+type ToolConfigRef struct {
+	// Name is the name of the MCPToolConfig resource in the same namespace
+	// +kubebuilder:validation:Required
+	Name string `json:"name"`
+}
+
 // InlineAuthzConfig contains direct authorization configuration
 type InlineAuthzConfig struct {
 	// Policies is a list of Cedar policy strings
@@ -543,6 +559,10 @@ type MCPServerStatus struct {
 	// +optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
+	// ToolConfigHash stores the hash of the referenced ToolConfig for change detection
+	// +optional
+	ToolConfigHash string `json:"toolConfigHash,omitempty"`
+
 	// URL is the URL where the MCP server can be accessed
 	// +optional
 	URL string `json:"url,omitempty"`

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

@@ -0,0 +1,84 @@
+package v1alpha1
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// MCPToolConfigSpec defines the desired state of MCPToolConfig.
+// MCPToolConfig resources are namespace-scoped and can only be referenced by
+// MCPServer resources in the same namespace.
+type MCPToolConfigSpec struct {
+	// ToolsFilter is a list of tool names to filter (allow list).
+	// Only tools in this list will be exposed by the MCP server.
+	// If empty, all tools are exposed.
+	// +optional
+	ToolsFilter []string `json:"toolsFilter,omitempty"`
+
+	// ToolsOverride is a map from actual tool names to their overridden configuration.
+	// This allows renaming tools and/or changing their descriptions.
+	// +optional
+	ToolsOverride map[string]ToolOverride `json:"toolsOverride,omitempty"`
+}
+
+// ToolOverride represents a tool override configuration.
+// Both Name and Description can be overridden independently, but
+// they can't be both empty.
+type ToolOverride struct {
+	// Name is the redefined name of the tool
+	// +optional
+	Name string `json:"name,omitempty"`
+
+	// Description is the redefined description of the tool
+	// +optional
+	Description string `json:"description,omitempty"`
+}
+
+// MCPToolConfigStatus defines the observed state of MCPToolConfig
+type MCPToolConfigStatus struct {
+	// ObservedGeneration is the most recent generation observed for this MCPToolConfig.
+	// It corresponds to the MCPToolConfig's generation, which is updated on mutation by the API Server.
+	// +optional
+	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
+
+	// ConfigHash is a hash of the current configuration for change detection
+	// +optional
+	ConfigHash string `json:"configHash,omitempty"`
+
+	// ReferencingServers is a list of MCPServer resources that reference this MCPToolConfig
+	// This helps track which servers need to be reconciled when this config changes
+	// +optional
+	ReferencingServers []string `json:"referencingServers,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+// +kubebuilder:resource:shortName=tc;toolconfig
+// +kubebuilder:printcolumn:name="Filter Count",type=integer,JSONPath=`.spec.toolsFilter[*]`
+// +kubebuilder:printcolumn:name="Override Count",type=integer,JSONPath=`.spec.toolsOverride`
+// +kubebuilder:printcolumn:name="Referenced By",type=string,JSONPath=`.status.referencingServers`
+// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
+
+// MCPToolConfig is the Schema for the mcptoolconfigs API.
+// MCPToolConfig resources are namespace-scoped and can only be referenced by
+// MCPServer resources within the same namespace. Cross-namespace references
+// are not supported for security and isolation reasons.
+type MCPToolConfig struct {
+	metav1.TypeMeta   `json:",inline"` // nolint:revive
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	Spec   MCPToolConfigSpec   `json:"spec,omitempty"`
+	Status MCPToolConfigStatus `json:"status,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+
+// MCPToolConfigList contains a list of MCPToolConfig
+type MCPToolConfigList struct {
+	metav1.TypeMeta `json:",inline"` // nolint:revive
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []MCPToolConfig `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&MCPToolConfig{}, &MCPToolConfigList{})
+}

cmd/thv-operator/api/v1alpha1/zz_generated.deepcopy.go

@@ -127,6 +127,7 @@ func (r *MCPServerReconciler) detectPlatform(ctx context.Context) (kubernetes.Pl
 // +kubebuilder:rbac:groups=toolhive.stacklok.dev,resources=mcpservers,verbs=get;list;watch;create;update;patch;delete
 // +kubebuilder:rbac:groups=toolhive.stacklok.dev,resources=mcpservers/status,verbs=get;update;patch
 // +kubebuilder:rbac:groups=toolhive.stacklok.dev,resources=mcpservers/finalizers,verbs=update
+// +kubebuilder:rbac:groups=toolhive.stacklok.dev,resources=mcptoolconfigs,verbs=get;list;watch
 // +kubebuilder:rbac:groups="",resources=configmaps,verbs=create;delete;get;list;patch;update;watch
 // +kubebuilder:rbac:groups="",resources=services,verbs=create;delete;get;list;patch;update;watch;apply
 // +kubebuilder:rbac:groups="rbac.authorization.k8s.io",resources=roles,verbs=create;delete;get;list;patch;update;watch
@@ -162,6 +163,17 @@ func (r *MCPServerReconciler) Reconcile(ctx context.Context, req ctrl.Request) (
 		return ctrl.Result{}, err
 	}
 
+	// Check if MCPToolConfig is referenced and handle it
+	if err := r.handleToolConfig(ctx, mcpServer); err != nil {
+		ctxLogger.Error(err, "Failed to handle MCPToolConfig")
+		// Update status to reflect the error
+		mcpServer.Status.Phase = mcpv1alpha1.MCPServerPhaseFailed
+		if statusErr := r.Status().Update(ctx, mcpServer); statusErr != nil {
+			ctxLogger.Error(statusErr, "Failed to update MCPServer status after MCPToolConfig error")
+		}
+		return ctrl.Result{}, err
+	}
+
 	// Check if the MCPServer instance is marked to be deleted
 	if mcpServer.GetDeletionTimestamp() != nil {
 		// The object is being deleted
@@ -393,6 +405,50 @@ func (r *MCPServerReconciler) updateRBACResourceIfNeeded(
 }
 
 // ensureRBACResources ensures that the RBAC resources are in place for the MCP server
+
+// handleToolConfig handles MCPToolConfig reference for an MCPServer
+func (r *MCPServerReconciler) handleToolConfig(ctx context.Context, m *mcpv1alpha1.MCPServer) error {
+	if m.Spec.ToolConfigRef == nil {
+		// No MCPToolConfig referenced, clear any stored hash
+		if m.Status.ToolConfigHash != "" {
+			m.Status.ToolConfigHash = ""
+			if err := r.Status().Update(ctx, m); err != nil {
+				return fmt.Errorf("failed to clear MCPToolConfig hash from status: %w", err)
+			}
+		}
+		return nil
+	}
+
+	// Get the referenced MCPToolConfig
+	toolConfig, err := GetToolConfigForMCPServer(ctx, r.Client, m)
+	if err != nil {
+		return err
+	}
+
+	if toolConfig == nil {
+		return fmt.Errorf("MCPToolConfig %s not found", m.Spec.ToolConfigRef.Name)
+	}
+
+	// Check if the MCPToolConfig hash has changed
+	if m.Status.ToolConfigHash != toolConfig.Status.ConfigHash {
+		ctxLogger.Info("MCPToolConfig has changed, updating MCPServer",
+			"mcpserver", m.Name,
+			"toolconfig", toolConfig.Name,
+			"oldHash", m.Status.ToolConfigHash,
+			"newHash", toolConfig.Status.ConfigHash)
+
+		// Update the stored hash
+		m.Status.ToolConfigHash = toolConfig.Status.ConfigHash
+		if err := r.Status().Update(ctx, m); err != nil {
+			return fmt.Errorf("failed to update MCPToolConfig hash in status: %w", err)
+		}
+
+		// The change in hash will trigger a reconciliation of the RunConfig
+		// which will pick up the new tool configuration
+	}
+
+	return nil
+}
 func (r *MCPServerReconciler) ensureRBACResources(ctx context.Context, mcpServer *mcpv1alpha1.MCPServer) error {
 	proxyRunnerNameForRBAC := proxyRunnerServiceAccountName(mcpServer.Name)