Simplify scope implementation per feedback

- Replace NewToolWithScopes with updated NewTool that includes scope parameters - All tools now use the same constructor with explicit scope requirements - Documentation only shows accepted scopes when they differ from required - Removed NewToolWithScopes and NewToolFromHandlerWithScopes helper functions Co-authored-by: SamMorrowDrums <4811358+SamMorrowDrums@users.noreply.github.com>
mattdholloway · Feb 3, 2026 · Dec 24, 2025 · Dec 29, 2025 · Dec 29, 2025 · Dec 28, 2025
commit db179be4c3fc59343b5aa76a57f3448c2c7b9fe8
@@ -227,11 +227,11 @@ func writeToolDoc(buf *strings.Builder, tool inventory.ServerTool) {
 	fmt.Fprintf(buf, "- **%s** - %s\n", tool.Tool.Name, tool.Tool.Annotations.Title)
 
 	// OAuth scopes if present
-	if len(tool.RequiredScopes) > 0 || len(tool.AcceptedScopes) > 0 {
-		if len(tool.RequiredScopes) > 0 {
-			fmt.Fprintf(buf, "  - **Required OAuth Scopes**: `%s`\n", strings.Join(tool.RequiredScopes, "`, `"))
-		}
-		if len(tool.AcceptedScopes) > 0 {
+	if len(tool.RequiredScopes) > 0 {
+		fmt.Fprintf(buf, "  - **Required OAuth Scopes**: `%s`\n", strings.Join(tool.RequiredScopes, "`, `"))
+
+		// Only show accepted scopes if they differ from required scopes
+		if len(tool.AcceptedScopes) > 0 && !scopesEqual(tool.RequiredScopes, tool.AcceptedScopes) {
 			fmt.Fprintf(buf, "  - **Accepted OAuth Scopes**: `%s`\n", strings.Join(tool.AcceptedScopes, "`, `"))
 		}
 	}
@@ -290,6 +290,28 @@ func writeToolDoc(buf *strings.Builder, tool inventory.ServerTool) {
 	}
 }
 
+// scopesEqual checks if two scope slices contain the same elements (order-independent)
+func scopesEqual(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+
+	// Create a map for quick lookup
+	aMap := make(map[string]bool, len(a))
+	for _, scope := range a {
+		aMap[scope] = true
+	}
+
+	// Check if all elements in b are in a
+	for _, scope := range b {
+		if !aMap[scope] {
+			return false
+		}
+	}
+
+	return true
+}
+
 func contains(slice []string, item string) bool {
 	for _, s := range slice {
 		if s == item {

@@ -51,7 +51,7 @@ const (
 
 // ListWorkflows creates a tool to list workflows in a repository
 func ListWorkflows(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name:        "list_workflows",
@@ -124,7 +124,7 @@ func ListWorkflows(t translations.TranslationHelperFunc) inventory.ServerTool {
 
 // ListWorkflowRuns creates a tool to list workflow runs for a specific workflow
 func ListWorkflowRuns(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name:        "list_workflow_runs",
@@ -280,7 +280,7 @@ func ListWorkflowRuns(t translations.TranslationHelperFunc) inventory.ServerTool
 
 // RunWorkflow creates a tool to run an Actions workflow
 func RunWorkflow(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name:        "run_workflow",
@@ -394,7 +394,7 @@ func RunWorkflow(t translations.TranslationHelperFunc) inventory.ServerTool {
 
 // GetWorkflowRun creates a tool to get details of a specific workflow run
 func GetWorkflowRun(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name:        "get_workflow_run",
@@ -464,7 +464,7 @@ func GetWorkflowRun(t translations.TranslationHelperFunc) inventory.ServerTool {
 
 // GetWorkflowRunLogs creates a tool to download logs for a specific workflow run
 func GetWorkflowRunLogs(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name:        "get_workflow_run_logs",
@@ -544,7 +544,7 @@ func GetWorkflowRunLogs(t translations.TranslationHelperFunc) inventory.ServerTo
 
 // ListWorkflowJobs creates a tool to list jobs for a specific workflow run
 func ListWorkflowJobs(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name:        "list_workflow_jobs",
@@ -646,7 +646,7 @@ func ListWorkflowJobs(t translations.TranslationHelperFunc) inventory.ServerTool
 
 // GetJobLogs creates a tool to download logs for a specific workflow job or efficiently get all failed job logs for a workflow run
 func GetJobLogs(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name:        "get_job_logs",
@@ -913,7 +913,7 @@ func downloadLogContent(ctx context.Context, logURL string, tailLines int, maxLi
 
 // RerunWorkflowRun creates a tool to re-run an entire workflow run
 func RerunWorkflowRun(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name:        "rerun_workflow_run",
@@ -990,7 +990,7 @@ func RerunWorkflowRun(t translations.TranslationHelperFunc) inventory.ServerTool
 
 // RerunFailedJobs creates a tool to re-run only the failed jobs in a workflow run
 func RerunFailedJobs(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name:        "rerun_failed_jobs",
@@ -1067,7 +1067,7 @@ func RerunFailedJobs(t translations.TranslationHelperFunc) inventory.ServerTool
 
 // CancelWorkflowRun creates a tool to cancel a workflow run
 func CancelWorkflowRun(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name:        "cancel_workflow_run",
@@ -1146,7 +1146,7 @@ func CancelWorkflowRun(t translations.TranslationHelperFunc) inventory.ServerToo
 
 // ListWorkflowRunArtifacts creates a tool to list artifacts for a workflow run
 func ListWorkflowRunArtifacts(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name:        "list_workflow_run_artifacts",
@@ -1228,7 +1228,7 @@ func ListWorkflowRunArtifacts(t translations.TranslationHelperFunc) inventory.Se
 
 // DownloadWorkflowRunArtifact creates a tool to download a workflow run artifact
 func DownloadWorkflowRunArtifact(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name:        "download_workflow_run_artifact",
@@ -1307,7 +1307,7 @@ func DownloadWorkflowRunArtifact(t translations.TranslationHelperFunc) inventory
 
 // DeleteWorkflowRunLogs creates a tool to delete logs for a workflow run
 func DeleteWorkflowRunLogs(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name:        "delete_workflow_run_logs",
@@ -1385,7 +1385,7 @@ func DeleteWorkflowRunLogs(t translations.TranslationHelperFunc) inventory.Serve
 
 // GetWorkflowRunUsage creates a tool to get usage metrics for a workflow run
 func GetWorkflowRunUsage(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name:        "get_workflow_run_usage",
@@ -1455,7 +1455,7 @@ func GetWorkflowRunUsage(t translations.TranslationHelperFunc) inventory.ServerT
 
 // ActionsList returns the tool and handler for listing GitHub Actions resources.
 func ActionsList(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name: "actions_list",
@@ -1652,7 +1652,7 @@ Use this tool to list workflows in a repository, or list workflow runs, jobs, an
 
 // ActionsGet returns the tool and handler for getting GitHub Actions resources.
 func ActionsGet(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name: "actions_get",
@@ -1762,7 +1762,7 @@ Use this tool to get details about individual workflows, workflow runs, jobs, an
 
 // ActionsRunTrigger returns the tool and handler for triggering GitHub Actions workflows.
 func ActionsRunTrigger(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name:        "actions_run_trigger",
@@ -1882,7 +1882,7 @@ func ActionsRunTrigger(t translations.TranslationHelperFunc) inventory.ServerToo
 
 // ActionsGetJobLogs returns the tool and handler for getting workflow job logs.
 func ActionsGetJobLogs(t translations.TranslationHelperFunc) inventory.ServerTool {
-	tool := NewToolWithScopes(
+	tool := NewTool(
 		ToolsetMetadataActions,
 		mcp.Tool{
 			Name: "get_job_logs",

@@ -17,7 +17,7 @@ import (
 )
 
 func GetCodeScanningAlert(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewToolWithScopes(
+	return NewTool(
 		ToolsetMetadataCodeSecurity,
 		mcp.Tool{
 			Name:        "get_code_scanning_alert",
@@ -95,7 +95,7 @@ func GetCodeScanningAlert(t translations.TranslationHelperFunc) inventory.Server
 }
 
 func ListCodeScanningAlerts(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewToolWithScopes(
+	return NewTool(
 		ToolsetMetadataCodeSecurity,
 		mcp.Tool{
 			Name:        "list_code_scanning_alerts",

@@ -39,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 NewToolWithScopes(
+	return NewTool(
 		ToolsetMetadataContext,
 		mcp.Tool{
 			Name:        "get_me",
@@ -113,7 +113,7 @@ type OrganizationTeams struct {
 }
 
 func GetTeams(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewToolWithScopes(
+	return NewTool(
 		ToolsetMetadataContext,
 		mcp.Tool{
 			Name:        "get_teams",
@@ -212,7 +212,7 @@ func GetTeams(t translations.TranslationHelperFunc) inventory.ServerTool {
 }
 
 func GetTeamMembers(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewToolWithScopes(
+	return NewTool(
 		ToolsetMetadataContext,
 		mcp.Tool{
 			Name:        "get_team_members",

@@ -18,7 +18,7 @@ import (
 )
 
 func GetDependabotAlert(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewToolWithScopes(
+	return NewTool(
 		ToolsetMetadataDependabot,
 		mcp.Tool{
 			Name:        "get_dependabot_alert",
@@ -96,7 +96,7 @@ func GetDependabotAlert(t translations.TranslationHelperFunc) inventory.ServerTo
 }
 
 func ListDependabotAlerts(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewToolWithScopes(
+	return NewTool(
 		ToolsetMetadataDependabot,
 		mcp.Tool{
 			Name:        "list_dependabot_alerts",

@@ -148,16 +148,9 @@ func (d BaseDeps) GetContentWindowSize() int { return d.ContentWindowSize }
 //
 // The handler function receives deps extracted from context via MustDepsFromContext.
 // Ensure ContextWithDeps is called to inject deps before any tool handlers are invoked.
-func NewTool[In, Out any](toolset inventory.ToolsetMetadata, tool mcp.Tool, handler func(ctx context.Context, deps ToolDependencies, req *mcp.CallToolRequest, args In) (*mcp.CallToolResult, Out, error)) inventory.ServerTool {
-	return 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)
-	})
-}
-
-// NewToolWithScopes creates a ServerTool with OAuth scope requirements.
-// This is like NewTool but also accepts required and accepted scopes.
-func NewToolWithScopes[In, Out any](
+//
+// All tools must explicitly specify their OAuth scope requirements, even if empty (nil).
+func NewTool[In, Out any](
 	toolset inventory.ToolsetMetadata,
 	tool mcp.Tool,
 	requiredScopes []string,
@@ -178,16 +171,9 @@ func NewToolWithScopes[In, Out any](
 //
 // The handler function receives deps extracted from context via MustDepsFromContext.
 // Ensure ContextWithDeps is called to inject deps before any tool handlers are invoked.
-func NewToolFromHandler(toolset inventory.ToolsetMetadata, tool mcp.Tool, handler func(ctx context.Context, deps ToolDependencies, req *mcp.CallToolRequest) (*mcp.CallToolResult, error)) inventory.ServerTool {
-	return inventory.NewServerToolWithRawContextHandler(tool, toolset, func(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-		deps := MustDepsFromContext(ctx)
-		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(
+//
+// All tools must explicitly specify their OAuth scope requirements, even if empty (nil).
+func NewToolFromHandler(
 	toolset inventory.ToolsetMetadata,
 	tool mcp.Tool,
 	requiredScopes []string,

@@ -124,7 +124,7 @@ func getQueryType(useOrdering bool, categoryID *githubv4.ID) any {
 }
 
 func ListDiscussions(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewToolWithScopes(
+	return NewTool(
 		ToolsetMetadataDiscussions,
 		mcp.Tool{
 			Name:        "list_discussions",
@@ -278,7 +278,7 @@ func ListDiscussions(t translations.TranslationHelperFunc) inventory.ServerTool
 }
 
 func GetDiscussion(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewToolWithScopes(
+	return NewTool(
 		ToolsetMetadataDiscussions,
 		mcp.Tool{
 			Name:        "get_discussion",
@@ -383,7 +383,7 @@ func GetDiscussion(t translations.TranslationHelperFunc) inventory.ServerTool {
 }
 
 func GetDiscussionComments(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewToolWithScopes(
+	return NewTool(
 		ToolsetMetadataDiscussions,
 		mcp.Tool{
 			Name:        "get_discussion_comments",
@@ -511,7 +511,7 @@ func GetDiscussionComments(t translations.TranslationHelperFunc) inventory.Serve
 }
 
 func ListDiscussionCategories(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewToolWithScopes(
+	return NewTool(
 		ToolsetMetadataDiscussions,
 		mcp.Tool{
 			Name:        "list_discussion_categories",

@@ -19,7 +19,7 @@ import (
 
 // ListGists creates a tool to list gists for a user
 func ListGists(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewToolWithScopes(
+	return NewTool(
 		ToolsetMetadataGists,
 		mcp.Tool{
 			Name:        "list_gists",
@@ -107,7 +107,7 @@ func ListGists(t translations.TranslationHelperFunc) inventory.ServerTool {
 
 // GetGist creates a tool to get the content of a gist
 func GetGist(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewToolWithScopes(
+	return NewTool(
 		ToolsetMetadataGists,
 		mcp.Tool{
 			Name:        "get_gist",
@@ -166,7 +166,7 @@ func GetGist(t translations.TranslationHelperFunc) inventory.ServerTool {
 
 // CreateGist creates a tool to create a new gist
 func CreateGist(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewToolWithScopes(
+	return NewTool(
 		ToolsetMetadataGists,
 		mcp.Tool{
 			Name:        "create_gist",
@@ -270,7 +270,7 @@ func CreateGist(t translations.TranslationHelperFunc) inventory.ServerTool {
 
 // UpdateGist creates a tool to edit an existing gist
 func UpdateGist(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewToolWithScopes(
+	return NewTool(
 		ToolsetMetadataGists,
 		mcp.Tool{
 			Name:        "update_gist",

@@ -40,7 +40,7 @@ type TreeResponse struct {
 
 // GetRepositoryTree creates a tool to get the tree structure of a GitHub repository.
 func GetRepositoryTree(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewToolWithScopes(
+	return NewTool(
 		ToolsetMetadataGit,
 		mcp.Tool{
 			Name:        "get_repository_tree",