feat: Add list-scopes command to show required OAuth scopes #1487
+388
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Adds a new 'list-scopes' subcommand that outputs the required OAuth scopes for all enabled tools. This helps users determine what scopes their token needs to use specific tools. Features: - Respects all toolset configuration flags (--toolsets, --read-only) - Three output formats: text (default), json, summary - JSON output includes tools, unique_scopes, scopes_by_tool, tools_by_scope - Calculates accepted scopes (parent scopes that satisfy requirements) - Includes convenience wrapper script at script/list-scopes Usage examples: github-mcp-server list-scopes github-mcp-server list-scopes --toolsets=all --output=json github-mcp-server list-scopes --read-only --output=summary
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds a new list-scopes subcommand to help users determine which OAuth scopes their GitHub token needs to use specific tools. The command respects all toolset configuration flags and supports multiple output formats (text, json, summary).
Key changes:
- New CLI command that analyzes enabled toolsets and reports required OAuth scopes
- Calculates both required scopes and accepted parent scopes that satisfy requirements
- Three output formats for different use cases (human-readable, programmatic, and concise)
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| script/list-scopes | Shell wrapper script that builds and executes the list-scopes command with argument forwarding |
| cmd/github-mcp-server/list_scopes.go | Main implementation of the list-scopes subcommand including command definition, scope collection logic, and output formatting functions |
Comment on lines
+120
to
+128
| // Process enabled toolsets (same logic as server.go) | ||
| // If "all" is present, override all other toolsets | ||
| if github.ContainsToolset(enabledToolsets, github.ToolsetMetadataAll.ID) { | ||
| enabledToolsets = []string{github.ToolsetMetadataAll.ID} | ||
| } | ||
| // If "default" is present, expand to real toolset IDs | ||
| if github.ContainsToolset(enabledToolsets, github.ToolsetMetadataDefault.ID) { | ||
| enabledToolsets = github.AddDefaultToolset(enabledToolsets) | ||
| } |
There was a problem hiding this comment.
The toolset processing logic is missing a call to github.CleanToolsets() that exists in the stdio command (see internal/ghmcp/server.go line 102). This function:
- Removes whitespace from toolset names
- Removes duplicates
- Validates toolset names and identifies invalid ones
Without this, the command may behave inconsistently with the stdio command when users provide invalid or malformed toolset names. Add the CleanToolsets call before processing special keywords:
// Clean up the passed toolsets
enabledToolsets, invalidToolsets := github.CleanToolsets(enabledToolsets)
// Optionally warn about invalid toolsets (like server.go does)
if len(invalidToolsets) > 0 {
fmt.Fprintf(os.Stderr, "Invalid toolsets ignored: %s\n", strings.Join(invalidToolsets, ", "))
}
// If "all" is present, override all other toolsets
if github.ContainsToolset(enabledToolsets, github.ToolsetMetadataAll.ID) {
enabledToolsets = []string{github.ToolsetMetadataAll.ID}
}
// ...
Comment on lines
+182
to
+201
| acceptedScopeStrs := []string{} | ||
| for _, reqScope := range requiredScopes { | ||
| accepted := scopes.GetAcceptedScopes(reqScope) | ||
| for _, accScope := range accepted { | ||
| if accScope != reqScope { // Don't duplicate the required scope | ||
| accStr := accScope.String() | ||
| // Avoid duplicates | ||
| found := false | ||
| for _, existing := range acceptedScopeStrs { | ||
| if existing == accStr { | ||
| found = true | ||
| break | ||
| } | ||
| } | ||
| if !found { | ||
| acceptedScopeStrs = append(acceptedScopeStrs, accStr) | ||
| } | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
The manual deduplication of acceptedScopeStrs using nested loops is O(n²) and could be simplified for better maintainability and performance. Consider using a map for deduplication:
// Calculate accepted scopes (scopes that also satisfy the requirement due to hierarchy)
acceptedScopeMap := make(map[string]bool)
for _, reqScope := range requiredScopes {
accepted := scopes.GetAcceptedScopes(reqScope)
for _, accScope := range accepted {
if accScope != reqScope { // Don't duplicate the required scope
acceptedScopeMap[accScope.String()] = true
}
}
}
acceptedScopeStrs := make([]string, 0, len(acceptedScopeMap))
for scope := range acceptedScopeMap {
acceptedScopeStrs = append(acceptedScopeStrs, scope)
}
sort.Strings(acceptedScopeStrs)This approach is more efficient and clearer in intent.
Suggested change
| acceptedScopeStrs := []string{} | |
| for _, reqScope := range requiredScopes { | |
| accepted := scopes.GetAcceptedScopes(reqScope) | |
| for _, accScope := range accepted { | |
| if accScope != reqScope { // Don't duplicate the required scope | |
| accStr := accScope.String() | |
| // Avoid duplicates | |
| found := false | |
| for _, existing := range acceptedScopeStrs { | |
| if existing == accStr { | |
| found = true | |
| break | |
| } | |
| } | |
| if !found { | |
| acceptedScopeStrs = append(acceptedScopeStrs, accStr) | |
| } | |
| } | |
| } | |
| } | |
| // Calculate accepted scopes (scopes that also satisfy the requirement due to hierarchy) | |
| acceptedScopeMap := make(map[string]bool) | |
| for _, reqScope := range requiredScopes { | |
| accepted := scopes.GetAcceptedScopes(reqScope) | |
| for _, accScope := range accepted { | |
| if accScope != reqScope { // Don't duplicate the required scope | |
| acceptedScopeMap[accScope.String()] = true | |
| } | |
| } | |
| } | |
| acceptedScopeStrs := make([]string, 0, len(acceptedScopeMap)) | |
| for scope := range acceptedScopeMap { | |
| acceptedScopeStrs = append(acceptedScopeStrs, scope) | |
| } |
Comment on lines
+18
to
+24
| # 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 "$@" |
There was a problem hiding this comment.
[nitpick] The conditional build check may not detect all necessary rebuilds (e.g., when dependencies in other packages change). For consistency with other scripts like script/generate-docs, consider using go run instead:
exec go run ./cmd/github-mcp-server list-scopes "$@"This approach is simpler, always ensures up-to-date code execution, and aligns with the project's script patterns. The build time overhead is minimal (~1s according to the guidelines).
Suggested change
| # 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 "$@" | |
| # Always run the latest code, consistent with other scripts | |
| exec go run ./cmd/github-mcp-server list-scopes "$@" |
Collaborator
Author
|
Note: By default (without $ ./github-mcp-server list-scopes --output=summary
Required OAuth scopes for enabled tools:
(no scope required for public read access)
read:org
repo
Total: 3 unique scope(s)Compare this to all toolsets: $ ./github-mcp-server list-scopes --toolsets=all --output=summary
Required OAuth scopes for enabled tools:
(no scope required for public read access)
gist
notifications
project
public_repo
read:org
read:project
repo
security_events
Total: 9 unique scope(s)This matches the same default behavior as the |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new
list-scopessubcommand that outputs the required OAuth scopes for all enabled tools. This helps users determine what scopes their token needs to use specific tools.Part 3 of the OAuth scopes work:
Changes
cmd/github-mcp-server/list_scopes.go- new subcommandscript/list-scopes- convenience wrapper scriptFeatures
--toolsets,--read-only)text(default),json,summaryUsage Examples
Example Output
Testing
script/lint- 0 issuesscript/test- All tests pass