feat: gate filtered write guidance behind feature flag

Hide write-oriented prompts and toolset instructions only when the new
filtered_write_guidance feature flag is enabled. The flag is user-opt-in
via --features / X-MCP-Features and auto-on in insiders mode, so default
users see no behavior or context change.

- Add FeatureFlagFilteredWriteGuidance to allowed + insiders flag lists
- Gate the RequiredTools prompt filtering in AvailablePrompts behind it
- Restore the original always-on issues/PR instructions when the flag is off
- Expose Inventory.IsFeatureEnabled for instruction functions in pkg/github

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: SamMorrowDrums

pkg/errors/error_test.go

@@ -3,13 +3,13 @@ package errors
 import (
 	"context"
 	"fmt"
-	"net/http"
-	"testing"
-	"time"
 	"github.com/google/go-github/v87/github"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"net/http"
+	"testing"
+	"time"
 )
 
 func TestGitHubErrorContext(t *testing.T) {
@@ -687,4 +687,3 @@ func TestNewGitHubAPIErrorResponse_RateLimits(t *testing.T) {
 		assert.Contains(t, text, "validation failed")
 	})
 }
-

pkg/github/feature_flags.go

@@ -16,6 +16,12 @@ const FeatureFlagIFCLabels = "ifc_labels"
 // and field_values enrichment in list_issues / search_issues output.
 const FeatureFlagIssueFields = "remote_mcp_issue_fields"
 
+// FeatureFlagFilteredWriteGuidance is the feature flag name for hiding
+// write-oriented prompts and toolset instructions when the underlying write
+// tools have been filtered out (e.g. read-only mode or excluded tools). When
+// disabled, write guidance is always advertised regardless of tool availability.
+const FeatureFlagFilteredWriteGuidance = "filtered_write_guidance"
+
 // AllowedFeatureFlags is the allowlist of feature flags that can be enabled
 // by users via --features CLI flag or X-MCP-Features HTTP header.
 // Only flags in this list are accepted; unknown flags are silently ignored.
@@ -27,6 +33,7 @@ var AllowedFeatureFlags = []string{
 	FeatureFlagIssueFields,
 	FeatureFlagIssuesGranular,
 	FeatureFlagPullRequestsGranular,
+	FeatureFlagFilteredWriteGuidance,
 }
 
 // InsidersFeatureFlags is the list of feature flags that insiders mode enables.
@@ -37,6 +44,7 @@ var InsidersFeatureFlags = []string{
 	MCPAppsFeatureFlag,
 	FeatureFlagCSVOutput,
 	FeatureFlagIssueFields,
+	FeatureFlagFilteredWriteGuidance,
 }
 
 // FeatureFlags defines runtime feature toggles that adjust tool behavior.

pkg/github/toolset_instructions.go

