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) } // 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 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, err := inventoryBuilder.Build() if err != nil { return fmt.Errorf("failed to build inventory: %w", err) } // 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 { fmt.Printf(" %s\n", formatScopeDisplay(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", formatToolsetName(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 { fmt.Printf(" • %s\n", formatScopeDisplay(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 }