feat: Add fine-grained permissions support and tool permissions docs (Phase 2) #1486
+12,912
−8,596
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
…ents and return values.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…cp-server into omgitsads/go-sdk
We should do this eventually, but to keep the existing behavior, we just return the error to the client.
Co-authored-by: SamMorrowDrums <4811358+SamMorrowDrums@users.noreply.github.com>
…cp-server into omgitsads/go-sdk
- Update imports from mark3labs/mcp-go to modelcontextprotocol/go-sdk - Update setupMCPClient to use CommandTransport and NewInMemoryTransports - Convert CallToolRequest usage to CallToolParams inline style - Update type assertions to use pointer types (*mcp.TextContent, etc.) - Update tool slice type to []*mcp.Tool - Update EmbeddedResource.Resource access (now *ResourceContents, not interface) - Update consolidated tool names (issue_write, issue_read, pull_request_read, pull_request_review_write) - Fix go-github v79 CreateTag/CreateRef API changes - Fix commitId -> commitID naming convention - Default to 'all' toolsets for comprehensive testing
…ommentSubmit - Fix TestDirectoryDeletion: Create file in test-dir/ subdirectory to match expected filename assertion - Fix TestDirectoryDeletion: Search for deletion commit by message instead of assuming first commit in list (order can vary) - Fix TestPullRequestReviewCommentSubmit: Relax assertion from exactly 3 comments to at least 2 (FILE-level comments may not be returned by ListReviewComments API)
The side parameter is required for review comments but FILE-level comments still don't appear in ListReviewComments API results.
- FILE-level review comments: Document that they are silently dropped by GitHub API under certain conditions and the test doesn't fully verify them - Directory deletion: Document that the test only deletes a single file in a subdirectory, not actual recursive directory deletion
The e2e tests were migrated to modelcontextprotocol/go-sdk, so the old SDK and its transitive dependencies are no longer needed.
- 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)
Phase 2 of OAuth scopes work: - Extend pkg/scopes package with fine-grained permission types: - Permission type with constants (actions, contents, issues, etc.) - PermissionLevel type (read, write, admin) - FineGrainedPermission struct and helper functions - WithScopesAndPermissions(), AddPermissions(), GetPermissionsFromMeta() - ReadPerm(), WritePerm(), AdminPerm() convenience functions - Create comprehensive docs/tool-permissions.md: - OAuth scope hierarchy reference - Fine-grained permission levels explanation - Tool-by-category permission tables for all ~90 tools - Minimum required scopes by use case - Notes about limitations and special cases - Update README.md with links to permissions docs: - Link in Prerequisites section for PAT creation - Callout note before Tools section - Add tests for all new fine-grained permission functionality
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive support for fine-grained personal access token permissions alongside existing OAuth scope support, and provides detailed documentation to help users understand authentication requirements for each tool.
Key Changes:
- Extended the scopes package with fine-grained permission types, levels, and utility functions
- Created comprehensive tool permissions documentation mapping 100+ tools to their required OAuth scopes and fine-grained permissions
- Updated README to link to the new permissions documentation
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
pkg/scopes/scopes.go |
Added fine-grained permission types (Permission, PermissionLevel, FineGrainedPermission) with 20+ permission constants, and 7 new functions for working with permissions in tool metadata |
pkg/scopes/scopes_test.go |
Added 5 comprehensive test functions covering all new permission functionality including helper functions, metadata operations, and edge cases |
docs/tool-permissions.md |
Created new 312-line documentation file organizing all tools by category with OAuth scopes and fine-grained permissions, plus permission hierarchy explanations and use-case guides |
README.md |
Added two strategic links to the new tool permissions documentation in the Prerequisites and Tools sections |
This was referenced Nov 25, 2025
SamMorrowDrums
force-pushed
the
SamMorrowDrums/oauth-scopes
branch
10 times, most recently
from
ee31dc6 to
c6f31f3
Compare
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
This PR adds fine-grained permission types to the scopes package and creates comprehensive tool permissions documentation.
Changes
Extended
pkg/scopes/scopes.goAdded support for fine-grained personal access token permissions:
New Types:
Permission- Fine-grained permission constants (e.g.,PermActions,PermContents,PermIssues,PermPullRequests)PermissionLevel- Access levels (PermissionRead,PermissionWrite,PermissionAdmin)FineGrainedPermission- Struct combining permission and levelNew Functions:
WithScopesAndPermissions()- Create Meta with both OAuth scopes and fine-grained permissionsAddPermissions()- Add permissions to existing Meta mapGetPermissionsFromMeta()- Extract permissions from tool MetaReadPerm(),WritePerm(),AdminPerm()- Convenience constructorsPerm()- General permission constructorNew
docs/tool-permissions.mdComprehensive documentation covering:
Categories documented:
Updated README.md
Added links to the new permissions documentation:
Testing
TestFineGrainedPermissionStringTestWithScopesAndPermissionsTestAddPermissionsTestAddPermissionsToNilMetaTestGetPermissionsFromMetaTestPermHelperFunctionsPart of OAuth Scopes Work (Phase 2 of 4)