进阶 📋 6 个步骤 第 630 / 632 篇

GitHub MCP server 2.2.0 升级实操:用 --features=skills 换掉说明、agent_automations 十一个工具与 hide_secret 脱敏

GitHub 官方 MCP server 2.2.0 把服务器说明换成了 18 条按工具过滤的工作流技能,并新增 Copilot 自动化 11 个工具与密钥脱敏开关。本教程按官方 README、feature-flags 文档与 v2.2.0 Release 六步落地:验哈希装二进制、用 --features=skills 观察 instructions 消失、客户端补 MCP_SKILLS 跑 /skills list、用工具集收窄技能目录、开 agent_automations 看清确认表单与 10 分钟过期、最后用 hide_secret 与 --read-only 收口。

2026.11.18· 15 分钟上手· 约 4851 字· 🐙 GitHub MCP server / 🧩 MCP Skills 扩展

GitHub 官方 MCP server 在 2026 年 11 月 16 日发布 2.2.0,版本代号「The one with Skills」。这次更新把三件事塞进了同一个版本:用 18 条内置工作流技能替换掉原来那一大段服务器 instructions、把 Copilot 自动化的 11 个工具放进来、给密钥扫描告警加了脱敏开关。它们的共同点是默认全关——升级本身不会改变任何行为,你必须显式打开,才会看到差异。

🧩 适合谁:已经在用 GitHub MCP server 接编码 Agent、并且被「工具太多、提示太长、Agent 老选错工具」困扰的开发者。前置准备:一个 GitHub 个人访问令牌(PAT,含 repo 与 read:org 即可)、一台装了 Node 或 Go 的电脑、一个支持 MCP 的客户端。本文用 Copilot CLI 做客户端验证,因为它已经支持 Skills 扩展;换成别的客户端要按 Step 4 的告警先确认兼容性。

动手前先记住四条边界:① 打开 skills 后,服务端在 initialize 与 server/discover 里不再返回任何 instructions,也没有兜底文案,客户端若不支持该扩展,会同时拿不到技能和原来的说明;② 加载一条 skill 不授予任何工具权限,工具白名单仍由 --toolsets、--tools、--read-only 和令牌 scope 决定;③ 自动化写操作弹出的 MCP 表单,服务端无法证明按下确认的是人,必须由你的客户端把它显示给用户;④ --read-only 优先级最高,即使你用 --tools 点名要写工具,也会被跳过。

先弄清:2.2.0 的三个开关,两个默认关闭

别急着改配置,先看懂这三个开关各自的落点。它们不共用一个入口、默认值也不同,混在一起调最容易出现「我明明开了,怎么没生效」。

开关怎么开默认状态实际影响
skills本地 --features=skills 或 GITHUB_FEATURES=skills;远程用 X-MCP-Features 头或 ?features= 查询参数关;Insiders 模式会自动打开instructions 整段被替换成按工具过滤的技能目录
agent_automations--features=agent_automations 再加 --toolsets=copilot_automations关,Insiders 模式也不会替你开多出 11 个自动化读写工具
hide_secret调用密钥扫描工具时传布尔参数关,默认仍把密钥值带回给模型只影响密钥扫描的两个工具
issue_artifacts--features=issue_artifacts关,Insiders 也不开给 issues 工具集加两个 artifact 工具

还有一个容易踩的细节:远程服务器的特性头与查询参数永不合并,两者同时出现时以请求头为准——即使这个头的值是空的、只有空格,或全是无法识别的名字。

💡 为什么这次升级值得花时间:以前 90 多个工具共用一段说明,模型只能靠工具名猜该用哪个;现在服务端按你当前连接实际拥有的工具,筛选出一份「这个连接能用的工作流」清单,每条都写明「用来干什么、不用于什么」。

升级前后到底差在哪,用一张对照表最容易看清。注意第三列不是「新功能」,而是行为变化——这类变化不会报错,但会让老配置的输出变样。

场景2.1.0 及以前2.2.0 默认配置2.2.0 开了 skills
初始化响应带一段长 instructions与旧版一致instructions 整段消失,改为技能目录
Agent 选择工具的依据工具名 + 通用说明与旧版一致按工具集过滤后的技能清单,含「不用于什么」
不支持该扩展的客户端正常工作正常工作拿不到技能,也没有兜底说明
Copilot 自动化工具不存在不存在仍需单独开特性与工具集
密钥扫描返回带密钥值带密钥值带密钥值(要脱敏得显式传参)

别把「升级」和「开启」当成一件事:升级只换了二进制,默认行为完全保留;真正会改变 Agent 表现的是你加上 --features=skills 的那一刻。所以灰度顺序应当是:先升级二进制跑一周,再在单个客户端上开技能,最后才推广到团队配置。

Step 1:取二进制、验哈希、锁住版本

