服务注册与分布式协调 / 系统课时
热更新工具描述与开关
热更新工具描述与开关
本节用一个正在运行的 Python MCP Server 验证 Nacos 的运行时治理:不重启进程,直接修改工具描述、参数说明和启停状态,并观察这些变化如何传到已注册服务,同时明确哪些变化不应作为同版本热更新。
学习目标
- 在已注册 MCP Server 上热更新工具描述、参数说明和启停状态。
- 通过刷新工具列表验证变更已经进入运行时视图,而不是只停留在控制台。
- 区分可动态治理的元数据与需要随代码版本发布的接口结构。
划清热更新边界
热更新最适合处理“怎么向模型说明和暴露工具”,而不是偷偷改变工具本身的调用契约。工具描述、参数描述和启停状态可以作为运行时治理信息;工具名、工具数量、参数类型以及是否必填一旦变化,就可能让现有客户端生成错误调用。
准备可治理工具
下面的最小服务用于观察热更新。它只返回固定天气文本,避免把外部天气 API 的网络问题混进治理验证。
import os
from nacos_mcp_wrapper.server.nacos_mcp import NacosMCP
from nacos_mcp_wrapper.server.nacos_settings import NacosSettings
settings = NacosSettings()
settings.SERVER_ADDR = os.environ["NACOS_SERVER_ADDR"]
settings.NAMESPACE = os.environ.get("NACOS_NAMESPACE", "public")
settings.USERNAME = os.environ.get("NACOS_USERNAME", "")
settings.PASSWORD = os.environ.get("NACOS_PASSWORD", "")
mcp = NacosMCP(
"weather-hot-update",
nacos_settings=settings,
version="1.0.0",
port=int(os.environ["MCP_PORT"]),
)
# 初始描述故意保持简单,后续在 Nacos 中改写它。
@mcp.tool()
def get_weather(city: str) -> str:
"""Get weather by city."""
return f"{city}: sunny"
if __name__ == "__main__":
mcp.run(transport="sse")预期结果
代码本身定义了一个名为 get_weather 的工具;运行后该工具会随 weather-hot-update 1.0.0 注册到 Nacos。启动服务:
export NACOS_SERVER_ADDR="<HOST>:<PORT>"
export NACOS_NAMESPACE="public"
export NACOS_USERNAME="<USERNAME>"
export NACOS_PASSWORD="<PASSWORD>"
export MCP_PORT="<PORT>"
python server.py预期结果
进程持续运行且没有 Python 异常退出。
Nacos 中可以看到 weather-hot-update 1.0.0 及其 get_weather 工具。在 Nacos 中发布变更
保持 Python 进程运行,在 Nacos 的 MCP 服务管理中打开 weather-hot-update 的 1.0.0 版本,找到 get_weather。先把工具描述改成“按城市查询演示天气”,再把参数 city 的说明改成“城市名称”,保存后刷新工具信息。
随后把该工具切换为停用。验证完成后再恢复启用,便于后续继续调用。这里不要改工具名、参数类型或必填关系,否则测试目标会从“热治理”变成“接口兼容性变更”。

观察运行时传播
验证时不要重启 server.py,否则无法证明是热更新。让已经连接到该 Server 的 MCP 客户端重新获取工具列表;客户端如果有自己的缓存,也需要触发刷新或重新建立会话。
描述更新后,get_weather 的名字仍然不变,但工具描述与参数说明应显示新文本;切换为停用后,它不应继续作为可选工具暴露。恢复启用后,再次刷新应能重新看到该工具。整个过程中 Python 进程 PID 不应因为治理操作而变化。
如果控制台已保存但客户端仍看到旧值,按“控制台发布是否成功 → Wrapper 是否仍与 Nacos 连通 → 客户端是否刷新工具列表”的顺序定位。这样可以把服务端同步问题与客户端缓存问题分开。
什么时候必须发新版本
| 变更 | 建议方式 | 原因 |
|---|---|---|
| 工具描述、参数说明 | 运行时热更新 | 不改变调用形状,适合快速修正文案与模型提示 |
| 工具启用或停用 | 运行时治理 | 用于临时下线高风险或不可用能力 |
| 工具名、工具数量 | 发布新版本 | 会改变客户端可发现的能力集合 |
| 参数名称、类型、必填关系 | 发布新版本 | 会改变输入 Schema 与调用契约 |
| 传输协议、服务引用 | 发布新版本并联调 | 影响连接与路由方式 |
把“可发现性和描述”交给运行时治理,把“调用契约”交给版本发布,才能既保留 Nacos 动态管理的灵活性,又避免同一版本在不同时间表现出不兼容接口。