GitHub MCP Server 工具可见性与描述覆盖机制拆解一个 Builder 看清 ~90 个工具如何被筛出【免费下载链接】github-mcp-serverGitHubs official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-serverGitHub MCP Server 是 GitHub 官方的 MCPModel Context Protocol模型上下文协议服务端它把 AI 客户端变成 GitHub 的遥控器你在编辑器里说一句列出这个仓库的未合并 PR它就去调 GitHub GraphQL/REST API 并返回结果。下面带你从源码级看它如何筛选工具、如何用 i18n 覆盖机制重写工具描述。先说清楚它解决的三类真实痛点痛点一AI 客户端不知道现在能看到哪些 GitHub 工具。MCP 的tools/list决定模型能调用什么。这个仓库注册了约 90 个工具pkg/github/下按领域拆成issues.go、pullrequests.go、code_scanning.go等文件但你大概率只想暴露其中一部分。--toolsets、--tools、--exclude-tools三个开关就是为此设计的。痛点二token 权限不够时工具列表骗了模型。一个只有public_repo的 PAT 面对能写 Issue 的工具列表模型会自信地发起写操作然后报错。pkg/github/scope_filter.go在启动时就按 token 实际 scope 把够不着的工具藏掉。痛点三工具描述是英文的团队想换语言或换措辞。pkg/translations/translations.go提供了一个三级覆盖机制环境变量 JSON 配置文件 代码默认值不改一行代码就能把工具描述换成中文、日文。一张图看全局工具从注册到可见的过滤管道先记住这张判断图——后续每个小节都在拆解其中一段顺序有讲究--tools是绕过 toolset 但不过滤器的旁路--exclude-tools和 scope 过滤则优先级更高谁拦都躲不掉。描述覆盖的三级优先级在哪里实现打开pkg/translations/translations.go整个国际化机制就是这个闭包func TranslationHelper() (TranslationHelperFunc, func()) { var translationKeyMap map[string]string{} v : viper.New() v.SetConfigName(github-mcp-server-config) v.SetConfigType(json) v.AddConfigPath(.) if err : v.ReadInConfig(); err ! nil { if _, ok : err.(viper.ConfigFileNotFoundError); !ok { log.Printf(Could not read JSON config: %v, err) } } return func(key string, defaultValue string) string { key strings.ToUpper(key) if value, exists : translationKeyMap[key]; exists { return value } // check if the env var exists if value, exists : os.LookupEnv(GITHUB_MCP_ key); exists { translationKeyMap[key] value return value } v.SetDefault(key, defaultValue) translationKeyMap[key] v.GetString(key) return translationKeyMap[key] }, func() { // dump the translationKeyMap to a json file if err : DumpTranslationKeyMap(translationKeyMap); err ! nil { log.Fatalf(Could not dump translation key map: %v, err) } } }解读第一级是闭包外的translationKeyMap内存缓存保证每个 key 只解析一次90 个工具、每个两三个 key这个缓存避免重复查环境变量第二级是GITHUB_MCP_前缀的环境变量源码里那句// TODO I could not get Viper to play ball注释暴露了作者放弃了用 viper 读环境变量、改手写os.LookupEnv——这是务实的取舍第三级才落到viper读 JSON 文件或代码默认值。返回的第二个函数配合--export-translations启动参数能把已解析的全部键值 dump 成github-mcp-server-config.json方便你拿到完整键名清单再翻译。工具定义里长这样pkg/github/git.goDescription: t(TOOL_GET_REPOSITORY_TREE_DESCRIPTION, Get the tree structure (files and directories) of a GitHub repository at a specific ref or SHA), // ... Title: t(TOOL_GET_REPOSITORY_TREE_USER_TITLE, Get repository tree),键名规律是TOOL_工具名大写_DESCRIPTION|USER_TITLE。点评好处是把默认文案内联在调用点翻译永远不缺默认值NullTranslationHelper测试用直接返回默认值即可坑在于 key 是字符串字面量拼出来的写错了编译器不报错只能靠--export-translations导出后比对。工具集展开nil、空切片、all 是三种完全不同的语义pkg/inventory/builder.go的processToolsets()处理--toolsets参数时最容易被忽略的是nil与空切片的区分func (b *Builder) WithToolsets(toolsetIDs []string) *Builder { b.toolsetIDs toolsetIDs b.toolsetIDsIsNil toolsetIDs nil return b } // ... // all keyword - enables all toolsets for _, id : range toolsetIDs { if strings.TrimSpace(id) all { return nil, nil, allToolsetIDs, validIDs, defaultToolsetIDList, descriptions // nil means all enabled } } // nil means use defaults, empty slice means no toolsets if b.toolsetIDsIsNil { toolsetIDs []string{default} }注意cmd/github-mcp-server/main.go里配套的防御作者特意不用viper.GetStringSlice(toolsets)注释引用了 viper 对逗号分隔环境变量的已知缺陷而是先viper.IsSet(toolsets)判断——没设置就让enabledToolsets保持nil走默认 toolset分支。这个三元语义是不传 默认 toolset 组传all 全部传default 显式展开标记了Default: true的 toolset。点评语义清晰但隐蔽--toolsets和完全不传是两回事另外传了不认识的 toolset ID 不会报错只是记录进unrecognizedToolsets供告警拼错了的工具集会静默失效这是典型的坑。scope 过滤PAT 的软权限检查HTTP 模式下服务端可以发 OAuth scope challenge 让客户端补授权但 stdio 模式拿的是用户的 PAT没法这么玩。pkg/github/scope_filter.go的解法是藏工具var repoScopesSet map[string]bool{ string(scopes.Repo): true, string(scopes.PublicRepo): true, } // ... func CreateToolScopeFilter(tokenScopes []string) inventory.ToolFilter { return func(_ context.Context, tool *inventory.ServerTool) (bool, error) { // Read-only tools requiring only repo/public_repo work on public repos without any scope if tool.Tool.Annotations ! nil tool.Tool.Annotations.ReadOnlyHint onlyRequiresRepoScopes(tool.AcceptedScopes) { return true, nil } if len(tool.RequiredScopeGroups) 0 { return scopes.HasRequiredScopeGroups(tokenScopes, tool.RequiredScopeGroups), nil } return scopes.HasRequiredScopes(tokenScopes, tool.AcceptedScopes), nil } }规则是无 scope 要求的工具放行只读且只需要repo/public_repo的工具放行公开仓库本来就免 scope 可读其余按 token 实际 scope 匹配。触发点在internal/ghmcp/server.gostrings.HasPrefix(cfg.Token, ghp_)判断是经典 PAT 才去FetchTokenScopes抓不到就降级为不过滤并打 warn 日志。点评好在这种隐藏而非拦截避免了模型反复撞墙坑在于细粒度 PAT 和 GitHub App token 不 advertise scope会整体跳过过滤——你看到的工具列表可能比 token 实际能做的多。认证模式互斥与零配置登录的边界cmd/github-mcp-server/main.go的stdio子命令开头做了三种认证模式的互斥校验oauthClientID : viper.GetString(oauth-client-id) // ... if oauthClientID !appAuthRequested oauth.NormalizeHost(viper.GetString(host)) https://github.com { oauthClientID buildinfo.OAuthClientID oauthClientSecret buildinfo.OAuthClientSecret } if token !appAuthRequested oauthClientID { return errors.New(authentication required: set GITHUB_PERSONAL_ACCESS_TOKEN, configure GitHub App auth, or pass --oauth-client-id to log in via OAuth) } if appAuthRequested token ! { return errors.New(GitHub App authentication and GITHUB_PERSONAL_ACCESS_TOKEN are mutually exclusive: set only one) }三种模式静态GITHUB_PERSONAL_ACCESS_TOKEN、GitHub App--app-id 私有钥文件服务间认证、OAuth 浏览器登录--oauth-client-id。注意那个回退逻辑只有当 host 归一化后是https://github.com时才启用编译期内置的 OAuth client——GHESGitHub Enterprise Server用户必须自带--oauth-client-id。点评把零配置边界划在官方站点这一个点很克制坑在于 GHES 用户第一次跑会直接收到 authentication required 报错得自己注册 OAuth App。HTTP 模式的性能设计ForMCPRequest 只注册一个工具pkg/inventory/registry.go的ForMCPRequest(method, itemName)是远程/HTTP 模式的关键优化。注释写得很直白per-request 实例only register the items needed for that specific request rather than all ~90 toolsswitch method { case MCPMethodInitialize, MCPMethodDiscover: clearAll() case MCPMethodToolsList: result.resourceTemplates, result.prompts nil, nil case MCPMethodToolsCall: result.resourceTemplates, result.prompts nil, nil if itemName ! { result.tools r.filterToolsByName(itemName) } // ... }每次请求浅拷贝一份 Inventory、清空与本次请求无关的条目tools/call get_job_logs就只注册get_job_logs这一个工具。为什么必须这么干因为 MCP 注册表里同名工具只能存在一份而 feature flag 切换时新旧两个变体可能共用一个名字filterToolsByName的注释专门解释了这点GetJobLogs和ActionsGetJobLogs都叫get_job_logs但受不同 flag 控制。点评这是请求级投影模式代价是每请求一次浅拷贝换来注册表永远干净——比全局注册 90 个再靠名字去重可靠得多。配置源对照同一件事的不同配置方式配置源行为优先级 / 开销适用场景GITHUB_MCP_KEY环境变量覆盖任意TOOL_*键及SERVER_NAME/SERVER_TITLE最高启动时一次读取后入缓存容器化部署、CI 中按环境切换文案github-mcp-server-config.json二进制同目录键值对覆盖描述中viper 启动时读一次团队共享的固定翻译文件代码默认值t(key, default)第二参数英文原文最低零配置开发、未做任何本地化--tools按名追加单个工具绕过 toolset 筛选与 toolset 叠加OR 关系只多开一两个工具--exclude-tools强制隐藏压过以上一切对工具名最高黑名单式禁用三步跑通最小部署# 1. 克隆并构建Go 项目需要本机装了 Go 工具链 git clone https://gitcode.com/GitHub_Trending/gi/github-mcp-server cd github-mcp-server go build ./cmd/github-mcp-server # 预期当前目录生成 github-mcp-server 二进制 # 2. 用 PAT 启动 stdio 服务器 GITHUB_PERSONAL_ACCESS_TOKENghp_xxx ./github-mcp-server stdio # 预期stderr 输出 GitHub MCP Server running on stdio进程随后阻塞等待 stdin 的 JSON-RPC # 3. 导出全部翻译键作为你的本地化底稿 GITHUB_PERSONAL_ACCESS_TOKENghp_xxx ./github-mcp-server stdio --export-translations # 预期当前目录生成 github-mcp-server-config.json含 TOOL_* 全量键进程随后报错退出属正常进阶技巧与避坑现象设置了GITHUB_MCP_TOOL_GET_COMMITS_DESCRIPTION但描述没变。原因key 会被strings.ToUpper归一后匹配但环境变量前缀必须严格是GITHUB_MCP_全大写且 JSON 文件必须与二进制同目录v.AddConfigPath(.)只认当前目录。处理先--export-translations导出确认真实 key 名再对照检查前缀。现象明明配了--tools get_job_logs工具列表里却没有。原因--tools只是绕过 toolset 这一关scope 过滤器和 feature flag 过滤器仍然生效若该工具挂在未开启的 feature flag 后面照样被藏。处理用--features打开对应 flag或确认 PAT scope 满足RequiredScopeGroups。现象--toolsets完全不生效行为像没传。原因viper 对逗号分隔环境变量的GetStringSlice有已知缺陷作者因此在 main.go 改用IsSetUnmarshalKey如果你绕过 CLI 直接改环境变量注意下划线替换-→_。处理优先用命令行 flag 而非环境变量传列表参数。现象同时设了GITHUB_PERSONAL_ACCESS_TOKEN和--app-id进程直接退出。原因RunStdioServer开头统计三种认证模式开启数1即报choose exactly one authentication mode。处理三种认证PAT / GitHub App / OAuth client只能选一。现象传了不认识的 toolset ID没报错但工具变少了。原因processToolsets把未识别 ID 记入unrecognizedToolsets但不 fail-fast。处理用--toolsets all先确认全量工具再逐步收窄。FAQ--tools和--toolsets到底什么关系叠加ORtoolset 决定基线集合--tools里的工具即使不在启用 toolset 中也会加入但两者都躲不过 scope 过滤、feature flag 和--exclude-tools。为什么我换了 token工具列表反而少了经典 PATghp_前缀会触发FetchTokenScopes做 scope 过滤token 权限变小被隐藏的工具就变多。抓 scope 失败时是 warn 后不过滤日志里能看到。怎么让多个实例github.com GHES在客户端里区分开用同一套覆盖机制改SERVER_NAME/SERVER_TITLEJSON 里写{SERVER_NAME: ghes-mcp-server}或export GITHUB_MCP_SERVER_NAMEghes-mcp-serverREADME 有专门章节。--read-only是怎么过滤的过滤器链第 2 步见isToolEnabled按工具自带的IsReadOnly()判定剔除写工具且它压过--tools的追加。这个项目只做 i18n 吗不是。i18n 只是描述层核心价值是工具面管理toolset/scope/feature flag 三级筛选、认证互斥、lockdown 模式、per-request 注册优化这一整套工具可见性基础设施。适用边界适合本地 AI 客户端IDE 插件、CLI agent接 GitHubCI 里做只读审计--read-onlyGHES 环境私有化部署需要按环境定制工具面与文案的团队。 不适合直接暴露到公网做多租户服务它是单 token 模型HTTP 模式面向的是你自己的 host 接入不是公共 API 网关需要运行时热切换 toolset的场景——工具面在启动时构建改配置要重启以及把pkg/当稳定库依赖——README 明确声明导出的 Go API 目前是 unstable、可能有 breaking change。写在最后回到那个 Builder整个 GitHub MCP Server 的工具可见性问题被拆成了静态注册 过滤器链 请求级投影三段每段独立可测、顺序固定、语义无歧义。i18n 那个 60 行的闭包同理——三级优先级写在一个函数里缓存、fallback、导出全在一处。如果你自己的项目也面临能力很多、每个环境暴露不一、文案要本地化的问题这套注册表 有序过滤器 key 覆盖闭包的组合值得直接搬。【免费下载链接】github-mcp-serverGitHubs official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
GitHub MCP Server 工具可见性与描述覆盖机制拆解：一个 Builder 看清 ~90 个工具如何被筛出
GitHub MCP Server 工具可见性与描述覆盖机制拆解一个 Builder 看清 ~90 个工具如何被筛出【免费下载链接】github-mcp-serverGitHubs official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-serverGitHub MCP Server 是 GitHub 官方的 MCPModel Context Protocol模型上下文协议服务端它把 AI 客户端变成 GitHub 的遥控器你在编辑器里说一句列出这个仓库的未合并 PR它就去调 GitHub GraphQL/REST API 并返回结果。下面带你从源码级看它如何筛选工具、如何用 i18n 覆盖机制重写工具描述。先说清楚它解决的三类真实痛点痛点一AI 客户端不知道现在能看到哪些 GitHub 工具。MCP 的tools/list决定模型能调用什么。这个仓库注册了约 90 个工具pkg/github/下按领域拆成issues.go、pullrequests.go、code_scanning.go等文件但你大概率只想暴露其中一部分。--toolsets、--tools、--exclude-tools三个开关就是为此设计的。痛点二token 权限不够时工具列表骗了模型。一个只有public_repo的 PAT 面对能写 Issue 的工具列表模型会自信地发起写操作然后报错。pkg/github/scope_filter.go在启动时就按 token 实际 scope 把够不着的工具藏掉。痛点三工具描述是英文的团队想换语言或换措辞。pkg/translations/translations.go提供了一个三级覆盖机制环境变量 JSON 配置文件 代码默认值不改一行代码就能把工具描述换成中文、日文。一张图看全局工具从注册到可见的过滤管道先记住这张判断图——后续每个小节都在拆解其中一段顺序有讲究--tools是绕过 toolset 但不过滤器的旁路--exclude-tools和 scope 过滤则优先级更高谁拦都躲不掉。描述覆盖的三级优先级在哪里实现打开pkg/translations/translations.go整个国际化机制就是这个闭包func TranslationHelper() (TranslationHelperFunc, func()) { var translationKeyMap map[string]string{} v : viper.New() v.SetConfigName(github-mcp-server-config) v.SetConfigType(json) v.AddConfigPath(.) if err : v.ReadInConfig(); err ! nil { if _, ok : err.(viper.ConfigFileNotFoundError); !ok { log.Printf(Could not read JSON config: %v, err) } } return func(key string, defaultValue string) string { key strings.ToUpper(key) if value, exists : translationKeyMap[key]; exists { return value } // check if the env var exists if value, exists : os.LookupEnv(GITHUB_MCP_ key); exists { translationKeyMap[key] value return value } v.SetDefault(key, defaultValue) translationKeyMap[key] v.GetString(key) return translationKeyMap[key] }, func() { // dump the translationKeyMap to a json file if err : DumpTranslationKeyMap(translationKeyMap); err ! nil { log.Fatalf(Could not dump translation key map: %v, err) } } }解读第一级是闭包外的translationKeyMap内存缓存保证每个 key 只解析一次90 个工具、每个两三个 key这个缓存避免重复查环境变量第二级是GITHUB_MCP_前缀的环境变量源码里那句// TODO I could not get Viper to play ball注释暴露了作者放弃了用 viper 读环境变量、改手写os.LookupEnv——这是务实的取舍第三级才落到viper读 JSON 文件或代码默认值。返回的第二个函数配合--export-translations启动参数能把已解析的全部键值 dump 成github-mcp-server-config.json方便你拿到完整键名清单再翻译。工具定义里长这样pkg/github/git.goDescription: t(TOOL_GET_REPOSITORY_TREE_DESCRIPTION, Get the tree structure (files and directories) of a GitHub repository at a specific ref or SHA), // ... Title: t(TOOL_GET_REPOSITORY_TREE_USER_TITLE, Get repository tree),键名规律是TOOL_工具名大写_DESCRIPTION|USER_TITLE。点评好处是把默认文案内联在调用点翻译永远不缺默认值NullTranslationHelper测试用直接返回默认值即可坑在于 key 是字符串字面量拼出来的写错了编译器不报错只能靠--export-translations导出后比对。工具集展开nil、空切片、all 是三种完全不同的语义pkg/inventory/builder.go的processToolsets()处理--toolsets参数时最容易被忽略的是nil与空切片的区分func (b *Builder) WithToolsets(toolsetIDs []string) *Builder { b.toolsetIDs toolsetIDs b.toolsetIDsIsNil toolsetIDs nil return b } // ... // all keyword - enables all toolsets for _, id : range toolsetIDs { if strings.TrimSpace(id) all { return nil, nil, allToolsetIDs, validIDs, defaultToolsetIDList, descriptions // nil means all enabled } } // nil means use defaults, empty slice means no toolsets if b.toolsetIDsIsNil { toolsetIDs []string{default} }注意cmd/github-mcp-server/main.go里配套的防御作者特意不用viper.GetStringSlice(toolsets)注释引用了 viper 对逗号分隔环境变量的已知缺陷而是先viper.IsSet(toolsets)判断——没设置就让enabledToolsets保持nil走默认 toolset分支。这个三元语义是不传 默认 toolset 组传all 全部传default 显式展开标记了Default: true的 toolset。点评语义清晰但隐蔽--toolsets和完全不传是两回事另外传了不认识的 toolset ID 不会报错只是记录进unrecognizedToolsets供告警拼错了的工具集会静默失效这是典型的坑。scope 过滤PAT 的软权限检查HTTP 模式下服务端可以发 OAuth scope challenge 让客户端补授权但 stdio 模式拿的是用户的 PAT没法这么玩。pkg/github/scope_filter.go的解法是藏工具var repoScopesSet map[string]bool{ string(scopes.Repo): true, string(scopes.PublicRepo): true, } // ... func CreateToolScopeFilter(tokenScopes []string) inventory.ToolFilter { return func(_ context.Context, tool *inventory.ServerTool) (bool, error) { // Read-only tools requiring only repo/public_repo work on public repos without any scope if tool.Tool.Annotations ! nil tool.Tool.Annotations.ReadOnlyHint onlyRequiresRepoScopes(tool.AcceptedScopes) { return true, nil } if len(tool.RequiredScopeGroups) 0 { return scopes.HasRequiredScopeGroups(tokenScopes, tool.RequiredScopeGroups), nil } return scopes.HasRequiredScopes(tokenScopes, tool.AcceptedScopes), nil } }规则是无 scope 要求的工具放行只读且只需要repo/public_repo的工具放行公开仓库本来就免 scope 可读其余按 token 实际 scope 匹配。触发点在internal/ghmcp/server.gostrings.HasPrefix(cfg.Token, ghp_)判断是经典 PAT 才去FetchTokenScopes抓不到就降级为不过滤并打 warn 日志。点评好在这种隐藏而非拦截避免了模型反复撞墙坑在于细粒度 PAT 和 GitHub App token 不 advertise scope会整体跳过过滤——你看到的工具列表可能比 token 实际能做的多。认证模式互斥与零配置登录的边界cmd/github-mcp-server/main.go的stdio子命令开头做了三种认证模式的互斥校验oauthClientID : viper.GetString(oauth-client-id) // ... if oauthClientID !appAuthRequested oauth.NormalizeHost(viper.GetString(host)) https://github.com { oauthClientID buildinfo.OAuthClientID oauthClientSecret buildinfo.OAuthClientSecret } if token !appAuthRequested oauthClientID { return errors.New(authentication required: set GITHUB_PERSONAL_ACCESS_TOKEN, configure GitHub App auth, or pass --oauth-client-id to log in via OAuth) } if appAuthRequested token ! { return errors.New(GitHub App authentication and GITHUB_PERSONAL_ACCESS_TOKEN are mutually exclusive: set only one) }三种模式静态GITHUB_PERSONAL_ACCESS_TOKEN、GitHub App--app-id 私有钥文件服务间认证、OAuth 浏览器登录--oauth-client-id。注意那个回退逻辑只有当 host 归一化后是https://github.com时才启用编译期内置的 OAuth client——GHESGitHub Enterprise Server用户必须自带--oauth-client-id。点评把零配置边界划在官方站点这一个点很克制坑在于 GHES 用户第一次跑会直接收到 authentication required 报错得自己注册 OAuth App。HTTP 模式的性能设计ForMCPRequest 只注册一个工具pkg/inventory/registry.go的ForMCPRequest(method, itemName)是远程/HTTP 模式的关键优化。注释写得很直白per-request 实例only register the items needed for that specific request rather than all ~90 toolsswitch method { case MCPMethodInitialize, MCPMethodDiscover: clearAll() case MCPMethodToolsList: result.resourceTemplates, result.prompts nil, nil case MCPMethodToolsCall: result.resourceTemplates, result.prompts nil, nil if itemName ! { result.tools r.filterToolsByName(itemName) } // ... }每次请求浅拷贝一份 Inventory、清空与本次请求无关的条目tools/call get_job_logs就只注册get_job_logs这一个工具。为什么必须这么干因为 MCP 注册表里同名工具只能存在一份而 feature flag 切换时新旧两个变体可能共用一个名字filterToolsByName的注释专门解释了这点GetJobLogs和ActionsGetJobLogs都叫get_job_logs但受不同 flag 控制。点评这是请求级投影模式代价是每请求一次浅拷贝换来注册表永远干净——比全局注册 90 个再靠名字去重可靠得多。配置源对照同一件事的不同配置方式配置源行为优先级 / 开销适用场景GITHUB_MCP_KEY环境变量覆盖任意TOOL_*键及SERVER_NAME/SERVER_TITLE最高启动时一次读取后入缓存容器化部署、CI 中按环境切换文案github-mcp-server-config.json二进制同目录键值对覆盖描述中viper 启动时读一次团队共享的固定翻译文件代码默认值t(key, default)第二参数英文原文最低零配置开发、未做任何本地化--tools按名追加单个工具绕过 toolset 筛选与 toolset 叠加OR 关系只多开一两个工具--exclude-tools强制隐藏压过以上一切对工具名最高黑名单式禁用三步跑通最小部署# 1. 克隆并构建Go 项目需要本机装了 Go 工具链 git clone https://gitcode.com/GitHub_Trending/gi/github-mcp-server cd github-mcp-server go build ./cmd/github-mcp-server # 预期当前目录生成 github-mcp-server 二进制 # 2. 用 PAT 启动 stdio 服务器 GITHUB_PERSONAL_ACCESS_TOKENghp_xxx ./github-mcp-server stdio # 预期stderr 输出 GitHub MCP Server running on stdio进程随后阻塞等待 stdin 的 JSON-RPC # 3. 导出全部翻译键作为你的本地化底稿 GITHUB_PERSONAL_ACCESS_TOKENghp_xxx ./github-mcp-server stdio --export-translations # 预期当前目录生成 github-mcp-server-config.json含 TOOL_* 全量键进程随后报错退出属正常进阶技巧与避坑现象设置了GITHUB_MCP_TOOL_GET_COMMITS_DESCRIPTION但描述没变。原因key 会被strings.ToUpper归一后匹配但环境变量前缀必须严格是GITHUB_MCP_全大写且 JSON 文件必须与二进制同目录v.AddConfigPath(.)只认当前目录。处理先--export-translations导出确认真实 key 名再对照检查前缀。现象明明配了--tools get_job_logs工具列表里却没有。原因--tools只是绕过 toolset 这一关scope 过滤器和 feature flag 过滤器仍然生效若该工具挂在未开启的 feature flag 后面照样被藏。处理用--features打开对应 flag或确认 PAT scope 满足RequiredScopeGroups。现象--toolsets完全不生效行为像没传。原因viper 对逗号分隔环境变量的GetStringSlice有已知缺陷作者因此在 main.go 改用IsSetUnmarshalKey如果你绕过 CLI 直接改环境变量注意下划线替换-→_。处理优先用命令行 flag 而非环境变量传列表参数。现象同时设了GITHUB_PERSONAL_ACCESS_TOKEN和--app-id进程直接退出。原因RunStdioServer开头统计三种认证模式开启数1即报choose exactly one authentication mode。处理三种认证PAT / GitHub App / OAuth client只能选一。现象传了不认识的 toolset ID没报错但工具变少了。原因processToolsets把未识别 ID 记入unrecognizedToolsets但不 fail-fast。处理用--toolsets all先确认全量工具再逐步收窄。FAQ--tools和--toolsets到底什么关系叠加ORtoolset 决定基线集合--tools里的工具即使不在启用 toolset 中也会加入但两者都躲不过 scope 过滤、feature flag 和--exclude-tools。为什么我换了 token工具列表反而少了经典 PATghp_前缀会触发FetchTokenScopes做 scope 过滤token 权限变小被隐藏的工具就变多。抓 scope 失败时是 warn 后不过滤日志里能看到。怎么让多个实例github.com GHES在客户端里区分开用同一套覆盖机制改SERVER_NAME/SERVER_TITLEJSON 里写{SERVER_NAME: ghes-mcp-server}或export GITHUB_MCP_SERVER_NAMEghes-mcp-serverREADME 有专门章节。--read-only是怎么过滤的过滤器链第 2 步见isToolEnabled按工具自带的IsReadOnly()判定剔除写工具且它压过--tools的追加。这个项目只做 i18n 吗不是。i18n 只是描述层核心价值是工具面管理toolset/scope/feature flag 三级筛选、认证互斥、lockdown 模式、per-request 注册优化这一整套工具可见性基础设施。适用边界适合本地 AI 客户端IDE 插件、CLI agent接 GitHubCI 里做只读审计--read-onlyGHES 环境私有化部署需要按环境定制工具面与文案的团队。 不适合直接暴露到公网做多租户服务它是单 token 模型HTTP 模式面向的是你自己的 host 接入不是公共 API 网关需要运行时热切换 toolset的场景——工具面在启动时构建改配置要重启以及把pkg/当稳定库依赖——README 明确声明导出的 Go API 目前是 unstable、可能有 breaking change。写在最后回到那个 Builder整个 GitHub MCP Server 的工具可见性问题被拆成了静态注册 过滤器链 请求级投影三段每段独立可测、顺序固定、语义无歧义。i18n 那个 60 行的闭包同理——三级优先级写在一个函数里缓存、fallback、导出全在一处。如果你自己的项目也面临能力很多、每个环境暴露不一、文案要本地化的问题这套注册表 有序过滤器 key 覆盖闭包的组合值得直接搬。【免费下载链接】github-mcp-serverGitHubs official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
