Merge branch 'main' into iunia/reapply-issue-field-commits

Author: SamMorrowDrums

.github/workflows/mcp-diff.yml

@@ -19,32 +19,35 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
       - name: Build UI
         uses: ./.github/actions/build-ui
 
+      - name: Generate diff configurations
+        id: configs
+        # The generator imports pkg/github so any new entry in
+        # AllowedFeatureFlags is automatically diffed without touching this
+        # workflow. See script/print-mcp-diff-configs/main.go.
+        run: |
+          {
+            echo 'configurations<<MCP_DIFF_EOF'
+            go run ./script/print-mcp-diff-configs
+            echo 'MCP_DIFF_EOF'
+          } >> "$GITHUB_OUTPUT"
+
       - name: Run MCP Server Diff
         uses: SamMorrowDrums/mcp-server-diff@v2.3.5
         with:
-          setup_go: "true"
+          setup_go: "false"
           install_command: go mod download
           start_command: go run ./cmd/github-mcp-server stdio
           env_vars: |
             GITHUB_PERSONAL_ACCESS_TOKEN=test-token
-          configurations: |
-            [
-              {"name": "default", "args": ""},
-              {"name": "read-only", "args": "--read-only"},
-              {"name": "toolsets-repos", "args": "--toolsets=repos"},
-              {"name": "toolsets-issues", "args": "--toolsets=issues"},
-              {"name": "toolsets-context", "args": "--toolsets=context"},
-              {"name": "toolsets-pull_requests", "args": "--toolsets=pull_requests"},
-              {"name": "toolsets-repos,issues", "args": "--toolsets=repos,issues"},
-              {"name": "toolsets-issues,context", "args": "--toolsets=issues,context"},
-              {"name": "toolsets-all", "args": "--toolsets=all"},
-              {"name": "tools-get_me", "args": "--tools=get_me"},
-              {"name": "tools-get_me,list_issues", "args": "--tools=get_me,list_issues"},
-              {"name": "toolsets-repos+read-only", "args": "--toolsets=repos --read-only"}
-            ]
+          configurations: ${{ steps.configs.outputs.configurations }}
 
       - name: Add interpretation note
         if: always()
@@ -58,3 +61,51 @@ jobs:
           echo "- New tools/toolsets added" >> $GITHUB_STEP_SUMMARY
           echo "- Tool descriptions updated" >> $GITHUB_STEP_SUMMARY
           echo "- Capability changes (intentional improvements)" >> $GITHUB_STEP_SUMMARY
+
+  mcp-diff-http:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Build UI
+        uses: ./.github/actions/build-ui
+
+      - name: Generate diff configurations
+        id: configs
+        # See script/print-mcp-diff-configs/main.go. The http-headers variant
+        # points every config at a shared HTTP server started by the action
+        # and carries per-config settings via X-MCP-* headers, mirroring how
+        # the remote server is invoked in production (server-side defaults +
+        # per-user header overrides).
+        run: |
+          {
+            echo 'configurations<<MCP_DIFF_EOF'
+            go run ./script/print-mcp-diff-configs -transport http-headers
+            echo 'MCP_DIFF_EOF'
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Run MCP Server Diff (streamable-http)
+        uses: SamMorrowDrums/mcp-server-diff@v2.3.5
+        with:
+          setup_go: "false"
+          install_command: go mod download
+          http_start_command: go run ./cmd/github-mcp-server http --port 8082
+          http_startup_wait_ms: "5000"
+          configurations: ${{ steps.configs.outputs.configurations }}
+
+      - name: Add interpretation note
+        if: always()
+        run: |
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "---" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "ℹ️ **Note:** This job exercises the streamable-http transport against a shared server, with per-config settings supplied via X-MCP-* request headers." >> $GITHUB_STEP_SUMMARY

README.md

@@ -126,6 +126,13 @@ var (
 				}
 			}
 
