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

热更新工具描述与开关

热更新工具描述与开关

本节用一个正在运行的 Python MCP Server 验证 Nacos 的运行时治理:不重启进程,直接修改工具描述、参数说明和启停状态,并观察这些变化如何传到已注册服务,同时明确哪些变化不应作为同版本热更新。

学习目标

  • 在已注册 MCP Server 上热更新工具描述、参数说明和启停状态。
  • 通过刷新工具列表验证变更已经进入运行时视图,而不是只停留在控制台。
  • 区分可动态治理的元数据与需要随代码版本发布的接口结构。

划清热更新边界

热更新最适合处理“怎么向模型说明和暴露工具”,而不是偷偷改变工具本身的调用契约。工具描述、参数描述和启停状态可以作为运行时治理信息;工具名、工具数量、参数类型以及是否必填一旦变化,就可能让现有客户端生成错误调用。

准备可治理工具

下面的最小服务用于观察热更新。它只返回固定天气文本,避免把外部天气 API 的网络问题混进治理验证。

python
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")

预期结果

text
代码本身定义了一个名为 get_weather 的工具;运行后该工具会随 weather-hot-update 1.0.0 注册到 Nacos。

启动服务:

bash
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

预期结果

text
进程持续运行且没有 Python 异常退出。
Nacos 中可以看到 weather-hot-update 1.0.0 及其 get_weather 工具。

在 Nacos 中发布变更

保持 Python 进程运行,在 Nacos 的 MCP 服务管理中打开 weather-hot-update 的 1.0.0 版本,找到 get_weather。先把工具描述改成“按城市查询演示天气”,再把参数 city 的说明改成“城市名称”,保存后刷新工具信息。

随后把该工具切换为停用。验证完成后再恢复启用,便于后续继续调用。这里不要改工具名、参数类型或必填关系,否则测试目标会从“热治理”变成“接口兼容性变更”。

MCP 工具元数据热更新传播流程

观察运行时传播

验证时不要重启 server.py,否则无法证明是热更新。让已经连接到该 Server 的 MCP 客户端重新获取工具列表;客户端如果有自己的缓存,也需要触发刷新或重新建立会话。

描述更新后,get_weather 的名字仍然不变,但工具描述与参数说明应显示新文本;切换为停用后,它不应继续作为可选工具暴露。恢复启用后,再次刷新应能重新看到该工具。整个过程中 Python 进程 PID 不应因为治理操作而变化。

如果控制台已保存但客户端仍看到旧值,按“控制台发布是否成功 → Wrapper 是否仍与 Nacos 连通 → 客户端是否刷新工具列表”的顺序定位。这样可以把服务端同步问题与客户端缓存问题分开。

什么时候必须发新版本

变更 建议方式 原因
工具描述、参数说明 运行时热更新 不改变调用形状,适合快速修正文案与模型提示
工具启用或停用 运行时治理 用于临时下线高风险或不可用能力
工具名、工具数量 发布新版本 会改变客户端可发现的能力集合
参数名称、类型、必填关系 发布新版本 会改变输入 Schema 与调用契约
传输协议、服务引用 发布新版本并联调 影响连接与路由方式

把“可发现性和描述”交给运行时治理,把“调用契约”交给版本发布,才能既保留 Nacos 动态管理的灵活性,又避免同一版本在不同时间表现出不兼容接口。

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

目录与阅读设置

阅读设置

17

记录一个想法

热更新工具描述与开关

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

登录哪都通