Add PAT scope filtering for stdio server

Add the ability to filter tools based on token scopes for PAT users.
This uses an HTTP HEAD request to GitHub's API to discover token scopes.

New components:
- pkg/scopes/filter.go: HasRequiredScopes checks if scopes satisfy tool requirements
- pkg/scopes/fetcher.go: FetchTokenScopes gets scopes via HTTP HEAD to GitHub API
- pkg/github/scope_filter.go: CreateScopeFilter creates inventory.ToolFilter

Integration:
- Add --filter-by-scope flag to stdio command (disabled by default)
- When enabled, fetches token scopes on startup
- Tools requiring unavailable scopes are hidden from tool list
- Gracefully continues without filtering if scope fetch fails (logs warning)

This allows the OSS server to have similar scope-based tool visibility
as the remote server, and the filter logic can be reused by remote server.

Author: SamMorrowDrums

README.md

@@ -602,7 +602,7 @@ The following sets of tools are available:
 
 - **get_code_scanning_alert** - Get code scanning alert
   - **Required OAuth Scopes**: `security_events`
-  - **Accepted OAuth Scopes**: `security_events`, `repo`
+  - **Accepted OAuth Scopes**: `repo`, `security_events`
   - `alertNumber`: The number of the alert. (number, required)
   - `owner`: The owner of the repository. (string, required)
   - `repo`: The name of the repository. (string, required)
@@ -628,7 +628,7 @@ The following sets of tools are available:
 
 - **get_team_members** - Get team members
   - **Required OAuth Scopes**: `read:org`
-  - **Accepted OAuth Scopes**: `write:org`, `read:org`, `admin:org`
+  - **Accepted OAuth Scopes**: `read:org`, `admin:org`, `write:org`
   - `org`: Organization login (owner) that contains the team. (string, required)
   - `team_slug`: Team slug (string, required)
 
@@ -953,15 +953,15 @@ The following sets of tools are available:
 
 - **get_project_field** - Get project field
   - **Required OAuth Scopes**: `read:project`
-  - **Accepted OAuth Scopes**: `read:project`, `project`
+  - **Accepted OAuth Scopes**: `project`, `read:project`
   - `field_id`: The field's id. (number, required)
   - `owner`: If owner_type == user it is the handle for the GitHub user account. If owner_type == org it is the name of the organization. The name is not case sensitive. (string, required)
   - `owner_type`: Owner type (string, required)
   - `project_number`: The project's number. (number, required)
 
 - **get_project_item** - Get project item
   - **Required OAuth Scopes**: `read:project`
-  - **Accepted OAuth Scopes**: `project`, `read:project`
+  - **Accepted OAuth Scopes**: `read:project`, `project`
   - `fields`: Specific list of field IDs to include in the response (e.g. ["102589", "985201", "169875"]). If not provided, only the title field is included. (string[], optional)
   - `item_id`: The item's ID. (number, required)
   - `owner`: If owner_type == user it is the handle for the GitHub user account. If owner_type == org it is the name of the organization. The name is not case sensitive. (string, required)
@@ -980,7 +980,7 @@ The following sets of tools are available:
 
 - **list_project_items** - List project items
   - **Required OAuth Scopes**: `read:project`
-  - **Accepted OAuth Scopes**: `read:project`, `project`
+  - **Accepted OAuth Scopes**: `project`, `read:project`
   - `after`: Forward pagination cursor from previous pageInfo.nextCursor. (string, optional)
   - `before`: Backward pagination cursor from previous pageInfo.prevCursor (rare). (string, optional)
   - `fields`: Field IDs to include (e.g. ["102589", "985201"]). CRITICAL: Always provide to get field values. Without this, only titles returned. (string[], optional)

cmd/github-mcp-server/main.go

@@ -84,6 +84,7 @@ var (
 				ContentWindowSize:    viper.GetInt("content-window-size"),
 				LockdownMode:         viper.GetBool("lockdown-mode"),
 				RepoAccessCacheTTL:   &ttl,
+				EnableScopeFiltering: viper.GetBool("enable-scope-filtering"),
 			}
 			return ghmcp.RunStdioServer(stdioServerConfig)
 		},