+			var enabledFeatures []string
+			if viper.IsSet("features") {
+				if err := viper.UnmarshalKey("features", &enabledFeatures); err != nil {
+					return fmt.Errorf("failed to unmarshal features: %w", err)
+				}
+			}
+
 			ttl := viper.GetDuration("repo-access-cache-ttl")
 			httpConfig := ghhttp.ServerConfig{
 				Version:              version,
@@ -144,6 +151,7 @@ var (
 				EnabledToolsets:      enabledToolsets,
 				EnabledTools:         enabledTools,
 				ExcludeTools:         excludeTools,
+				EnabledFeatures:      enabledFeatures,
 				InsidersMode:         viper.GetBool("insiders"),
 			}
 

cmd/github-mcp-server/main.go

@@ -42,3 +42,60 @@ MCP Apps requires a host that supports the [MCP Apps extension](https://modelcon
 
 - **VS Code Insiders** — enable via the `chat.mcp.apps.enabled` setting
 - **Visual Studio Code** — enable via the `chat.mcp.apps.enabled` setting
+
+---
+
+## CSV output for list tools
+
+CSV output mode returns supported list tool responses as CSV instead of JSON. This is intended to reduce response context for agents when scanning or summarising lists of GitHub data.
+
+CSV output applies only to tools in default toolsets whose names start with `list_`, such as `list_issues`, `list_pull_requests`, `list_commits`, and `list_branches`. It does not add new tools or expose a tool argument for selecting the format; the server controls the response format through the Insiders feature flag.
+
+### Format
+
+- Nested objects are flattened into dot-notation columns, for example `user.login`, `category.name`, or `head.ref`.
+- Arrays are represented as compact single-cell values joined with `;`.
+- `body` fields are whitespace-normalized so multiline Markdown does not expand a list response into many output lines.
+- Response metadata present in wrapped responses, such as `pageInfo.*` and `totalCount`, is emitted as `#`-prefixed lines before the CSV rows, followed by a blank line. Tools that return a root JSON array do not include metadata preamble lines.
+
+### Enabling CSV output
+
+CSV output is enabled by Insiders Mode. For local development, it can also be enabled explicitly with the `csv_output` feature flag:
+
+```bash
+github-mcp-server stdio --features csv_output
+```
+
+Because this changes list tool response shape, clients that require JSON list responses should avoid enabling this feature.
+
+---
+
+## How feature flags are resolved
+
+> [!NOTE]
+> This section is for contributors. End users only need the table at the top of this page.
+
+Insiders is a **meta feature flag** — the same shape as `default` or `all` for toolsets. It expands once at startup into a curated set of individual feature flags, and from that point on every code path keys off concrete flags, never `InsidersMode` directly. New experimental work should always get its own flag and then be added to the insiders expansion list, never folded into `insiders` as a catch-all.
+
+### Resolution order
+
+1. **User input.** Users may opt into specific features:
+   - Local server: `--features=<flag>,<flag>` CLI flag (or `GITHUB_FEATURES` env var).
+   - Self-hosted HTTP server: `X-MCP-Features: <flag>,<flag>` request header.
+2. **Allowlist filter.** User-supplied flags are filtered against [`AllowedFeatureFlags`](../pkg/github/feature_flags.go). Anything not on the allowlist is silently dropped — flags missing from the allowlist can only be turned on by remote-server feature management, not by end users.
+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.
+
+`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.
+- A flag in **`InsidersFeatureFlags` only** is reachable through insiders (and remote-server rollouts), but cannot be enabled by user input. Internal-only experiments work this way.
+- A flag in **both** is opt-in for end users *and* automatically on under insiders.
+
+### Adding a new feature flag
+
+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`.

docs/insiders-features.md

@@ -143,7 +143,6 @@ func NewStdioMCPServer(ctx context.Context, cfg github.MCPServerConfig) (*mcp.Se
 		cfg.Translator,
 		github.FeatureFlags{
 			LockdownMode: cfg.LockdownMode,
-			InsidersMode: cfg.InsidersMode,
 		},
 		cfg.ContentWindowSize,
 		featureChecker,
@@ -229,7 +228,7 @@ type StdioServerConfig struct {
 	// LockdownMode indicates if we should enable lockdown mode
 	LockdownMode bool
 
-	// InsidersMode indicates if we should enable experimental features
+	// InsidersMode expands to the curated set of feature flags enabled for insiders.
 	InsidersMode bool
 
 	// ExcludeTools is a list of tool names to disable regardless of other settings.
@@ -345,7 +344,7 @@ func RunStdioServer(cfg StdioServerConfig) error {
 
 // createFeatureChecker returns a FeatureFlagChecker that resolves features
 // using the centralized ResolveFeatureFlags function. For the local server,
-// features are resolved once at startup from --features CLI flag + insiders mode.
+// 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) {

internal/ghmcp/server.go

@@ -1,7 +1,7 @@
 {
   "annotations": {
     "readOnlyHint": true,
-    "title": "Get a specific label from a repository."
+    "title": "Get a specific label from a repository"
   },
   "description": "Get a specific label from a repository.",
   "inputSchema": {

pkg/github/__toolsnaps__/get_label.snap

@@ -9,7 +9,7 @@
     }
   },
   "annotations": {
-    "title": "Create or update issue."
+    "title": "Create or update issue"
   },
   "description": "Create a new or update an existing issue in a GitHub repository.",
   "inputSchema": {

pkg/github/__toolsnaps__/issue_write.snap

@@ -1,6 +1,6 @@
 {
   "annotations": {
-    "title": "Write operations on repository labels."
+    "title": "Write operations on repository labels"
   },
   "description": "Perform write operations on repository labels. To set labels on issues, use the 'update_issue' tool.",
   "inputSchema": {

pkg/github/__toolsnaps__/label_write.snap

@@ -0,0 +1,24 @@
+{
+  "annotations": {
+    "readOnlyHint": true,
+    "title": "List issue fields"
+  },
+  "description": "List issue fields for a repository or organization. Returns field definitions including name, type (text, number, date, single_select), and for single_select fields the list of valid option names. When repo is omitted, returns org-level fields directly.",
+  "inputSchema": {
+    "properties": {
+      "owner": {
+        "description": "The account owner of the repository or organization. The name is not case sensitive.",
+        "type": "string"
+      },
+      "repo": {
+        "description": "The name of the repository. When provided, returns fields for this specific repository (inherited from its organization). When omitted, returns org-level fields directly.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "owner"
+    ],
+    "type": "object"
+  },
+  "name": "list_issue_fields"
+}

pkg/github/__toolsnaps__/list_issue_fields.snap

@@ -18,6 +18,27 @@
         ],
         "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": {