Add compare-scopes command to validate PAT permissions against tool requirements

[Copilot]

Summary

Adds a compare-scopes command that fetches a PAT's OAuth scopes and compares them against all tool requirements, reporting missing permissions and affected tools.

Why

Users need to validate their PAT has required scopes before tools fail at runtime. This enables proactive permission checks and CI validation.

What changed

• Added compare-scopes CLI command using existing scopes.Fetcher and inventory infrastructure
• Created script/compare-scopes convenience wrapper with error handling
• Command displays token scopes, required scopes, missing scopes, and lists affected tools per missing scope
• Returns exit code 1 when scopes are missing (CI-friendly)
• Supports GITHUB_PERSONAL_ACCESS_TOKEN env var and --gh-host flag for GHES

Usage:

GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx script/compare-scopes

Example output:

=== PAT Scope Comparison ===

Token Scopes:
  - gist
  - read:org
  - repo

Required Scopes (by tools):
  - gist
  - notifications
  - project
  - read:org
  - repo

=== Comparison Summary ===

Missing Scopes (required by tools but not granted to token):
  - notifications
    Tools affected: dismiss_notification, list_notifications, ... and 3 more
  - project
    Tools affected: add_project_item, delete_project_item, projects_write

Warning: Some tools may not be available due to missing scopes.

MCP impact

• No tool or API changes

Security / limits

• No security or limits impact

Tool renaming

• I am not renaming tools as part of this PR

Lint & tests

• Linted locally with ./script/lint
• Tested locally with ./script/test

Docs

• Updated (README / docs / examples)
  • Added detailed usage guide in docs/scope-filtering.md
  • Added quick reference tip in README Token Security section

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/
  • Triggering command: ./github-mcp-server ./github-mcp-server compare-scopes race -buildid QqJvTexPQ_LdGmMwQDJr/QqJvTexPQ_LdGmMwQDJr -dwarf=false -goversion go1.24.11 -c=4 -race -nolocalimports -importcfg GoFi�� x64/src/runtime/-errorsas om/stretchr/test-ifaceassert (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Create a stacked pull request on top of #1750 that adds a new helper to compare a user-provided PAT’s scopes with the scopes required by the MCP server tools.

Requirements:

• Extend the existing script/list-scopes inventory-based command suite introduced in PR feat: Add list-scopes command using inventory architecture #1750 to accept a Personal Access Token (PAT) as input (via an env var like GITHUB_PERSONAL_ACCESS_TOKEN or a CLI flag) and fetch the token’s granted scopes using:

curl -sI -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
  https://api.github.com/user | grep -i x-oauth-scopes

• Parse and display the PAT’s scopes in a readable list (one per line or comma-separated) as part of the command output.
• Invoke the existing list-scopes.sh (which lists scopes requested by the server/tools) and print those scopes alongside the PAT scopes, clearly labeled.
• Provide a concise comparison summary highlighting scopes that are missing from the PAT but required by tools (and optionally extra scopes on the PAT).
• Keep the implementation consistent with the inventory architecture introduced in PR feat: Add list-scopes command using inventory architecture #1750 (e.g., follow existing patterns for commands, output helpers, wiring, tests if present).
• Add/update documentation or README snippets for the new comparison capability, including how to provide the PAT and example command usage.
• Ensure scripts fail with a clear error when no PAT is provided and exit non-zero on fetch/parse failures.

Deliverables:

• Code changes implementing the comparison command/option.
• Any new or updated tests.
• Updated documentation/examples.

Notes:

• Do not leak or hardcode any PAT; rely on env-var input.
• This PR should be based on the branch from PR feat: Add list-scopes command using inventory architecture #1750 (stacked PR).

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.