[SPIKE] Expand FGP per-tool permission annotations + consolidate docs

README.md

@@ -588,14 +588,16 @@ The following sets of tools are available:
 
 ## Tools
 
+> [!NOTE]
+> The fine-grained permission (and OAuth scope) each tool requires is documented separately to keep this listing readable. See [Fine-Grained Permission Filtering](./docs/permissions-filtering.md) for the full per-tool requirement table (useful when authenticating with a fine-grained PAT or GitHub App), and [PAT Scope Filtering](./docs/scope-filtering.md) for classic-PAT OAuth scopes.
+
 <!-- START AUTOMATED TOOLS -->
 <details>
 
 <summary><picture><source media="(prefers-color-scheme: dark)" srcset="pkg/octicons/icons/workflow-dark.png"><source media="(prefers-color-scheme: light)" srcset="pkg/octicons/icons/workflow-light.png"><img src="pkg/octicons/icons/workflow-light.png" width="20" height="20" alt="workflow"></picture> Actions</summary>
 
 - **actions_get** - Get details of GitHub Actions resources (workflows, workflow runs, jobs, and artifacts)
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `actions:read`
   - `method`: The method to execute (string, required)
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
@@ -608,7 +610,6 @@ The following sets of tools are available:
 
 - **actions_list** - List GitHub Actions workflows in a repository
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `actions:read`
   - `method`: The action to perform (string, required)
   - `owner`: Repository owner (string, required)
   - `page`: Page number for pagination (default: 1) (number, optional)
@@ -624,7 +625,6 @@ The following sets of tools are available:
 
 - **actions_run_trigger** - Trigger GitHub Actions workflow actions
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `actions:write`
   - `inputs`: Inputs the workflow accepts. Only used for 'run_workflow' method. (object, optional)
   - `method`: The method to execute (string, required)
   - `owner`: Repository owner (string, required)
@@ -635,7 +635,6 @@ The following sets of tools are available:
 
 - **get_job_logs** - Get GitHub Actions workflow job logs
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `actions:read`
   - `failed_only`: When true, gets logs for all failed jobs in the workflow run specified by run_id. Requires run_id to be provided. (boolean, optional)
   - `job_id`: The unique identifier of the workflow job. Required when getting logs for a single job. (number, optional)
   - `owner`: Repository owner (string, required)
@@ -653,15 +652,13 @@ The following sets of tools are available:
 - **get_code_scanning_alert** - Get code scanning alert
   - **Required OAuth Scopes**: `security_events`
   - **Accepted OAuth Scopes**: `repo`, `security_events`
-  - **Required Permissions (fine-grained)**: `security_events:read`
   - `alertNumber`: The number of the alert. (number, required)
   - `owner`: The owner of the repository. (string, required)
   - `repo`: The name of the repository. (string, required)
 
 - **list_code_scanning_alerts** - List code scanning alerts
   - **Required OAuth Scopes**: `security_events`
   - **Accepted OAuth Scopes**: `repo`, `security_events`
-  - **Required Permissions (fine-grained)**: `security_events:read`
   - `owner`: The owner of the repository. (string, required)
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
@@ -720,15 +717,13 @@ The following sets of tools are available:
 - **get_dependabot_alert** - Get dependabot alert
   - **Required OAuth Scopes**: `security_events`
   - **Accepted OAuth Scopes**: `repo`, `security_events`
-  - **Required Permissions (fine-grained)**: `vulnerability_alerts:read`
   - `alertNumber`: The number of the alert. (number, required)
   - `owner`: The owner of the repository. (string, required)
   - `repo`: The name of the repository. (string, required)
 
 - **list_dependabot_alerts** - List dependabot alerts
   - **Required OAuth Scopes**: `security_events`
   - **Accepted OAuth Scopes**: `repo`, `security_events`
-  - **Required Permissions (fine-grained)**: `vulnerability_alerts:read`
   - `after`: Cursor for pagination. Use the cursor from the previous response. (string, optional)
   - `owner`: The owner of the repository. (string, required)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
@@ -853,7 +848,6 @@ The following sets of tools are available:
 
 - **issue_read** - Get issue details
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `issues:read`
   - `issue_number`: The number of the issue (number, required)
   - `method`: The read operation to perform on a single issue.
     Options are:
@@ -869,7 +863,6 @@ The following sets of tools are available:
 
 - **issue_write** - Create or update issue/pull request
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `issues:write`
   - `assignees`: Usernames to assign to this issue (string[], optional)
   - `body`: Issue body content (string, optional)
   - `duplicate_of`: Issue number that this issue is a duplicate of. Only used when state_reason is 'duplicate'. (number, optional)
