Skip to content

[SPIKE] Add declarative fine-grained permission (FGP) requirement subsystem #2676

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.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
SamMorrowDrums wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

[SPIKE] Add declarative fine-grained permission (FGP) requirement subsystem #2676

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -398,6 +398,10 @@ docker run -it --rm ghcr.io/github/github-mcp-server tool-search "issue" --max-r
github-mcp-server tool-search "issue" --max-results 5
```

- `github-mcp-server list-scopes` lists the OAuth scopes each enabled tool requires. See [PAT Scope Filtering](./docs/scope-filtering.md).
- `github-mcp-server list-permissions` lists the fine-grained permission each enabled tool requires. See [Fine-Grained Permission Filtering](./docs/permissions-filtering.md).


## Tool Configuration

The GitHub MCP Server supports enabling or disabling specific groups of functionalities via the `--toolsets` flag. This allows you to control which GitHub API capabilities are available to your AI tools. Enabling only the toolsets that you need can help the LLM with tool choice and reduce the context size.
Expand Down Expand Up @@ -591,6 +595,7 @@ The following sets of tools are available:

- **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)
Expand All @@ -603,6 +608,7 @@ 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)
Expand All @@ -618,6 +624,7 @@ 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)
Expand All @@ -628,6 +635,7 @@ 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)
Expand All @@ -645,13 +653,15 @@ 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)
Expand Down Expand Up @@ -710,13 +720,15 @@ 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)
Expand Down Expand Up @@ -841,6 +853,7 @@ 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:
Expand All @@ -856,6 +869,7 @@ 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)
Expand All @@ -881,6 +895,7 @@ 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)
Expand Down Expand Up @@ -1083,6 +1098,7 @@ 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)
Expand All @@ -1094,6 +1110,7 @@ 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)
Expand All @@ -1115,6 +1132,7 @@ 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:
Expand Down Expand Up @@ -1183,13 +1201,15 @@ 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)
Expand Down Expand Up @@ -1231,6 +1251,7 @@ 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)
Expand All @@ -1256,13 +1277,15 @@ 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)
Expand Down Expand Up @@ -1290,13 +1313,15 @@ 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)
Expand Down Expand Up @@ -1337,13 +1362,15 @@ 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)
Expand Down
65 changes: 65 additions & 0 deletions cmd/github-mcp-server/generate_docs.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ func generateAllDocs() error {
{"docs/insiders-features.md", generateInsidersFeaturesDocs},
{"docs/feature-flags.md", generateFeatureFlagsDocs},
{"docs/tool-renaming.md", generateDeprecatedAliasesDocs},
{"docs/permissions-filtering.md", generatePermissionsDocs},
} {
if err := doc.fn(doc.path); err != nil {
return fmt.Errorf("failed to generate docs for %s: %w", doc.path, err)
Expand Down Expand Up @@ -229,6 +230,11 @@ 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())
}

// 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
// stripped by inventory.ToolsForRegistration before rendering).
Expand Down Expand Up @@ -499,3 +505,62 @@ func generateDeprecatedAliasesTable() string {

return buf.String()
}

func generatePermissionsDocs(docsPath string) error {
// Read the current file
content, err := os.ReadFile(docsPath) //#nosec G304
if err != nil {
return fmt.Errorf("failed to read docs file: %w", err)
}

// Replace content between markers
updatedContent, err := replaceSection(string(content), "START AUTOMATED PERMISSIONS", "END AUTOMATED PERMISSIONS", generatePermissionsTable())
if err != nil {
return err
}

// Write back to file
if err := os.WriteFile(docsPath, []byte(updatedContent), 0600); err != nil {
return fmt.Errorf("failed to write permissions docs: %w", err)
}

return nil
}

// generatePermissionsTable renders the tool -> fine-grained permission requirement
// table for the default (no-flags) tool inventory. Only tools with a non-zero
// RequiredPermissions are listed; everything else is ungated and always shown.
func generatePermissionsTable() string {
t, _ := translations.TranslationHelper()

// Mirror generateReadmeDocs: document the default, no-flags experience.
r, _ := github.NewInventory(t).
WithToolsets([]string{"all"}).
WithFeatureChecker(noFeatureFlagsChecker).
Build()

var buf strings.Builder
buf.WriteString("| Toolset | Tool | Required Permissions (fine-grained) |\n")
buf.WriteString("|---------|------|-------------------------------------|\n")

// ToolsForRegistration applies the same feature-flag filtering as the
// README so flag-gated duplicates (e.g. list_issues) don't appear twice.
tools := r.ToolsForRegistration(context.Background())
var rows []string
for _, tool := range tools {
if tool.RequiredPermissions.IsZero() {
continue
}
rows = append(rows, fmt.Sprintf("| `%s` | `%s` | `%s` |",
tool.Toolset.ID, tool.Tool.Name, tool.RequiredPermissions.String()))
}
sort.Strings(rows)

if len(rows) == 0 {
buf.WriteString("| *(none currently)* | | |")
return buf.String()
}

buf.WriteString(strings.Join(rows, "\n"))
return buf.String()
}
Loading
Loading