@@ -109,6 +110,7 @@ func init() {
 	rootCmd.PersistentFlags().Int("content-window-size", 5000, "Specify the content window size")
 	rootCmd.PersistentFlags().Bool("lockdown-mode", false, "Enable lockdown mode")
 	rootCmd.PersistentFlags().Duration("repo-access-cache-ttl", 5*time.Minute, "Override the repo access cache TTL (e.g. 1m, 0s to disable)")
+	rootCmd.PersistentFlags().Bool("enable-scope-filtering", false, "Filter tools based on the token's OAuth scopes")
 
 	// Bind flag to viper
 	_ = viper.BindPFlag("toolsets", rootCmd.PersistentFlags().Lookup("toolsets"))
@@ -123,6 +125,7 @@ func init() {
 	_ = viper.BindPFlag("content-window-size", rootCmd.PersistentFlags().Lookup("content-window-size"))
 	_ = viper.BindPFlag("lockdown-mode", rootCmd.PersistentFlags().Lookup("lockdown-mode"))
 	_ = viper.BindPFlag("repo-access-cache-ttl", rootCmd.PersistentFlags().Lookup("repo-access-cache-ttl"))
+	_ = viper.BindPFlag("enable-scope-filtering", rootCmd.PersistentFlags().Lookup("enable-scope-filtering"))
 
 	// Add subcommands
 	rootCmd.AddCommand(stdioCmd)

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, ", "))
@@ -312,6 +324,11 @@ type StdioServerConfig struct {
 
 	// RepoAccessCacheTTL overrides the default TTL for repository access cache entries.
 	RepoAccessCacheTTL *time.Duration
+
+	// EnableScopeFiltering enables PAT scope-based tool filtering.
+	// When true, the server will fetch the token's OAuth scopes at startup
+	// and hide tools that require scopes the token doesn't have.
+	EnableScopeFiltering bool
 }
 
 // RunStdioServer is not concurrent safe.
@@ -336,7 +353,19 @@ func RunStdioServer(cfg StdioServerConfig) error {
 		slogHandler = slog.NewTextHandler(logOutput, &slog.HandlerOptions{Level: slog.LevelInfo})
 	}
 	logger := slog.New(slogHandler)
-	logger.Info("starting server", "version", cfg.Version, "host", cfg.Host, "dynamicToolsets", cfg.DynamicToolsets, "readOnly", cfg.ReadOnly, "lockdownEnabled", cfg.LockdownMode)
+	logger.Info("starting server", "version", cfg.Version, "host", cfg.Host, "dynamicToolsets", cfg.DynamicToolsets, "readOnly", cfg.ReadOnly, "lockdownEnabled", cfg.LockdownMode, "scopeFiltering", cfg.EnableScopeFiltering)
+
+	// Fetch token scopes if scope filtering is enabled
+	var tokenScopes []string
+	if cfg.EnableScopeFiltering {
+		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)
+		}
+	}
 
 	ghServer, err := NewMCPServer(MCPServerConfig{
 		Version:           cfg.Version,
@@ -352,6 +381,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 +666,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,36 @@
+package github
+
+import (
+	"context"
+
+	"github.com/github/github-mcp-server/pkg/inventory"
+	"github.com/github/github-mcp-server/pkg/scopes"
+)
+
+// 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 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) {
+		return scopes.HasRequiredScopes(tokenScopes, tool.AcceptedScopes), nil
+	}
+}

pkg/github/scope_filter_test.go

