Add icon validation tests and single source of truth for required icons

- Add pkg/octicons/required_icons.txt as single source of truth for icons
- Add RequiredIcons() function to read the required icons list
- Update script/fetch-icons to read from required_icons.txt
- Update octicons_test.go to use RequiredIcons() instead of hardcoded list
- Add pkg/github/toolset_icons_test.go with:
  - TestAllToolsetIconsExist: validates all toolset icons are embedded
  - TestToolsetMetadataHasIcons: ensures all toolsets have icons set
- Add 'book' icon for SupportSearch toolset
- Update docs/toolsets-and-icons.md with fetch-icons and CI validation docs

Author: SamMorrowDrums

docs/toolsets-and-icons.md

@@ -32,22 +32,42 @@ Icons help users quickly identify toolsets in MCP-compatible clients. We use [Pr
 
 Browse the [Octicon gallery](https://primer.style/foundations/icons) and select an appropriate icon. Use the base name without size suffix (e.g., `repo` not `repo-16`).
 
-### Step 2: Add the Icon Files
+### Step 2: Add Icon to Required Icons List
 
-Icons are stored as PNG files in `pkg/octicons/icons/` with light and dark theme variants:
+Icons are defined in `pkg/octicons/required_icons.txt`, which is the single source of truth for which icons should be embedded:
 
 ```
-pkg/octicons/icons/
-├── repo-light.png    # For light theme
-├── repo-dark.png     # For dark theme
-├── issue-opened-light.png
-├── issue-opened-dark.png
-└── ...
+# Required icons for the GitHub MCP Server
+# Add new icons below (one per line)
+repo
+issue-opened
+git-pull-request
+your-new-icon  # Add your icon here
 ```
 
-Icon files should be 20x20 pixels in size.
+### Step 3: Fetch the Icon Files
 
-### Step 3: Update the Toolset Metadata
+Run the fetch-icons script to download and convert the icon:
+
+```bash
+# Fetch a specific icon
+script/fetch-icons your-new-icon
+
+# Or fetch all required icons
+script/fetch-icons
+```
+
+This script:
+- Downloads the 24px SVG from [Primer Octicons](https://github.com/primer/octicons)
+- Converts to PNG with light theme (dark icons for light backgrounds)
+- Converts to PNG with dark theme (white icons for dark backgrounds)
+- Saves both variants to `pkg/octicons/icons/`
+
+**Requirements:** The script requires `rsvg-convert`:
+- Ubuntu/Debian: `sudo apt-get install librsvg2-bin`
+- macOS: `brew install librsvg`
+
+### Step 4: Update the Toolset Metadata
 
 Add or update the `Icon` field in the toolset definition:
 
@@ -61,7 +81,7 @@ ToolsetMetadataRepos = inventory.ToolsetMetadata{
 }
 ```
 
-### Step 4: Regenerate Documentation
+### Step 5: Regenerate Documentation
 
 Run the documentation generator to update all markdown files:
 
@@ -158,3 +178,24 @@ icons := octicons.Icons("repo")
 1. Verify the client supports MCP tool icons
 2. Check that the octicons package is properly generating base64 data URIs
 3. Ensure the icon name matches a file in `pkg/octicons/icons/`
+
+## CI Validation
+
+The following tests run in CI to catch icon issues early:
+
+### `pkg/octicons.TestEmbeddedIconsExist`
+
+Verifies that all icons listed in `pkg/octicons/required_icons.txt` have corresponding PNG files embedded.
+
+### `pkg/github.TestAllToolsetIconsExist`
+
+Verifies that all toolset `Icon` fields reference icons that are properly embedded.
+
+### `pkg/github.TestToolsetMetadataHasIcons`
+
+Ensures all toolsets have an `Icon` field set.
+
+If any of these tests fail:
+1. Add the missing icon to `pkg/octicons/required_icons.txt`
+2. Run `script/fetch-icons` to download the icon
+3. Commit the new icon files

pkg/github/toolset_icons_test.go

@@ -0,0 +1,86 @@
+package github
+
+import (
+	"testing"
+
+	"github.com/github/github-mcp-server/pkg/octicons"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestAllToolsetIconsExist validates that every toolset with an Icon field
+// references an icon that actually exists in the embedded octicons.
+// This prevents broken icon references from being merged.
+func TestAllToolsetIconsExist(t *testing.T) {
+	// Get all available toolsets from the inventory
+	inv := NewInventory(stubTranslator).Build()
+	toolsets := inv.AvailableToolsets()
+
+	// Also test remote-only toolsets
+	remoteToolsets := RemoteOnlyToolsets()
+
+	// Combine both lists
+	allToolsets := make([]struct {
+		name string
+		icon string
+	}, 0)
+
+	for _, ts := range toolsets {
+		if ts.Icon != "" {
+			allToolsets = append(allToolsets, struct {
+				name string
+				icon string
+			}{name: string(ts.ID), icon: ts.Icon})
+		}
+	}
+
+	for _, ts := range remoteToolsets {
+		if ts.Icon != "" {
+			allToolsets = append(allToolsets, struct {
+				name string
+				icon string
+			}{name: string(ts.ID), icon: ts.Icon})
+		}
+	}
+
+	require.NotEmpty(t, allToolsets, "expected at least one toolset with an icon")
+
+	for _, ts := range allToolsets {
+		t.Run(ts.name, func(t *testing.T) {
+			// Check that icons return valid data URIs (not empty)
+			icons := octicons.Icons(ts.icon)
+			require.NotNil(t, icons, "toolset %s references icon %q which does not exist", ts.name, ts.icon)
+			assert.Len(t, icons, 2, "expected light and dark icon variants for toolset %s", ts.name)
+
+			// Verify both variants have valid data URIs
+			for _, icon := range icons {
+				assert.NotEmpty(t, icon.Source, "icon source should not be empty for toolset %s", ts.name)
+				assert.Contains(t, icon.Source, "data:image/png;base64,",
+					"icon %s for toolset %s should be a valid data URI", ts.icon, ts.name)
+			}
+		})
+	}
+}
+
+// TestToolsetMetadataHasIcons ensures all toolsets have icons defined.
+// This is a policy test - if you want to allow toolsets without icons,
+// you can remove or modify this test.
+func TestToolsetMetadataHasIcons(t *testing.T) {
+	// These toolsets are expected to NOT have icons (internal/special purpose)
+	exceptionsWithoutIcons := map[string]bool{
+		"all":     true, // Meta-toolset
+		"default": true, // Meta-toolset
+	}
+
+	inv := NewInventory(stubTranslator).Build()
+	toolsets := inv.AvailableToolsets()
+
+	for _, ts := range toolsets {
+		if exceptionsWithoutIcons[string(ts.ID)] {
+			continue
+		}
+		t.Run(string(ts.ID), func(t *testing.T) {
+			assert.NotEmpty(t, ts.Icon, "toolset %s should have an icon defined", ts.ID)
+		})
+	}
+}

pkg/octicons/icons/book-dark.png

@@ -3,16 +3,37 @@
 package octicons
 
 import (
+	"bufio"
 	"embed"
 	"encoding/base64"
 	"fmt"
+	"strings"
 
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
 //go:embed icons/*.png
 var iconsFS embed.FS
 
+//go:embed required_icons.txt
+var requiredIconsTxt string
+
+// RequiredIcons returns the list of icon names from required_icons.txt.
+// This is the single source of truth for which icons should be embedded.
+func RequiredIcons() []string {
+	var icons []string
+	scanner := bufio.NewScanner(strings.NewReader(requiredIconsTxt))
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		// Skip empty lines and comments
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		icons = append(icons, line)
+	}
+	return icons
+}
+
 // Theme represents the color theme of an icon.
 type Theme string
 

pkg/octicons/icons/book-light.png

@@ -104,15 +104,9 @@ func TestThemeConstants(t *testing.T) {
 }
 
 func TestEmbeddedIconsExist(t *testing.T) {
-	// Test that all icons used by toolsets are properly embedded
-	expectedIcons := []string{
-		"apps", "beaker", "bell", "check-circle", "codescan",
-		"comment-discussion", "copilot", "dependabot", "file", "git-branch",
-		"git-commit", "git-merge", "git-pull-request", "issue-opened", "logo-gist", "mark-github",
-		"organization", "people", "person", "project", "repo", "repo-forked",
-		"shield", "shield-lock", "star", "star-fill", "tag", "tools", "workflow",
-	}
-
+        // Test that all required icons from required_icons.txt are properly embedded
+        // This is the single source of truth for which icons should be available
+        expectedIcons := RequiredIcons()
 	for _, icon := range expectedIcons {
 		t.Run(icon, func(t *testing.T) {
 			lightURI := DataURI(icon, ThemeLight)

pkg/octicons/octicons.go

@@ -0,0 +1,45 @@
+# Required Octicons for the GitHub MCP Server
+# This file is the source of truth for icon requirements.
+# Used by:
+#   - script/fetch-icons (to download icons)
+#   - pkg/octicons/octicons_test.go (to validate icons are embedded)
+#   - pkg/github/toolset_icons_test.go (to validate toolset icons exist)
+#
+# Add new icons here when:
+#   - Adding a new toolset with an icon
+#   - Adding a new tool that needs a custom icon
+#
+# Format: one icon name per line (without -24.svg suffix)
+# Lines starting with # are comments
+# Empty lines are ignored
+
+apps
+beaker
+bell
+book
+check-circle
+codescan
+comment-discussion
+copilot
+dependabot
+file
+git-branch
+git-commit
+git-merge
+git-pull-request
+issue-opened
+logo-gist
+mark-github
+organization
+people
+person
+project
+repo
+repo-forked
+shield
+shield-lock
+star
+star-fill
+tag
+tools
+workflow

pkg/octicons/octicons_test.go

@@ -5,47 +5,17 @@
 # Requires: rsvg-convert (from librsvg2-bin on Ubuntu/Debian)
 #
 # Usage:
-#   script/fetch-icons              # Fetch all default icons
+#   script/fetch-icons              # Fetch all required icons
 #   script/fetch-icons icon1 icon2  # Fetch specific icons
 
 set -e
 
-ICONS_DIR="pkg/octicons/icons"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+ICONS_DIR="$REPO_ROOT/pkg/octicons/icons"
+REQUIRED_ICONS_FILE="$REPO_ROOT/pkg/octicons/required_icons.txt"
 OCTICONS_BASE="https://raw.githubusercontent.com/primer/octicons/main/icons"
 
-# Default icons used by toolsets - add new icons here as needed
-DEFAULT_ICONS=(
-    apps
-    beaker
-    bell
-    check-circle
-    codescan
-    comment-discussion
-    copilot
-    dependabot
-    file
-    git-branch
-    git-commit
-    git-merge
-    git-pull-request
-    issue-opened
-    logo-gist
-    mark-github
-    organization
-    people
-    person
-    project
-    repo
-    repo-forked
-    shield
-    shield-lock
-    star
-    star-fill
-    tag
-    tools
-    workflow
-)
-
 # Check for rsvg-convert
 if ! command -v rsvg-convert &> /dev/null; then
     echo "Error: rsvg-convert not found. Install with:"
@@ -54,11 +24,16 @@ if ! command -v rsvg-convert &> /dev/null; then
     exit 1
 fi
 
-# Use provided icons or defaults
+# Load icons from required_icons.txt or use command-line arguments
 if [ $# -gt 0 ]; then
     ICONS=("$@")
 else
-    ICONS=("${DEFAULT_ICONS[@]}")
+    if [ ! -f "$REQUIRED_ICONS_FILE" ]; then
+        echo "Error: Required icons file not found: $REQUIRED_ICONS_FILE"
+        exit 1
+    fi
+    # Read icons from file, skipping comments and empty lines
+    mapfile -t ICONS < <(grep -v '^#' "$REQUIRED_ICONS_FILE" | grep -v '^$')
 fi
 
 # Ensure icons directory exists
@@ -91,6 +66,7 @@ done
 
 echo "Done. Icons saved to $ICONS_DIR"
 echo ""
-echo "Remember to:"
-echo "  1. Update pkg/octicons/octicons_test.go if adding new icons"
-echo "  2. Run 'UPDATE_TOOLSNAPS=true go test ./...' to update snapshots"
+echo "Next steps:"
+echo "  1. Run 'go test ./pkg/octicons/...' to verify icons are embedded"
+echo "  2. Run 'go test ./pkg/github/...' to verify toolset icons are valid"
+echo "  3. Commit the new icon files"