@@ -14,6 +14,12 @@ func generateContextToolsetInstructions(_ *inventory.Inventory) string {
 }
 
 func generateIssuesToolsetInstructions(inv *inventory.Inventory) string {
+	if !inv.IsFeatureEnabled(context.Background(), FeatureFlagFilteredWriteGuidance) {
+		return `## Issues
+
+Check 'list_issue_types' first for organizations to use proper issue types. Use 'search_issues' before creating new issues to avoid duplicates. Always set 'state_reason' when closing issues.`
+	}
+
 	instructions := `## Issues
 
 Use 'search_issues' before creating new issues to avoid duplicates.`
@@ -26,6 +32,19 @@ Check 'list_issue_types' first for organizations to use proper issue types. Alwa
 }
 
 func generatePullRequestsToolsetInstructions(inv *inventory.Inventory) string {
+	if !inv.IsFeatureEnabled(context.Background(), FeatureFlagFilteredWriteGuidance) {
+		instructions := `## Pull Requests
+
+PR review workflow: Always use 'pull_request_review_write' with method 'create' to create a pending review, then 'add_comment_to_pending_review' to add comments, and finally 'pull_request_review_write' with method 'submit_pending' to submit the review for complex reviews with line-specific comments.`
+
+		if inv.HasToolset("repos") {
+			instructions += `
+
+Before creating a pull request, search for pull request templates in the repository. Template files are called pull_request_template.md or they're located in '.github/PULL_REQUEST_TEMPLATE' directory. Use the template content to structure the PR description and then call create_pull_request tool.`
+		}
+		return instructions
+	}
+
 	instructions := ""
 
 	if inv.HasAvailableTool(context.Background(), "pull_request_review_write") {

pkg/github/toolset_instructions_test.go

@@ -0,0 +1,74 @@
+package github
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/github/github-mcp-server/pkg/inventory"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/stretchr/testify/require"
+)
+
+// featureCheckerFor is defined in feature_flags_test.go.
+
+func buildInstructionsInventory(t *testing.T, readOnly bool, checker inventory.FeatureFlagChecker) *inventory.Inventory {
+	t.Helper()
+	tools := []inventory.ServerTool{
+		{Tool: mcp.Tool{Name: "search_issues"}, Toolset: ToolsetMetadataIssues},
+		{Tool: mcp.Tool{Name: "issue_write"}, Toolset: ToolsetMetadataIssues},
+		{Tool: mcp.Tool{Name: "pull_request_review_write"}, Toolset: ToolsetMetadataPullRequests},
+		{Tool: mcp.Tool{Name: "create_pull_request"}, Toolset: ToolsetMetadataRepos},
+	}
+	builder := inventory.NewBuilder().
+		SetTools(tools).
+		WithToolsets([]string{"issues", "pull_requests", "repos"}).
+		WithReadOnly(readOnly)
+	if checker != nil {
+		builder = builder.WithFeatureChecker(checker)
+	}
+	inv, err := builder.Build()
+	require.NoError(t, err)
+	return inv
+}
+
+func TestToolsetInstructionsFeatureFlagGating(t *testing.T) {
+	t.Run("flag disabled always advertises write guidance", func(t *testing.T) {
+		// Even in read-only mode, with the flag off the original (unconditional)
+		// guidance is returned so default users see no change.
+		inv := buildInstructionsInventory(t, true, nil)
+
+		issues := generateIssuesToolsetInstructions(inv)
+		require.Contains(t, issues, "Check 'list_issue_types' first")
+		require.Contains(t, issues, "Always set 'state_reason' when closing issues.")
+
+		prs := generatePullRequestsToolsetInstructions(inv)
+		require.Contains(t, prs, "PR review workflow")
+		require.Contains(t, prs, "search for pull request templates")
+	})
+
+	t.Run("flag enabled and write tools present keeps full guidance", func(t *testing.T) {
+		inv := buildInstructionsInventory(t, false, featureCheckerFor(FeatureFlagFilteredWriteGuidance))
+
+		issues := generateIssuesToolsetInstructions(inv)
+		require.Contains(t, issues, "Use 'search_issues' before creating new issues")
+		require.Contains(t, issues, "Check 'list_issue_types' first")
+
+		prs := generatePullRequestsToolsetInstructions(inv)
+		require.Contains(t, prs, "PR review workflow")
+		require.Contains(t, prs, "search for pull request templates")
+	})
+
+	t.Run("flag enabled and write tools filtered hides write guidance", func(t *testing.T) {
+		inv := buildInstructionsInventory(t, true, featureCheckerFor(FeatureFlagFilteredWriteGuidance))
+
+		issues := generateIssuesToolsetInstructions(inv)
+		require.Contains(t, issues, "Use 'search_issues' before creating new issues")
+		require.NotContains(t, issues, "Check 'list_issue_types' first")
+		require.NotContains(t, issues, "state_reason")
+
+		prs := generatePullRequestsToolsetInstructions(inv)
+		require.NotContains(t, prs, "PR review workflow")
+		require.NotContains(t, prs, "search for pull request templates")
+		require.True(t, strings.TrimSpace(prs) == "", "expected empty PR instructions when write tools filtered, got %q", prs)
+	})
+}

pkg/inventory/builder.go

@@ -19,6 +19,12 @@ var (
 // The value must match github.MCPAppsFeatureFlag.
 const mcpAppsFeatureFlag = "remote_mcp_ui_apps"
 
+// filteredWriteGuidanceFeatureFlag gates hiding write-oriented prompts when the
+// tools they depend on have been filtered out. Defined here to avoid importing
+// pkg/github (which imports pkg/inventory). The value must match
+// github.FeatureFlagFilteredWriteGuidance.
+const filteredWriteGuidanceFeatureFlag = "filtered_write_guidance"
+
 // 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)

pkg/inventory/filters.go

@@ -36,6 +36,13 @@ func (r *Inventory) checkFeatureFlag(ctx context.Context, flagName string) bool
 	return enabled
 }
 
+// IsFeatureEnabled reports whether the named feature flag is enabled for this
+// inventory's feature checker. It is the exported entry point used by toolset
+// instruction functions (in pkg/github) to gate optional guidance text.
+func (r *Inventory) IsFeatureEnabled(ctx context.Context, flagName string) bool {
+	return r.checkFeatureFlag(ctx, flagName)
+}
+
 // featureFlagAllowed reports whether an item with the given enable/disable
 // flag pair is permitted under the supplied checker. The checker must be
 // non-nil — callers that don't want feature filtering should not call this at
@@ -222,10 +229,12 @@ func (r *Inventory) AvailablePrompts(ctx context.Context) []ServerPrompt {
 			continue
 		}
 		requiredToolsAvailable := true
-		for _, toolName := range prompt.RequiredTools {
-			if !r.HasAvailableTool(ctx, toolName) {
-				requiredToolsAvailable = false
-				break
+		if r.checkFeatureFlag(ctx, filteredWriteGuidanceFeatureFlag) {
+			for _, toolName := range prompt.RequiredTools {
+				if !r.HasAvailableTool(ctx, toolName) {
+					requiredToolsAvailable = false
+					break
+				}
 			}
 		}
 		if !requiredToolsAvailable {

pkg/inventory/registry_test.go

@@ -1224,23 +1224,36 @@ func TestPromptRequiredToolsRespectReadOnlyAndExcludedTools(t *testing.T) {
 		},
 	}
 
-	reg := mustBuild(t, NewBuilder().SetTools(tools).SetPrompts(prompts).WithToolsets([]string{"all"}))
+	// The RequiredTools filtering is gated behind the filtered_write_guidance
+	// feature flag, so these cases enable it via a feature checker.
+	flagOn := func(_ context.Context, _ string) (bool, error) { return true, nil }
+
+	reg := mustBuild(t, NewBuilder().SetTools(tools).SetPrompts(prompts).WithToolsets([]string{"all"}).WithFeatureChecker(flagOn))
 	available := reg.AvailablePrompts(context.Background())
 	if len(available) != 2 {
 		t.Fatalf("Expected 2 prompts before filtering, got %d", len(available))
 	}
 
-	readOnly := mustBuild(t, NewBuilder().SetTools(tools).SetPrompts(prompts).WithToolsets([]string{"all"}).WithReadOnly(true))
+	readOnly := mustBuild(t, NewBuilder().SetTools(tools).SetPrompts(prompts).WithToolsets([]string{"all"}).WithReadOnly(true).WithFeatureChecker(flagOn))
 	availableReadOnly := readOnly.AvailablePrompts(context.Background())
 	if len(availableReadOnly) != 1 || availableReadOnly[0].Prompt.Name != "always_available" {
 		t.Fatalf("Expected only always_available in read-only mode, got %#v", availableReadOnly)
 	}
 
-	excluded := mustBuild(t, NewBuilder().SetTools(tools).SetPrompts(prompts).WithToolsets([]string{"all"}).WithExcludeTools([]string{"write_tool"}))
+	excluded := mustBuild(t, NewBuilder().SetTools(tools).SetPrompts(prompts).WithToolsets([]string{"all"}).WithExcludeTools([]string{"write_tool"}).WithFeatureChecker(flagOn))
 	availableExcluded := excluded.AvailablePrompts(context.Background())
 	if len(availableExcluded) != 1 || availableExcluded[0].Prompt.Name != "always_available" {
 		t.Fatalf("Expected only always_available when write_tool is excluded, got %#v", availableExcluded)
 	}
+
+	// With the flag disabled, RequiredTools filtering is skipped entirely, so
+	// the write-gated prompt is advertised even in read-only mode.
+	flagOff := func(_ context.Context, _ string) (bool, error) { return false, nil }
+	flagDisabled := mustBuild(t, NewBuilder().SetTools(tools).SetPrompts(prompts).WithToolsets([]string{"all"}).WithReadOnly(true).WithFeatureChecker(flagOff))
+	availableFlagDisabled := flagDisabled.AvailablePrompts(context.Background())
+	if len(availableFlagDisabled) != 2 {
+		t.Fatalf("Expected 2 prompts when filtered_write_guidance is disabled, got %#v", availableFlagDisabled)
+	}
 }
 
 func TestServerToolHasHandler(t *testing.T) {