Add scopes package and update ServerTool struct with scope fields

- Created pkg/scopes package with OAuth scope constants
- Added RequiredScopes and AcceptedScopes fields to ServerTool
- Added NewToolWithScopes helpers in dependencies.go
- Updated context tools (get_me, get_teams, get_team_members) with scopes

Co-authored-by: SamMorrowDrums <4811358+SamMorrowDrums@users.noreply.github.com>

Author: Copilot

pkg/github/context_tools.go

@@ -7,6 +7,7 @@ import (
 
 	ghErrors "github.com/github/github-mcp-server/pkg/errors"
 	"github.com/github/github-mcp-server/pkg/inventory"
+	"github.com/github/github-mcp-server/pkg/scopes"
 	"github.com/github/github-mcp-server/pkg/translations"
 	"github.com/github/github-mcp-server/pkg/utils"
 	"github.com/google/jsonschema-go/jsonschema"
@@ -38,7 +39,7 @@ type UserDetails struct {
 
 // GetMe creates a tool to get details of the authenticated user.
 func GetMe(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewTool(
+	return NewToolWithScopes(
 		ToolsetMetadataContext,
 		mcp.Tool{
 			Name:        "get_me",
@@ -51,6 +52,8 @@ func GetMe(t translations.TranslationHelperFunc) inventory.ServerTool {
 			// OpenAI strict mode requires the properties field to be present.
 			InputSchema: json.RawMessage(`{"type":"object","properties":{}}`),
 		},
+		nil, // no required scopes
+		nil, // no accepted scopes
 		func(ctx context.Context, deps ToolDependencies, _ *mcp.CallToolRequest, _ map[string]any) (*mcp.CallToolResult, any, error) {
 			client, err := deps.GetClient(ctx)
 			if err != nil {
@@ -110,7 +113,7 @@ type OrganizationTeams struct {
 }
 
 func GetTeams(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewTool(
+	return NewToolWithScopes(
 		ToolsetMetadataContext,
 		mcp.Tool{
 			Name:        "get_teams",
@@ -129,6 +132,8 @@ func GetTeams(t translations.TranslationHelperFunc) inventory.ServerTool {
 				},
 			},
 		},
+		scopes.ToStringSlice(scopes.ReadOrg),
+		scopes.ToStringSlice(scopes.ReadOrg, scopes.WriteOrg, scopes.AdminOrg),
 		func(ctx context.Context, deps ToolDependencies, _ *mcp.CallToolRequest, args map[string]any) (*mcp.CallToolResult, any, error) {
 			user, err := OptionalParam[string](args, "user")
 			if err != nil {
@@ -207,7 +212,7 @@ func GetTeams(t translations.TranslationHelperFunc) inventory.ServerTool {
 }
 
 func GetTeamMembers(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewTool(
+	return NewToolWithScopes(
 		ToolsetMetadataContext,
 		mcp.Tool{
 			Name:        "get_team_members",
@@ -231,6 +236,8 @@ func GetTeamMembers(t translations.TranslationHelperFunc) inventory.ServerTool {
 				Required: []string{"org", "team_slug"},
 			},
 		},
+		scopes.ToStringSlice(scopes.ReadOrg),
+		scopes.ToStringSlice(scopes.ReadOrg, scopes.WriteOrg, scopes.AdminOrg),
 		func(ctx context.Context, deps ToolDependencies, _ *mcp.CallToolRequest, args map[string]any) (*mcp.CallToolResult, any, error) {
 			org, err := RequiredParam[string](args, "org")
 			if err != nil {

pkg/github/dependencies.go

@@ -155,6 +155,24 @@ func NewTool[In, Out any](toolset inventory.ToolsetMetadata, tool mcp.Tool, hand
 	})
 }
 
+// NewToolWithScopes creates a ServerTool with OAuth scope requirements.
+// This is like NewTool but also accepts required and accepted scopes.
+func NewToolWithScopes[In, Out any](
+	toolset inventory.ToolsetMetadata,
+	tool mcp.Tool,
+	requiredScopes []string,
+	acceptedScopes []string,
+	handler func(ctx context.Context, deps ToolDependencies, req *mcp.CallToolRequest, args In) (*mcp.CallToolResult, Out, error),
+) inventory.ServerTool {
+	st := inventory.NewServerToolWithContextHandler(tool, toolset, func(ctx context.Context, req *mcp.CallToolRequest, args In) (*mcp.CallToolResult, Out, error) {
+		deps := MustDepsFromContext(ctx)
+		return handler(ctx, deps, req, args)
+	})
+	st.RequiredScopes = requiredScopes
+	st.AcceptedScopes = acceptedScopes
+	return st
+}
+
 // NewToolFromHandler creates a ServerTool that retrieves ToolDependencies from context at call time.
 // Use this when you have a handler that conforms to mcp.ToolHandler directly.
 //
@@ -166,3 +184,21 @@ func NewToolFromHandler(toolset inventory.ToolsetMetadata, tool mcp.Tool, handle
 		return handler(ctx, deps, req)
 	})
 }
+
+// NewToolFromHandlerWithScopes creates a ServerTool with OAuth scope requirements.
+// This is like NewToolFromHandler but also accepts required and accepted scopes.
+func NewToolFromHandlerWithScopes(
+	toolset inventory.ToolsetMetadata,
+	tool mcp.Tool,
+	requiredScopes []string,
+	acceptedScopes []string,
+	handler func(ctx context.Context, deps ToolDependencies, req *mcp.CallToolRequest) (*mcp.CallToolResult, error),
+) inventory.ServerTool {
+	st := inventory.NewServerToolWithRawContextHandler(tool, toolset, func(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+		deps := MustDepsFromContext(ctx)
+		return handler(ctx, deps, req)
+	})
+	st.RequiredScopes = requiredScopes
+	st.AcceptedScopes = acceptedScopes
+	return st
+}

pkg/inventory/server_tool.go

@@ -70,6 +70,15 @@ type ServerTool struct {
 	// The context carries request-scoped information for the consumer to use.
 	// Returns (enabled, error). On error, the tool should be treated as disabled.
 	Enabled func(ctx context.Context) (bool, error)
+
+	// RequiredScopes specifies the minimum OAuth scopes required for this tool.
+	// These are the scopes that must be present for the tool to function.
+	RequiredScopes []string
+
+	// AcceptedScopes specifies all OAuth scopes that can be used with this tool.
+	// This includes the required scopes plus any higher-level scopes that provide
+	// the necessary permissions due to scope hierarchy.
+	AcceptedScopes []string
 }
 
 // IsReadOnly returns true if this tool is marked as read-only via annotations.

pkg/scopes/scopes.go

@@ -0,0 +1,77 @@
+package scopes
+
+// Scope represents a GitHub OAuth scope.
+// These constants define all OAuth scopes used by the GitHub MCP server tools.
+// See https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps
+type Scope string
+
+const (
+// Repo grants full control of private repositories
+Repo Scope = "repo"
+
+// PublicRepo grants access to public repositories
+PublicRepo Scope = "public_repo"
+
+// ReadOrg grants read-only access to organization membership, teams, and projects
+ReadOrg Scope = "read:org"
+
+// WriteOrg grants write access to organization membership and teams
+WriteOrg Scope = "write:org"
+
+// AdminOrg grants full control of organizations and teams
+AdminOrg Scope = "admin:org"
+
+// Gist grants write access to gists
+Gist Scope = "gist"
+
+// Notifications grants access to notifications
+Notifications Scope = "notifications"
+
+// ReadProject grants read-only access to projects
+ReadProject Scope = "read:project"
+
+// Project grants full control of projects
+Project Scope = "project"
+
+// SecurityEvents grants read and write access to security events
+SecurityEvents Scope = "security_events"
+)
+
+// ScopeSet represents a set of OAuth scopes.
+type ScopeSet map[Scope]bool
+
+// NewScopeSet creates a new ScopeSet from the given scopes.
+func NewScopeSet(scopes ...Scope) ScopeSet {
+set := make(ScopeSet)
+for _, scope := range scopes {
+set[scope] = true
+}
+return set
+}
+
+// ToSlice converts a ScopeSet to a slice of Scope values.
+func (s ScopeSet) ToSlice() []Scope {
+scopes := make([]Scope, 0, len(s))
+for scope := range s {
+scopes = append(scopes, scope)
+}
+return scopes
+}
+
+// ToStringSlice converts a ScopeSet to a slice of string values.
+func (s ScopeSet) ToStringSlice() []string {
+scopes := make([]string, 0, len(s))
+for scope := range s {
+scopes = append(scopes, string(scope))
+}
+return scopes
+}
+
+// ToStringSlice converts a slice of Scopes to a slice of strings.
+func ToStringSlice(scopes ...Scope) []string {
+result := make([]string, len(scopes))
+for i, scope := range scopes {
+result[i] = string(scope)
+}
+return result
+}