1 先拿到 2.2.0 的官方产物,别用 latest

2.2.0 的 Release 页面提供了各平台压缩包和一份 checksums.txt。先在本地校验,再解压运行——这一步能挡掉「下载被劫持」和「缓存里其实是 2.1.0」两种问题。

# 1) 取 Windows x86_64 包与校验清单(macOS 换成 Darwin_arm64.tar.gz)
curl -L -o github-mcp-server.zip \
  https://github.com/github/github-mcp-server/releases/download/v2.2.0/github-mcp-server_Windows_x86_64.zip
curl -L -o checksums.txt \
  https://github.com/github/github-mcp-server/releases/download/v2.2.0/github-mcp-server_2.2.0_checksums.txt

# 2) 算本地哈希(Windows)
certutil -hashfile github-mcp-server.zip SHA256

# 3) 与 checksums.txt 里对应行逐字符比对,一致后再解压
Expand-Archive github-mcp-server.zip -DestinationPath .
.\github-mcp-server.exe --help

不要跳过校验:这个二进制会以你的令牌身份读写仓库,一旦跑到被替换的副本,泄露的是仓库权限。另外 Release 里的文件名带平台后缀,Windows_x86_64 与 Windows_arm64 是两套产物,别装错。

Step 2:起 stdio 服务,先确认「开了技能,说明就没了」

2 用最小工具集跑一次对照实验

先用窄工具集启动,把变量降到最少。下面两条命令只有 --features=skills 之差,正好用来观察 instructions 的去留。

# 令牌只放环境变量,不要写进命令行(会被 shell 历史记录)
export GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_TOKEN

# A 组:不开技能,工具集只留上下文相关的几条
github-mcp-server stdio --toolsets=context

# B 组:打开技能,其余不变
github-mcp-server stdio --features=skills --toolsets=context

判断标准来自官方文档:开启后 initialize 与 server/discover 都会完全省略 instructions;关闭时说明保持原样,且不会宣告技能扩展。想把开关写进环境变量而不是每次敲参数,用 GITHUB_FEATURES=skills 等价替代。

💡 服务端还支持 --insiders(或 GITHUB_INSIDERS=true),它会自动打开一批策展过的特性,其中包含 skills。但 agent_automations 明确不在 Insiders 的自动集合里,别以为开了 insiders 就什么都有。

工具集不用背全表,先记住四组常用组合,再按需加减。工具集是逗号分隔的 allow-list,写 --toolsets=all 表示全开,写具体名字表示只留这些。

目的推荐工具集副作用
只做代码阅读与检索context,repos技能目录只剩「仓库发现」相关几条
issue 分诊issues,repos,必要时加 context看不到 PR 与 Actions 相关技能
PR 评审pull_requests,repos,context写操作仍需 PR 相关工具,注意只读开关
故障排查actions,code_security,repos能读运行日志与安全告警,适合排障会话

工具集不只决定「有哪些工具」,还决定「有哪些技能」——两层是同一份过滤器的两个输出。这也解释了一个常见困惑:有人抱怨技能太少,实际是他把工具集收得太窄。

Step 3:客户端侧补上 MCP_SKILLS,跑通 /skills list

3 服务端与客户端必须同时开,缺一半等于两头空

这是 2.2.0 最容易漏的一步:技能能不能被发现,取决于客户端是否实现了 io.modelcontextprotocol/skills 扩展。官方给的验证路径是 Copilot CLI,启动时带上 MCP_SKILLS=true 和一段 stdio 配置。

MCP_SKILLS=true copilot --additional-mcp-config '{"mcpServers":{"github":{"type":"local","command":"/absolute/path/to/github-mcp-server","args":["stdio","--features=skills","--toolsets=context"],"tools":["*"]}}}'

# 进入会话后列出技能
/skills list

# 调用其中一条(命名规则:/mcp:服务器名:skill:仓库域:技能名)
/mcp:github:skill:github.com:account-and-team-context

注意 command 必须写完整路径,客户端不会替你解析相对路径。技能激活还需要你在客户端里明确同意,官方写明即使开了 /allow-all 或 --yolo 也照样要确认。用 VS Code Insiders 的话,客户端侧开关是设置项 chat.agentHost.mcpSkills.enabled。

常见误判:在 MCP Inspector 里看到工具列表正常,就以为技能也生效了。工具列表和技能目录是两条独立通道——只有实现了该扩展的客户端才能读到 skills/list。官方文档还特别标注:发现、命令命名与授权行为取决于客户端构建版本,仅有服务端这个开关并不构成客户端兼容性承诺。

Step 4:用工具集把技能目录收窄,让 Agent 少走弯路

4 技能是按「你实际拥有的工具」过滤出来的