@@ -895,7 +888,6 @@ The following sets of tools are available:
 
 - **list_issues** - List issues
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `issues:read`
   - `after`: Cursor for pagination. Use the cursor from the previous response. (string, optional)
   - `direction`: Order direction. If provided, the 'orderBy' also needs to be provided. (string, optional)
   - `labels`: Filter by labels (string[], optional)
@@ -1098,7 +1090,6 @@ The following sets of tools are available:
 
 - **create_pull_request** - Open new pull request
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `pull_requests:write`
   - `base`: Branch to merge into (string, required)
   - `body`: PR description (string, optional)
   - `draft`: Create as draft PR (boolean, optional)
@@ -1110,7 +1101,6 @@ The following sets of tools are available:
 
 - **list_pull_requests** - List pull requests
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `pull_requests:read`
   - `base`: Filter by base branch (string, optional)
   - `direction`: Sort direction (string, optional)
   - `head`: Filter by head user/org and branch (string, optional)
@@ -1132,7 +1122,6 @@ The following sets of tools are available:
 
 - **pull_request_read** - Get details for a single pull request
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `pull_requests:read`
   - `after`: Cursor for pagination, used only by the get_review_comments method. Pass the endCursor from the previous page's PageInfo to fetch the next page. (string, optional)
   - `method`: Action to specify what pull request data needs to be retrieved from GitHub. 
     Possible options: 
@@ -1201,15 +1190,13 @@ The following sets of tools are available:
 
 - **create_branch** - Create branch
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `contents:write`
   - `branch`: Name for new branch (string, required)
   - `from_branch`: Source branch (defaults to repo default) (string, optional)
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
 
 - **create_or_update_file** - Create or update file
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `contents:write`
   - `branch`: Branch to create/update the file in (string, required)
   - `content`: Content of the file (string, required)
   - `message`: Commit message (string, required)
@@ -1251,7 +1238,6 @@ The following sets of tools are available:
 
 - **get_file_contents** - Get file or directory contents
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `contents:read`
   - `owner`: Repository owner (username or organization) (string, required)
   - `path`: Path to file/directory (string, optional)
   - `ref`: Accepts optional git refs such as `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head` (string, optional)
@@ -1277,15 +1263,13 @@ The following sets of tools are available:
 
 - **list_branches** - List branches
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `contents:read`
   - `owner`: Repository owner (string, required)
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `repo`: Repository name (string, required)
 
 - **list_commits** - List commits
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `contents:read`
   - `author`: Author username or email address to filter commits by (string, optional)
   - `owner`: Repository owner (string, required)
   - `page`: Page number for pagination (min 1) (number, optional)
@@ -1313,15 +1297,13 @@ The following sets of tools are available:
 
 - **list_tags** - List tags
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `contents:read`
   - `owner`: Repository owner (string, required)
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `repo`: Repository name (string, required)
 
 - **push_files** - Push files to repository
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `contents:write`
   - `branch`: Branch to push to (string, required)
   - `files`: Array of file objects to push, each object with path (string) and content (string) (object[], required)
   - `message`: Commit message (string, required)
@@ -1362,15 +1344,13 @@ The following sets of tools are available:
 - **get_secret_scanning_alert** - Get secret scanning alert
   - **Required OAuth Scopes**: `security_events`
   - **Accepted OAuth Scopes**: `repo`, `security_events`
-  - **Required Permissions (fine-grained)**: `secret_scanning_alerts:read`
   - `alertNumber`: The number of the alert. (number, required)
   - `owner`: The owner of the repository. (string, required)
   - `repo`: The name of the repository. (string, required)
 
 - **list_secret_scanning_alerts** - List secret scanning alerts
   - **Required OAuth Scopes**: `security_events`
   - **Accepted OAuth Scopes**: `repo`, `security_events`
-  - **Required Permissions (fine-grained)**: `secret_scanning_alerts:read`
   - `owner`: The owner of the repository. (string, required)
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)

cmd/github-mcp-server/generate_docs.go

@@ -230,10 +230,10 @@ func writeToolDoc(buf *strings.Builder, tool inventory.ServerTool) {
 		}
 	}
 
-	// Fine-grained permission requirement if present
-	if !tool.RequiredPermissions.IsZero() {
-		fmt.Fprintf(buf, "  - **Required Permissions (fine-grained)**: `%s`\n", tool.RequiredPermissions.String())
-	}
+	// Fine-grained permission requirements are intentionally NOT rendered per
+	// tool here: they would clutter the large tool listings. The consolidated
+	// requirement table lives in docs/permissions-filtering.md (generated by
+	// generatePermissionsTable), which the README links to.
 
 	// MCP App UI metadata (only rendered when the remote_mcp_ui_apps flag
 	// applied to the inventory; for the no-flags README this section is

