服务注册与分布式协调 / 系统课时

发布多版本 MCP 服务

发布多版本 MCP 服务

同一个 MCP Server 升级工具参数或返回契约时,不应直接覆盖旧定义。本篇用版本化发布保留旧契约,再分别读取指定版本与默认版本,让客户端可以固定版本,也能在验证后安全切换默认版本。

学习目标

  • 为同一 MCP Server 增加新版本而保留旧版本
  • 识别工具契约中的兼容变更与破坏性变更
  • 使用管理 API 按显式版本读取服务并验证版本共存

把版本看成契约快照

Nacos 的 MCP 服务详情包含当前版本信息和全部版本列表;查询详情时传入 version 可读取指定版本,不传则读取当前最新版本。版本记录包含版本号、发布时间和是否为最新版本等信息。([Nacos 官网][1])

这意味着版本号不只是部署标签,而是客户端可选择的工具契约快照。例如 1.0.0 的 get_order 只接收 orderId,1.1.0 增加可选参数 currency。旧客户端继续固定 1.0.0 时,不会因为新契约出现而被迫同步升级。

同一 MCP Server 的多版本与读取路径

发布新版本而不切默认版本

假设 order-tools 已经存在 1.0.0,且它仍是默认版本。发布 1.1.0 时使用更新接口提交新的 versionDetail.version,同时把 latest 设为 false,先让新版本进入目录但不改变默认读取结果。MCP 管理 API 的更新接口为 PUT /nacos/v3/admin/ai/mcp,需要对应命名空间的写权限。([Nacos 官网][1])

下面示例假设原服务使用 streamable 协议,远端端点已经存在,因此不覆盖端点信息。若部署启用了鉴权,请按实际环境补充凭据。

bash
NACOS="http://<HOST>:<PORT>"
MCP_ID="<ID>"

# 新版本先进入目录,不切换默认 latest
curl -sS -X PUT "${NACOS}/nacos/v3/admin/ai/mcp" \
  -d 'namespaceId=public' \
  --data-urlencode 'serverSpecification={"id":"<ID>","name":"order-tools","protocol":"streamable","frontProtocol":"streamable","description":"Order query tools","versionDetail":{"version":"1.1.0"},"enabled":true}' \
  --data-urlencode 'toolSpecification={"tools":[{"name":"get_order","description":"Query an order","inputSchema":{"type":"object","properties":{"orderId":{"type":"string"},"currency":{"type":"string"}},"required":["orderId"]}}]}' \
  -d 'latest=false'

预期输出:

json
{"code":0,"message":"success","data":"ok"}

其中 <HOST>、<PORT>、<ID> 要替换为实际值。接口成功只说明目录更新完成,不等于新版本已经通过业务验证。

记录工具契约变化

版本升级前先比较工具名、输入 Schema、返回语义和安全要求。一个实用原则是:新增可选字段通常可以做小版本升级,而删除字段、重命名工具、把可选字段改为必填,都会让旧调用方更容易失败,应按破坏性变更处理。

变化 示例 建议
新增可选参数 currency 可省略 可作为兼容升级
新增工具 增加 list_orders 通常兼容
删除或重命名工具 get_order 改名 视为破坏性变更
可选改必填 currency 必填 视为破坏性变更

版本号只能告诉使用者“发生了哪一轮变化”,不能替代契约审查。发布记录里应保留变更原因、兼容结论和回滚目标版本。

按版本读取并验证共存

发布后显式读取两个版本,最容易确认旧版本没有被覆盖。下面命令依赖 curl 与 Python 3,分别请求 1.0.0 与 1.1.0,只打印服务器实际返回的版本号。

bash
NACOS="http://<HOST>:<PORT>"
MCP_ID="<ID>"

# 显式读取两个固定版本,避免默认指针影响验证
for VERSION in 1.0.0 1.1.0; do
  curl -sS --get "${NACOS}/nacos/v3/admin/ai/mcp" \
    --data-urlencode 'namespaceId=public' \
    --data-urlencode "mcpId=${MCP_ID}" \
    --data-urlencode "version=${VERSION}" \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["data"]["versionDetail"]["version"])'
done

预期输出:

text
1.0.0
1.1.0

若显式读取旧版本失败,应先检查旧版本是否仍在 allVersions 中,再检查是否误用了相同版本号覆盖契约。只有在新版本验证通过后,才应考虑修改默认版本指针;在此之前,让生产调用方固定旧版本更安全。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

发布多版本 MCP 服务

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通