feat(issues): gate issue-fields features behind remote_mcp_issue_fields flag (#2520)

* feat(issues): gate issue-fields features behind remote_mcp_issue_fields flag

Gates the recently merged issue-fields work (list_issue_fields tool,
field_values enrichment on list_issues/search_issues, and field_filters
input on list_issues) behind a new feature flag, also enabled in
insiders mode.

- list_issues splits into two same-named registrations: the field-aware
  variant requires the flag, while LegacyListIssues (FeatureFlagDisable)
  preserves the prior schema and GraphQL selection set so disabled
  callers don't pay the extra wire/server cost.
- search_issues skips the field-values lookup when the flag is off.
- list_issue_fields requires the flag to be registered at all.
- Adopts <tool>_ff_<flag>.snap naming for flagged toolsnap variants so
  same-named duplicates each get a distinct snapshot.

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

* fix: address PR review on issue-fields gating

- docs generator: install a no-flags feature checker so README reflects
  the default user experience (tools enabled with no special flags),
  fixing duplicate `list_issues` and removing granular/flagged-only
  tools that were never meant to appear in the default docs.
- csv_output: drop the FeatureFlagEnable/Disable exclusion in
  isCSVOutputTool. Wrapping happens before the per-request flag filter
  picks the live variant, so flag-gated list_* tools wrap safely; this
  restores CSV conversion for `list_issues` and enables it for
  `list_issue_fields` when both flags are on.

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

---------

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

Author: SamMorrowDrums

README.md

@@ -829,21 +829,6 @@ The following sets of tools are available:
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
 
-- **add_sub_issue** - Add Sub-Issue
-  - **Required OAuth Scopes**: `repo`
-  - `issue_number`: The parent issue number (number, required)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `replace_parent`: If true, reparent the sub-issue if it already has a parent (boolean, optional)
-  - `repo`: Repository name (string, required)
-  - `sub_issue_id`: The ID of the sub-issue to add. ID is not the same as issue number (number, required)
-
-- **create_issue** - Create Issue
-  - **Required OAuth Scopes**: `repo`
-  - `body`: Issue body content (optional) (string, optional)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `repo`: Repository name (string, required)
-  - `title`: Issue title (string, required)
-
 - **get_label** - Get a specific label from a repository
   - **Required OAuth Scopes**: `repo`
   - `name`: Label name. (string, required)
@@ -885,12 +870,6 @@ The following sets of tools are available:
   - `title`: Issue title (string, optional)
   - `type`: Type of this issue. Only use if the repository has issue types configured. Use list_issue_types tool to get valid type values for the organization. If the repository doesn't support issue types, omit this parameter. (string, optional)
 
-- **list_issue_fields** - List issue fields
-  - **Required OAuth Scopes**: `repo`, `read:org`
-  - **Accepted OAuth Scopes**: `admin:org`, `read:org`, `repo`, `write:org`
-  - `owner`: The account owner of the repository or organization. The name is not case sensitive. (string, required)
-  - `repo`: The name of the repository. When provided, returns fields for this specific repository (inherited from its organization). When omitted, returns org-level fields directly. (string, optional)
-
 - **list_issue_types** - List available issue types
   - **Required OAuth Scopes**: `read:org`
   - **Accepted OAuth Scopes**: `admin:org`, `read:org`, `write:org`
@@ -900,7 +879,6 @@ The following sets of tools are available:
   - **Required OAuth Scopes**: `repo`
   - `after`: Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs. (string, optional)
   - `direction`: Order direction. If provided, the 'orderBy' also needs to be provided. (string, optional)
-  - `field_filters`: Filter by custom issue field values. Each entry takes a field_name and a value; the server looks up the field and coerces the value to its type (single-select option name, text, number, or YYYY-MM-DD date). (object[], optional)
   - `labels`: Filter by labels (string[], optional)
   - `orderBy`: Order issues by field. If provided, the 'direction' also needs to be provided. (string, optional)
   - `owner`: Repository owner (string, required)
@@ -909,22 +887,6 @@ The following sets of tools are available:
   - `since`: Filter by date (ISO 8601 timestamp) (string, optional)
   - `state`: Filter by state, by default both open and closed issues are returned when not provided (string, optional)
 
-- **remove_sub_issue** - Remove Sub-Issue
-  - **Required OAuth Scopes**: `repo`
-  - `issue_number`: The parent issue number (number, required)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `repo`: Repository name (string, required)
-  - `sub_issue_id`: The ID of the sub-issue to remove. ID is not the same as issue number (number, required)
-
-- **reprioritize_sub_issue** - Reprioritize Sub-Issue
-  - **Required OAuth Scopes**: `repo`
-  - `after_id`: The ID of the sub-issue to place this after (either after_id OR before_id should be specified) (number, optional)
-  - `before_id`: The ID of the sub-issue to place this before (either after_id OR before_id should be specified) (number, optional)
-  - `issue_number`: The parent issue number (number, required)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `repo`: Repository name (string, required)
-  - `sub_issue_id`: The ID of the sub-issue to reorder. ID is not the same as issue number (number, required)
-
 - **search_issues** - Search issues
   - **Required OAuth Scopes**: `repo`
   - `order`: Sort order (string, optional)
@@ -935,13 +897,6 @@ The following sets of tools are available:
   - `repo`: Optional repository name. If provided with owner, only issues for this repository are listed. (string, optional)
   - `sort`: Sort field by number of matches of categories, defaults to best match (string, optional)
 
-- **set_issue_fields** - Set Issue Fields
-  - **Required OAuth Scopes**: `repo`
-  - `fields`: Array of issue field values to set. Each element must have a 'field_id' (string, the GraphQL node ID of the field) and exactly one value field: 'text_value' for text fields, 'number_value' for number fields, 'date_value' (ISO 8601 date string) for date fields, or 'single_select_option_id' (the GraphQL node ID of the option) for single select fields. Set 'delete' to true to remove a field value. (object[], required)
-  - `issue_number`: The issue number to update (number, required)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `repo`: Repository name (string, required)
-
 - **sub_issue_write** - Change sub-issue
   - **Required OAuth Scopes**: `repo`
   - `after_id`: The ID of the sub-issue to be prioritized after (either after_id OR before_id should be specified) (number, optional)
@@ -958,57 +913,6 @@ The following sets of tools are available:
   - `repo`: Repository name (string, required)
   - `sub_issue_id`: The ID of the sub-issue to add. ID is not the same as issue number (number, required)
 
-- **update_issue_assignees** - Update Issue Assignees
-  - **Required OAuth Scopes**: `repo`
-  - `assignees`: GitHub usernames to assign to this issue (string[], required)
-  - `issue_number`: The issue number to update (number, required)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `repo`: Repository name (string, required)
-
-- **update_issue_body** - Update Issue Body
-  - **Required OAuth Scopes**: `repo`
-  - `body`: The new body content for the issue (string, required)
-  - `issue_number`: The issue number to update (number, required)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `repo`: Repository name (string, required)
-
-- **update_issue_labels** - Update Issue Labels
-  - **Required OAuth Scopes**: `repo`
-  - `issue_number`: The issue number to update (number, required)
-  - `labels`: Labels to apply to this issue. ([], required)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `repo`: Repository name (string, required)
-
-- **update_issue_milestone** - Update Issue Milestone
-  - **Required OAuth Scopes**: `repo`
-  - `issue_number`: The issue number to update (number, required)
-  - `milestone`: The milestone number to set on the issue (integer, required)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `repo`: Repository name (string, required)
-
-- **update_issue_state** - Update Issue State
-  - **Required OAuth Scopes**: `repo`
-  - `issue_number`: The issue number to update (number, required)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `repo`: Repository name (string, required)
-  - `state`: The new state for the issue (string, required)
-  - `state_reason`: The reason for the state change (only for closed state) (string, optional)
-
-- **update_issue_title** - Update Issue Title
-  - **Required OAuth Scopes**: `repo`
-  - `issue_number`: The issue number to update (number, required)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `repo`: Repository name (string, required)
-  - `title`: The new title for the issue (string, required)
-
-- **update_issue_type** - Update Issue Type
-  - **Required OAuth Scopes**: `repo`
-  - `issue_number`: The issue number to update (number, required)
-  - `issue_type`: The issue type to set (string, required)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `rationale`: One concise sentence explaining what specifically about the issue led you to choose this type. State the concrete signal (e.g. 'Reports a crash when saving' → bug, 'Asks for dark mode support' → feature). (string, optional)
-  - `repo`: Repository name (string, required)
-
 </details>
 
 <details>
@@ -1161,19 +1065,6 @@ The following sets of tools are available:
   - `startSide`: For multi-line comments, the starting side of the diff that the comment applies to. LEFT indicates the previous state, RIGHT indicates the new state (string, optional)
   - `subjectType`: The level at which the comment is targeted (string, required)
 
-- **add_pull_request_review_comment** - Add Pull Request Review Comment
-  - **Required OAuth Scopes**: `repo`
-  - `body`: The comment body (string, required)
-  - `line`: The line number in the diff to comment on (optional) (number, optional)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `path`: The relative path of the file to comment on (string, required)
-  - `pullNumber`: The pull request number (number, required)
-  - `repo`: Repository name (string, required)
-  - `side`: The side of the diff to comment on (optional) (string, optional)
-  - `startLine`: The start line of a multi-line comment (optional) (number, optional)
-  - `startSide`: The start side of a multi-line comment (optional) (string, optional)
-  - `subjectType`: The subject type of the comment (string, required)
-
 - **add_reply_to_pull_request_comment** - Add reply to pull request comment
   - **Required OAuth Scopes**: `repo`
   - `body`: The text of the reply (string, required)
@@ -1193,21 +1084,6 @@ The following sets of tools are available:
   - `repo`: Repository name (string, required)
   - `title`: PR title (string, required)
 
-- **create_pull_request_review** - Create Pull Request Review
-  - **Required OAuth Scopes**: `repo`
-  - `body`: The review body text (optional) (string, optional)
-  - `commitID`: The SHA of the commit to review (optional, defaults to latest) (string, optional)
-  - `event`: The review action to perform. If omitted, creates a pending review. (string, optional)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `pullNumber`: The pull request number (number, required)
-  - `repo`: Repository name (string, required)
-
-- **delete_pending_pull_request_review** - Delete Pending Pull Request Review
-  - **Required OAuth Scopes**: `repo`
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `pullNumber`: The pull request number (number, required)
-  - `repo`: Repository name (string, required)
-
 - **list_pull_requests** - List pull requests
   - **Required OAuth Scopes**: `repo`
   - `base`: Filter by base branch (string, optional)
@@ -1260,17 +1136,6 @@ The following sets of tools are available:
   - `repo`: Repository name (string, required)
   - `threadId`: The node ID of the review thread (e.g., PRRT_kwDOxxx). Required for resolve_thread and unresolve_thread methods. Get thread IDs from pull_request_read with method get_review_comments. (string, optional)
 
-- **request_pull_request_reviewers** - Request Pull Request Reviewers
-  - **Required OAuth Scopes**: `repo`
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `pullNumber`: The pull request number (number, required)
-  - `repo`: Repository name (string, required)
-  - `reviewers`: GitHub usernames to request reviews from (string[], required)
-
-- **resolve_review_thread** - Resolve Review Thread
-  - **Required OAuth Scopes**: `repo`
-  - `threadID`: The node ID of the review thread to resolve (e.g., PRRT_kwDOxxx) (string, required)
-
 - **search_pull_requests** - Search pull requests
   - **Required OAuth Scopes**: `repo`
   - `order`: Sort order (string, optional)
@@ -1281,18 +1146,6 @@ The following sets of tools are available:
   - `repo`: Optional repository name. If provided with owner, only pull requests for this repository are listed. (string, optional)
   - `sort`: Sort field by number of matches of categories, defaults to best match (string, optional)
 
-- **submit_pending_pull_request_review** - Submit Pending Pull Request Review
-  - **Required OAuth Scopes**: `repo`
-  - `body`: The review body text (optional) (string, optional)
-  - `event`: The review action to perform (string, required)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `pullNumber`: The pull request number (number, required)
-  - `repo`: Repository name (string, required)
-
-- **unresolve_review_thread** - Unresolve Review Thread
-  - **Required OAuth Scopes**: `repo`
-  - `threadID`: The node ID of the review thread to unresolve (e.g., PRRT_kwDOxxx) (string, required)
-
 - **update_pull_request** - Edit pull request
   - **Required OAuth Scopes**: `repo`
   - `base`: New base branch name (string, optional)
@@ -1306,41 +1159,13 @@ The following sets of tools are available:
   - `state`: New state (string, optional)
   - `title`: New title (string, optional)
 
-- **update_pull_request_body** - Update Pull Request Body
-  - **Required OAuth Scopes**: `repo`
-  - `body`: The new body content for the pull request (string, required)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `pullNumber`: The pull request number (number, required)
-  - `repo`: Repository name (string, required)
-
 - **update_pull_request_branch** - Update pull request branch
   - **Required OAuth Scopes**: `repo`
   - `expectedHeadSha`: The expected SHA of the pull request's HEAD ref (string, optional)
   - `owner`: Repository owner (string, required)
   - `pullNumber`: Pull request number (number, required)
   - `repo`: Repository name (string, required)
 
-- **update_pull_request_draft_state** - Update Pull Request Draft State
-  - **Required OAuth Scopes**: `repo`
-  - `draft`: Set to true to convert to draft, false to mark as ready for review (boolean, required)
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `pullNumber`: The pull request number (number, required)
-  - `repo`: Repository name (string, required)
-
-- **update_pull_request_state** - Update Pull Request State
-  - **Required OAuth Scopes**: `repo`
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `pullNumber`: The pull request number (number, required)
-  - `repo`: Repository name (string, required)
-  - `state`: The new state for the pull request (string, required)
-
-- **update_pull_request_title** - Update Pull Request Title
-  - **Required OAuth Scopes**: `repo`
-  - `owner`: Repository owner (username or organization) (string, required)
-  - `pullNumber`: The pull request number (number, required)
-  - `repo`: Repository name (string, required)
-  - `title`: The new title for the pull request (string, required)
-
 </details>
 
 <details>

cmd/github-mcp-server/generate_docs.go

@@ -29,6 +29,12 @@ func init() {
 	rootCmd.AddCommand(generateDocsCmd)
 }
 
+// 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) {
+	return false, nil
+}
+
 func generateAllDocs() error {
 	for _, doc := range []struct {
 		path string
@@ -51,9 +57,16 @@ func generateReadmeDocs(readmePath string) error {
 	// Create translation helper
 	t, _ := translations.TranslationHelper()
 
-	// (not available to regular users) while including tools with FeatureFlagDisable.
+	// 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.
 	// Build() can only fail if WithTools specifies invalid tools - not used here
-	r, _ := github.NewInventory(t).WithToolsets([]string{"all"}).Build()
+	r, _ := github.NewInventory(t).
+		WithToolsets([]string{"all"}).
+		WithFeatureChecker(noFeatureFlagsChecker).
+		Build()
 
 	// Generate toolsets documentation
 	toolsetsDoc := generateToolsetsDoc(r)

pkg/github/__toolsnaps__/list_issues.snap

@@ -18,27 +18,6 @@
         ],
         "type": "string"
       },
-      "field_filters": {
-        "description": "Filter by custom issue field values. Each entry takes a field_name and a value; the server looks up the field and coerces the value to its type (single-select option name, text, number, or YYYY-MM-DD date).",
-        "items": {
-          "properties": {
-            "field_name": {
-              "description": "Name of the custom field (e.g. \"Priority\"). Case-insensitive.",
-              "type": "string"
-            },
-            "value": {
-              "description": "Value to filter on. For single-select fields, the option name (e.g. \"P1\"). For dates, YYYY-MM-DD. For numbers, the numeric value as a string. For text, the text value.",
-              "type": "string"
-            }
-          },
-          "required": [
-            "field_name",
-            "value"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
       "labels": {
         "description": "Filter by labels",
         "items": {