docs/feature-flags.md

@@ -36,7 +36,6 @@ runtime behavior (such as output formatting) won't appear here.
 
 - **create_pull_request** - Open new pull request
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `pull_requests:write`
   - **MCP App UI**: `ui://github-mcp-server/pr-write`
   - `base`: Branch to merge into (string, required)
   - `body`: PR description (string, optional)
@@ -53,7 +52,6 @@ runtime behavior (such as output formatting) won't appear here.
 
 - **issue_write** - Create or update issue/pull request
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `issues:write`
   - **MCP App UI**: `ui://github-mcp-server/issue-write`
   - `assignees`: Usernames to assign to this issue (string[], optional)
   - `body`: Issue body content (string, optional)
@@ -77,7 +75,6 @@ runtime behavior (such as output formatting) won't appear here.
 
 - **issue_write** - Create or update issue/pull request
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `issues:write`
   - `assignees`: Usernames to assign to this issue (string[], optional)
   - `body`: Issue body content (string, optional)
   - `duplicate_of`: Issue number that this issue is a duplicate of. Only used when state_reason is 'duplicate'. (number, optional)
@@ -105,7 +102,6 @@ runtime behavior (such as output formatting) won't appear here.
 
 - **list_issues** - List issues
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `issues:read`
   - `after`: Cursor for pagination. Use the cursor from the previous response. (string, optional)
   - `direction`: Order direction. If provided, the 'orderBy' also needs to be provided. (string, optional)
   - `field_filters`: Filter by custom issue field values. Each entry takes a field_name and a value; the server looks up the field and coerces the value to its type (single-select option name, text, number, or YYYY-MM-DD date). (object[], optional)
@@ -129,7 +125,6 @@ runtime behavior (such as output formatting) won't appear here.
 
 - **create_issue** - Create Issue
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `issues:write`
   - `body`: Issue body content (optional) (string, optional)
   - `owner`: Repository owner (username or organization) (string, required)
   - `repo`: Repository name (string, required)

docs/insiders-features.md

@@ -30,7 +30,6 @@ The list below is generated from the Go source. It covers tool **inventory and s
 
 - **create_pull_request** - Open new pull request
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `pull_requests:write`
   - **MCP App UI**: `ui://github-mcp-server/pr-write`
   - `base`: Branch to merge into (string, required)
   - `body`: PR description (string, optional)
@@ -47,7 +46,6 @@ The list below is generated from the Go source. It covers tool **inventory and s
 
 - **issue_write** - Create or update issue/pull request
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `issues:write`
   - **MCP App UI**: `ui://github-mcp-server/issue-write`
   - `assignees`: Usernames to assign to this issue (string[], optional)
   - `body`: Issue body content (string, optional)
@@ -71,7 +69,6 @@ The list below is generated from the Go source. It covers tool **inventory and s
 
 - **issue_write** - Create or update issue/pull request
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `issues:write`
   - `assignees`: Usernames to assign to this issue (string[], optional)
   - `body`: Issue body content (string, optional)
   - `duplicate_of`: Issue number that this issue is a duplicate of. Only used when state_reason is 'duplicate'. (number, optional)
@@ -99,7 +96,6 @@ The list below is generated from the Go source. It covers tool **inventory and s
 
 - **list_issues** - List issues
   - **Required OAuth Scopes**: `repo`
-  - **Required Permissions (fine-grained)**: `issues:read`
   - `after`: Cursor for pagination. Use the cursor from the previous response. (string, optional)
   - `direction`: Order direction. If provided, the 'orderBy' also needs to be provided. (string, optional)
   - `field_filters`: Filter by custom issue field values. Each entry takes a field_name and a value; the server looks up the field and coerces the value to its type (single-select option name, text, number, or YYYY-MM-DD date). (object[], optional)

docs/permissions-filtering.md

@@ -57,23 +57,55 @@ The generated table below is produced by `script/generate-docs` and lists every
 | `actions` | `get_job_logs` | `actions:read` |
 | `code_security` | `get_code_scanning_alert` | `security_events:read` |
 | `code_security` | `list_code_scanning_alerts` | `security_events:read` |
