feat: add exclude and excludeRegex support for tool selectors

[majiayu000]

Description

Add Exclude and ExcludeRegex fields to MCPToolFilter for exclusion-based tool filtering, complementing the existing Include/IncludeRegex fields. Exclude rules take precedence over include rules (deny-wins semantics).

Fixes #1921

Changes

Modified across 4 layers:

• API types (api/v1alpha1/mcp_route.go): New fields with MaxItems=32 validation. CEL rules enforce mutual exclusivity within include/exclude pairs and require at least one field set.
• Filter API (internal/filterapi/mcpconfig.go): Mirror fields in MCPToolSelector.
• Proxy config (internal/mcpproxy/config.go): Compiled exclude map + regexps. allows() checks excludes first for short-circuit denial.
• Controller (internal/controller/gateway.go): Field mapping from CRD to filterapi.

Test Plan

• Unit tests for allows(): exclude-only, excludeRegex-only, include+exclude combo, include+excludeRegex combo
• LoadConfig tests for exclude parsing and invalid regex error handling
• Controller test for field mapping
• CRD CEL validation fixtures: valid exclude-only, valid excludeRegex-only, valid include+exclude, invalid exclude+excludeRegex combo
• make precommit and make test pass

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.40%. Comparing base (304b221) to head (123d741).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1963      +/-   ##
==========================================
+ Coverage   84.35%   84.40%   +0.04%     
==========================================
  Files         130      130              
  Lines       18068    18104      +36     
==========================================
+ Hits        15242    15280      +38     
+ Misses       1878     1877       -1     
+ Partials      948      947       -1     

☔ 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.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[dosubot]

Documentation Updates

3 document(s) were updated by changes in this PR:

index

View Changes

@@ -169,8 +169,55 @@
 ```
 
 :::note
-The `toolSelector` field requires exactly one of `include` or `includeRegex` to be specified. If not specified, all tools from the MCP server are exposed.
+The `toolSelector` field requires at least one of `include`, `includeRegex`, `exclude`, or `excludeRegex` to be specified. You cannot specify both `include` and `includeRegex` together, nor both `exclude` and `excludeRegex` together. If not specified, all tools from the MCP server are exposed.
 :::
+
+You can also use exclusion patterns to block specific tools or patterns:
+
+- **`exclude`**: A list of exact tool names to exclude. The specified tools will not be available.
+- **`excludeRegex`**: A list of RE2-compatible regular expressions that, when matched, exclude the tool. Tools matching these patterns will not be available.
+
+Exclude rules take precedence over include rules (deny-wins semantics). When both include and exclude patterns are specified, a tool must match an include rule AND not match any exclude rule to be allowed.
+
+```yaml
+apiVersion: aigateway.envoyproxy.io/v1alpha1
+kind: MCPRoute
+metadata:
+  name: mcp-route
+  namespace: default
+spec:
+  parentRefs:
+    - name: aigw-run
+      kind: Gateway
+      group: gateway.networking.k8s.io
+  backendRefs:
+    # Allow all tools except dangerous ones
+    - name: github
+      kind: Backend
+      group: gateway.envoyproxy.io
+      path: "/mcp/x/issues"
+      toolSelector:
+        include:
+          - issue_read
+          - issue_list
+          - issue_write
+        exclude:
+          - issue_write # Deny-wins: even though listed in include, this tool is blocked
+      securityPolicy:
+        apiKey:
+          secretRef:
+            name: github-token
+
+    # Exclude tools matching a pattern
+    - name: context7
+      kind: Backend
+      group: gateway.envoyproxy.io
+      path: "/mcp"
+      toolSelector:
+        excludeRegex:
+          - ^admin_.* # Block all admin tools
+          - .*delete.* # Block any tools with "delete" in the name
+```
 
 ### Server Multiplexing
 

index

View Changes

@@ -169,8 +169,51 @@
 ```
 
 :::note
-The `toolSelector` field requires exactly one of `include` or `includeRegex` to be specified. If not specified, all tools from the MCP server are exposed.
+The `toolSelector` field requires at least one of `include`, `includeRegex`, `exclude`, or `excludeRegex` to be specified. You cannot specify both `include` and `includeRegex` together, nor both `exclude` and `excludeRegex` together. If not specified, all tools from the MCP server are exposed.
 :::
