feat: Add OAuth scopes to tool metadata

- Add pkg/scopes package with OAuth scope constants and utilities
- Add scopes to all ~90 tool definitions using mcp.Tool.Meta field
- Update generate_docs.go to include scopes in README output
- Add comprehensive test coverage for scopes package
- Update all toolsnaps to include _meta.requiredOAuthScopes

Scope assignments follow GitHub OAuth app documentation:
- repo: Most repository operations (private repos)
- public_repo: Star/unstar operations
- notifications: Notification operations
- gist: Gist write operations
- security_events: Code scanning, dependabot, secret scanning
- project/read:project: Project operations
- read:org: Organization/team read operations
- No scope: Public read operations (get_me, list_gists)

Author: SamMorrowDrums

README.md

@@ -12,6 +12,7 @@ import (
 	"github.com/github/github-mcp-server/pkg/github"
 	"github.com/github/github-mcp-server/pkg/lockdown"
 	"github.com/github/github-mcp-server/pkg/raw"
+	"github.com/github/github-mcp-server/pkg/scopes"
 	"github.com/github/github-mcp-server/pkg/toolsets"
 	"github.com/github/github-mcp-server/pkg/translations"
 	gogithub "github.com/google/go-github/v79/github"
@@ -224,7 +225,20 @@ func generateToolDoc(tool mcp.Tool) string {
 	var lines []string
 
 	// Tool name only (using annotation name instead of verbose description)
-	lines = append(lines, fmt.Sprintf("- **%s** - %s", tool.Name, tool.Annotations.Title))
+	toolLine := fmt.Sprintf("- **%s** - %s", tool.Name, tool.Annotations.Title)
+
+	// Add required scopes if present
+	if tool.Meta != nil {
+		toolScopes := scopes.GetScopesFromMeta(tool.Meta)
+		if len(toolScopes) > 0 {
+			scopeStrs := make([]string, len(toolScopes))
+			for i, s := range toolScopes {
+				scopeStrs[i] = fmt.Sprintf("`%s`", s.String())
+			}
+			toolLine += fmt.Sprintf(" (scopes: %s)", strings.Join(scopeStrs, ", "))
+		}
+	}
+	lines = append(lines, toolLine)
 
 	// Parameters
 	if tool.InputSchema == nil {

cmd/github-mcp-server/generate_docs.go

@@ -1,4 +1,9 @@
 {
+  "_meta": {
+    "requiredOAuthScopes": [
+      "repo"
+    ]
+  },
   "annotations": {
     "title": "Add review comment to the requester's latest pending pull request review"
   },

pkg/github/__toolsnaps__/add_comment_to_pending_review.snap

@@ -1,4 +1,9 @@
 {
+  "_meta": {
+    "requiredOAuthScopes": [
+      "repo"
+    ]
+  },
   "annotations": {
     "title": "Add comment to issue"
   },

pkg/github/__toolsnaps__/add_issue_comment.snap

@@ -1,4 +1,9 @@
 {
+  "_meta": {
+    "requiredOAuthScopes": [
+      "project"
+    ]
+  },
   "annotations": {
     "title": "Add project item"
   },

pkg/github/__toolsnaps__/add_project_item.snap

@@ -1,4 +1,9 @@
 {
+  "_meta": {
+    "requiredOAuthScopes": [
+      "repo"
+    ]
+  },
   "annotations": {
     "idempotentHint": true,
     "title": "Assign Copilot to issue"

pkg/github/__toolsnaps__/assign_copilot_to_issue.snap

@@ -1,4 +1,9 @@
 {
+  "_meta": {
+    "requiredOAuthScopes": [
+      "repo"
+    ]
+  },
   "annotations": {
     "title": "Cancel workflow run"
   },

pkg/github/__toolsnaps__/cancel_workflow_run.snap

@@ -1,4 +1,9 @@
 {
+  "_meta": {
+    "requiredOAuthScopes": [
+      "repo"
+    ]
+  },
   "annotations": {
     "title": "Create branch"
   },

pkg/github/__toolsnaps__/create_branch.snap

@@ -1,4 +1,9 @@
 {
+  "_meta": {
+    "requiredOAuthScopes": [
+      "gist"
+    ]
+  },
   "annotations": {
     "title": "Create Gist"
   },

pkg/github/__toolsnaps__/create_gist.snap

@@ -1,4 +1,9 @@
 {
+  "_meta": {
+    "requiredOAuthScopes": [
+      "repo"
+    ]
+  },
   "annotations": {
     "title": "Create or update file"
   },