Uh oh!
There was an error while loading. Please reload this page.
feat: Add OAuth scopes to tool metadata (Phase 1) - #1485
Closed
SamMorrowDrums wants to merge 7 commits into
Closed
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR implements Phase 1 of OAuth scope support by adding scope metadata to all MCP tools, enabling clients to determine required permissions before making tool calls.
Key Changes:
- New
pkg/scopespackage with OAuth scope constants, hierarchy definitions, and utility functions for scope validation - Added
Meta: scopes.WithScopes(...)to ~90 MCP tools across the codebase with appropriate scope assignments - Updated documentation generation to include scope information in README
- All toolsnaps updated with
_meta.requiredOAuthScopesfield
Reviewed changes
Copilot reviewed 113 out of 113 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| pkg/scopes/scopes.go | New package defining OAuth scopes, hierarchy, and utility functions (MetaKey, WithScopes, GetScopesFromMeta, ScopeIncludes, HasRequiredScopes, GetAcceptedScopes) |
| pkg/scopes/scopes_test.go | Comprehensive test coverage for all scope utilities including hierarchy checks and metadata handling |
| pkg/github/*.go (multiple files) | Added scope metadata to tools - repo for most operations, security_events for security features, notifications for notification tools, gist for gist writes, read:org/project for reads, NoScope for public access |
| pkg/github/toolsnaps/*.snap (many files) | Added _meta.requiredOAuthScopes arrays to all tool snapshots |
| cmd/github-mcp-server/generate_docs.go | Enhanced doc generation to append scope information (e.g., "(scopes: `repo`)") to tool descriptions |
| README.md | Updated with scope annotations for all tools in documentation |
Comment on lines
+153
to
+176
| // GetAcceptedScopes returns all scopes that satisfy the given required scope. | ||
| // This includes the scope itself plus any parent scopes that include it. | ||
| func GetAcceptedScopes(required Scope) []Scope { | ||
| accepted := []Scope{required} | ||
| // Find all scopes that include the required scope | ||
| for parent, children := range ScopeHierarchy { | ||
| for _, child := range children { | ||
| if child == required { | ||
| accepted = append(accepted, parent) | ||
| // Also check if this parent is included by another scope | ||
| for grandparent, grandchildren := range ScopeHierarchy { | ||
| for _, gc := range grandchildren { | ||
| if gc == parent { | ||
| accepted = append(accepted, grandparent) | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| return accepted | ||
| } |
There was a problem hiding this comment.
[nitpick] The GetAcceptedScopes function only handles up to 2 levels of hierarchy (parent and grandparent) using nested loops, while ScopeIncludes properly handles arbitrary depth using recursion. Although this works for the current GitHub OAuth scope hierarchy (which has at most 3 levels), consider refactoring to use recursion for consistency and future-proofing:
funcGetAcceptedScopes(requiredScope) []Scope {
accepted:= []Scope{required}
seen:=make(map[Scope]bool)
seen[required] =true// Recursively find all parent scopesvarfindParentsfunc(Scope)
findParents=func(childScope) {
forparent, children:=rangeScopeHierarchy {
for_, c:=rangechildren {
ifc==child&&!seen[parent] {
seen[parent] =trueaccepted=append(accepted, parent)
findParents(parent) // Recursively find parents of this parent
}
}
}
}
findParents(required)
returnaccepted
}This approach would handle hierarchies of any depth and avoid potential issues if the scope hierarchy is extended in the future.
This was referenced Nov 25, 2025
SamMorrowDrumsforce-pushed
the
SamMorrowDrums/oauth-scopes
branch
9 times, most recently
from
December 13, 2025 00:13
51fef26 to
ee31dc6Compare- Add pkg/scopes package with OAuth scope constants and utilities - Add scopes to all ~90 tool definitions using mcp.Tool.Meta field - Update generate_docs.go to include scopes in README output - Add comprehensive test coverage for scopes package - Update all toolsnaps to include _meta.requiredOAuthScopes Scope assignments follow GitHub OAuth app documentation: - repo: Most repository operations (private repos) - public_repo: Star/unstar operations - notifications: Notification operations - gist: Gist write operations - security_events: Code scanning, dependabot, secret scanning - project/read:project: Project operations - read:org: Organization/team read operations - No scope: Public read operations (get_me, list_gists)
SamMorrowDrumsforce-pushed
the
SamMorrowDrums/oauth-scopes
branch
from
December 13, 2025 00:22
ee31dc6 to
c6f31f3CompareAdd a new constructor that creates a ToolsetGroup from a list of ServerTools. Tools are automatically categorized as read or write based on their ReadOnlyHint annotation, and grouped into toolsets based on the 'toolset' field in their Meta. This enables tools to be fully self-describing - registration can now derive toolset membership and read/write classification directly from the tool definition.
…roupFromTools - Move ToolsetMetadata type to toolsets package with alias in github package - Update NewToolMeta to accept ToolsetMetadata instead of string - Update NewToolsetGroupFromTools to accept []ToolsetMetadata slice - Remove need for .ID when calling NewToolMeta (e.g., NewToolMeta(ToolsetMetadataRepos) instead of NewToolMeta(ToolsetMetadataRepos.ID))
Add ToolsetRegistry struct that holds toolset definitions and tools, with a NewToolsetGroup method that accepts ToolsetGroupConfig: - ReadOnly: restricts to read-only tools - ActiveToolsets: which toolsets to enable - AvailableScopes: filter tools by OAuth scope requirements - nil: no scope checking (all tools available) - []: empty means no scopes (only tools with no requirements) - [...]: tools must have required scopes in the list This enables dynamic tool filtering based on the user's actual OAuth token scopes, ensuring only authorized tools are exposed.
Refactor DefaultToolsetGroup to use the new ToolsetRegistry pattern: - Add NewDefaultToolsetRegistry() that creates a registry with all tools - Tools are now self-describing (toolset + read/write from metadata) - No more manual AddReadTools/AddWriteTools categorization - DefaultToolsetGroup uses the registry with ToolsetGroupConfig - Resource templates and prompts handled separately (not tools) This enables scope-aware tool filtering when creating ToolsetGroups.
The function returns toolset metadata, not tools. Renamed for clarity and simplified the toolset collection code per staticcheck suggestion.
- Add Meta field with toolset info to all resource templates and prompts - Create NewResourceMeta and NewPromptMeta helpers - Extend ToolsetRegistry to accept resources and prompts via WithResourceTemplates/WithPrompts - Registry now automatically distributes resources/prompts to correct toolsets - Remove addResourceTemplatesAndPrompts helper (no longer needed)
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
Sign up for freeto 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
This PR adds OAuth scope metadata to all MCP tools, enabling clients to know which scopes are required for each tool before calling them.
Changes
New Package:
pkg/scopesscopes.go: OAuth scope constants based on GitHub's OAuth app scopes documentationScopetype with constants for all GitHub OAuth scopes (Repo,PublicRepo,Notifications,Gist,SecurityEvents,Project,ReadProject,ReadOrg, etc.)ScopeHierarchymap defining parent-child relationships (e.g.,repoincludespublic_repo,security_events, etc.)WithScopes()helper to createmcp.Tool.MetamapsGetScopesFromMeta()to extract scopes from tool metadataScopeIncludes(),HasRequiredScopes()for scope checkingscopes_test.go: Comprehensive test coverage for all utilitiesTool Updates (~90 tools)
Added
Meta: scopes.WithScopes(...)to all tool definitions:repopublic_repostar_repository,unstar_repositorynotificationsgistcreate_gist,update_gistsecurity_eventsprojectread:projectread:orgget_teams,get_team_members,list_issue_typesget_me,list_gists,get_gist(public reads)Documentation Updates
generate_docs.go: Updated to include scope information in README output(scopes: \repo`)` after each tool description_meta.requiredOAuthScopesarrayTesting
pkg/scopes/scopes_test.gowith tests for:TestScopeString- Scope string conversionTestScopeIncludes- Hierarchy checkingTestHasRequiredScopes- Multiple scope validationTestWithScopes- Meta map creationTestGetScopesFromMeta- Meta extractionTestGetAcceptedScopes- Parent scope lookupTestScopeStringsAndParseScopes- Round-trip conversionPart of OAuth Scopes Work (Phase 1 of 4)