refactor(features)!: use functional availability rules

Resolve declared inventory features once per request and share the request-owned cache with in-handler feature checks.

BREAKING CHANGE: Inventory items now use FeatureRule instead of FeatureFlagEnable, FeatureFlagEnableAll, and FeatureFlagDisable; FeatureFlagChecker now accepts FeatureFlag.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1e4a1ca6-53f7-4158-af22-35d2448d0b13

Author: SamMorrowDrums

cmd/github-mcp-server/feature_flag_docs.go

@@ -33,7 +33,7 @@ func generateFeatureFlagsDocs(docsPath string) error {
 // whose registration or definition differs from the default user experience.
 // Each affected tool is printed with its full schema using the same writer
 // used by the README so the output style stays consistent.
-func generateFlaggedToolsDoc(flags []string, emptyMessage string) string {
+func generateFlaggedToolsDoc(flags []inventory.FeatureFlag, emptyMessage string) string {
 	t, _ := translations.TranslationHelper()
 	defaultTools := indexToolsByName(buildInventoryWithFlags(t, nil).ToolsForRegistration(context.Background()))
 
@@ -73,8 +73,8 @@ func generateFlaggedToolsDoc(flags []string, emptyMessage string) string {
 // differs from the default-flagged inventory when only the given flag is on,
 // plus tools that exist only in the flag-on inventory. Results are sorted by
 // tool name.
-func flaggedToolDiff(t translations.TranslationHelperFunc, flag string, defaultTools map[string]inventory.ServerTool) []inventory.ServerTool {
-	flagTools := buildInventoryWithFlags(t, map[string]bool{flag: true}).ToolsForRegistration(context.Background())
+func flaggedToolDiff(t translations.TranslationHelperFunc, flag inventory.FeatureFlag, defaultTools map[string]inventory.ServerTool) []inventory.ServerTool {
+	flagTools := buildInventoryWithFlags(t, map[inventory.FeatureFlag]bool{flag: true}).ToolsForRegistration(context.Background())
 
 	out := make([]inventory.ServerTool, 0)
 	seen := make(map[string]struct{}, len(flagTools))
@@ -99,8 +99,8 @@ func flaggedToolDiff(t translations.TranslationHelperFunc, flag string, defaultT
 // buildInventoryWithFlags constructs an inventory whose feature checker treats
 // the given flags as enabled and every other flag as disabled. Passing nil
 // produces the default-flagged inventory.
-func buildInventoryWithFlags(t translations.TranslationHelperFunc, enabled map[string]bool) *inventory.Inventory {
-	checker := func(_ context.Context, flag string) (bool, error) {
+func buildInventoryWithFlags(t translations.TranslationHelperFunc, enabled map[inventory.FeatureFlag]bool) *inventory.Inventory {
+	checker := func(_ context.Context, flag inventory.FeatureFlag) (bool, error) {
 		return enabled[flag], nil
 	}
 	inv, _ := github.NewInventory(t).

cmd/github-mcp-server/generate_docs.go

@@ -31,7 +31,7 @@ func init() {
 
 // noFeatureFlagsChecker reports every feature flag as disabled. It models the
 // default user experience used by the generated documentation.
-func noFeatureFlagsChecker(_ context.Context, _ string) (bool, error) {
+func noFeatureFlagsChecker(_ context.Context, _ inventory.FeatureFlag) (bool, error) {
 	return false, nil
 }
 
@@ -61,9 +61,8 @@ func generateReadmeDocs(readmePath string) error {
 
 	// The README documents the default user experience: tools that are
 	// enabled with no special flags set. Installing a checker that reports
-	// every flag as disabled excludes tools gated by FeatureFlagEnable and
-	// keeps the legacy variants of tools gated by FeatureFlagDisable, so
-	// flag-gated duplicates don't appear twice.
+	// every flag as disabled keeps the default variants selected by functional
+	// feature rules, so flag-gated duplicates don't appear twice.
 	// Build() can only fail if WithTools specifies invalid tools - not used here
 	r, _ := github.NewInventory(t).
 		WithToolsets([]string{"all"}).

docs/feature-flags.md

@@ -20,15 +20,34 @@ Only flags listed in
 [`AllowedFeatureFlags`](../pkg/github/feature_flags.go) can be enabled by
 end users. Insiders-only flags are not user-toggleable.
 
+## Declaring tool availability
+
+Tools, resources, and prompts use `inventory.NewFeatureRule` when feature flags
+change whether they are available. Each rule declares the flags it references
+and evaluates them with a fail-closed `FeatureResolver`, so normal Go boolean
+expressions can represent AND, OR, NOT, and mixed conditions:
+
+```go
+tool.FeatureRule = inventory.NewFeatureRule(
+	[]inventory.FeatureFlag{x, y},
+	func(featureAsBool inventory.FeatureResolver) bool {
+		return !(featureAsBool(x) && featureAsBool(y))
+	},
+)
+```
+
+The service deduplicates the declared flags, resolves each one at most once for
+the request, and shares those values with tool dependencies. Feature checks
+inside handlers continue to use `deps.IsFeatureEnabled`.
+
 ---
 
 ## Tools affected by each flag
 
-The list below is regenerated from the Go source. For each user-controllable
-feature flag, it lists every tool whose **inventory or input schema** differs
-from the default — either because the flag introduces a new tool, or because
-it selects a flag-aware variant of an existing tool. Flags that only affect
-runtime behavior (such as output formatting) won't appear here.
+The list below is regenerated by comparing the default tool surface with each
+user-controllable flag enabled individually. Complex multi-flag rules may
+require separate documentation. Flags that only affect runtime behavior (such
+as output formatting) won't appear here.
 
 <!-- START AUTOMATED FEATURE FLAG TOOLS -->
 
@@ -357,7 +376,7 @@ runtime behavior (such as output formatting) won't appear here.
 ### `thread_resolution_reason`
 
 - **pull_request_review_write** - Write operations (create, submit, delete) on pull request reviews
-  - **Required OAuth Scopes**: `repo`
+  - **OAuth Challenge Scopes**: `repo`
   - `body`: Review comment text (string, optional)
   - `commitID`: SHA of commit to review (string, optional)
   - `event`: Review action to perform. (string, optional)

docs/insiders-features.md

@@ -205,6 +205,13 @@ Insiders is a **meta feature flag** — the same shape as `default` or `all` for
 3. **Insiders expansion.** If insiders mode is on (`--insiders`, `/insiders` route, or `X-MCP-Insiders: true`), every flag in [`InsidersFeatureFlags`](../pkg/github/feature_flags.go) is unioned in. The insiders expansion is **not** re-validated against the allowlist — insiders is a server-controlled switch that can reach internal-only flags.
 4. **Server-side fallback (remote server only).** Any flag not yet decided falls back to the remote server's feature manager, which can roll a feature out independently of user input or insiders membership.
 
+For tool availability, each functional feature rule statically declares the
+flags it reads. The service deduplicates those declarations, resolves every
+relevant flag once into request-owned state, and then evaluates all rules as
+in-memory boolean expressions. The same state backs
+`deps.IsFeatureEnabled`, so checks made inside a tool call reuse resolved values
+and lazily cache any handler-only flag using the live tool-call context.
+
 `AllowedFeatureFlags` and `InsidersFeatureFlags` are deliberately independent sets:
 
 - A flag in **`AllowedFeatureFlags` only** is a regular opt-in: users can turn it on, but insiders does not auto-enable it. Granular issues/PRs flags work this way.
@@ -216,5 +223,6 @@ Insiders is a **meta feature flag** — the same shape as `default` or `all` for
 1. Add a constant in `pkg/github/feature_flags.go`.
 2. Add it to `AllowedFeatureFlags` if end users should be able to opt in via `--features` / `X-MCP-Features`.
 3. Add it to `InsidersFeatureFlags` if insiders mode should turn it on automatically.
-4. Gate the behavior on the concrete flag (`deps.IsFeatureEnabled(ctx, FeatureFlagX)`), never on `cfg.InsidersMode`. There is a `TestGitHubPackageDoesNotReadInsidersMode` guard test that fails if `pkg/github` reads `InsidersMode` directly.
-5. The MCP-diff CI workflow picks up new entries in `AllowedFeatureFlags` automatically — see `.github/workflows/mcp-diff.yml`.
+4. For tool availability, attach an `inventory.NewFeatureRule` that declares every flag used by its predicate. For behavior inside a handler, use `deps.IsFeatureEnabled(ctx, FeatureFlagX)`.
+5. Gate on concrete flags, never on `cfg.InsidersMode`. There is a `TestGitHubPackageDoesNotReadInsidersMode` guard test that fails if `pkg/github` reads `InsidersMode` directly.
+6. The MCP-diff CI workflow picks up new entries in `AllowedFeatureFlags` automatically — see `.github/workflows/mcp-diff.yml`.

internal/ghmcp/server.go

@@ -256,7 +256,7 @@ type StdioServerConfig struct {
 	EnabledTools []string
 
 	// EnabledFeatures is a list of feature flags that are enabled
-	// Items with FeatureFlagEnable matching an entry in this list will be available
+	// Tool feature rules evaluate entries in this list.
 	EnabledFeatures []string
 
 	// ReadOnly indicates if we should only register read-only tools
@@ -435,8 +435,8 @@ func RunStdioServer(cfg StdioServerConfig) error {
 // using the centralized ResolveFeatureFlags function. For the local server,
 // features are resolved once at startup from --features CLI flag and insiders mode.
 func createFeatureChecker(enabledFeatures []string, insidersMode bool) inventory.FeatureFlagChecker {
-	featureSet := github.ResolveFeatureFlags(enabledFeatures, insidersMode)
-	return func(_ context.Context, flagName string) (bool, error) {
+	featureSet := github.ResolveFeatureFlags(github.FeatureFlagsFromStrings(enabledFeatures), insidersMode)
+	return func(_ context.Context, flagName inventory.FeatureFlag) (bool, error) {
 		return featureSet[flagName], nil
 	}
 }

pkg/github/actions_test.go

@@ -574,7 +574,7 @@ func Test_ActionsGetJobLogs(t *testing.T) {
 	// Note: consolidated ActionsGetJobLogs has same tool name "get_job_logs" as the individual tool
 	// but with different descriptions. We skip toolsnap validation here since the individual
 	// tool's toolsnap already exists and is tested in Test_GetJobLogs.
-	// The consolidated tool has FeatureFlagEnable set, so only one will be active at a time.
+	// The functional feature rules ensure only one variant is active at a time.
 	assert.Equal(t, "get_job_logs", toolDef.Tool.Name)
 	assert.NotEmpty(t, toolDef.Tool.Description)
 	inputSchema := toolDef.Tool.InputSchema.(*jsonschema.Schema)

pkg/github/context_tools_test.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/github/github-mcp-server/internal/githubv4mock"
 	"github.com/github/github-mcp-server/internal/toolsnaps"
+	"github.com/github/github-mcp-server/pkg/inventory"
 	"github.com/github/github-mcp-server/pkg/translations"
 	"github.com/google/go-github/v89/github"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
@@ -189,7 +190,7 @@ func Test_GetMe_IFC_FeatureFlag(t *testing.T) {
 			translations.NullTranslationHelper,
 			FeatureFlags{},
 			0,
-			func(_ context.Context, flagName string) (bool, error) {
+			func(_ context.Context, flagName inventory.FeatureFlag) (bool, error) {
 				return flagName == FeatureFlagIFCLabels && enabled, nil
 			},
 			stubExporters(),

pkg/github/csv_output_test.go

@@ -29,20 +29,18 @@ func TestCSVOutputAppliedToDefaultListTools(t *testing.T) {
 		require.Len(t, available, 2)
 
 		listing := requireToolByName(t, available, "list_things")
-		assert.Empty(t, listing.FeatureFlagEnable)
-		assert.Empty(t, listing.FeatureFlagDisable)
+		assert.True(t, listing.FeatureRule.IsZero())
 
 		getting := requireToolByName(t, available, "get_thing")
-		assert.Empty(t, getting.FeatureFlagEnable)
-		assert.Empty(t, getting.FeatureFlagDisable)
+		assert.True(t, getting.FeatureRule.IsZero())
 	}
 }
 
 func TestCSVOutputAppliesToFlagGatedListTools(t *testing.T) {
 	enabledOnly := testCSVOutputTool("list_things", `[{"number":1}]`)
-	enabledOnly.FeatureFlagEnable = FeatureFlagFileBlame
+	enabledOnly.FeatureRule = featureEnabledRule(FeatureFlagFileBlame)
 	disabledOnly := testCSVOutputTool("list_legacy_things", `[{"number":2}]`)
-	disabledOnly.FeatureFlagDisable = []string{FeatureFlagFileBlame}
+	disabledOnly.FeatureRule = featureDisabledRule(FeatureFlagFileBlame)
 
 	tools := withCSVOutput([]inventory.ServerTool{enabledOnly, disabledOnly})
 	require.Len(t, tools, 2)
@@ -368,7 +366,7 @@ type csvOutputTestDeps struct {
 	csvOn bool
 }
 
-func (d csvOutputTestDeps) IsFeatureEnabled(_ context.Context, flag string) bool {
+func (d csvOutputTestDeps) IsFeatureEnabled(_ context.Context, flag inventory.FeatureFlag) bool {
 	return flag == FeatureFlagCSVOutput && d.csvOn
 }
 

pkg/github/dependencies.go

@@ -6,7 +6,6 @@ import (
 	"fmt"
 	"log/slog"
 	"net/http"
-	"os"
 
 	ghcontext "github.com/github/github-mcp-server/pkg/context"
 	"github.com/github/github-mcp-server/pkg/http/transport"
@@ -95,7 +94,7 @@ type ToolDependencies interface {
 	GetContentWindowSize() int
 
 	// IsFeatureEnabled checks if a feature flag is enabled.
-	IsFeatureEnabled(ctx context.Context, flagName string) bool
+	IsFeatureEnabled(ctx context.Context, flag inventory.FeatureFlag) bool
 
 	// Logger returns the structured logger, optionally enriched with
 	// request-scoped data from ctx. Integrators provide their own slog.Handler
@@ -207,19 +206,8 @@ func (d BaseDeps) GetRequestStateSealer() RequestStateSealer { return d.StateSea
 // IsFeatureEnabled checks if a feature flag is enabled.
 // Returns false if the feature checker is nil, flag name is empty, or an error occurs.
 // This allows tools to conditionally change behavior based on feature flags.
-func (d BaseDeps) IsFeatureEnabled(ctx context.Context, flagName string) bool {
-	if d.featureChecker == nil || flagName == "" {
-		return false
-	}
-
-	enabled, err := d.featureChecker(ctx, flagName)
-	if err != nil {
-		// Log error but don't fail the tool - treat as disabled
-		fmt.Fprintf(os.Stderr, "Feature flag check error for %q: %v\n", flagName, err)
-		return false
-	}
-
-	return enabled
+func (d BaseDeps) IsFeatureEnabled(ctx context.Context, flag inventory.FeatureFlag) bool {
+	return inventory.ResolveFeature(ctx, d.featureChecker, flag)
 }
 
 // NewTool creates a ServerTool that retrieves ToolDependencies from context at call time.
@@ -496,17 +484,6 @@ func (d *RequestDeps) Metrics(ctx context.Context) metrics.Metrics {
 }
 
 // IsFeatureEnabled checks if a feature flag is enabled.
-func (d *RequestDeps) IsFeatureEnabled(ctx context.Context, flagName string) bool {
-	if d.featureChecker == nil || flagName == "" {
-		return false
-	}
-
-	enabled, err := d.featureChecker(ctx, flagName)
-	if err != nil {
-		// Log error but don't fail the tool - treat as disabled
-		fmt.Fprintf(os.Stderr, "Feature flag check error for %q: %v\n", flagName, err)
-		return false
-	}
-
-	return enabled
+func (d *RequestDeps) IsFeatureEnabled(ctx context.Context, flag inventory.FeatureFlag) bool {
+	return inventory.ResolveFeature(ctx, d.featureChecker, flag)
 }

pkg/github/dependencies_test.go

@@ -14,6 +14,7 @@ import (
 	ghcontext "github.com/github/github-mcp-server/pkg/context"
 	"github.com/github/github-mcp-server/pkg/github"
 	"github.com/github/github-mcp-server/pkg/http/headers"
+	"github.com/github/github-mcp-server/pkg/inventory"
 	"github.com/github/github-mcp-server/pkg/observability"
 	"github.com/github/github-mcp-server/pkg/observability/metrics"
 	"github.com/github/github-mcp-server/pkg/translations"
@@ -202,7 +203,7 @@ func TestIsFeatureEnabled_WithEnabledFlag(t *testing.T) {
 	t.Parallel()
 
 	// Create a feature checker that returns true for "test_flag"
-	checker := func(_ context.Context, flagName string) (bool, error) {
+	checker := func(_ context.Context, flagName inventory.FeatureFlag) (bool, error) {
 		return flagName == "test_flag", nil
 	}
 
@@ -253,7 +254,7 @@ func TestIsFeatureEnabled_EmptyFlagName(t *testing.T) {
 	t.Parallel()
 
 	// Create a feature checker
-	checker := func(_ context.Context, _ string) (bool, error) {
+	checker := func(_ context.Context, _ inventory.FeatureFlag) (bool, error) {
 		return true, nil
 	}
 
@@ -388,7 +389,7 @@ func TestIsFeatureEnabled_CheckerError(t *testing.T) {
 	t.Parallel()
 
 	// Create a feature checker that returns an error
-	checker := func(_ context.Context, _ string) (bool, error) {
+	checker := func(_ context.Context, _ inventory.FeatureFlag) (bool, error) {
 		return false, errors.New("checker error")
 	}