+
+**Excluding Tools**
+
+You can also exclude specific tools or patterns while allowing others:
+
+```yaml
+# Exclude specific tools by exact name
+- name: github
+  kind: Backend
+  group: gateway.envoyproxy.io
+  path: "/mcp/x/issues/readonly"
+  toolSelector:
+    exclude:
+      - delete_issue
+      - close_issue
+  securityPolicy:
+    apiKey:
+      secretRef:
+        name: github-token
+
+# Exclude tools matching a pattern
+- name: internal-tools
+  kind: Backend
+  group: gateway.envoyproxy.io
+  path: "/mcp"
+  toolSelector:
+    excludeRegex:
+      - ^internal_.* # Excludes all tools starting with "internal_"
+
+# Combine include and exclude (exclude takes precedence)
+- name: mcp-service
+  kind: Backend
+  group: gateway.envoyproxy.io
+  path: "/mcp"
+  toolSelector:
+    include:
+      - read
+      - write
+    exclude:
+      - write # Only "read" will be available
+```
+
+When both include and exclude patterns are specified, exclude rules take precedence (deny-wins semantics). A tool must match an include rule AND not match any exclude rule to be allowed.
 
 ### Server Multiplexing
 

index

View Changes

@@ -168,8 +168,59 @@
           - query-docs
 ```
 
+The `toolSelector` supports both inclusion and exclusion patterns:
+
+- **`include`**: A list of exact tool names to include. Only the specified tools will be available.
+- **`includeRegex`**: A list of RE2-compatible regular expressions that, when matched, include the tool. Only tools matching these patterns will be available.
+- **`exclude`**: A list of exact tool names to exclude. The specified tools will not be available.
+- **`excludeRegex`**: A list of RE2-compatible regular expressions that, when matched, exclude the tool. Tools matching these patterns will not be available.
+
+Exclude rules take precedence over include rules (deny-wins semantics). When both include and exclude patterns are specified, a tool must match an include rule AND not match any exclude rule to be allowed.
+
+**Example using exclude patterns:**
+
+```yaml
+apiVersion: aigateway.envoyproxy.io/v1alpha1
+kind: MCPRoute
+metadata:
+  name: mcp-route
+  namespace: default
+spec:
+  parentRefs:
+    - name: aigw-run
+      kind: Gateway
+      group: gateway.networking.k8s.io
+  backendRefs:
+    # GitHub: allow all tools except dangerous ones
+    - name: github
+      kind: Backend
+      group: gateway.envoyproxy.io
+      path: "/mcp/x/issues/readonly"
+      toolSelector:
+        excludeRegex:
+          - .*delete.* # Block any tools with "delete" in the name
+          - .*admin.*  # Block any admin tools
+      securityPolicy:
+        apiKey:
+          secretRef:
+            name: github-token
+
+    # Context7: allow specific tools but exclude one
+    - name: context7
+      kind: Backend
+      group: gateway.envoyproxy.io
+      path: "/mcp"
+      toolSelector:
+        include:
+          - read-docs
+          - write-docs
+          - admin-reset
+        exclude:
+          - admin-reset # Exclude this specific tool even though it's in include
+```
+
 :::note
-The `toolSelector` field requires exactly one of `include` or `includeRegex` to be specified. If not specified, all tools from the MCP server are exposed.
+The `toolSelector` field requires at least one of `include`, `includeRegex`, `exclude`, or `excludeRegex` to be specified. You cannot specify both `include` and `includeRegex` together, nor both `exclude` and `excludeRegex` together. If not specified, all tools from the MCP server are exposed.
 :::
 
 ### Server Multiplexing

^{How did I do? Any feedback?}  

[nacx]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces Exclude and ExcludeRegex fields for tool filtering, which is a great enhancement. The changes are well-implemented across the API, controller, and proxy layers, with comprehensive tests and documentation updates. I've identified one high-severity issue related to an unintended side effect in the configuration comparison logic and a medium-severity issue regarding code duplication. Overall, this is a solid contribution.

[nacx]

Can you format the code to fix the style checks?

[majiayu000]

fixed — ran gofmt on the test file, was just struct field alignment.

[nacx]

/retest