GitHub 官方 MCP server 在 2026 年 11 月 16 日发布 2.2.0,版本代号「The one with Skills」。这次更新把三件事塞进了同一个版本:用 18 条内置工作流技能替换掉原来那一大段服务器 instructions、把 Copilot 自动化的 11 个工具放进来、给密钥扫描告警加了脱敏开关。它们的共同点是默认全关——升级本身不会改变任何行为,你必须显式打开,才会看到差异。
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 工具 |
还有一个容易踩的细节:远程服务器的特性头与查询参数永不合并,两者同时出现时以请求头为准——即使这个头的值是空的、只有空格,或全是无法识别的名字。
升级前后到底差在哪,用一张对照表最容易看清。注意第三列不是「新功能」,而是行为变化——这类变化不会报错,但会让老配置的输出变样。
| 场景 | 2.1.0 及以前 | 2.2.0 默认配置 | 2.2.0 开了 skills |
|---|---|---|---|
| 初始化响应 | 带一段长 instructions | 与旧版一致 | instructions 整段消失,改为技能目录 |
| Agent 选择工具的依据 | 工具名 + 通用说明 | 与旧版一致 | 按工具集过滤后的技能清单,含「不用于什么」 |
| 不支持该扩展的客户端 | 正常工作 | 正常工作 | 拿不到技能,也没有兜底说明 |
| Copilot 自动化工具 | 不存在 | 不存在 | 仍需单独开特性与工具集 |
| 密钥扫描返回 | 带密钥值 | 带密钥值 | 带密钥值(要脱敏得显式传参) |
别把「升级」和「开启」当成一件事:升级只换了二进制,默认行为完全保留;真正会改变 Agent 表现的是你加上 --features=skills 的那一刻。所以灰度顺序应当是:先升级二进制跑一周,再在单个客户端上开技能,最后才推广到团队配置。
Step 1:取二进制、验哈希、锁住版本
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 服务,先确认「开了技能,说明就没了」
先用窄工具集启动,把变量降到最少。下面两条命令只有 --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
这是 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 少走弯路
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
如果你用的是托管版而不是本地二进制,开技能的方式换成请求头或查询参数。两者语义相同,但优先级不同,混用时容易出「明明带着参数却没生效」的怪现象。
# 方式一:请求头(推荐,不会出现在 URL 与代理日志里)
X-MCP-Features: skills
# 方式二:查询参数,给那些替你拼 URL、无法设置自定义头的客户端用
https://api.githubcopilot.com/mcp/?features=skills
# 同时出现时:以请求头为准,即使头是空值也会覆盖查询参数
远程接入的两条额外注意:① 特性名不是密钥,但它会出现在客户端历史、代理日志与服务端访问日志里,某些团队会把「工具集名」当成内部信息,那就别用查询参数;② OAuth 受保护资源发现会保留完整查询串(它属于规范化的资源标识),因此改参数等于换了资源标识,客户端可能要求重新授权。
技能在协议层有三条读取路径,客户端可以按需组合。理解它们的分工,排查「明明有这条技能却读不到内容」时特别有用。
| 路径 | 拿什么 | 典型用途 |
|---|---|---|
skills/list | 分页的技能清单 | 会话开始时给模型一份可选项 |
skills/get | 单条技能的元数据与文件清单 | 确认版本、字节数与摘要 |
resources/read | skill://github.com/<name>/SKILL.md 与附件文件 | 真正把正文读进上下文 |
命令命名也遵循同一套坐标:服务器名、仓库域、技能名三段拼起来,例如 /mcp:github:skill:github.com:account-and-team-context。换服务器名或换技能名,这条命令就失效——它不是全局别名,而是带命名空间的定位符。
Step 5:打开 agent_automations,看清 11 个工具与那道确认表单
这组工具管理的是仓库里的 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 做脱敏,再做一次只读复核
密钥扫描的两个告警工具在 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 后,初始化响应里没有 instructions | Step 2 |
| 客户端兼容 | /skills list 能列出技能,且能调用其中一条 | Step 3 |
| 目录过滤 | 收窄工具集后,技能数量随之减少,且取不到被过滤项 | Step 4 |
| 自动化工具 | 默认看不到;开特性 + 指定工具集后出现 11 个 | Step 5 |
| 脱敏与只读 | 告警响应里没有密钥值;只读模式下写工具全部消失 | Step 6 |
常见问题速查
| 现象 | 大概率原因与处理 |
|---|---|
| 开了技能,客户端什么也没多出来 | 客户端没实现 skills 扩展,且服务端已不再发 instructions;换 Copilot CLI 或 VS Code Insiders 验证 |
| Agent 突然不知道该怎么用工具了 | 技能开着但客户端读不到目录,属于「两头空」;先关掉 skills 回到旧行为,再排查客户端 |
| 只看到一部分技能 | 正常:目录按工具集、令牌 scope、只读模式过滤;放宽工具集或换令牌再试 |
| 找不到自动化工具 | 只开了特性没加 --toolsets=copilot_automations,或反过来;两个条件缺一不可 |
| 确认表单没弹出来 | HTTP 模式下缺少请求状态键时写工具会被隐藏;改用 stdio,或换支持 elicitation 的客户端 |
run_automation 报参数过长 | 附加上下文上限 10,000 字符,且不会被当作提示注入过滤,超长请自行摘要 |
| 远程服务器特性不生效 | 头与查询参数不合并,头优先;检查是否发了一个空值头把查询参数覆盖了 |
| 只读模式下仍想用某个写工具 | 做不到:只读优先级最高,显式点名的写工具也会被跳过 |