2.2.0 内置 18 条工作流技能,但你在一次连接里通常只会看到其中一部分。过滤维度包括工具集、显式工具列表、排除项、只读模式、特性变体和令牌 scope;被过滤掉的技能,通过列举、直接 get、目录读、文件读四条路都取不到,不存在「猜 URI 绕过」。

分组技能名典型用途
仓库发现(4)account-and-team-context、repository-discovery、codebase-exploration、repository-health-review先认清「这是谁的仓库、代码在哪、最近为什么改」
Issue 与协作(6)issue-authoring、issue-backlog-triage、label-scheme-management、project-planning、discussion-participation、notification-triage写 issue、分诊积压、管标签与项目板
变更与 PR(5)repository-content-changes、pull-request-authoring、pull-request-code-review、pull-request-review-feedback、copilot-task-delegation改文件、开 PR、做代码评审、回评审意见
CI 与安全(3)workflow-failure-triage、security-alert-triage、release-preparation查失败的 Actions、处理安全告警、起草发布说明
# 只要「读仓库 + 看 issue」:技能目录会自动收缩到对应子集
github-mcp-server stdio --features=skills --toolsets=repos,issues --read-only

# 想显式点名工具,也同样会参与过滤
github-mcp-server stdio --features=skills --tools=search_code,get_file_contents,issue_read
💡 一条技能最多可带 512 个资源文件、合计 16 MiB,条目里带文件清单、字节长度与 SHA-256 摘要。这意味着你可以在客户端里核对「拿到的这份技能说明有没有被改过」,而不是盲信一段提示词。

如果你用的是托管版而不是本地二进制,开技能的方式换成请求头或查询参数。两者语义相同,但优先级不同,混用时容易出「明明带着参数却没生效」的怪现象。

# 方式一:请求头(推荐,不会出现在 URL 与代理日志里)
X-MCP-Features: skills

# 方式二:查询参数,给那些替你拼 URL、无法设置自定义头的客户端用
https://api.githubcopilot.com/mcp/?features=skills

# 同时出现时:以请求头为准,即使头是空值也会覆盖查询参数

远程接入的两条额外注意:① 特性名不是密钥,但它会出现在客户端历史、代理日志与服务端访问日志里,某些团队会把「工具集名」当成内部信息,那就别用查询参数;② OAuth 受保护资源发现会保留完整查询串(它属于规范化的资源标识),因此改参数等于换了资源标识,客户端可能要求重新授权。

技能在协议层有三条读取路径,客户端可以按需组合。理解它们的分工,排查「明明有这条技能却读不到内容」时特别有用。

路径拿什么典型用途
skills/list分页的技能清单会话开始时给模型一份可选项
skills/get单条技能的元数据与文件清单确认版本、字节数与摘要
resources/readskill://github.com/<name>/SKILL.md 与附件文件真正把正文读进上下文

命令命名也遵循同一套坐标:服务器名、仓库域、技能名三段拼起来,例如 /mcp:github:skill:github.com:account-and-team-context。换服务器名或换技能名,这条命令就失效——它不是全局别名,而是带命名空间的定位符。

Step 5:打开 agent_automations,看清 11 个工具与那道确认表单

5 写操作要过一道「绑定到具体参数」的表单

这组工具管理的是仓库里的 Copilot 自动化,默认不出现在任何列表里。开启需要两个条件同时满足:特性开关打开、并且工具集包含 copilot_automations。

# 特性开关 + 专用工具集,两个都要
github-mcp-server stdio --features=agent_automations --toolsets=copilot_automations,repos

# 只读复核:写工具会消失,只剩读
github-mcp-server stdio --features=agent_automations --toolsets=copilot_automations --read-only
类别工具关键约束
读(7)自动化列表/详情、修订列表/详情、可用工具目录、可用触发器目录、仓库配置每个仓库级工具都必须显式给 owner 与 repo
写(4)create_automation、update_automation、delete_automation、run_automation每次调用都要一张与本次参数绑定的 MCP 表单

表单的行为值得逐条记住:绑定精确参数,十分钟过期,未获接受就失败关闭;确认文案只显示转义后的目标与字段名,不显示字段值;HTTP 模式下如果拿不到多轮请求的状态键,写工具会被隐藏而不是降级放行。run_automation 只支持手动事件,附加上下文上限 10,000 字符,接口返回 202 即视为已受理。

别把它当审批系统用:官方在 PR 里写得很直白——服务端无法证明表单是人答的还是模型自己答的,客户端有义务把 elicitation 呈现给用户。若你的客户端不展示表单,这套「人工确认」在事实上不存在。

真正要创建一条自动化时,create_automation 的必填项只有 owner、repo、name、prompt 四个,其余都是可选项。先照下面这张表准备参数,能少来回几轮。