@@ -0,0 +1,162 @@
+package github
+
+import (
+	"context"
+	"testing"
+
+	"github.com/github/github-mcp-server/pkg/inventory"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCreateToolScopeFilter(t *testing.T) {
+	// Create test tools with various scope requirements
+	toolNoScopes := &inventory.ServerTool{
+		Tool:           mcp.Tool{Name: "no_scopes_tool"},
+		AcceptedScopes: nil,
+	}
+
+	toolEmptyScopes := &inventory.ServerTool{
+		Tool:           mcp.Tool{Name: "empty_scopes_tool"},
+		AcceptedScopes: []string{},
+	}
+
+	toolRepoScope := &inventory.ServerTool{
+		Tool:           mcp.Tool{Name: "repo_tool"},
+		AcceptedScopes: []string{"repo"},
+	}
+
+	toolPublicRepoScope := &inventory.ServerTool{
+		Tool:           mcp.Tool{Name: "public_repo_tool"},
+		AcceptedScopes: []string{"public_repo", "repo"}, // repo is parent, also accepted
+	}
+
+	toolGistScope := &inventory.ServerTool{
+		Tool:           mcp.Tool{Name: "gist_tool"},
+		AcceptedScopes: []string{"gist"},
+	}
+
+	toolMultiScope := &inventory.ServerTool{
+		Tool:           mcp.Tool{Name: "multi_scope_tool"},
+		AcceptedScopes: []string{"repo", "admin:org"},
+	}
+
+	tests := []struct {
+		name        string
+		tokenScopes []string
+		tool        *inventory.ServerTool
+		expected    bool
+	}{
+		{
+			name:        "tool with no scopes is always visible",
+			tokenScopes: []string{},
+			tool:        toolNoScopes,
+			expected:    true,
+		},
+		{
+			name:        "tool with empty scopes is always visible",
+			tokenScopes: []string{"repo"},
+			tool:        toolEmptyScopes,
+			expected:    true,
+		},
+		{
+			name:        "token with exact scope can see tool",
+			tokenScopes: []string{"repo"},
+			tool:        toolRepoScope,
+			expected:    true,
+		},
+		{
+			name:        "token with parent scope can see child-scoped tool",
+			tokenScopes: []string{"repo"},
+			tool:        toolPublicRepoScope,
+			expected:    true,
+		},
+		{
+			name:        "token missing required scope cannot see tool",
+			tokenScopes: []string{"gist"},
+			tool:        toolRepoScope,
+			expected:    false,
+		},
+		{
+			name:        "token with unrelated scope cannot see tool",
+			tokenScopes: []string{"repo"},
+			tool:        toolGistScope,
+			expected:    false,
+		},
+		{
+			name:        "token with one of multiple accepted scopes can see tool",
+			tokenScopes: []string{"admin:org"},
+			tool:        toolMultiScope,
+			expected:    true,
+		},
+		{
+			name:        "empty token scopes cannot see scoped tools",
+			tokenScopes: []string{},
+			tool:        toolRepoScope,
+			expected:    false,
+		},
+		{
+			name:        "token with multiple scopes where one matches",
+			tokenScopes: []string{"gist", "repo"},
+			tool:        toolPublicRepoScope,
+			expected:    true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			filter := CreateToolScopeFilter(tt.tokenScopes)
+			result, err := filter(context.Background(), tt.tool)
+
+			require.NoError(t, err)
+			assert.Equal(t, tt.expected, result, "filter result should match expected")
+		})
+	}
+}
+
+func TestCreateToolScopeFilter_Integration(t *testing.T) {
+	// Test integration with inventory builder
+	tools := []inventory.ServerTool{
+		{
+			Tool:           mcp.Tool{Name: "public_tool"},
+			Toolset:        inventory.ToolsetMetadata{ID: "test"},
+			AcceptedScopes: nil, // No scopes required
+		},
+		{
+			Tool:           mcp.Tool{Name: "repo_tool"},
+			Toolset:        inventory.ToolsetMetadata{ID: "test"},
+			AcceptedScopes: []string{"repo"},
+		},
+		{
+			Tool:           mcp.Tool{Name: "gist_tool"},
+			Toolset:        inventory.ToolsetMetadata{ID: "test"},
+			AcceptedScopes: []string{"gist"},
+		},
+	}
+
+	// Create filter for token with only "repo" scope
+	filter := CreateToolScopeFilter([]string{"repo"})
+
+	// Build inventory with the filter
+	inv := inventory.NewBuilder().
+		SetTools(tools).
+		WithToolsets([]string{"test"}).
+		WithFilter(filter).
+		Build()
+
+	// Get available tools
+	availableTools := inv.AvailableTools(context.Background())
+
+	// Should see public_tool and repo_tool, but not gist_tool
+	assert.Len(t, availableTools, 2)
+
+	toolNames := make([]string, len(availableTools))
+	for i, tool := range availableTools {
+		toolNames[i] = tool.Tool.Name
+	}
+
+	assert.Contains(t, toolNames, "public_tool")
+	assert.Contains(t, toolNames, "repo_tool")
+	assert.NotContains(t, toolNames, "gist_tool")
+}