Merge branch 'main' into actions-consolidation-ff

Author: mattdholloway

CONTRIBUTING.md

@@ -40,6 +40,7 @@ These are one time installations required to be able to test your changes locall
     - Update snapshots and run tests: `UPDATE_TOOLSNAPS=true go test ./...`
     - Update readme documentation: `script/generate-docs`
     - If renaming a tool, add a deprecation alias (see [Tool Renaming Guide](docs/tool-renaming.md))
+    - For toolset and icon configuration, see [Toolsets and Icons Guide](docs/toolsets-and-icons.md)
 6. Push to your fork and [submit a pull request][pr] targeting the `main` branch
 7. Pat yourself on the back and wait for your pull request to be reviewed and merged.
 

README.md

@@ -36,7 +36,7 @@ func generateAllDocs() error {
 		// File to edit, function to generate its docs
 		{"README.md", generateReadmeDocs},
 		{"docs/remote-server.md", generateRemoteServerDocs},
-		{"docs/deprecated-tool-aliases.md", generateDeprecatedAliasesDocs},
+		{"docs/tool-renaming.md", generateDeprecatedAliasesDocs},
 	} {
 		if err := doc.fn(doc.path); err != nil {
 			return fmt.Errorf("failed to generate docs for %s: %w", doc.path, err)
@@ -101,23 +101,52 @@ func generateRemoteServerDocs(docsPath string) error {
 		return err
 	}
 
+	// Also generate remote-only toolsets section
+	remoteOnlyDoc := generateRemoteOnlyToolsetsDoc()
+	updatedContent, err = replaceSection(updatedContent, "START AUTOMATED REMOTE TOOLSETS", "END AUTOMATED REMOTE TOOLSETS", remoteOnlyDoc)
+	if err != nil {
+		return err
+	}
+
 	return os.WriteFile(docsPath, []byte(updatedContent), 0600) //#nosec G306
 }
 
+// octiconImg returns an img tag for an Octicon that works with GitHub's light/dark theme.
+// Uses picture element with prefers-color-scheme for automatic theme switching.
+// References icons from the repo's pkg/octicons/icons directory.
+// Optional pathPrefix for files in subdirectories (e.g., "../" for docs/).
+func octiconImg(name string, pathPrefix ...string) string {
+	if name == "" {
+		return ""
+	}
+	prefix := ""
+	if len(pathPrefix) > 0 {
+		prefix = pathPrefix[0]
+	}
+	// Use picture element with media queries for light/dark mode support
+	// GitHub renders these correctly in markdown
+	lightIcon := fmt.Sprintf("%spkg/octicons/icons/%s-light.png", prefix, name)
+	darkIcon := fmt.Sprintf("%spkg/octicons/icons/%s-dark.png", prefix, name)
+	return fmt.Sprintf(`<picture><source media="(prefers-color-scheme: dark)" srcset="%s"><source media="(prefers-color-scheme: light)" srcset="%s"><img src="%s" width="20" height="20" alt="%s"></picture>`, darkIcon, lightIcon, lightIcon, name)
+}
+
 func generateToolsetsDoc(i *inventory.Inventory) string {
 	var buf strings.Builder
 
-	// Add table header and separator
-	buf.WriteString("| Toolset                 | Description                                                   |\n")
-	buf.WriteString("| ----------------------- | ------------------------------------------------------------- |\n")
+	// Add table header and separator (with icon column)
+	buf.WriteString("|     | Toolset                 | Description                                                   |\n")
+	buf.WriteString("| --- | ----------------------- | ------------------------------------------------------------- |\n")
 
 	// Add the context toolset row with custom description (strongly recommended)
-	buf.WriteString("| `context`               | **Strongly recommended**: Tools that provide context about the current user and GitHub context you are operating in |\n")
+	// Get context toolset for its icon
+	contextIcon := octiconImg("person")
+	fmt.Fprintf(&buf, "| %s | `context`               | **Strongly recommended**: Tools that provide context about the current user and GitHub context you are operating in |\n", contextIcon)
 
 	// AvailableToolsets() returns toolsets that have tools, sorted by ID
 	// Exclude context (custom description above) and dynamic (internal only)
 	for _, ts := range i.AvailableToolsets("context", "dynamic") {
-		fmt.Fprintf(&buf, "| `%s` | %s |\n", ts.ID, ts.Description)
+		icon := octiconImg(ts.Icon)
+		fmt.Fprintf(&buf, "| %s | `%s` | %s |\n", icon, ts.ID, ts.Description)
 	}
 
 	return strings.TrimSuffix(buf.String(), "\n")
@@ -134,6 +163,7 @@ func generateToolsDoc(r *inventory.Inventory) string {
 	var buf strings.Builder
 	var toolBuf strings.Builder
 	var currentToolsetID inventory.ToolsetID
+	var currentToolsetIcon string
 	firstSection := true
 
 	writeSection := func() {
@@ -145,7 +175,11 @@ func generateToolsDoc(r *inventory.Inventory) string {
 		}
 		firstSection = false
 		sectionName := formatToolsetName(string(currentToolsetID))
-		fmt.Fprintf(&buf, "<details>\n\n<summary>%s</summary>\n\n%s\n\n</details>", sectionName, strings.TrimSuffix(toolBuf.String(), "\n\n"))
+		icon := octiconImg(currentToolsetIcon)
+		if icon != "" {
+			icon += " "
+		}
+		fmt.Fprintf(&buf, "<details>\n\n<summary>%s%s</summary>\n\n%s\n\n</details>", icon, sectionName, strings.TrimSuffix(toolBuf.String(), "\n\n"))
 		toolBuf.Reset()
 	}
 
@@ -154,6 +188,7 @@ func generateToolsDoc(r *inventory.Inventory) string {
 		if tool.Toolset.ID != currentToolsetID {
 			writeSection()
 			currentToolsetID = tool.Toolset.ID
+			currentToolsetIcon = tool.Toolset.Icon
 		}
 		writeToolDoc(&toolBuf, tool.Tool)
 		toolBuf.WriteString("\n\n")
@@ -190,7 +225,7 @@ func formatToolsetName(name string) string {
 }
 
 func writeToolDoc(buf *strings.Builder, tool mcp.Tool) {
-	// Tool name only (using annotation name instead of verbose description)
+	// Tool name (no icon - section header already has the toolset icon)
 	fmt.Fprintf(buf, "- **%s** - %s\n", tool.Name, tool.Annotations.Title)
 
 	// Parameters
@@ -302,12 +337,13 @@ func generateRemoteToolsetsDoc() string {
 	// Build inventory - stateless
 	r := github.NewInventory(t).Build()
 
-	// Generate table header
-	buf.WriteString("| Name           | Description                                      | API URL                                               | 1-Click Install (VS Code)                                                                                                                                                                                                 | Read-only Link                                                                                                 | 1-Click Read-only Install (VS Code)                                                                                                                                                                                                 |\n")
-	buf.WriteString("|----------------|--------------------------------------------------|-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n")
+	// Generate table header (icon is combined with Name column)
+	buf.WriteString("| Name | Description | API URL | 1-Click Install (VS Code) | Read-only Link | 1-Click Read-only Install (VS Code) |\n")
+	buf.WriteString("| ---- | ----------- | ------- | ------------------------- | -------------- | ----------------------------------- |\n")
 
 	// Add "all" toolset first (special case)
-	buf.WriteString("| all            | All available GitHub MCP tools                    | https://api.githubcopilot.com/mcp/                    | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2F%22%7D)                                      | [read-only](https://api.githubcopilot.com/mcp/readonly)                                                      | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Freadonly%22%7D) |\n")
+	allIcon := octiconImg("apps", "../")
+	fmt.Fprintf(&buf, "| %s<br>all | All available GitHub MCP tools | https://api.githubcopilot.com/mcp/ | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%%7B%%22type%%22%%3A%%20%%22http%%22%%2C%%22url%%22%%3A%%20%%22https%%3A%%2F%%2Fapi.githubcopilot.com%%2Fmcp%%2F%%22%%7D) | [read-only](https://api.githubcopilot.com/mcp/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%%7B%%22type%%22%%3A%%20%%22http%%22%%2C%%22url%%22%%3A%%20%%22https%%3A%%2F%%2Fapi.githubcopilot.com%%2Fmcp%%2Freadonly%%22%%7D) |\n", allIcon)
 
 	// AvailableToolsets() returns toolsets that have tools, sorted by ID
 	// Exclude context (handled separately) and dynamic (internal only)
@@ -329,19 +365,61 @@ func generateRemoteToolsetsDoc() string {
 		installLink := fmt.Sprintf("[Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-%s&config=%s)", idStr, installConfig)
 		readonlyInstallLink := fmt.Sprintf("[Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-%s&config=%s)", idStr, readonlyConfig)
 
-		fmt.Fprintf(&buf, "| %-14s | %-48s | %-53s | %-218s | %-110s | %-288s |\n",
+		icon := octiconImg(ts.Icon, "../")
+		fmt.Fprintf(&buf, "| %s<br>%s | %s | %s | %s | [read-only](%s) | %s |\n",
+			icon,
 			formattedName,
 			ts.Description,
 			apiURL,
 			installLink,
-			fmt.Sprintf("[read-only](%s)", readonlyURL),
+			readonlyURL,
 			readonlyInstallLink,
 		)
 	}
 
 	return strings.TrimSuffix(buf.String(), "\n")
 }
 
+func generateRemoteOnlyToolsetsDoc() string {
+	var buf strings.Builder
+
+	// Generate table header (icon is combined with Name column)
+	buf.WriteString("| Name | Description | API URL | 1-Click Install (VS Code) | Read-only Link | 1-Click Read-only Install (VS Code) |\n")
+	buf.WriteString("| ---- | ----------- | ------- | ------------------------- | -------------- | ----------------------------------- |\n")
+
+	// Use RemoteOnlyToolsets from github package
+	for _, ts := range github.RemoteOnlyToolsets() {
+		idStr := string(ts.ID)
+
+		formattedName := formatToolsetName(idStr)
+		apiURL := fmt.Sprintf("https://api.githubcopilot.com/mcp/x/%s", idStr)
+		readonlyURL := fmt.Sprintf("https://api.githubcopilot.com/mcp/x/%s/readonly", idStr)
+
+		// Create install config JSON (URL encoded)
+		installConfig := url.QueryEscape(fmt.Sprintf(`{"type": "http","url": "%s"}`, apiURL))
+		readonlyConfig := url.QueryEscape(fmt.Sprintf(`{"type": "http","url": "%s"}`, readonlyURL))
+
+		// Fix URL encoding to use %20 instead of + for spaces
+		installConfig = strings.ReplaceAll(installConfig, "+", "%20")
+		readonlyConfig = strings.ReplaceAll(readonlyConfig, "+", "%20")
+
+		installLink := fmt.Sprintf("[Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-%s&config=%s)", idStr, installConfig)
+		readonlyInstallLink := fmt.Sprintf("[Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-%s&config=%s)", idStr, readonlyConfig)
+
+		icon := octiconImg(ts.Icon, "../")
+		fmt.Fprintf(&buf, "| %s<br>%s | %s | %s | %s | [read-only](%s) | %s |\n",
+			icon,
+			formattedName,
+			ts.Description,
+			apiURL,
+			installLink,
+			readonlyURL,
+			readonlyInstallLink,
+		)
+	}
+
+	return strings.TrimSuffix(buf.String(), "\n")
+}
 func generateDeprecatedAliasesDocs(docsPath string) error {
 	// Read the current file
 	content, err := os.ReadFile(docsPath) //#nosec G304