Merge branch 'main' into fix-resource-handler-deps-from-context

Author: SamMorrowDrums

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)

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, " ")
+	}
+}

cmd/github-mcp-server/list_scopes.go

@@ -0,0 +1,291 @@
+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 := 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 {
+		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
+}