参数必填说明
name / prompt是自动化名称与每次运行使用的提示词
owner / repo是仓库级工具都要显式给,不会从会话上下文猜
enabled否建议首次创建时设为 false,确认 prompt 后再启用
model / reasoning_effort否不填则用仓库默认;两者都会影响额度消耗
continuous_history否是否保留连续对话历史,长任务打开更连贯但更贵
tools / triggers否可用工具与触发配置,建议先用读目录工具查一遍合法值
require_actor_write_permission否要求触发者具备写权限,公开仓库建议开
type否自动化类型;可选值以可用工具目录的返回为准
💡 拿不准可选值时,先调「可用工具目录」与「可用触发器目录」两个读工具,把返回值当作枚举来源。这比翻文档快,也能避免模型凭记忆编一个不存在的工具名——那种错误会在真正运行时才暴露。

Step 6:用 hide_secret 做脱敏,再做一次只读复核

6 让密钥值根本不进入模型上下文

密钥扫描的两个告警工具在 2.2.0 新增了可选布尔参数 hide_secret。它的实现方式是把请求转发给 REST API 的对应选项,在取数阶段就不返回密钥值,而不是取回来再删——这点很重要,后者已经进过模型的上下文了。

# 在支持手动构造工具调用的客户端里,给告警查询带上这个参数
{
  "owner": "your-org",
  "repo": "your-repo",
  "hide_secret": true
}

# 不传或传 false:行为与 2.1.0 完全一致,仍然带出密钥值

最后做一次收口复核:把服务端按 --read-only 重启,确认写工具整体消失,再回看技能目录是否同步收缩。只读优先级高于显式工具名单,这是官方写明的一条规则,也是你做「只读演示环境」时最省事的开关。

💡 把这三组开关写进不同的启动配置(只读巡检、日常开发、自动化管理),比在一个配置里反复改参数安全得多。技能目录会随配置自动变化,正好充当「当前连接能干什么」的自描述。

最后留一份回滚路径。2.2.0 声称默认无破坏性变更,但「开了特性之后」的行为差异是实打实的,出问题时按下面的顺序退,比现场 debug 快。

症状先退哪一步退完怎么验证
Agent 突然不会用工具去掉 --features=skills初始化响应重新带上 instructions
技能列表对不上文档放宽工具集到 all再跑一次 /skills list 对比条数
自动化工具干扰正常流程去掉 copilot_automations工具列表回到 11 个以内
告警内容缺字段把 hide_secret 去掉响应恢复完整字段(密钥值也会回来,注意日志)
整体不可用回退到 v2.1.0 二进制用同一份配置启动,确认行为与升级前一致

做到哪一步算成功

不需要截图对照,用下面这张表逐项打勾即可。任何一项对不上,就回到对应步骤重做,不要继续往下走。

检查项期望现象对应步骤
版本锁定--help 正常输出,压缩包哈希与 checksums.txt 一致Step 1
技能开关生效开 --features=skills 后,初始化响应里没有 instructionsStep 2
客户端兼容/skills list 能列出技能,且能调用其中一条Step 3
目录过滤收窄工具集后,技能数量随之减少,且取不到被过滤项Step 4
自动化工具默认看不到;开特性 + 指定工具集后出现 11 个Step 5
脱敏与只读告警响应里没有密钥值;只读模式下写工具全部消失Step 6
🎉 全部打勾后,你的 Agent 拿到的是一份「按当前权限定制的操作手册」,而不是一段包打天下的提示词。后续想加能力,优先加工具集让技能自动扩张,而不是手写更长的系统提示。

常见问题速查

现象大概率原因与处理
开了技能,客户端什么也没多出来客户端没实现 skills 扩展,且服务端已不再发 instructions;换 Copilot CLI 或 VS Code Insiders 验证
Agent 突然不知道该怎么用工具了技能开着但客户端读不到目录,属于「两头空」;先关掉 skills 回到旧行为,再排查客户端
只看到一部分技能正常:目录按工具集、令牌 scope、只读模式过滤;放宽工具集或换令牌再试
找不到自动化工具只开了特性没加 --toolsets=copilot_automations,或反过来;两个条件缺一不可
确认表单没弹出来HTTP 模式下缺少请求状态键时写工具会被隐藏;改用 stdio,或换支持 elicitation 的客户端
run_automation 报参数过长附加上下文上限 10,000 字符,且不会被当作提示注入过滤,超长请自行摘要
远程服务器特性不生效头与查询参数不合并,头优先;检查是否发了一个空值头把查询参数覆盖了
只读模式下仍想用某个写工具做不到:只读优先级最高,显式点名的写工具也会被跳过
📌 配套阅读:本中心《MCP 官方参考服务器 v2.3.0 升级实操》讲的是文件与联网工具的边界参数,本篇讲的是 GitHub 官方服务器的技能分发与写操作表单,两者都在解决「Agent 能做什么、做到哪一步必须停下来」这个问题。
← 返回教程中心