From 6f8287bc777ef82ff8b3289626bb542ecc51e399 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 6 Jan 2026 17:42:32 +0000 Subject: [PATCH 1/6] Initial plan From a1885cc77eb2086368e01c98f29dacb3c36d22a3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 6 Jan 2026 17:53:24 +0000 Subject: [PATCH 2/6] Add list-scopes command using inventory architecture Co-authored-by: SamMorrowDrums <4811358+SamMorrowDrums@users.noreply.github.com> --- script/list-scopes | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100755 script/list-scopes diff --git a/script/list-scopes b/script/list-scopes new file mode 100755 index 000000000..2f7502823 --- /dev/null +++ b/script/list-scopes @@ -0,0 +1,24 @@ +#!/bin/bash +# +# List required OAuth scopes for enabled tools. +# +# Usage: +# script/list-scopes [--toolsets=...] [--output=text|json|summary] +# +# Examples: +# script/list-scopes +# script/list-scopes --toolsets=all --output=json +# script/list-scopes --toolsets=repos,issues --output=summary +# + +set -e + +cd "$(dirname "$0")/.." + +# Build the server if it doesn't exist or is outdated +if [ ! -f github-mcp-server ] || [ cmd/github-mcp-server/list_scopes.go -nt github-mcp-server ]; then + echo "Building github-mcp-server..." >&2 + go build -o github-mcp-server ./cmd/github-mcp-server +fi + +exec ./github-mcp-server list-scopes "$@" From 9be3315f6b513bc400a5e263a1722b99f05d85cb Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 6 Jan 2026 17:55:59 +0000 Subject: [PATCH 3/6] Add list_scopes.go implementation file Co-authored-by: SamMorrowDrums <4811358+SamMorrowDrums@users.noreply.github.com> --- cmd/github-mcp-server/list_scopes.go | 315 +++++++++++++++++++++++++++ 1 file changed, 315 insertions(+) create mode 100644 cmd/github-mcp-server/list_scopes.go diff --git a/cmd/github-mcp-server/list_scopes.go b/cmd/github-mcp-server/list_scopes.go new file mode 100644 index 000000000..a63bd44f5 --- /dev/null +++ b/cmd/github-mcp-server/list_scopes.go @@ -0,0 +1,315 @@ +package main + +import ( + "context" + "encoding/json" + "fmt" + "os" + "sort" + "strings" + + "github.com/github/github-mcp-server/pkg/github" + "github.com/github/github-mcp-server/pkg/inventory" + "github.com/github/github-mcp-server/pkg/translations" + "github.com/spf13/cobra" + "github.com/spf13/viper" +) + +// ToolScopeInfo contains scope information for a single tool. +type ToolScopeInfo struct { + Name string `json:"name"` + Toolset string `json:"toolset"` + ReadOnly bool `json:"read_only"` + RequiredScopes []string `json:"required_scopes"` + AcceptedScopes []string `json:"accepted_scopes,omitempty"` +} + +// ScopesOutput is the full output structure for the list-scopes command. +type ScopesOutput struct { + Tools []ToolScopeInfo `json:"tools"` + UniqueScopes []string `json:"unique_scopes"` + ScopesByTool map[string][]string `json:"scopes_by_tool"` + ToolsByScope map[string][]string `json:"tools_by_scope"` + EnabledToolsets []string `json:"enabled_toolsets"` + ReadOnly bool `json:"read_only"` +} + +var listScopesCmd = &cobra.Command{ + Use: "list-scopes", + Short: "List required OAuth scopes for enabled tools", + Long: `List the required OAuth scopes for all enabled tools. + +This command creates an inventory based on the same flags as the stdio command +and outputs the required OAuth scopes for each enabled tool. This is useful for +determining what scopes a token needs to use specific tools. + +The output format can be controlled with the --output flag: + - text (default): Human-readable text output + - json: JSON output for programmatic use + - summary: Just the unique scopes needed + +Examples: + # List scopes for default toolsets + github-mcp-server list-scopes + + # List scopes for specific toolsets + github-mcp-server list-scopes --toolsets=repos,issues,pull_requests + + # List scopes for all toolsets + github-mcp-server list-scopes --toolsets=all + + # Output as JSON + github-mcp-server list-scopes --output=json + + # Just show unique scopes needed + github-mcp-server list-scopes --output=summary`, + RunE: func(_ *cobra.Command, _ []string) error { + return runListScopes() + }, +} + +func init() { + listScopesCmd.Flags().StringP("output", "o", "text", "Output format: text, json, or summary") + _ = viper.BindPFlag("list-scopes-output", listScopesCmd.Flags().Lookup("output")) + + rootCmd.AddCommand(listScopesCmd) +} + +func runListScopes() error { + // Get toolsets configuration (same logic as stdio command) + var enabledToolsets []string + if viper.IsSet("toolsets") { + if err := viper.UnmarshalKey("toolsets", &enabledToolsets); err != nil { + return fmt.Errorf("failed to unmarshal toolsets: %w", err) + } + } + // else: enabledToolsets stays nil, meaning "use defaults" + + // Get specific tools (similar to toolsets) + var enabledTools []string + if viper.IsSet("tools") { + if err := viper.UnmarshalKey("tools", &enabledTools); err != nil { + return fmt.Errorf("failed to unmarshal tools: %w", err) + } + } + + readOnly := viper.GetBool("read-only") + outputFormat := viper.GetString("list-scopes-output") + + // Create translation helper + t, _ := translations.TranslationHelper() + + // Build inventory using the same logic as the stdio server + inventoryBuilder := github.NewInventory(t). + WithReadOnly(readOnly) + + // Configure toolsets (same as stdio) + if enabledToolsets != nil { + inventoryBuilder = inventoryBuilder.WithToolsets(enabledToolsets) + } + + // Configure specific tools + if len(enabledTools) > 0 { + inventoryBuilder = inventoryBuilder.WithTools(enabledTools) + } + + inv := inventoryBuilder.Build() + + // Collect all tools and their scopes + output := collectToolScopes(inv, readOnly) + + // Output based on format + switch outputFormat { + case "json": + return outputJSON(output) + case "summary": + return outputSummary(output) + default: + return outputText(output) + } +} + +func collectToolScopes(inv *inventory.Inventory, readOnly bool) ScopesOutput { + var tools []ToolScopeInfo + scopeSet := make(map[string]bool) + scopesByTool := make(map[string][]string) + toolsByScope := make(map[string][]string) + + // Get all available tools from the inventory + // Use context.Background() for feature flag evaluation + availableTools := inv.AvailableTools(context.Background()) + + for _, serverTool := range availableTools { + tool := serverTool.Tool + + // Get scope information directly from ServerTool + requiredScopes := serverTool.RequiredScopes + acceptedScopes := serverTool.AcceptedScopes + + // Determine if tool is read-only + isReadOnly := serverTool.IsReadOnly() + + toolInfo := ToolScopeInfo{ + Name: tool.Name, + Toolset: string(serverTool.Toolset.ID), + ReadOnly: isReadOnly, + RequiredScopes: requiredScopes, + AcceptedScopes: acceptedScopes, + } + tools = append(tools, toolInfo) + + // Track unique scopes + for _, s := range requiredScopes { + scopeSet[s] = true + toolsByScope[s] = append(toolsByScope[s], tool.Name) + } + + // Track scopes by tool + scopesByTool[tool.Name] = requiredScopes + } + + // Sort tools by name + sort.Slice(tools, func(i, j int) bool { + return tools[i].Name < tools[j].Name + }) + + // Get unique scopes as sorted slice + var uniqueScopes []string + for s := range scopeSet { + uniqueScopes = append(uniqueScopes, s) + } + sort.Strings(uniqueScopes) + + // Sort tools within each scope + for scope := range toolsByScope { + sort.Strings(toolsByScope[scope]) + } + + // Get enabled toolsets as string slice + toolsetIDs := inv.ToolsetIDs() + toolsetIDStrs := make([]string, len(toolsetIDs)) + for i, id := range toolsetIDs { + toolsetIDStrs[i] = string(id) + } + + return ScopesOutput{ + Tools: tools, + UniqueScopes: uniqueScopes, + ScopesByTool: scopesByTool, + ToolsByScope: toolsByScope, + EnabledToolsets: toolsetIDStrs, + ReadOnly: readOnly, + } +} + +func outputJSON(output ScopesOutput) error { + encoder := json.NewEncoder(os.Stdout) + encoder.SetIndent("", " ") + return encoder.Encode(output) +} + +func outputSummary(output ScopesOutput) error { + if len(output.UniqueScopes) == 0 { + fmt.Println("No OAuth scopes required for enabled tools.") + return nil + } + + fmt.Println("Required OAuth scopes for enabled tools:") + fmt.Println() + for _, scope := range output.UniqueScopes { + if scope == "" { + fmt.Println(" (no scope required for public read access)") + } else { + fmt.Printf(" %s\n", scope) + } + } + fmt.Printf("\nTotal: %d unique scope(s)\n", len(output.UniqueScopes)) + return nil +} + +func outputText(output ScopesOutput) error { + fmt.Printf("OAuth Scopes for Enabled Tools\n") + fmt.Printf("==============================\n\n") + + fmt.Printf("Enabled Toolsets: %s\n", strings.Join(output.EnabledToolsets, ", ")) + fmt.Printf("Read-Only Mode: %v\n\n", output.ReadOnly) + + // Group tools by toolset + toolsByToolset := make(map[string][]ToolScopeInfo) + for _, tool := range output.Tools { + toolsByToolset[tool.Toolset] = append(toolsByToolset[tool.Toolset], tool) + } + + // Get sorted toolset names + var toolsetNames []string + for name := range toolsByToolset { + toolsetNames = append(toolsetNames, name) + } + sort.Strings(toolsetNames) + + for _, toolsetName := range toolsetNames { + tools := toolsByToolset[toolsetName] + fmt.Printf("## %s\n\n", formatToolsetNameForOutput(toolsetName)) + + for _, tool := range tools { + rwIndicator := "📝" + if tool.ReadOnly { + rwIndicator = "👁" + } + + scopeStr := "(no scope required)" + if len(tool.RequiredScopes) > 0 { + scopeStr = strings.Join(tool.RequiredScopes, ", ") + } + + fmt.Printf(" %s %s: %s\n", rwIndicator, tool.Name, scopeStr) + } + fmt.Println() + } + + // Summary + fmt.Println("## Summary") + fmt.Println() + if len(output.UniqueScopes) == 0 { + fmt.Println("No OAuth scopes required for enabled tools.") + } else { + fmt.Println("Unique scopes required:") + for _, scope := range output.UniqueScopes { + if scope == "" { + fmt.Println(" • (no scope - public read access)") + } else { + fmt.Printf(" • %s\n", scope) + } + } + } + fmt.Printf("\nTotal: %d tools, %d unique scopes\n", len(output.Tools), len(output.UniqueScopes)) + + // Legend + fmt.Println("\nLegend: 👁 = read-only, 📝 = read-write") + + return nil +} + +func formatToolsetNameForOutput(name string) string { + switch name { + case "pull_requests": + return "Pull Requests" + case "repos": + return "Repositories" + case "code_security": + return "Code Security" + case "secret_protection": + return "Secret Protection" + case "orgs": + return "Organizations" + default: + // Capitalize first letter and replace underscores with spaces + parts := strings.Split(name, "_") + for i, part := range parts { + if len(part) > 0 { + parts[i] = strings.ToUpper(string(part[0])) + part[1:] + } + } + return strings.Join(parts, " ") + } +} From 67df381558e4b74417412d3eaec6a0e87b89ae20 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 6 Jan 2026 18:00:00 +0000 Subject: [PATCH 4/6] Refactor formatToolsetName to shared helper function Co-authored-by: SamMorrowDrums <4811358+SamMorrowDrums@users.noreply.github.com> --- cmd/github-mcp-server/generate_docs.go | 24 ------------------------ cmd/github-mcp-server/list_scopes.go | 26 +------------------------- 2 files changed, 1 insertion(+), 49 deletions(-) diff --git a/cmd/github-mcp-server/generate_docs.go b/cmd/github-mcp-server/generate_docs.go index 85d7ecdbf..14d771330 100644 --- a/cmd/github-mcp-server/generate_docs.go +++ b/cmd/github-mcp-server/generate_docs.go @@ -198,30 +198,6 @@ func generateToolsDoc(r *inventory.Inventory) string { return buf.String() } -func formatToolsetName(name string) string { - switch name { - case "pull_requests": - return "Pull Requests" - case "repos": - return "Repositories" - case "code_security": - return "Code Security" - case "secret_protection": - return "Secret Protection" - case "orgs": - return "Organizations" - default: - // Fallback: capitalize first letter and replace underscores with spaces - parts := strings.Split(name, "_") - for i, part := range parts { - if len(part) > 0 { - parts[i] = strings.ToUpper(string(part[0])) + part[1:] - } - } - return strings.Join(parts, " ") - } -} - func writeToolDoc(buf *strings.Builder, tool inventory.ServerTool) { // Tool name (no icon - section header already has the toolset icon) fmt.Fprintf(buf, "- **%s** - %s\n", tool.Tool.Name, tool.Tool.Annotations.Title) diff --git a/cmd/github-mcp-server/list_scopes.go b/cmd/github-mcp-server/list_scopes.go index a63bd44f5..9f7dcabce 100644 --- a/cmd/github-mcp-server/list_scopes.go +++ b/cmd/github-mcp-server/list_scopes.go @@ -249,7 +249,7 @@ func outputText(output ScopesOutput) error { for _, toolsetName := range toolsetNames { tools := toolsByToolset[toolsetName] - fmt.Printf("## %s\n\n", formatToolsetNameForOutput(toolsetName)) + fmt.Printf("## %s\n\n", formatToolsetName(toolsetName)) for _, tool := range tools { rwIndicator := "📝" @@ -289,27 +289,3 @@ func outputText(output ScopesOutput) error { return nil } - -func formatToolsetNameForOutput(name string) string { - switch name { - case "pull_requests": - return "Pull Requests" - case "repos": - return "Repositories" - case "code_security": - return "Code Security" - case "secret_protection": - return "Secret Protection" - case "orgs": - return "Organizations" - default: - // Capitalize first letter and replace underscores with spaces - parts := strings.Split(name, "_") - for i, part := range parts { - if len(part) > 0 { - parts[i] = strings.ToUpper(string(part[0])) + part[1:] - } - } - return strings.Join(parts, " ") - } -} From 1cf9261f453f8ac22366e56c4533b6b143f83aaf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 6 Jan 2026 18:00:47 +0000 Subject: [PATCH 5/6] Add helpers.go with shared formatToolsetName function Co-authored-by: SamMorrowDrums <4811358+SamMorrowDrums@users.noreply.github.com> --- cmd/github-mcp-server/helpers.go | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 cmd/github-mcp-server/helpers.go diff --git a/cmd/github-mcp-server/helpers.go b/cmd/github-mcp-server/helpers.go new file mode 100644 index 000000000..c5f498813 --- /dev/null +++ b/cmd/github-mcp-server/helpers.go @@ -0,0 +1,29 @@ +package main + +import "strings" + +// formatToolsetName converts a toolset ID to a human-readable name. +// Used by both generate_docs.go and list_scopes.go for consistent formatting. +func formatToolsetName(name string) string { + switch name { + case "pull_requests": + return "Pull Requests" + case "repos": + return "Repositories" + case "code_security": + return "Code Security" + case "secret_protection": + return "Secret Protection" + case "orgs": + return "Organizations" + default: + // Fallback: capitalize first letter and replace underscores with spaces + parts := strings.Split(name, "_") + for i, part := range parts { + if len(part) > 0 { + parts[i] = strings.ToUpper(string(part[0])) + part[1:] + } + } + return strings.Join(parts, " ") + } +} From 71c4adcf4924744efb3b2f073bc6fecfc6b754ae Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 6 Jan 2026 18:03:29 +0000 Subject: [PATCH 6/6] Add formatScopeDisplay helper and improve empty scope handling Co-authored-by: SamMorrowDrums <4811358+SamMorrowDrums@users.noreply.github.com> --- cmd/github-mcp-server/list_scopes.go | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/cmd/github-mcp-server/list_scopes.go b/cmd/github-mcp-server/list_scopes.go index 9f7dcabce..2d1817500 100644 --- a/cmd/github-mcp-server/list_scopes.go +++ b/cmd/github-mcp-server/list_scopes.go @@ -75,6 +75,14 @@ func init() { rootCmd.AddCommand(listScopesCmd) } +// formatScopeDisplay formats a scope string for display, handling empty scopes. +func formatScopeDisplay(scope string) string { + if scope == "" { + return "(no scope required for public read access)" + } + return scope +} + func runListScopes() error { // Get toolsets configuration (same logic as stdio command) var enabledToolsets []string @@ -217,11 +225,7 @@ func outputSummary(output ScopesOutput) error { fmt.Println("Required OAuth scopes for enabled tools:") fmt.Println() for _, scope := range output.UniqueScopes { - if scope == "" { - fmt.Println(" (no scope required for public read access)") - } else { - fmt.Printf(" %s\n", scope) - } + fmt.Printf(" %s\n", formatScopeDisplay(scope)) } fmt.Printf("\nTotal: %d unique scope(s)\n", len(output.UniqueScopes)) return nil @@ -275,11 +279,7 @@ func outputText(output ScopesOutput) error { } else { fmt.Println("Unique scopes required:") for _, scope := range output.UniqueScopes { - if scope == "" { - fmt.Println(" • (no scope - public read access)") - } else { - fmt.Printf(" • %s\n", scope) - } + fmt.Printf(" • %s\n", formatScopeDisplay(scope)) } } fmt.Printf("\nTotal: %d tools, %d unique scopes\n", len(output.Tools), len(output.UniqueScopes))