GitHub MCP Server 的 Toolset 与图标体系元数据定义、Octicon 嵌入与文档生成全解析【免费下载链接】github-mcp-serverGitHubs official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server导读GitHub 官方 MCP Server本仓库通过Toolset工具集将上百个工具按领域逻辑分组并为每个工具集绑定一个 Primer Octicon 图标从而让 MCP 兼容客户端Claude、Cursor、Copilot 等能以清晰、可识别的方式呈现工具列表。本文围绕仓库中的 docs/toolsets-and-icons.md 展开完整讲解工具集的元数据结构、required_icons.txt单一事实来源、script/fetch-icons图标拉取流程、图标在 MCP 协议中的 Base64 Data URI 编码方式以及 CI 中的图标一致性校验测试。读完本文你将掌握如何为现有工具集更换/新增图标、如何定义仅远程可用的工具集以及图标从选型、嵌入到生成文档的完整闭环。一、Toolset 概览工具的逻辑分组单元在 GitHub MCP Server 中工具集是相关工具的逻辑分组。每个工具集携带一组元数据全部定义在 pkg/github/tools.go 中的ToolsetMetadata*常量里例如ToolsetMetadataRepos inventory.ToolsetMetadata{ ID: repos, Description: GitHub Repository related tools, Default: true, Icon: repo, }这段代码的含义是repos工具集承载所有仓库相关工具SearchRepositories、GetFileContents、ListCommits等见 pkg/github/tools.go 中的AllTools分组注释默认启用并使用repo作为视觉标识。从源码结构看pkg/github/tools.go 定义了 20 余个工具集常量包括context、repos、git、issues、pull_requests、users、orgs、actions、code_quality、code_security、secret_protection、dependabot、notifications、discussions、gists、security_advisories、projects、stargazers、labels、copilot等此外还有两个特殊元工具集all与default分别表示启用所有工具集与启用默认工具集组合。Toolset 字段说明ToolsetMetadata结构体定义在 pkg/inventory/server_tool.go字段含义如下字段类型说明IDToolsetID唯一标识符用于 URL、CLI 标志如--toolsetsrepos,issues以及文档锚点Descriptionstring人类可读的描述展示在文档与客户端 UI 中Defaultbool该工具集是否默认启用true时无需显式声明即被注册IconstringOcticon 基础名不带尺寸后缀用于 MCP 客户端的可视化呈现InstructionsFuncfunc(*Inventory) string可选返回该工具集专属的使用说明如context、issues工具集均配置了此函数其中ID被定义为独立的ToolsetID字符串类型而非裸string这是为了在编译期提供类型安全见 pkg/inventory/server_tool.go 的注释说明。二、默认启用与 CLI 交互Default: true字段直接驱动着服务器的默认行为。在 pkg/github/tools.go 的GenerateToolsetsHelp()函数中服务器会通过NewInventory(stubTranslator).Build()构建库存再调用r.DefaultToolsetIDs()与r.AvailableToolsets(context)动态生成--toolsets标志的帮助文本包括Comma-separated list of tool groups to enable (no spaces). Special toolset keywords: - all: Enables all available toolsets - default: Enables the default toolset configuration Examples: - --toolsetsactions,gists,notifications - Default additional: --toolsetsdefault,actions,gists - All tools: --toolsetsalldefault关键字会在注册前被AddDefaultToolset()展开为实际的默认工具集 ID 列表见 pkg/github/tools.go未识别的工具集名则会在 pkg/github/server.go 处被记录为 warning 后忽略。三、为工具集添加图标五步完整流程图标帮助用户在各种 MCP 兼容客户端中快速识别工具集。本项目统一使用Primer Octicons作为图标来源即 GitHub 自身的开源图标库。Step 1挑选 Octicon浏览 Primer Octicons 图标库选择一个语义贴切的图标。务必使用不带尺寸后缀的基础名例如写repo而不是repo-16或repo-24。Step 2把图标加入必需图标清单图标是否被嵌入由 pkg/octicons/required_icons.txt 决定它是唯一事实来源single source of truth。文件采用每行一个图标名、#开头为注释、空行忽略的格式# 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该文件同时被三个环节消费script/fetch-icons下载图标、pkg/octicons/octicons_test.go 的TestEmbeddedIconsExist校验已嵌入、以及 pkg/github/toolset_icons_test.go 的工具集图标校验。从源码看RequiredIcons()函数会逐行扫描该文件并跳过注释与空行见 pkg/octicons/octicons.go。Step 3运行 fetch-icons 脚本拉取并转换图标# 拉取单个图标 script/fetch-icons your-new-icon # 或拉取 required_icons.txt 中列出的全部图标 script/fetch-iconsscript/fetch-icons 脚本内部的工作流程是从 Primer Octicons 仓库的icons/目录下载${icon}-24.svg24px SVG使用sed给 SVG 根标签注入fill颜色浅色主题用#24292f深色图标适配浅色背景深色主题用#ffffff白色图标适配深色背景通过rsvg-convert将两份 SVG 分别转换为 PNG保存为pkg/octicons/icons/${icon}-light.png与pkg/octicons/icons/${icon}-dark.png扫描pkg/octicons/icons/下全部 PNG逐行生成文件名TABdata:image/png;base64,...格式的映射写入pkg/octicons/icons_data_uris.txt。前置依赖脚本要求系统安装rsvg-convert安装方式Ubuntu/Debiansudo apt-get install librsvg2-binmacOSbrew install librsvgStep 4更新工具集元数据在工具集定义中设置或更新Icon字段// In pkg/github/tools.go ToolsetMetadataRepos inventory.ToolsetMetadata{ ID: repos, Description: GitHub Repository related tools, Default: true, Icon: repo, // 这里添加图标 }Step 5重新生成文档go run ./cmd/github-mcp-server generate-docs该命令由 cmd/github-mcp-server/generate_docs.go 实现会自动更新以下文件中的图标README.md—— 工具集表格与工具章节标题docs/remote-server.md—— 远程工具集表格从实现看generate-docs通过replaceSection替换START AUTOMATED TOOLSETS与END AUTOMATED TOOLSETS标记之间的内容其中的octiconImg()函数会生成同时引用-light.png与-dark.png的img标签借助 GitHub 的浅色/深色主题机制自动切换见 cmd/github-mcp-server/generate_docs.go。由于这些 Markdown 段落是自动生成的手动编辑会被下一次生成覆盖。四、仅远程可用的工具集Remote-Only Toolsets部分工具集只在远程 GitHub MCP Server托管于api.githubcopilot.com上可用。它们同样定义在 pkg/github/tools.go 中并配有图标但不会注册到本地服务器// Remote-only toolsets ToolsetMetadataCopilotSpaces inventory.ToolsetMetadata{ ID: copilot_spaces, Description: Copilot Spaces tools, Icon: copilot, } ToolsetMetadataSupportSearch inventory.ToolsetMetadata{ ID: github_support_docs_search, Description: Retrieve documentation to answer GitHub product and support questions. Topics include: GitHub Actions Workflows, Authentication, ..., Icon: book, }RemoteOnlyToolsets()函数见 pkg/github/tools.go返回这些工具集的元数据切片供文档生成等自动化流程使用func RemoteOnlyToolsets() []inventory.ToolsetMetadata { return []inventory.ToolsetMetadata{ ToolsetMetadataCopilotSpaces, ToolsetMetadataSupportSearch, } }添加一个新的远程专用工具集的步骤在 pkg/github/tools.go 中定义元数据常量将其加入RemoteOnlyToolsets()返回的切片重新运行go run ./cmd/github-mcp-server generate-docs生成文档。五、工具图标继承机制单个工具自动继承其所属工具集的图标无需逐个设置。核心逻辑在 pkg/inventory/server_tool.go 的RegisterFunc中// Make a shallow copy of the tool to avoid mutating the original toolCopy : st.Tool // Apply icons from toolset metadata if tool doesnt have icons set if len(toolCopy.Icons) 0 { toolCopy.Icons st.Toolset.Icons() }这里有两个值得注意的实现细节继承是有条件的只有工具自身未设置图标Icons为空时才从工具集元数据补齐工具若显式定义了图标则保留自己的。这为工具集统一图标 个别工具特例保留了扩展空间。写保护注册时对工具做浅拷贝再修改避免直接改动原始ServerTool定义防止并发注册时产生数据竞争。ToolsetMetadata.Icons()只是octicons.Icons(tm.Icon)的一层薄封装见 pkg/inventory/server_tool.go。这意味着你只需在工具集上设置一次图标该工具集内所有工具如repos下的几十个仓库工具都会展示同一个图标。六、图标在 MCP 协议中如何工作MCP 协议通过工具的icons字段支持图标。本项目为每个图标提供两种格式的变体Data URI—— 以 Base64 编码的 PNG 图片直接内嵌在工具定义中可离线使用且加载更快浅色/深色双主题—— 同时提供两种主题变体保证在亮色与暗色客户端 UI 中都能正确显示。octicons.Icons()函数负责生成 MCP 兼容的图标对象见 pkg/octicons/octicons.go// 返回同时包含浅色与深色变体的 []mcp.Icon icons : octicons.Icons(repo)其内部实现要点return []mcp.Icon{ { Source: DataURI(name, ThemeLight), // 深色图标用于浅色背景 MIMEType: image/png, Theme: mcp.IconThemeLight, }, { Source: DataURI(name, ThemeDark), // 白色图标用于深色背景 MIMEType: image/png, Theme: mcp.IconThemeDark, }, }数据来源是编译期通过//go:embed icons_data_uris.txt嵌入的映射文件。loadDataURIs()在包初始化时解析该文件每行以 Tab 分隔文件名与data:image/png;base64,...前缀的 URI并从文件名尾部的-light/-dark后缀解析出主题格式非法会直接panic见 pkg/octicons/octicons.go这种启动即崩溃的设计保证了错误的图标数据不可能悄悄上线。一个值得注意的兼容性细节Icons()生成的对象刻意省略了Sizes字段因为 2025-11-25 版 MCP 规范将其从字符串改为数组省略该字段可以兼容期望字符串类型的旧版 MCP 客户端见 pkg/octicons/octicons.go 的注释。七、现有工具集与图标的完整对照下表汇总了当前仓库中所有已配置图标含本地与远程工具集数据取自 pkg/github/tools.go 各元数据常量的Icon字段Toolset工具集 IDOcticon 图标名ContextcontextpersonRepositoriesreposrepoIssuesissuesissue-openedPull Requestspull_requestsgit-pull-requestGitgitgit-branchUsersuserspeopleOrganizationsorgsorganizationActionsactionsworkflowCode Qualitycode_qualitycode-squareCode Securitycode_securitycodescanSecret Protectionsecret_protectionshield-lockDependabotdependabotdependabotDiscussionsdiscussionscomment-discussionGistsgistslogo-gistSecurity Advisoriessecurity_advisoriesshieldProjectsprojectsprojectLabelslabelstagStargazersstargazersstarNotificationsnotificationsbellCopilotcopilotcopilotCopilot Issue Intentscopilot_issue_intents非默认、需 Opt-incopilotCopilot Spaces远程专用copilotSupport Searchgithub_support_docs_search远程专用book此外元工具集all使用apps、default使用check-circle作为图标见 pkg/github/tools.go。pkg/octicons/required_icons.txt 中还包含beaker、file、git-commit、git-merge、mark-github、repo-forked、star-fill、tools等未直接对应工具集的图标它们服务于工具级特例或文档/资源展示场景同样会被 fetch-icons 拉取并嵌入。对应的 PNG 文件位于 pkg/octicons/icons/每个图标同时存在-light.png与-dark.png两个变体。八、故障排查文档中不显示图标确认pkg/octicons/icons/中存在带-light.png与-dark.png后缀的 PNG 文件重新运行go run ./cmd/github-mcp-server generate-docs重新生成文档检查工具集元数据中是否已设置Icon字段generate-docs只会渲染已配置图标的工具集。MCP 客户端中不显示图标确认客户端支持 MCP 协议的工具图标icons字段检查pkg/octicons包是否正确生成了 Base64 Data URI可用go test ./pkg/octicons/...验证确认图标名与pkg/octicons/icons/中的文件名匹配注意使用基础名例如repo而非repo-16如果客户端报错与Sizes字段有关属于旧版客户端兼容性问题——本项目已有意省略该字段以兼容旧客户端可升级客户端到支持 2025-11-25 规范的版本。九、CI 校验把图标问题挡在合并之前仓库在 CI 中运行以下测试尽早发现图标相关的三类问题pkg/octicons.TestEmbeddedIconsExist逐条校验 pkg/octicons/required_icons.txt 中列出的每个图标都必须在嵌入集合中同时存在ThemeLight与ThemeDark两个有效的 Base64 Data URI见 pkg/octicons/octicons_test.go。pkg/github.TestAllToolsetIconsExist遍历库存中所有可用工具集含RemoteOnlyToolsets()返回的远程工具集断言每个Icon字段引用octicons.Icons(icon)返回非空、恰好包含 2 个变体、且每个变体的Source都是data:image/png;base64,前缀的合法 Data URI见 pkg/github/toolset_icons_test.go。它防止引用了一个未被嵌入的图标名这类破坏性变更被合并。pkg/github.TestToolsetMetadataHasIcons策略性测试断言所有工具集都必须设置Icon字段仅all与default两个元工具集豁免见 pkg/github/toolset_icons_test.go。与上述测试配套的还有数据层校验TestDataURIForEveryEmbeddedIcon它会遍历嵌入的全部 PNG解码 Base64 后与源文件逐字节比对确保数据 URI 与实际 PNG 完全一致见 pkg/octicons/octicons_test.go。若任一测试失败修复路径是将缺失的图标名加入 pkg/octicons/required_icons.txt运行script/fetch-icons下载并转换图标如已存在图标但缺变体可只针对该图标运行提交新增的 PNG 文件与重新生成的pkg/octicons/icons_data_uris.txt脚本最后两步会提示运行go test ./pkg/octicons/...与go test ./pkg/github/...验证。十、结语从元数据到协议的完整链路回顾整条链路工具集元数据pkg/github/tools.go→ 图标清单pkg/octicons/required_icons.txt→ 拉取转换script/fetch-icons→ 编译期嵌入//go:embed→ 运行期生成 MCP 图标对象pkg/octicons/octicons.go→ 注册时自动继承到每个工具pkg/inventory/server_tool.go→ 文档自动生成cmd/github-mcp-server generate-docs→ CI 三层校验兜底octicons_test.go与toolset_icons_test.go。理解这条链路后无论是为项目新增一个工具集、更换既有图标还是排查客户端中图标消失的问题都能在仓库内快速定位到对应环节完成一次可靠的修改并验证通过。【免费下载链接】github-mcp-serverGitHubs official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 GitHub MCP Server 的 Toolset 与图标体系：元数据定义、Octicon 嵌入与文档生成全解析
GitHub MCP Server 的 Toolset 与图标体系元数据定义、Octicon 嵌入与文档生成全解析【免费下载链接】github-mcp-serverGitHubs official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server导读GitHub 官方 MCP Server本仓库通过Toolset工具集将上百个工具按领域逻辑分组并为每个工具集绑定一个 Primer Octicon 图标从而让 MCP 兼容客户端Claude、Cursor、Copilot 等能以清晰、可识别的方式呈现工具列表。本文围绕仓库中的 docs/toolsets-and-icons.md 展开完整讲解工具集的元数据结构、required_icons.txt单一事实来源、script/fetch-icons图标拉取流程、图标在 MCP 协议中的 Base64 Data URI 编码方式以及 CI 中的图标一致性校验测试。读完本文你将掌握如何为现有工具集更换/新增图标、如何定义仅远程可用的工具集以及图标从选型、嵌入到生成文档的完整闭环。一、Toolset 概览工具的逻辑分组单元在 GitHub MCP Server 中工具集是相关工具的逻辑分组。每个工具集携带一组元数据全部定义在 pkg/github/tools.go 中的ToolsetMetadata*常量里例如ToolsetMetadataRepos inventory.ToolsetMetadata{ ID: repos, Description: GitHub Repository related tools, Default: true, Icon: repo, }这段代码的含义是repos工具集承载所有仓库相关工具SearchRepositories、GetFileContents、ListCommits等见 pkg/github/tools.go 中的AllTools分组注释默认启用并使用repo作为视觉标识。从源码结构看pkg/github/tools.go 定义了 20 余个工具集常量包括context、repos、git、issues、pull_requests、users、orgs、actions、code_quality、code_security、secret_protection、dependabot、notifications、discussions、gists、security_advisories、projects、stargazers、labels、copilot等此外还有两个特殊元工具集all与default分别表示启用所有工具集与启用默认工具集组合。Toolset 字段说明ToolsetMetadata结构体定义在 pkg/inventory/server_tool.go字段含义如下字段类型说明IDToolsetID唯一标识符用于 URL、CLI 标志如--toolsetsrepos,issues以及文档锚点Descriptionstring人类可读的描述展示在文档与客户端 UI 中Defaultbool该工具集是否默认启用true时无需显式声明即被注册IconstringOcticon 基础名不带尺寸后缀用于 MCP 客户端的可视化呈现InstructionsFuncfunc(*Inventory) string可选返回该工具集专属的使用说明如context、issues工具集均配置了此函数其中ID被定义为独立的ToolsetID字符串类型而非裸string这是为了在编译期提供类型安全见 pkg/inventory/server_tool.go 的注释说明。二、默认启用与 CLI 交互Default: true字段直接驱动着服务器的默认行为。在 pkg/github/tools.go 的GenerateToolsetsHelp()函数中服务器会通过NewInventory(stubTranslator).Build()构建库存再调用r.DefaultToolsetIDs()与r.AvailableToolsets(context)动态生成--toolsets标志的帮助文本包括Comma-separated list of tool groups to enable (no spaces). Special toolset keywords: - all: Enables all available toolsets - default: Enables the default toolset configuration Examples: - --toolsetsactions,gists,notifications - Default additional: --toolsetsdefault,actions,gists - All tools: --toolsetsalldefault关键字会在注册前被AddDefaultToolset()展开为实际的默认工具集 ID 列表见 pkg/github/tools.go未识别的工具集名则会在 pkg/github/server.go 处被记录为 warning 后忽略。三、为工具集添加图标五步完整流程图标帮助用户在各种 MCP 兼容客户端中快速识别工具集。本项目统一使用Primer Octicons作为图标来源即 GitHub 自身的开源图标库。Step 1挑选 Octicon浏览 Primer Octicons 图标库选择一个语义贴切的图标。务必使用不带尺寸后缀的基础名例如写repo而不是repo-16或repo-24。Step 2把图标加入必需图标清单图标是否被嵌入由 pkg/octicons/required_icons.txt 决定它是唯一事实来源single source of truth。文件采用每行一个图标名、#开头为注释、空行忽略的格式# 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该文件同时被三个环节消费script/fetch-icons下载图标、pkg/octicons/octicons_test.go 的TestEmbeddedIconsExist校验已嵌入、以及 pkg/github/toolset_icons_test.go 的工具集图标校验。从源码看RequiredIcons()函数会逐行扫描该文件并跳过注释与空行见 pkg/octicons/octicons.go。Step 3运行 fetch-icons 脚本拉取并转换图标# 拉取单个图标 script/fetch-icons your-new-icon # 或拉取 required_icons.txt 中列出的全部图标 script/fetch-iconsscript/fetch-icons 脚本内部的工作流程是从 Primer Octicons 仓库的icons/目录下载${icon}-24.svg24px SVG使用sed给 SVG 根标签注入fill颜色浅色主题用#24292f深色图标适配浅色背景深色主题用#ffffff白色图标适配深色背景通过rsvg-convert将两份 SVG 分别转换为 PNG保存为pkg/octicons/icons/${icon}-light.png与pkg/octicons/icons/${icon}-dark.png扫描pkg/octicons/icons/下全部 PNG逐行生成文件名TABdata:image/png;base64,...格式的映射写入pkg/octicons/icons_data_uris.txt。前置依赖脚本要求系统安装rsvg-convert安装方式Ubuntu/Debiansudo apt-get install librsvg2-binmacOSbrew install librsvgStep 4更新工具集元数据在工具集定义中设置或更新Icon字段// In pkg/github/tools.go ToolsetMetadataRepos inventory.ToolsetMetadata{ ID: repos, Description: GitHub Repository related tools, Default: true, Icon: repo, // 这里添加图标 }Step 5重新生成文档go run ./cmd/github-mcp-server generate-docs该命令由 cmd/github-mcp-server/generate_docs.go 实现会自动更新以下文件中的图标README.md—— 工具集表格与工具章节标题docs/remote-server.md—— 远程工具集表格从实现看generate-docs通过replaceSection替换START AUTOMATED TOOLSETS与END AUTOMATED TOOLSETS标记之间的内容其中的octiconImg()函数会生成同时引用-light.png与-dark.png的img标签借助 GitHub 的浅色/深色主题机制自动切换见 cmd/github-mcp-server/generate_docs.go。由于这些 Markdown 段落是自动生成的手动编辑会被下一次生成覆盖。四、仅远程可用的工具集Remote-Only Toolsets部分工具集只在远程 GitHub MCP Server托管于api.githubcopilot.com上可用。它们同样定义在 pkg/github/tools.go 中并配有图标但不会注册到本地服务器// Remote-only toolsets ToolsetMetadataCopilotSpaces inventory.ToolsetMetadata{ ID: copilot_spaces, Description: Copilot Spaces tools, Icon: copilot, } ToolsetMetadataSupportSearch inventory.ToolsetMetadata{ ID: github_support_docs_search, Description: Retrieve documentation to answer GitHub product and support questions. Topics include: GitHub Actions Workflows, Authentication, ..., Icon: book, }RemoteOnlyToolsets()函数见 pkg/github/tools.go返回这些工具集的元数据切片供文档生成等自动化流程使用func RemoteOnlyToolsets() []inventory.ToolsetMetadata { return []inventory.ToolsetMetadata{ ToolsetMetadataCopilotSpaces, ToolsetMetadataSupportSearch, } }添加一个新的远程专用工具集的步骤在 pkg/github/tools.go 中定义元数据常量将其加入RemoteOnlyToolsets()返回的切片重新运行go run ./cmd/github-mcp-server generate-docs生成文档。五、工具图标继承机制单个工具自动继承其所属工具集的图标无需逐个设置。核心逻辑在 pkg/inventory/server_tool.go 的RegisterFunc中// Make a shallow copy of the tool to avoid mutating the original toolCopy : st.Tool // Apply icons from toolset metadata if tool doesnt have icons set if len(toolCopy.Icons) 0 { toolCopy.Icons st.Toolset.Icons() }这里有两个值得注意的实现细节继承是有条件的只有工具自身未设置图标Icons为空时才从工具集元数据补齐工具若显式定义了图标则保留自己的。这为工具集统一图标 个别工具特例保留了扩展空间。写保护注册时对工具做浅拷贝再修改避免直接改动原始ServerTool定义防止并发注册时产生数据竞争。ToolsetMetadata.Icons()只是octicons.Icons(tm.Icon)的一层薄封装见 pkg/inventory/server_tool.go。这意味着你只需在工具集上设置一次图标该工具集内所有工具如repos下的几十个仓库工具都会展示同一个图标。六、图标在 MCP 协议中如何工作MCP 协议通过工具的icons字段支持图标。本项目为每个图标提供两种格式的变体Data URI—— 以 Base64 编码的 PNG 图片直接内嵌在工具定义中可离线使用且加载更快浅色/深色双主题—— 同时提供两种主题变体保证在亮色与暗色客户端 UI 中都能正确显示。octicons.Icons()函数负责生成 MCP 兼容的图标对象见 pkg/octicons/octicons.go// 返回同时包含浅色与深色变体的 []mcp.Icon icons : octicons.Icons(repo)其内部实现要点return []mcp.Icon{ { Source: DataURI(name, ThemeLight), // 深色图标用于浅色背景 MIMEType: image/png, Theme: mcp.IconThemeLight, }, { Source: DataURI(name, ThemeDark), // 白色图标用于深色背景 MIMEType: image/png, Theme: mcp.IconThemeDark, }, }数据来源是编译期通过//go:embed icons_data_uris.txt嵌入的映射文件。loadDataURIs()在包初始化时解析该文件每行以 Tab 分隔文件名与data:image/png;base64,...前缀的 URI并从文件名尾部的-light/-dark后缀解析出主题格式非法会直接panic见 pkg/octicons/octicons.go这种启动即崩溃的设计保证了错误的图标数据不可能悄悄上线。一个值得注意的兼容性细节Icons()生成的对象刻意省略了Sizes字段因为 2025-11-25 版 MCP 规范将其从字符串改为数组省略该字段可以兼容期望字符串类型的旧版 MCP 客户端见 pkg/octicons/octicons.go 的注释。七、现有工具集与图标的完整对照下表汇总了当前仓库中所有已配置图标含本地与远程工具集数据取自 pkg/github/tools.go 各元数据常量的Icon字段Toolset工具集 IDOcticon 图标名ContextcontextpersonRepositoriesreposrepoIssuesissuesissue-openedPull Requestspull_requestsgit-pull-requestGitgitgit-branchUsersuserspeopleOrganizationsorgsorganizationActionsactionsworkflowCode Qualitycode_qualitycode-squareCode Securitycode_securitycodescanSecret Protectionsecret_protectionshield-lockDependabotdependabotdependabotDiscussionsdiscussionscomment-discussionGistsgistslogo-gistSecurity Advisoriessecurity_advisoriesshieldProjectsprojectsprojectLabelslabelstagStargazersstargazersstarNotificationsnotificationsbellCopilotcopilotcopilotCopilot Issue Intentscopilot_issue_intents非默认、需 Opt-incopilotCopilot Spaces远程专用copilotSupport Searchgithub_support_docs_search远程专用book此外元工具集all使用apps、default使用check-circle作为图标见 pkg/github/tools.go。pkg/octicons/required_icons.txt 中还包含beaker、file、git-commit、git-merge、mark-github、repo-forked、star-fill、tools等未直接对应工具集的图标它们服务于工具级特例或文档/资源展示场景同样会被 fetch-icons 拉取并嵌入。对应的 PNG 文件位于 pkg/octicons/icons/每个图标同时存在-light.png与-dark.png两个变体。八、故障排查文档中不显示图标确认pkg/octicons/icons/中存在带-light.png与-dark.png后缀的 PNG 文件重新运行go run ./cmd/github-mcp-server generate-docs重新生成文档检查工具集元数据中是否已设置Icon字段generate-docs只会渲染已配置图标的工具集。MCP 客户端中不显示图标确认客户端支持 MCP 协议的工具图标icons字段检查pkg/octicons包是否正确生成了 Base64 Data URI可用go test ./pkg/octicons/...验证确认图标名与pkg/octicons/icons/中的文件名匹配注意使用基础名例如repo而非repo-16如果客户端报错与Sizes字段有关属于旧版客户端兼容性问题——本项目已有意省略该字段以兼容旧客户端可升级客户端到支持 2025-11-25 规范的版本。九、CI 校验把图标问题挡在合并之前仓库在 CI 中运行以下测试尽早发现图标相关的三类问题pkg/octicons.TestEmbeddedIconsExist逐条校验 pkg/octicons/required_icons.txt 中列出的每个图标都必须在嵌入集合中同时存在ThemeLight与ThemeDark两个有效的 Base64 Data URI见 pkg/octicons/octicons_test.go。pkg/github.TestAllToolsetIconsExist遍历库存中所有可用工具集含RemoteOnlyToolsets()返回的远程工具集断言每个Icon字段引用octicons.Icons(icon)返回非空、恰好包含 2 个变体、且每个变体的Source都是data:image/png;base64,前缀的合法 Data URI见 pkg/github/toolset_icons_test.go。它防止引用了一个未被嵌入的图标名这类破坏性变更被合并。pkg/github.TestToolsetMetadataHasIcons策略性测试断言所有工具集都必须设置Icon字段仅all与default两个元工具集豁免见 pkg/github/toolset_icons_test.go。与上述测试配套的还有数据层校验TestDataURIForEveryEmbeddedIcon它会遍历嵌入的全部 PNG解码 Base64 后与源文件逐字节比对确保数据 URI 与实际 PNG 完全一致见 pkg/octicons/octicons_test.go。若任一测试失败修复路径是将缺失的图标名加入 pkg/octicons/required_icons.txt运行script/fetch-icons下载并转换图标如已存在图标但缺变体可只针对该图标运行提交新增的 PNG 文件与重新生成的pkg/octicons/icons_data_uris.txt脚本最后两步会提示运行go test ./pkg/octicons/...与go test ./pkg/github/...验证。十、结语从元数据到协议的完整链路回顾整条链路工具集元数据pkg/github/tools.go→ 图标清单pkg/octicons/required_icons.txt→ 拉取转换script/fetch-icons→ 编译期嵌入//go:embed→ 运行期生成 MCP 图标对象pkg/octicons/octicons.go→ 注册时自动继承到每个工具pkg/inventory/server_tool.go→ 文档自动生成cmd/github-mcp-server generate-docs→ CI 三层校验兜底octicons_test.go与toolset_icons_test.go。理解这条链路后无论是为项目新增一个工具集、更换既有图标还是排查客户端中图标消失的问题都能在仓库内快速定位到对应环节完成一次可靠的修改并验证通过。【免费下载链接】github-mcp-serverGitHubs official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考