Merge branch 'main' into consolidate-project-tools

Author: mattdholloway

docs/scope-filtering.md

@@ -0,0 +1,103 @@
+# PAT Scope Filtering
+
+The GitHub MCP Server automatically filters available tools based on your classic Personal Access Token's (PAT) OAuth scopes. This ensures you only see tools that your token has permission to use, reducing clutter and preventing errors from attempting operations your token can't perform.
+
+> **Note:** This feature applies to **classic PATs** (tokens starting with `ghp_`). Fine-grained PATs, GitHub App installation tokens, and server-to-server tokens don't support scope detection and show all tools.
+
+## How It Works
+
+When the server starts with a classic PAT, it makes a lightweight HTTP HEAD request to the GitHub API to discover your token's scopes from the `X-OAuth-Scopes` header. Tools that require scopes your token doesn't have are automatically hidden.
+
+**Example:** If your token only has `repo` and `gist` scopes, you won't see tools that require `admin:org`, `project`, or `notifications` scopes.
+
+## PAT vs OAuth Authentication
+
+| Authentication | Scope Handling |
+|---------------|----------------|
+| **Classic PAT** (`ghp_`) | Filters tools at startup based on token scopes—tools requiring unavailable scopes are hidden |
+| **OAuth** (remote server only) | Uses OAuth scope challenges—when a tool needs a scope you haven't granted, you're prompted to authorize it |
+| **Fine-grained PAT** (`github_pat_`) | No filtering—all tools shown, API enforces permissions |
+| **GitHub App** (`ghs_`) | No filtering—all tools shown, permissions based on app installation |
+| **Server-to-server** | No filtering—all tools shown, permissions based on app/token configuration |
+
+With OAuth, the remote server can dynamically request additional scopes as needed. With PATs, scopes are fixed at token creation, so the server proactively hides tools you can't use.
+
+## OAuth Scope Challenges (Remote Server)
+
+When using the [remote MCP server](./remote-server.md) with OAuth authentication, the server uses a different approach called **scope challenges**. Instead of hiding tools upfront, all tools are available, and the server requests additional scopes on-demand when you try to use a tool that requires them.
+
+**How it works:**
+1. You attempt to use a tool (e.g., creating an issue)
+2. If your current OAuth token lacks the required scope, the server returns an OAuth scope challenge
+3. Your MCP client prompts you to authorize the additional scope
+4. After authorization, the operation completes successfully
+
+This provides a smoother user experience for OAuth users since you only grant permissions as needed, rather than requesting all scopes upfront.
+
+## Checking Your Token's Scopes
+
+To see what scopes your token has, you can run:
+
+```bash
+curl -sI -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
+  https://api.github.com/user | grep -i x-oauth-scopes
+```
+
+Example output:
+```
+x-oauth-scopes: delete_repo, gist, read:org, repo
+```
+
+## Scope Hierarchy
+
+Some scopes implicitly include others:
+
+- `repo` → includes `public_repo`, `security_events`
+- `admin:org` → includes `write:org` → includes `read:org`
+- `project` → includes `read:project`
+
+This means if your token has `repo`, tools requiring `security_events` will also be available.
+
+Each tool in the [README](../README.md#tools) lists its required and accepted OAuth scopes.
+
+## Public Repository Access
+
+Read-only tools that only require `repo` or `public_repo` scopes are **always visible**, even if your token doesn't have these scopes. This is because these tools work on public repositories without authentication.
+
+For example, `get_file_contents` is always available—you can read files from any public repository regardless of your token's scopes. However, write operations like `create_or_update_file` will be hidden if your token lacks `repo` scope.
+
+> **Note:** The GitHub API doesn't return `public_repo` in the `X-OAuth-Scopes` header—it's implicit. The server handles this by not filtering read-only repository tools.
+
+## Graceful Degradation
+
+If the server cannot fetch your token's scopes (e.g., network issues, rate limiting), it logs a warning and continues **without filtering**. This ensures the server remains usable even when scope detection fails.
+
+```
+WARN: failed to fetch token scopes, continuing without scope filtering
+```
+
+## Classic vs Fine-Grained Personal Access Tokens
+
+**Classic PATs** (`ghp_` prefix) support OAuth scopes and return them in the `X-OAuth-Scopes` header. Scope filtering works fully with these tokens.
+
+**Fine-grained PATs** (`github_pat_` prefix) use a different permission model based on repository access and specific permissions rather than OAuth scopes. They don't return the `X-OAuth-Scopes` header, so scope filtering is skipped. All tools will be available, but the GitHub API will still enforce permissions at the API level—you'll get errors if you try to use tools your token doesn't have permission for.
+
+## GitHub App and Server-to-Server Tokens
+
+**GitHub App installation tokens** (`ghs_` prefix) and other server-to-server tokens use a permission model based on the app's installation permissions rather than OAuth scopes. These tokens don't return the `X-OAuth-Scopes` header, so scope filtering is skipped. The GitHub API enforces permissions based on the app's configuration.
+
+## Troubleshooting
+
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| Missing expected tools | Token lacks required scope | [Edit your PAT's scopes](https://github.com/settings/tokens) in GitHub settings |
+| All tools visible despite limited PAT | Scope detection failed | Check logs for warnings about scope fetching |
+| "Insufficient permissions" errors | Tool visible but scope insufficient | This shouldn't happen with scope filtering; report as bug |
+
+> **Tip:** You can adjust the scopes of an existing classic PAT at any time via [GitHub's token settings](https://github.com/settings/tokens). After updating scopes, restart the MCP server to pick up the changes.
+
+## Related Documentation
+
+- [Server Configuration Guide](./server-configuration.md)
+- [GitHub PAT Documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+- [OAuth Scopes Reference](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps)

docs/server-configuration.md

@@ -12,6 +12,7 @@ We currently support the following ways in which the GitHub MCP Server can be co
 | Read-Only Mode | `X-MCP-Readonly` header or `/readonly` URL | `--read-only` flag or `GITHUB_READ_ONLY` env var |
 | Dynamic Mode | Not available | `--dynamic-toolsets` flag or `GITHUB_DYNAMIC_TOOLSETS` env var |
 | Lockdown Mode | `X-MCP-Lockdown` header | `--lockdown-mode` flag or `GITHUB_LOCKDOWN_MODE` env var |
+| Scope Filtering | Always enabled | Always enabled |
 
 > **Default behavior:** If you don't specify any configuration, the server uses the **default toolsets**: `context`, `issues`, `pull_requests`, `repos`, `users`.
 
@@ -330,6 +331,20 @@ Lockdown mode ensures the server only surfaces content in public repositories fr
 
 ---
 
+### Scope Filtering
+
+**Automatic feature:** The server handles OAuth scopes differently depending on authentication type:
+
+- **Classic PATs** (`ghp_` prefix): Tools are filtered at startup based on token scopes—you only see tools you have permission to use
+- **OAuth** (remote server): Uses scope challenges—when a tool needs a scope you haven't granted, you're prompted to authorize it
+- **Other tokens**: No filtering—all tools shown, API enforces permissions
+
+This happens transparently—no configuration needed. If scope detection fails for a classic PAT (e.g., network issues), the server logs a warning and continues with all tools available.
+
+See [Scope Filtering](./scope-filtering.md) for details on how filtering works with different token types.
+
+---
+
 ## Troubleshooting
 
 | Problem | Cause | Solution |

internal/ghmcp/server.go

@@ -19,6 +19,7 @@ import (
 	"github.com/github/github-mcp-server/pkg/lockdown"
 	mcplog "github.com/github/github-mcp-server/pkg/log"
 	"github.com/github/github-mcp-server/pkg/raw"
+	"github.com/github/github-mcp-server/pkg/scopes"
 	"github.com/github/github-mcp-server/pkg/translations"
 	gogithub "github.com/google/go-github/v79/github"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
@@ -67,6 +68,11 @@ type MCPServerConfig struct {
 	Logger *slog.Logger
 	// RepoAccessTTL overrides the default TTL for repository access cache entries.
 	RepoAccessTTL *time.Duration
+
+	// TokenScopes contains the OAuth scopes available to the token.
+	// When non-nil, tools requiring scopes not in this list will be hidden.
+	// This is used for PAT scope filtering where we can't issue scope challenges.
+	TokenScopes []string
 }
 
 // githubClients holds all the GitHub API clients created for a server instance.
@@ -211,13 +217,19 @@ func NewMCPServer(cfg MCPServerConfig) (*mcp.Server, error) {
 	})
 
 	// Build and register the tool/resource/prompt inventory
-	inventory := github.NewInventory(cfg.Translator).
+	inventoryBuilder := github.NewInventory(cfg.Translator).
 		WithDeprecatedAliases(github.DeprecatedToolAliases).
 		WithReadOnly(cfg.ReadOnly).
 		WithToolsets(enabledToolsets).
 		WithTools(github.CleanTools(cfg.EnabledTools)).
-		WithFeatureChecker(createFeatureChecker(cfg.EnabledFeatures)).
-		Build()
+		WithFeatureChecker(createFeatureChecker(cfg.EnabledFeatures))
+
+	// Apply token scope filtering if scopes are known (for PAT filtering)
+	if cfg.TokenScopes != nil {
+		inventoryBuilder = inventoryBuilder.WithFilter(github.CreateToolScopeFilter(cfg.TokenScopes))
+	}
+
+	inventory := inventoryBuilder.Build()
 
 	if unrecognized := inventory.UnrecognizedToolsets(); len(unrecognized) > 0 {
 		fmt.Fprintf(os.Stderr, "Warning: unrecognized toolsets ignored: %s\n", strings.Join(unrecognized, ", "))
@@ -338,6 +350,22 @@ func RunStdioServer(cfg StdioServerConfig) error {
 	logger := slog.New(slogHandler)
 	logger.Info("starting server", "version", cfg.Version, "host", cfg.Host, "dynamicToolsets", cfg.DynamicToolsets, "readOnly", cfg.ReadOnly, "lockdownEnabled", cfg.LockdownMode)
 
+	// Fetch token scopes for scope-based tool filtering (PAT tokens only)
+	// Only classic PATs (ghp_ prefix) return OAuth scopes via X-OAuth-Scopes header.
+	// Fine-grained PATs and other token types don't support this, so we skip filtering.
+	var tokenScopes []string
+	if strings.HasPrefix(cfg.Token, "ghp_") {
+		fetchedScopes, err := fetchTokenScopesForHost(ctx, cfg.Token, cfg.Host)
+		if err != nil {
+			logger.Warn("failed to fetch token scopes, continuing without scope filtering", "error", err)
+		} else {
+			tokenScopes = fetchedScopes
+			logger.Info("token scopes fetched for filtering", "scopes", tokenScopes)
+		}
+	} else {
+		logger.Debug("skipping scope filtering for non-PAT token")
+	}
+
 	ghServer, err := NewMCPServer(MCPServerConfig{
 		Version:           cfg.Version,
 		Host:              cfg.Host,
@@ -352,6 +380,7 @@ func RunStdioServer(cfg StdioServerConfig) error {
 		LockdownMode:      cfg.LockdownMode,
 		Logger:            logger,
 		RepoAccessTTL:     cfg.RepoAccessCacheTTL,
+		TokenScopes:       tokenScopes,
 	})
 	if err != nil {
 		return fmt.Errorf("failed to create MCP server: %w", err)
@@ -636,3 +665,18 @@ func addUserAgentsMiddleware(cfg MCPServerConfig, restClient *gogithub.Client, g
 		}
 	}
 }
+
+// fetchTokenScopesForHost fetches the OAuth scopes for a token from the GitHub API.
+// It constructs the appropriate API host URL based on the configured host.
+func fetchTokenScopesForHost(ctx context.Context, token, host string) ([]string, error) {
+	apiHost, err := parseAPIHost(host)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse API host: %w", err)
+	}
+
+	fetcher := scopes.NewFetcher(scopes.FetcherOptions{
+		APIHost: apiHost.baseRESTURL.String(),
+	})
+
+	return fetcher.FetchTokenScopes(ctx, token)
+}

pkg/github/scope_filter.go

@@ -0,0 +1,64 @@
+package github
+
+import (
+	"context"
+
+	"github.com/github/github-mcp-server/pkg/inventory"
+	"github.com/github/github-mcp-server/pkg/scopes"
+)
+
+// repoScopesSet contains scopes that grant access to repository content.
+// Tools requiring only these scopes work on public repos without any token scope,
+// so we don't filter them out even if the token lacks repo/public_repo.
+var repoScopesSet = map[string]bool{
+	string(scopes.Repo):       true,
+	string(scopes.PublicRepo): true,
+}
+
+// onlyRequiresRepoScopes returns true if all of the tool's accepted scopes
+// are repo-related scopes (repo, public_repo). Such tools work on public
+// repositories without needing any scope.
+func onlyRequiresRepoScopes(acceptedScopes []string) bool {
+	if len(acceptedScopes) == 0 {
+		return false
+	}
+	for _, scope := range acceptedScopes {
+		if !repoScopesSet[scope] {
+			return false
+		}
+	}
+	return true
+}
+
+// CreateToolScopeFilter creates an inventory.ToolFilter that filters tools
+// based on the token's OAuth scopes.
+//
+// For PATs (Personal Access Tokens), we cannot issue OAuth scope challenges
+// like we can with OAuth apps. Instead, we hide tools that require scopes
+// the token doesn't have.
+//
+// This is the recommended way to filter tools for stdio servers where the
+// token is known at startup and won't change during the session.
+//
+// The filter returns true (include tool) if:
+//   - The tool has no scope requirements (AcceptedScopes is empty)
+//   - The tool is read-only and only requires repo/public_repo scopes (works on public repos)
+//   - The token has at least one of the tool's accepted scopes
+//
+// Example usage:
+//
+//	tokenScopes, err := scopes.FetchTokenScopes(ctx, token)
+//	if err != nil {
+//	    // Handle error - maybe skip filtering
+//	}
+//	filter := github.CreateToolScopeFilter(tokenScopes)
+//	inventory := github.NewInventory(t).WithFilter(filter).Build()
+func CreateToolScopeFilter(tokenScopes []string) inventory.ToolFilter {
+	return func(_ context.Context, tool *inventory.ServerTool) (bool, error) {
+		// Read-only tools requiring only repo/public_repo work on public repos without any scope
+		if tool.Tool.Annotations != nil && tool.Tool.Annotations.ReadOnlyHint && onlyRequiresRepoScopes(tool.AcceptedScopes) {
+			return true, nil
+		}
+		return scopes.HasRequiredScopes(tokenScopes, tool.AcceptedScopes), nil
+	}
+}