MCP官方服务器v2.0.0发布：全面适配新版协议

Model Context Protocol（MCP）官方服务器仓库发布了 v2.0.0，这是一次横跨 TypeScript 与 Python 两条技术栈的整体重构，核心目标是让所有官方服务器同时支持「现代协议时代」（modern era spec），并继续兼容旧版客户端。对于依赖 MCP 生态构建 Agent 工具链的开发者，这次升级值得认真读一遍 changelog。

两套协议并行：现代与遗留时代的兼容策略

本次发布最关键的架构变化，是所有服务器同时服务于两个协议时代：2026-07-28 时代与 2025-11-25 时代。据仓库发布说明，服务器在遵循现代规范的同时，仍会「按预期应答遗留时代的客户端」。这种双轨设计意味着短期内无需担心下游客户端不兼容，但也要求服务端在能力声明、错误码、结构化返回等细节上做更精细的分支处理。

TypeScript 侧，四个 npm 包全部升到 2.0.0：server-everything、server-filesystem、server-memory、server-sequential-thinking。Python 侧的 mcp-server-fetch、mcp-server-git、mcp-server-time 采用 CalVer 版本号，统一标记为 2026.10.19。

MCP 协议版本与“时代”语义：MCP（Model Context Protocol）采用基于日期的版本号（如 2026-07-28），每次规范修订可能引入能力集、错误模型或传输层的变化，因此版本号实际标识的是一组协议契约，而非软件包版本。所谓“现代协议时代”与“遗留时代”，是官方仓库对两套契约的简称：服务端需根据客户端在初始化握手时声明的协议版本，选择对应的能力声明与返回格式。这种按会话协商版本的设计，使服务端可以在一套代码里同时服务新旧客户端，代价是分支逻辑必须严格对齐规范，任何在错误码、结构化返回上的偏差都可能导致某一时代的客户端解析失败。

TypeScript 服务器：Node 基线抬升与根目录修复

TS 服务器的主线改动是将代码迁移到 TypeScript SDK v2（以 codemod 方式批量完成），并将 Node 最低版本要求提升到 24。CI 同步在 Node 22、24、26 三个版本上并行验证，说明团队在激进抬升 floor 的同时仍在观察更宽版本区间的行为。

server-filesystem 的几处修复值得单独拎出来看：当 roots 更新后不再存在有效根目录时撤销访问权限；只采纳最新一次 roots 刷新请求的应答；在任意 roots 刷新挂起期间保持工具调用的等待状态。这三条合在一起，实质上是给文件系统服务器补了一套并发状态机，避免了 roots 变更过程中的竞态导致的越权访问或调用错配。

server-sequential-thinking 则修了一个渲染层面的小问题：思考框头部行与边框的对齐补齐。

roots 与并发状态机：在 MCP 中，roots 是客户端向服务端声明的“可操作范围”（例如允许访问的目录列表），服务端据此限制文件系统工具的作用域。roots 可由客户端在运行中动态刷新，而刷新是异步请求——服务端发出 roots/list 后，可能同时有多个工具调用正在等待。若不加控制，旧应答晚到、刷新期间无有效根、多次刷新交错等情况会导致服务端用过期或空的根集合判定权限，从而产生越权或误拒。v2.0.0 的三处修复本质上是在服务端维护一个带版本/序号的状态：只采纳最新请求的应答、刷新期间挂起工具调用、刷新后若无有效根则撤销访问，从而把 roots 生命周期变成可串行化的状态迁移。

Python 服务器：迁移到 MCPServer 高层封装

三个 Python 服务器没有独立的 CHANGELOG，发布说明直接列出了对客户端可见的行为变化。它们现在构建在 MCP Python SDK 的高层 MCPServer 之上，依赖范围收紧为 mcp>=2.3,<3。

行为层面的关键变化有三处：

• 未知工具的错误码变了。此前返回 isError 结果，现在按规范返回 JSON-RPC -32602 错误（Unknown tool: <name>），且两个协议时代都是如此。客户端如果依赖旧的错误形态做分支判断，需要调整。
• 工具错误的文本格式统一为 Error executing tool <name>: <message>，参数校验错误改用 pydantic 的措辞，但仍保持 isError 结果。
• 能力声明扩展：每个服务器现在都声明 prompts 和 resources 能力（listChanged: false），其中 fetch 的 fetch prompt 是这些列表中唯一的条目。

此外，time 服务器的 get_current_time 与 convert_time 声明了 outputSchema 并返回 structuredContent，文本内容保持不变；fetch 的 prompts/get 结果中的 description 现在始终使用 prompt 注册时的描述。

JSON-RPC 错误码与 isError 的区别：MCP 基于 JSON-RPC 2.0，因此存在两个层次的错误表达。协议层错误通过 JSON-RPC 的 error 对象返回，含数值错误码（如 -32602 表示 Invalid params）和 message；工具层错误则通过工具调用结果中的 isError: true 表达，属于“调用成功但业务失败”。前者通常意味着请求本身不合法（例如工具名不存在），后者意味着工具已执行但返回了错误内容。把未知工具从 isError 改为 -32602，是让“工具不存在”回归协议层语义，好处是客户端可统一在 RPC 层处理，坏处是依赖结果体做分支的旧客户端会漏判。

outputSchema 与 structuredContent：MCP 工具可以声明输出模式，使服务端在返回人类可读文本的同时，附带一份符合 outputSchema 的结构化 JSON（即 structuredContent）。这让 Agent 不必解析自然语言文本即可稳定提取字段，也让客户端能做输出校验。声明 outputSchema 后，服务端需保证结构化内容与 schema 一致，而文本内容可继续保留以兼容只读文本的旧客户端。time 服务器的两个工具正是这一模式的示例：返回结构不变、文本不变，但新增了机器可解析的结构化载荷。

已知问题：字面量 "null" 的陷阱

发布说明中明确记录了一个已知问题（#5176）：在 mcp-server-git 中，把字符串 "null" 作为 base_branch 传给 git_create_branch，或作为 contains/not_contains 传给 git_branch 时，会被当作无值处理。影响范围仅限名称字面为 null 的分支，根因在 Python SDK（python-sdk#3055）。官方给出的绕行方案是：过滤场景下改传 refs/heads/null 或 commit SHA；需要从 null 分支拉出新分支时，先 git_checkout 再不带 base_branch 调用 git_create_branch。

仓库工程化：CI 与发布流程的加固

除了服务器代码本身，这次发布还伴随一批仓库层面的治理改动：给 main 加上了防护规则，PR 合入 main 的内容必须已经存在于 v2/main；记录 v2/main 的 ruleset（仅允许 PR，禁止 force-push 与删除）；在 python.yml 和 typescript.yml 中声明只读的 GITHUB_TOKEN 权限；自动化版本 PR 也会触发 TS 与 Python 的 CI；还修了 win-shell-args 脚本中引号前反斜杠转义的问题。这些细节拼起来，是一套面向长期维护的发布纪律，而非一次性清理。

升级建议

如果你在用官方 MCP 服务器，升级前重点确认两件事：一是客户端是否依赖未知工具返回 isError 的旧行为；二是运行环境是否满足 Node 24+ 或 mcp>=2.3,<3 的依赖约束。若你的工作流涉及名为 null 的 git 分支，记得套用官方绕行方案。