Add generic filtering mechanisms to registry package

[Copilot]

Closes: #1618

Description

Adds two generic mechanisms for flexible tool filtering without coupling to domain-specific logic:

1. Tool self-filtering via Enabled field

• ServerTool.Enabled func(ctx context.Context) (bool, error) allows tools to filter themselves based on request context
• Optional field—nil means enabled by default
• Errors logged and treated as disabled

2. Cross-cutting filters via Builder.WithFilter

• ToolFilter func(ctx context.Context, tool *ServerTool) (bool, error) type for builder-level filters
• Multiple filters can be chained—all must pass
• Filters applied after feature flags but before toolset checks

Filter evaluation order

1. Tool.Enabled (if set)
2. FeatureFlagEnable/FeatureFlagDisable (existing)
3. Read-only filter (existing)
4. Builder filters (new)
5. Toolset/additional tools (existing)

New API

• Registry.FilteredTools(ctx context.Context) ([]ServerTool, error) provides explicit filtered tools access (currently aliases AvailableTools for consistency)

Usage

// Tool with self-filtering
tool := registry.ServerTool{
    Tool:        myTool,
    Toolset:     myToolset,
    HandlerFunc: myHandler,
    Enabled: func(ctx context.Context) (bool, error) {
        user := mypackage.UserFromContext(ctx)
        return user != nil && user.HasPermission("use_tool"), nil
    },
}

// Builder with cross-cutting filter
reg := registry.NewBuilder().
    SetTools(tools).
    WithFilter(func(ctx context.Context, tool *registry.ServerTool) (bool, error) {
        return !shouldHideForCurrentAuth(ctx, tool), nil
    }).
    Build()

// Get filtered tools per-request
enabledTools, err := reg.FilteredTools(ctx)

Tradeoffs

• FilteredTools returns same result as AvailableTools for now—kept as alias rather than consolidating to preserve clear API surface for future divergence
• Filter errors logged to stderr rather than returned—maintains existing error handling pattern for feature flag checks

Original prompt

Summary

Add two generic mechanisms to the registry package for flexible tool filtering without coupling to specific domain concepts:

1. Enabled function on ServerTool - Allows tools to self-filter based on request context
2. WithFilter method on Builder - Allows cross-cutting filters to be applied to all tools

Motivation

Consumers of the registry (like github-mcp-server-remote) need to filter tools based on various conditions:

• User permissions and policies
• Request context (e.g., which client is calling)
• Feature flags with complex logic (AND/OR combinations)
• Runtime availability of dependencies

Currently, consumers must do this filtering externally before passing tools to the registry, which leads to complex orchestration code. By adding generic filter hooks, consumers can encapsulate their domain-specific logic while the registry remains agnostic.

Implementation

1. Add Enabled field to ServerTool struct in pkg/registry/tool.go:

type ServerTool struct {
    Tool              mcp.Tool
    Toolset           ToolsetMetadata
    HandlerFunc       HandlerFunc
    FeatureFlagEnable string
    FeatureFlagDisable string
    
    // Enabled is an optional function called at build/filter time to determine
    // if this tool should be available. If nil, the tool is considered enabled
    // (subject to FeatureFlagEnable/FeatureFlagDisable checks).
    // The context carries request-scoped information for the consumer to use.
    // Returns (enabled, error). On error, the tool should be treated as disabled.
    Enabled func(ctx context.Context) (bool, error)
}

2. Add ToolFilter type and WithFilter method to Builder in pkg/registry/registry.go:

// ToolFilter is a function that determines if a tool should be included.
// Returns true if the tool should be included, false to exclude it.
type ToolFilter func(ctx context.Context, tool *ServerTool) (bool, error)

// WithFilter adds a filter function that will be applied to all tools.
// Multiple filters can be added and are evaluated in order.
// If any filter returns false or an error, the tool is excluded.
func (b *Builder) WithFilter(filter ToolFilter) *Builder {
    b.filters = append(b.filters, filter)
    return b
}

3. Update isToolEnabled in the builder to check these in order:

1. Check tool's own Enabled function (if set)
2. Check FeatureFlagEnable (existing behavior)
3. Check FeatureFlagDisable (existing behavior)
4. Apply builder filters (new)

4. Add a context-aware method to get filtered tools:

// FilteredTools returns tools filtered by the Enabled function and builder filters.
// This should be called per-request with the request context.
func (r *Registry) FilteredTools(ctx context.Context) ([]ServerTool, error)

Example Usage

// Tool with self-filtering logic
tool := registry.ServerTool{
    Tool:    myTool,
    Toolset: myToolset,
    HandlerFunc: myHandler,
    Enabled: func(ctx context.Context) (bool, error) {
        // Consumer's domain-specific logic here
        user := mypackage.UserFromContext(ctx)
        return user != nil && user.HasPermission("use_tool"), nil
    },
}

// Builder with cross-cutting filter
reg := registry.NewBuilder().
    SetTools(tools).
    WithFilter(func(ctx context.Context, tool *registry.ServerTool) (bool, error) {
        // Cross-cutting concern like scope filtering
        return !shouldHideForCurrentAuth(ctx, tool), nil
    }).
    Build()

// Get filtered tools for a request
enabledTools, err := reg.FilteredTools(ctx)

Testing

Add tests for:

• Enabled function returning true/false/error
• WithFilter with single and multiple filters
• Interaction between Enabled, feature flags, and filters
• FilteredTools method with various filter combinations

Backwards Compatibility

• All new fields are optional with nil/empty defaults
• Existing code continues to work unchanged
• FeatureFlagEnable/FeatureFlagDisable remain fully functional

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

This PR adds two generic filtering mechanisms to the registry package to enable flexible, context-aware tool filtering without coupling to domain-specific logic. The implementation adds an Enabled field to ServerTool for self-filtering and a WithFilter builder method for cross-cutting filters, along with a new FilteredTools method for explicit filtered tool access.

Key changes:

• Tool-level self-filtering via optional Enabled function field on ServerTool
• Builder-level cross-cutting filters via new WithFilter method
• New FilteredTools method as an explicit API for accessing filtered tools

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pkg/registry/server_tool.go	Added Enabled func(ctx context.Context) (bool, error) field to ServerTool struct for tool self-filtering
pkg/registry/builder.go	Added ToolFilter type and WithFilter builder method for applying cross-cutting filters
pkg/registry/registry.go	Added filters []ToolFilter field to Registry struct and propagated it in ForMCPRequest
pkg/registry/filters.go	Updated isToolEnabled to evaluate new filter mechanisms in correct order; added FilteredTools method
pkg/registry/registry_test.go	Added comprehensive test coverage for new filtering mechanisms, including edge cases and interaction tests