- Notifications
You must be signed in to change notification settings - Fork3.3k
Add OAuth scope metadata to all MCP tools#1679
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
base:main
Are you sure you want to change the base?
Uh oh!
There was an error while loading.Please reload this page.
Conversation
- Created pkg/scopes package with OAuth scope constants- Added RequiredScopes and AcceptedScopes fields to ServerTool- Added NewToolWithScopes helpers in dependencies.go- Updated context tools (get_me, get_teams, get_team_members) with scopesCo-authored-by: SamMorrowDrums <4811358+SamMorrowDrums@users.noreply.github.com>
- Updated 60+ tools with required and accepted OAuth scopes- Added scopes to: gists, git, notifications, projects, code scanning, dependabot, secret scanning, security advisories, actions, discussions, issues (partial), labels, pull requests (partial), repositories (partial), search (partial)- Remaining: ~20 tools in issues, pullrequests, repositories, and search filesCo-authored-by: SamMorrowDrums <4811358+SamMorrowDrums@users.noreply.github.com>
- Updated all remaining tools with OAuth scope information- Added scope documentation generation to generate-docs command- Documentation now shows Required and Accepted OAuth scopes for each tool- All 100+ tools now have scope information defined- Tests pass, linter passes, documentation generated successfullyCo-authored-by: SamMorrowDrums <4811358+SamMorrowDrums@users.noreply.github.com>
SamMorrowDrums left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
@copilot this is pretty great, but let's only show accepted scopes where they differ, we generally want to omit those.
Also now all the changes are made you don't need NewToolWithScopes and can simply replace NewTool as all new tools should have explicitly require no scopes rather than having a different constructors.
- Replace NewToolWithScopes with updated NewTool that includes scope parameters- All tools now use the same constructor with explicit scope requirements- Documentation only shows accepted scopes when they differ from required- Removed NewToolWithScopes and NewToolFromHandlerWithScopes helper functionsCo-authored-by: SamMorrowDrums <4811358+SamMorrowDrums@users.noreply.github.com>
Done in commit29e9374. Changes made:
Examples from the generated documentation:
|
Uh oh!
There was an error while loading.Please reload this page.
Summary
Added OAuth scope requirements to all 100+ MCP tools and automated scope documentation generation with conditional display logic.
Why
Enables users and systems to understand OAuth permission requirements for each tool. Prepares infrastructure for future scope validation logic.
What changed
pkg/scopespackage with typed OAuth scope constants (Repo,Gist,Notifications,ReadOrg,WriteOrg,AdminOrg,ReadProject,Project,SecurityEvents,PublicRepo)ServerToolstruct withRequiredScopesandAcceptedScopesstring slicesNewToolandNewToolFromHandlerto include scope parameters (all tools use same constructor)generate-docscommand to display scopes in tool documentationScope mapping examples:
get_me: no scopes required (public user data) - no scope info shownget_teams: requiresread:org, acceptsread:org,write:org,admin:org- shows bothcreate_gist: requiresgist, acceptsgist- only shows requiredstar_repository: requirespublic_repo, acceptspublic_repo,repo- shows bothrepo, acceptrepo- only shows requiredsecurity_events, acceptsecurity_events,repo- shows bothMCP impact
Prompts tested (tool changes only)
Security / limits
Tool renaming
Lint & tests
./script/lint./script/testDocs
Original prompt
I added a bunch of PRs in order to enable oauth scopes to be documented and available for end users.
Can you add per tool scope information provided for the server tools, and added to documentation using the new arch where tools are self defining. It should be small changes with current arch even though it is going to touch every tool definition. Maybe the available scopes should also be a typed set of string constants with a scopes package that can be used on remote server also.
We need both required and accepted scopes due to hierarchy and scopes getting rolled up, but for now just edit tools and document. Later we'll add logic.
Here's the tool scope's mapping:
{
"get_me": {
"required_scopes": {},
"accepted_scopes": {}
},
"get_teams": {
"required_scopes": {"read:org": true},
"accepted_scopes": {"read:org": true, "write:org": true, "admin:org": true}
},
"get_team_members": {
"required_scopes": {"read:org": true},
"accepted_scopes": {"read:org": true, "write:org": true, "admin:org": true}
},
"list_issue_types": {
"required_scopes": {"read:org": true},
"accepted_scopes": {"read:org": true, "write:org": true, "admin:org": true}
},
"list_gists": {
"required_scopes": {},
"accepted_scopes": {}
},
"get_gist": {
"required_scopes": {},
"accepted_scopes": {}
},
"create_gist": {
"required_scopes": {"gist": true},
"accepted_scopes": {"gist": true}
},
"update_gist": {
"required_scopes": {"gist": true},
"accepted_scopes": {"gist": true}
},
"list_notifications": {
"required_scopes": {"notifications": true},
"accepted_scopes": {"notifications": true}
},
"dismiss_notification": {
"required_scopes": {"notifications": true},
"accepted_scopes": {"notifications": true}
},
"get_notification_details": {
"required_scopes": {"notifications": true},
"accepted_scopes": {"notifications": true}
},
"manage_notification_subscription": {
"required_scopes": {"notifications": true},
"accepted_scopes": {"notifications": true}
},
"manage_repository_notification_subscription": {
"required_scopes": {"notifications": true},
"accepted_scopes": {"notifications": true}
},
"mark_all_notifications_read": {
"required_scopes": {"notifications": true},
"accepted_scopes": {"notifications": true}
},
"star_repository": {
"required_scopes": {"public_repo": true},
"accepted_scopes": {"public_repo": true, "repo": true}
},
"unstar_repository": {
"required_scopes": {"public_repo": true},
"accepted_scopes": {"public_repo": true, "repo": true}
},
"get_project": {
"required_scopes": {"read:project": true},
"accepted_scopes": {"read:project": true, "project": true}
},
"get_project_field": {
"required_scopes": {"read:project": true},
"accepted_scopes": {"read:project": true, "project": true}
},
"get_project_item": {
"required_scopes": {"read:project": true},
"accepted_scopes": {"read:project": true, "project": true}
},
"list_project_fields": {
"required_scopes": {"read:project": true},
"accepted_scopes": {"read:project": true, "project": true}
},
"list_project_items": {
"required_scopes": {"read:project": true},
"accepted_scopes": {"read:project": true, "project": true}
},
"list_projects": {
"required_scopes": {"read:project": true},
"accepted_scopes": {"read:project": true, "project": true}
},
"add_project_item": {
"required_scopes": {"project": true},
"accepted_scopes": {"project": true}
},
"delete_project_item": {
"required_scopes": {"project": true},
"accepted_scopes": {"project": true}
},
"update_project_item": {
"required_scopes": {"project": true},
"accepted_scopes": {"project": true}
},
"get_code_scanning_alert": {
"required_scopes": {"security_events": true},
"accepted_scopes": {"security_events": true, "repo": true}
},
"list_code_scanning_alerts": {
"required_scopes": {"security_events": true},
"accepted_scopes": {"security_events": true, "repo": true}
},
"get_dependabot_alert": {
"required_scopes": {"security_events": true},
"accepted_scopes": {"security_events": true, "repo": true}
},
"list_dependabot_alerts": {
"required_scopes": {"security_events": true},
"accepted_scopes": {"security_events": true, "repo": true}
},
"get_secret_scanning_alert": {
"required_scopes": {"security_events": true},
"accepted_scopes": {"security_events": true, "repo": true}
},
"list_secret_scanning_alerts": {
"required_scopes": {"security_events": true},
"accepted_scopes": {"security_events": true, "repo": true}
},
"get_global_security_advisory": {
"required_scopes": {"security_events": true},
"accepted_scopes": {"security_events": true, "repo": true}
},
"list_global_security_advisories": {
"required_scopes": {"security_events": true},
"accepted_scopes": {"security_events": true, "r...
💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn moreCopilot coding agent tips in the docs.