[mcp-tools] Update GitHub MCP toolsets mapping with latest tools from source (v2.1)

.github/workflows/github-mcp-tools-report.md

@@ -190,7 +190,7 @@ Create a detailed markdown report with the following structure:
 - **Toolset Categories**: [NUMBER]
 - **Report Date**: [DATE]
 - **Source**: [pkg/workflow/data/github_toolsets_permissions.json](https://github.com/github/gh-aw/blob/main/pkg/workflow/data/github_toolsets_permissions.json)
-- **Instructions File**: [.github/instructions/github-mcp-server.instructions.md](https://github.com/github/gh-aw/blob/main/.github/instructions/github-mcp-server.instructions.md)
+- **Instructions File**: [.github/aw/github-mcp-server.md](https://github.com/github/gh-aw/blob/main/.github/aw/github-mcp-server.md)
 - **Changes Since Last Report**: [If previous data exists, show changes summary]
   - **New Tools**: [NUMBER]
   - **Removed Tools**: [NUMBER]
@@ -348,7 +348,7 @@ tools:
 - **Categorization**: Based on GitHub API domains and functionality
 - **Documentation**: Derived from tool names, descriptions, and usage patterns
 - **JSON Mapping**: [pkg/workflow/data/github_toolsets_permissions.json](https://github.com/github/gh-aw/blob/main/pkg/workflow/data/github_toolsets_permissions.json)
-- **Instructions**: [.github/instructions/github-mcp-server.instructions.md](https://github.com/github/gh-aw/blob/main/.github/instructions/github-mcp-server.instructions.md)
+- **Instructions**: [.github/aw/github-mcp-server.md](https://github.com/github/gh-aw/blob/main/.github/aw/github-mcp-server.md)
 - **MCP Server Source**: [github/github-mcp-server](https://github.com/github/github-mcp-server/tree/main/pkg/github)
 ```
 
@@ -387,7 +387,7 @@ A successful report:
 - ✅ **Creates pull request** with updated JSON mapping if changes were made
 - ✅ Compares with previous run and identifies changes (new/removed/moved tools)
 - ✅ Saves current tools list to cache for next run
-- ✅ **Creates/updates `.github/instructions/github-mcp-server.instructions.md`** with comprehensive documentation
+- ✅ **Creates/updates `.github/aw/github-mcp-server.md`** with comprehensive documentation
 - ✅ **Identifies and documents recommended default toolsets** with rationale
 - ✅ **Updates default toolsets** in documentation files (github-agentic-workflows.md)
 - ✅ Organizes tools by their appropriate toolset categories
@@ -425,7 +425,7 @@ Your output MUST:
 8. Save the current tools list to `/tmp/gh-aw/cache-memory/github-mcp-tools.json` for the next run
    - Use a structured JSON format with tool names, toolsets, and descriptions
    - Include timestamp and metadata
-9. **Update `.github/instructions/github-mcp-server.instructions.md`** with comprehensive documentation:
+9. **Update `.github/aw/github-mcp-server.md`** with comprehensive documentation:
    - Document all available tools organized by toolset
    - Include tool descriptions, parameters, and usage examples
    - Provide configuration reference for remote vs local mode
@@ -507,7 +507,7 @@ Begin your tool discovery now. Follow these steps:
    - Evaluate the current defaults: `context`, `repos`, `issues`, `pull_requests`, `users`
    - Determine if these defaults should be updated based on actual tool availability and usage patterns
    - Document your rationale for the recommended defaults
-10. **Create comprehensive documentation file**: Create/update `.github/instructions/github-mcp-server.instructions.md` with:
+10. **Create comprehensive documentation file**: Create/update `.github/aw/github-mcp-server.md` with:
    - Overview of GitHub MCP server (remote vs local mode)
    - Complete list of available tools organized by toolset
    - Tool descriptions, parameters, and return values

pkg/workflow/data/github_toolsets_permissions.json

@@ -1,43 +1,25 @@
 {
-  "version": "2.0",
-  "description": "GitHub MCP server toolsets and their required permissions (updated to match actual MCP server capabilities)",
+  "version": "2.1",
+  "description": "GitHub MCP server toolsets and their required permissions (updated to match actual MCP server source code in github/github-mcp-server)",
   "toolsets": {
-    "context": {
-      "description": "GitHub Actions context and environment",
-      "read_permissions": [],
-      "write_permissions": [],
-      "tools": ["get_copilot_space", "github_support_docs_search", "list_copilot_spaces"]
-    },
-    "repos": {
-      "description": "Repository operations",
-      "read_permissions": ["contents"],
-      "write_permissions": ["contents"],
-      "tools": ["get_commit", "get_file_contents", "get_latest_release", "get_release_by_tag", "get_repository_tree", "get_tag", "list_branches", "list_commits", "list_releases", "list_tags"]
-    },
-    "issues": {
-      "description": "Issue management",
-      "read_permissions": ["issues"],
-      "write_permissions": ["issues"],
-      "tools": ["issue_read", "list_issue_types", "list_issues", "search_issues"]
-    },
-    "pull_requests": {
-      "description": "Pull request operations",
-      "read_permissions": ["pull-requests"],
-      "write_permissions": ["pull-requests"],
-      "tools": ["list_pull_requests", "pull_request_read", "search_pull_requests"]
-    },
     "actions": {
       "description": "GitHub Actions workflows",
       "read_permissions": ["actions"],
-      "write_permissions": [],
-      "tools": ["actions_get", "actions_list", "get_job_logs"]
+      "write_permissions": ["actions"],
+      "tools": ["actions_get", "actions_list", "actions_run_trigger", "get_job_logs"]
     },
     "code_security": {
       "description": "Code scanning alerts",
       "read_permissions": ["security-events"],
       "write_permissions": ["security-events"],
       "tools": ["get_code_scanning_alert", "list_code_scanning_alerts"]
     },
+    "context": {
+      "description": "GitHub context and environment (current user, teams)",
+      "read_permissions": [],
+      "write_permissions": [],
+      "tools": ["get_me", "get_team_members", "get_teams"]
+    },
     "dependabot": {
       "description": "Dependabot alerts",
       "read_permissions": ["security-events"],
@@ -51,28 +33,34 @@
       "tools": ["get_discussion", "get_discussion_comments", "list_discussion_categories", "list_discussions"]
     },
     "experiments": {
-      "description": "Experimental features",
+      "description": "Experimental features (dynamic toolset management)",
       "read_permissions": [],
       "write_permissions": [],
-      "tools": []
+      "tools": ["enable_toolset", "get_toolset_tools", "list_available_toolsets"]
     },
     "gists": {
       "description": "Gist operations",
       "read_permissions": [],
       "write_permissions": [],
-      "tools": ["get_gist", "list_gists"]
+      "tools": ["create_gist", "get_gist", "list_gists", "update_gist"]
+    },
+    "issues": {
+      "description": "Issue management",
+      "read_permissions": ["issues"],
+      "write_permissions": ["issues"],
+      "tools": ["add_issue_comment", "issue_read", "issue_write", "list_issue_types", "list_issues", "search_issues", "sub_issue_write"]
     },
     "labels": {
       "description": "Label management",
       "read_permissions": ["issues"],
       "write_permissions": ["issues"],
-      "tools": ["get_label", "list_label"]
+      "tools": ["get_label", "label_write", "list_label"]
     },
     "notifications": {
       "description": "Notification management",
       "read_permissions": [],
       "write_permissions": [],
-      "tools": ["get_notification_details", "list_notifications"]
+      "tools": ["dismiss_notification", "get_notification_details", "list_notifications", "manage_notification_subscription", "manage_repository_notification_subscription", "mark_all_notifications_read"]
     },
     "orgs": {
       "description": "Organization operations",
@@ -84,7 +72,52 @@
       "description": "GitHub Projects (requires PAT - not supported by GITHUB_TOKEN)",
       "read_permissions": [],
       "write_permissions": [],
-      "tools": ["get_project", "get_project_field", "get_project_item", "list_project_fields", "list_project_items", "list_projects"]
+      "tools": ["projects_get", "projects_list", "projects_write"]
+    },
+    "pull_requests": {
+      "description": "Pull request operations",
+      "read_permissions": ["pull-requests"],
+      "write_permissions": ["pull-requests"],
+      "tools": [
+        "add_comment_to_pending_review",
+        "add_reply_to_pull_request_comment",
+        "create_pull_request",
+        "list_pull_requests",
+        "merge_pull_request",
+        "pull_request_read",
+        "pull_request_review_write",
+        "search_pull_requests",
+        "update_pull_request",
+        "update_pull_request_branch"
+      ]
+    },
+    "repos": {
+      "description": "Repository operations",
+      "read_permissions": ["contents"],
+      "write_permissions": ["contents"],
+      "tools": [
+        "create_branch",
+        "create_or_update_file",
+        "create_repository",
+        "delete_file",
+        "fork_repository",
+        "get_commit",
+        "get_file_contents",
+        "get_latest_release",
+        "get_release_by_tag",
+        "get_tag",
+        "list_branches",
+        "list_commits",
+        "list_releases",
+        "list_tags",
+        "push_files"
+      ]
+    },
+    "search": {
+      "description": "Advanced search across GitHub",
+      "read_permissions": [],
+      "write_permissions": [],
+      "tools": ["search_code", "search_orgs", "search_repositories", "search_users"]
     },
     "secret_protection": {
       "description": "Secret scanning",
@@ -102,19 +135,13 @@
       "description": "Repository stars",
       "read_permissions": [],
       "write_permissions": [],
-      "tools": ["list_starred_repositories"]
+      "tools": ["list_starred_repositories", "star_repository", "unstar_repository"]
     },
     "users": {
       "description": "User information",
       "read_permissions": [],
       "write_permissions": [],
       "tools": []
-    },
-    "search": {
-      "description": "Advanced search",
-      "read_permissions": [],
-      "write_permissions": [],
-      "tools": ["search_code", "search_issues", "search_orgs", "search_pull_requests", "search_repositories", "search_users"]
     }
   }
 }

pkg/workflow/github_tool_to_toolset.go

@@ -18,7 +18,7 @@ var githubToolToToolsetJSON []byte
 
 // GitHubToolToToolsetMap maps individual GitHub MCP tools to their respective toolsets
 // This mapping is loaded from an embedded JSON file based on the documentation
-// in .github/instructions/github-mcp-server.instructions.md
+// in .github/aw/github-mcp-server.md
 var GitHubToolToToolsetMap map[string]string
 
 func init() {

pkg/workflow/github_toolsets.go

@@ -10,7 +10,7 @@ var toolsetsLog = logger.New("workflow:github_toolsets")
 
 // DefaultGitHubToolsets defines the toolsets that are enabled by default
 // when toolsets are not explicitly specified in the GitHub MCP configuration.
-// These match the documented default toolsets in github-mcp-server.instructions.md
+// These match the documented default toolsets in github-mcp-server.md
 var DefaultGitHubToolsets = []string{"context", "repos", "issues", "pull_requests"}
 
 // ActionFriendlyGitHubToolsets defines the default toolsets that work with GitHub Actions tokens.

pkg/workflow/permissions_validation.go

@@ -193,20 +193,13 @@ func collectRequiredPermissions(toolsets []string, readOnly bool) map[Permission
 			continue
 		}
 
-		// Add read permissions
+		// Add read permissions only (write tools are not considered for permission requirements)
 		for _, scope := range perms.ReadPermissions {
 			// Always require at least read access
 			if existing, found := required[scope]; !found || existing == PermissionNone {
 				required[scope] = PermissionRead
 			}
 		}
-
-		// Add write permissions only if not in read-only mode
-		if !readOnly {
-			for _, scope := range perms.WritePermissions {
-				required[scope] = PermissionWrite
-			}
-		}
 	}
 
 	return required

pkg/workflow/permissions_validator_test.go

@@ -25,7 +25,7 @@ func TestCollectRequiredPermissions(t *testing.T) {
 			toolsets: []string{"repos"},
 			readOnly: false,
 			expected: map[PermissionScope]PermissionLevel{
-				PermissionContents: PermissionWrite,
+				PermissionContents: PermissionRead,
 			},
 		},
 		{
@@ -41,31 +41,31 @@ func TestCollectRequiredPermissions(t *testing.T) {
 			toolsets: []string{"issues"},
 			readOnly: false,
 			expected: map[PermissionScope]PermissionLevel{
-				PermissionIssues: PermissionWrite,
+				PermissionIssues: PermissionRead,
 			},
 		},
 		{
 			name:     "Multiple toolsets",
 			toolsets: []string{"repos", "issues", "pull_requests"},
 			readOnly: false,
 			expected: map[PermissionScope]PermissionLevel{
-				PermissionContents:     PermissionWrite,
-				PermissionIssues:       PermissionWrite,
-				PermissionPullRequests: PermissionWrite,
+				PermissionContents:     PermissionRead,
+				PermissionIssues:       PermissionRead,
+				PermissionPullRequests: PermissionRead,
 			},
 		},
 		{
 			name:     "Default toolsets in read-write mode",
 			toolsets: DefaultGitHubToolsets,
 			readOnly: false,
 			expected: map[PermissionScope]PermissionLevel{
-				PermissionContents:     PermissionWrite,
-				PermissionIssues:       PermissionWrite,
-				PermissionPullRequests: PermissionWrite,
+				PermissionContents:     PermissionRead,
+				PermissionIssues:       PermissionRead,
+				PermissionPullRequests: PermissionRead,
 			},
 		},
 		{
-			name:     "Actions toolset (read-only)",
+			name:     "Actions toolset",
 			toolsets: []string{"actions"},
 			readOnly: false,
 			expected: map[PermissionScope]PermissionLevel{
@@ -77,15 +77,15 @@ func TestCollectRequiredPermissions(t *testing.T) {
 			toolsets: []string{"code_security"},
 			readOnly: false,
 			expected: map[PermissionScope]PermissionLevel{
-				PermissionSecurityEvents: PermissionWrite,
+				PermissionSecurityEvents: PermissionRead,
 			},
 		},
 		{
 			name:     "Discussions toolset",
 			toolsets: []string{"discussions"},
 			readOnly: false,
 			expected: map[PermissionScope]PermissionLevel{
-				PermissionDiscussions: PermissionWrite,
+				PermissionDiscussions: PermissionRead,
 			},
 		},
 		{
@@ -150,9 +150,9 @@ func TestValidatePermissions_MissingPermissions(t *testing.T) {
 		{
 			name: "Default toolsets with all required permissions",
 			permissions: NewPermissionsFromMap(map[PermissionScope]PermissionLevel{
-				PermissionContents:     PermissionWrite,
-				PermissionIssues:       PermissionWrite,
-				PermissionPullRequests: PermissionWrite,
+				PermissionContents:     PermissionRead,
+				PermissionIssues:       PermissionRead,
+				PermissionPullRequests: PermissionRead,
 			}),
 			githubToolConfig: &GitHubToolConfig{
 				Toolset:  GitHubToolsets{"default"},
@@ -162,17 +162,15 @@ func TestValidatePermissions_MissingPermissions(t *testing.T) {
 			expectHasIssues:    false,
 		},
 		{
-			name: "Default toolsets with only read permissions (missing write)",
+			name: "Default toolsets with no permissions (missing read)",
 			permissions: NewPermissionsFromMap(map[PermissionScope]PermissionLevel{
-				PermissionContents:     PermissionRead,
-				PermissionIssues:       PermissionRead,
-				PermissionPullRequests: PermissionRead,
+				PermissionContents: PermissionRead,
 			}),
 			githubToolConfig: &GitHubToolConfig{
 				Toolset:  GitHubToolsets{"default"},
-				ReadOnly: false, // Need write permissions
+				ReadOnly: false, // Only read permissions required
 			},
-			expectMissingCount: 3, // All need write
+			expectMissingCount: 2, // Missing issues: read, pull-requests: read
 			expectHasIssues:    true,
 		},
 		{
@@ -192,13 +190,13 @@ func TestValidatePermissions_MissingPermissions(t *testing.T) {
 		{
 			name: "Specific toolsets with partial permissions",
 			permissions: NewPermissionsFromMap(map[PermissionScope]PermissionLevel{
-				PermissionContents: PermissionWrite,
+				PermissionContents: PermissionRead,
 			}),
 			githubToolConfig: &GitHubToolConfig{
 				Toolset:  GitHubToolsets{"repos", "issues"},
 				ReadOnly: false,
 			},
-			expectMissingCount: 1, // Missing issues: write
+			expectMissingCount: 1, // Missing issues: read
 			expectHasIssues:    true,
 		},
 		{
@@ -350,12 +348,7 @@ func TestValidatePermissions_ComplexScenarios(t *testing.T) {
 				Toolset:  GitHubToolsets{"default"},
 				ReadOnly: false,
 			},
-			expectMsg: []string{
-				"Missing required permissions for GitHub toolsets:",
-				"contents: write",
-				"issues: write",
-				"pull-requests: write",
-			},
+			expectMsg: []string{}, // read-all satisfies the read-only permission requirements
 		},
 		{
 			name:        "All: read with discussions toolset",
@@ -364,10 +357,7 @@ func TestValidatePermissions_ComplexScenarios(t *testing.T) {
 				Toolset:  GitHubToolsets{"discussions"},
 				ReadOnly: false,
 			},
-			expectMsg: []string{
-				"Missing required permissions for GitHub toolsets:",
-				"discussions: write",
-			},
+			expectMsg: []string{}, // all:read satisfies discussions read requirement
 		},
 	}