refactor: immutable ToolsetGroup with self-describing tools and feature flags

[SamMorrowDrums]

Summary

Major refactor of the toolsets package to create an elegant, immutable filtering system with self-describing tools.

Key Changes

Self-Describing Tools:

• Tools now embed their own ToolsetMetadata (ID and description)
• Read-only hint is derived from Tool.Annotations.ReadOnlyHint
• No more separate AddReadTools() / AddWriteTools()

Simplified ToolsetGroup:

• NewToolsetGroup(tools, resources, prompts) - takes lists directly
• No more Toolset struct with SetDependencies()
• Dependencies are only needed at registration time: RegisterAll(ctx, server, deps)

Immutable Filter Chain:

filtered := tsg.
    WithReadOnly(true).
    WithToolsets([]string{"repos", "issues"}).
    WithTools([]string{"get_me"}).  // additive, bypasses toolset filter
    WithFeatureChecker(checker)       // for feature flags

tools := filtered.AvailableTools(ctx)

Feature Flags:

• FeatureFlagEnable - tool only available when flag is on
• FeatureFlagDisable - tool excluded when flag is on
• --features CLI flag for local server
• Context-based checker for remote server (actor extraction)

Deterministic Ordering:

• All Available*() methods return items sorted by toolset ID, then name
• Platform/language independent for consistent docs generation

New Files:

• pkg/github/toolset_group.go - NewToolsetGroup() factory
• pkg/github/prompts.go - AllPrompts()
• pkg/github/resources.go - AllResources()
• docs/deprecated-tool-aliases.md - alias documentation

Usage

# Enable specific features
github-mcp-server stdio --features=my_feature,another_feature
GITHUB_FEATURES=my_feature github-mcp-server stdio

---

Stack:

• refactor: convert projects, labels, and dynamic_tools to NewTool pattern #1601 ← base

[Copilot]

Pull request overview

This PR adds feature flag support to the local GitHub MCP server, enabling runtime control over which tools, resources, and prompts are available based on enabled features. The implementation includes a new --features CLI flag, feature flag fields on ServerTool/ServerResource/ServerPrompt, and a filtering mechanism integrated into the toolset group's filter chain.

Key Changes:

• Added --features CLI flag and GITHUB_FEATURES environment variable support for comma-separated feature flags
• Implemented FeatureFlagChecker interface and createFeatureChecker() for O(1) flag lookup
• Added FeatureFlagEnable and FeatureFlagDisable fields to ServerTool, ServerResourceTemplate, and ServerPrompt
• Integrated feature flag filtering into WithFeatureChecker() method with immutable filter chaining

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
pkg/toolsets/toolsets.go	Core feature flag filtering logic: FeatureFlagChecker type, WithFeatureChecker() method, isFeatureFlagAllowed() logic integrated into Available* methods
pkg/toolsets/toolsets_test.go	Comprehensive test coverage for feature flags (enable/disable/both/errors) across tools, resources, and prompts
pkg/toolsets/server_tool.go	Added FeatureFlagEnable and FeatureFlagDisable string fields to ServerTool, ServerResourceTemplate, and ServerPrompt
pkg/github/toolset_group.go	New factory function for creating ToolsetGroup with all tools/resources/prompts
internal/ghmcp/server.go	Added EnabledFeatures config field, createFeatureChecker() implementation, wired into filter chain via WithFeatureChecker()
cmd/github-mcp-server/main.go	Added --features persistent flag with viper binding and GITHUB_FEATURES env var support
Multiple pkg/github/*.go files	Updated all tool/resource/prompt constructors to include toolset metadata parameter (structural refactor supporting feature flags)

[SamMorrowDrums]

I am sure this can be removed too...

[JoannaaKL]

What do you mean by this comment? I think it's still possible to get a reference to particular ServerTool (for example by calling AvailableTools()), change fields and then tools slice will be changed as well. In order to make it truly immutable we need to make a deep copy

[SamMorrowDrums]

The immutable copy is for the registry metadata only, the protection is that a function cannot edit the copy of the registry that you hold, and change the filters you think have applied.

We could call it out in comments, but we don't want the expense of deep copy, and it's nice that it always returns a Registry. We could do a builder version, that's an option too.

WDYT?

The only issue with the builder version is if you want Registry in an intermediate state.

[SamMorrowDrums]

i.e. I'm not worried about people mutating tools too much and don't want to copy 😅

[SamMorrowDrums]

You are right though, the immutable is in wrong place.

[JoannaaKL]

Thx, that makes sense :)

[JoannaaKL]

Looking at the example from PR description the intended use of this function as as a builder pattern:

filtered := tsg.
    WithReadOnly(true).
    WithToolsets([]string{"repos", "issues"}).
    WithTools([]string{"get_me"}).  // additive, bypasses toolset filter
    WithFeatureChecker(checker)  

In current implementation every builder function is unnecessarily copying the registry. Each Registry.copy() is iterating over tool slices to copy them too.
Maybe we could introduce a struct like RegistryBuilder, then functions as WithReadOnly will just set one field in the builder. Once the user is done with constructing a new object she would call build() on the builder instance, which returns the copied registry object with some fields overridden.

[SamMorrowDrums]

I will do the builder pattern. Agree we don't need intermediate state and we couldn't efficiently achieve full immutability anyway! ❤️ thank you.