octicons.go

// Package octicons provides helpers for working with GitHub Octicon icons.
// See https://primer.style/foundations/icons for available icons.
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

const (
	// ThemeLight is for light backgrounds (dark/black icons).
	ThemeLight Theme = "light"
	// ThemeDark is for dark backgrounds (light/white icons).
	ThemeDark Theme = "dark"
)

// DataURI returns a data URI for the embedded Octicon PNG.
// The theme parameter specifies which variant to use:
// - ThemeLight: dark icons for light backgrounds
// - ThemeDark: light icons for dark backgrounds
// If the icon is not found in the embedded filesystem, it returns an empty string.
func DataURI(name string, theme Theme) string {
	filename := fmt.Sprintf("icons/%s-%s.png", name, theme)
	data, err := iconsFS.ReadFile(filename)
	if err != nil {
		return ""
	}
	return "data:image/png;base64," + base64.StdEncoding.EncodeToString(data)
}

// Icons returns MCP Icon objects for the given octicon name in light and dark themes.
// Icons are embedded as 24x24 PNG data URIs for offline use and faster loading.
// The name should be the base octicon name without size suffix (e.g., "repo" not "repo-16").
// See https://primer.style/foundations/icons for available icons.
//
// Note: The Sizes field is omitted for backward compatibility with older MCP clients
// that expect it to be a string rather than an array per the 2025-11-25 MCP spec.
func Icons(name string) []mcp.Icon {
	if name == "" {
		return nil
	}
	return []mcp.Icon{
		{
			Source:   DataURI(name, ThemeLight),
			MIMEType: "image/png",
			Theme:    mcp.IconThemeLight,
		},
		{
			Source:   DataURI(name, ThemeDark),
			MIMEType: "image/png",
			Theme:    mcp.IconThemeDark,
		},
	}
}