+| `context` | `get_team_members` | `members:read` |
+| `context` | `get_teams` | `members:read` |
 | `dependabot` | `get_dependabot_alert` | `vulnerability_alerts:read` |
 | `dependabot` | `list_dependabot_alerts` | `vulnerability_alerts:read` |
+| `discussions` | `discussion_comment_write` | `discussions:write` |
+| `discussions` | `get_discussion_comments` | `discussions:read` |
+| `discussions` | `get_discussion` | `discussions:read` |
+| `discussions` | `list_discussion_categories` | `discussions:read` |
+| `discussions` | `list_discussions` | `discussions:read` |
+| `git` | `get_repository_tree` | `contents:read` |
+| `issues` | `add_issue_comment` | `issues:write` |
+| `issues` | `get_label` | `issues:read` |
 | `issues` | `issue_read` | `issues:read` |
 | `issues` | `issue_write` | `issues:write` |
 | `issues` | `list_issues` | `issues:read` |
+| `issues` | `sub_issue_write` | `issues:write` |
+| `labels` | `get_label` | `issues:read` |
+| `labels` | `label_write` | `issues:write` |
+| `labels` | `list_label` | `issues:read` |
+| `pull_requests` | `add_comment_to_pending_review` | `pull_requests:write` |
+| `pull_requests` | `add_reply_to_pull_request_comment` | `pull_requests:write` |
 | `pull_requests` | `create_pull_request` | `pull_requests:write` |
 | `pull_requests` | `list_pull_requests` | `pull_requests:read` |
+| `pull_requests` | `merge_pull_request` | `contents:write` |
 | `pull_requests` | `pull_request_read` | `pull_requests:read` |
+| `pull_requests` | `pull_request_review_write` | `pull_requests:write` |
+| `pull_requests` | `update_pull_request_branch` | `pull_requests:write` |
+| `pull_requests` | `update_pull_request` | `pull_requests:write` |
 | `repos` | `create_branch` | `contents:write` |
 | `repos` | `create_or_update_file` | `contents:write` |
+| `repos` | `create_repository` | `administration:write` |
+| `repos` | `delete_file` | `contents:write` |
+| `repos` | `fork_repository` | `administration:write AND contents:read` |
+| `repos` | `get_commit` | `contents:read` |
 | `repos` | `get_file_contents` | `contents:read` |
+| `repos` | `get_latest_release` | `contents:read` |
+| `repos` | `get_release_by_tag` | `contents:read` |
+| `repos` | `get_tag` | `contents:read` |
 | `repos` | `list_branches` | `contents:read` |
 | `repos` | `list_commits` | `contents:read` |
+| `repos` | `list_releases` | `contents:read` |
+| `repos` | `list_repository_collaborators` | `metadata:read` |
 | `repos` | `list_tags` | `contents:read` |
 | `repos` | `push_files` | `contents:write` |
 | `secret_protection` | `get_secret_scanning_alert` | `secret_scanning_alerts:read` |
 | `secret_protection` | `list_secret_scanning_alerts` | `secret_scanning_alerts:read` |
+| `stargazers` | `list_starred_repositories` | `starring:read` |
+| `stargazers` | `star_repository` | `starring:write` |
+| `stargazers` | `unstar_repository` | `starring:write` |
 <!-- END AUTOMATED PERMISSIONS -->
 
 ## Related Documentation

pkg/github/context_tools.go

@@ -8,6 +8,7 @@ import (
 	ghErrors "github.com/github/github-mcp-server/pkg/errors"
 	"github.com/github/github-mcp-server/pkg/ifc"
 	"github.com/github/github-mcp-server/pkg/inventory"
+	"github.com/github/github-mcp-server/pkg/permissions"
 	"github.com/github/github-mcp-server/pkg/scopes"
 	"github.com/github/github-mcp-server/pkg/translations"
 	"github.com/github/github-mcp-server/pkg/utils"
@@ -223,7 +224,7 @@ func GetTeams(t translations.TranslationHelperFunc) inventory.ServerTool {
 			result = attachStaticIFCLabel(ctx, deps, result, ifc.LabelTeam())
 			return result, nil, nil
 		},
-	)
+	).WithPermissions(permissions.Require(permissions.Members.Read()))
 }
 
 func GetTeamMembers(t translations.TranslationHelperFunc) inventory.ServerTool {
@@ -299,5 +300,5 @@ func GetTeamMembers(t translations.TranslationHelperFunc) inventory.ServerTool {
 			result = attachStaticIFCLabel(ctx, deps, result, ifc.LabelTeam())
 			return result, nil, nil
 		},
-	)
+	).WithPermissions(permissions.Require(permissions.Members.Read()))
 }