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

完成内部 MCP 目录综合演练

完成内部 MCP 目录综合演练

本节把注册、版本、权限与路由能力串成一个可验收的内部 MCP 目录:自研服务自动注册,存量 HTTP API 转成工具,Agent 统一经 Router 调用,并用发布切换、实例下线和恢复演练验证治理链路。

学习目标

  • 搭建同时容纳自研 MCP Server 与存量 HTTP API 的内部服务目录。
  • 配置版本、命名空间和最小权限,让 Agent 只通过 Router 发现并调用工具。
  • 用发布切换、实例下线和重新注册验证目录在变更与故障下的行为。

规划目录与验收拓扑

本次使用独立命名空间 mcp-prod。目录中放两个资源:自研的 inventory-mcp 提供库存查询工具;已有的 customer-http 通过 MCP 声明与协议转换暴露为 customer-directory。运行时 Agent 不直接保存这两个服务的地址,只连接 Nacos MCP Router。

内部 MCP 目录的控制面与调用链

验收时重点观察三条链路:资源能否进入同一目录;Router 是否只能读取已授权资源;资源版本或实例状态变化后,Agent 的新调用是否命中当前可用端点。

接入自研 MCP 服务

先用 Nacos MCP Wrapper Python 启动一个最小服务。若环境还没有依赖,先安装并立即做导入检查。

bash
# 安装后直接导入模块,避免只看到 pip 成功却无法运行。
python -m pip install -q nacos-mcp-wrapper-python >/dev/null 2>&1 && python -c "import nacos_mcp_wrapper; print('nacos-mcp-wrapper ready')"

预期输出

text
nacos-mcp-wrapper ready

将下面代码保存为 inventory_mcp.py;实际环境通过变量注入 Nacos 地址、凭据、命名空间和实例端口,避免把生产凭据写入源码。

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.getenv("NACOS_ADDR", "127.0.0.1:8848")
settings.NAMESPACE = os.getenv("NACOS_NAMESPACE", "mcp-prod")
settings.USERNAME = os.getenv("NACOS_USERNAME", "")
settings.PASSWORD = os.getenv("NACOS_PASSWORD", "")

port = int(os.getenv("MCP_PORT", "18001"))
# 服务名和版本进入目录,端口只标识当前运行实例。
mcp = NacosMCP(
    "inventory-mcp",
    nacos_settings=settings,
    version="1.0.0",
    port=port,
)

@mcp.tool()
def get_stock(sku: str) -> dict:
    """Return a deterministic stock record for the exercise."""
    # 工具返回结构化结果,便于 Agent 继续处理库存状态。
    stock = {"SKU-001": 12, "SKU-002": 0}
    return {"sku": sku, "available": stock.get(sku, 0)}

if __name__ == "__main__":
    print(f"inventory-mcp starting: version=1.0.0 port={port}", flush=True)
    mcp.run(transport="streamable-http")

预期输出

text
inventory-mcp starting: version=1.0.0 port=18001

进程随后持续运行。进入 mcp-prod 的 MCP 列表确认出现 inventory-mcp,并检查版本为 1.0.0、工具为 get_stock、端点对应当前实例。若同一版本启动时报兼容性错误,不要直接改已有版本的工具结构;工具名、参数或协议发生不兼容变化时应提升版本号。

为了验证实例级容错,可再用不同端口启动第二个进程,但保持 MCP 名称、版本和工具定义一致。

bash
# 第二个实例保持同名同版本,只改变运行端口。
MCP_PORT=18002 python inventory_mcp.py

预期输出

text
inventory-mcp starting: version=1.0.0 port=18002

实际日志还会包含框架输出,内容可能随依赖版本不同;验收以 Nacos 中能看到两个可用端点为准。

把存量 HTTP API 纳入目录

假设已有 customer-http 服务已经注册到 Nacos,并提供按客户 ID 查询资料的 HTTP 接口。无需重写业务服务,先在 MCP 管理中创建 customer-directory:协议选择 sse 或 streamable,后端选择已有服务 customer-http,服务版本设为 1.0.0。

随后新增工具 get_customer,把真实 HTTP 路径、方法和参数映射填写到协议转换配置,并给 customer_id 写清类型与含义。保存只是保留编辑结果;供运行时读取的版本需要发布为最新版本。数据面使用 Higress 等支持 MCP 协议转换的网关时,还要确认它已经把 Nacos 设为 MCP 管理来源。

Nacos 控制台创建存量 API 转 MCP 的配置位置

可以直接从网关侧验证转换后的 SSE 入口。下面的 <HOST>、<PORT> 和响应中的 <ID> 都以实际环境为准。

bash
# 这里只验证协议转换入口;实际 HOST 和 PORT 以网关地址为准。
curl -N --max-time 12 "http://<HOST>:<PORT>/mcp/customer-directory/sse"

预期输出

text
event: endpoint
data: /mcp/customer-directory?sessionId=<ID>

若没有 endpoint 事件,先查 customer-directory 是否已经发布为最新版本,再查网关是否读取了正确命名空间,最后确认 customer-http 至少有一个健康实例。

配置权限并让 Agent 走 Router

生产目录不要让 Agent 使用发布者账号。至少拆成两类身份:发布者对 mcp-prod 有写权限,用于创建和更新 MCP 资源;Router 运行身份只授予该命名空间的读权限。若启用了 AI 资源可见性控制,再把可见范围收紧到 Agent 需要调用的 MCP Server,避免“能登录就能搜到全部工具”。

启动 Router 时让它指向同一命名空间。示例使用 Streamable HTTP 对外提供 Router,本机端口固定为 8000;生产环境可换成受管进程或容器。

bash
# Router 使用只读运行身份,发布账号不要复用到 Agent 侧。
export NACOS_ADDR=127.0.0.1:8848
export NACOS_NAMESPACE=mcp-prod
export NACOS_USERNAME=router-reader
export NACOS_PASSWORD='<PASSWORD>'
export TRANSPORT_TYPE=streamable_http
export PORT=8000
printf 'router target=%s namespace=%s port=%s\n' "$NACOS_ADDR" "$NACOS_NAMESPACE" "$PORT"
uvx nacos-mcp-router@latest

预期输出

text
router target=127.0.0.1:8848 namespace=mcp-prod port=8000

随后 Router 持续运行;实际启动日志会随版本变化,不作为验收条件。只要进程保持运行,并且 Agent 能连接 http://<HOST>:8000/mcp,就可以继续验收。

让 Agent 只加载 Router,并按顺序调用 Router 的三个能力:先用 search_mcp_server 按任务描述找到 inventory-mcp 或 customer-directory,再用 add_mcp_server 建立目标连接,最后通过 use_tool 调用真实工具。这样 Agent 不需要固化每个后端的地址,目录中的版本、端点和可见性变化也不会散落到 Agent 配置里。

验证发布切换与故障恢复

先为 inventory-mcp 准备 1.1.0,保持兼容的工具输入输出,只修改实现或增加经过评审的新能力,并将它发布为最新版本。随后重新执行 Router 搜索和安装流程,确认新会话读取到 1.1.0。如果新版本有回归,不要修改已经发布的 1.1.0 结构;以 1.0.0 的稳定实现为基线生成修复版本,例如 1.1.1,再发布为最新版本。

实例故障按“单实例下线”和“全部下线后恢复”两级验证。先停止端口 18001 的进程,保留 18002;Agent 再次调用 get_stock 应仍能成功。然后停止第二个实例,调用应明确失败,而不是返回伪造业务结果。完成全部下线后,用下面命令终止最后一个目标进程并重新启动一个实例,等待它重新注册后再次调用。

bash
# <ID> 替换为最后一个待下线实例的实际 PID,随后重启一个端点。
kill -TERM <ID>
MCP_PORT=18001 python inventory_mcp.py

预期输出

text
inventory-mcp starting: version=1.0.0 port=18001

<ID> 是待下线进程的实际 PID。故障恢复的验收点不是“Router 永远不报错”,而是目录能及时反映可用端点:有健康实例时继续路由,无健康实例时失败可见,实例重新注册后新调用能够恢复。

最终检查四项结果:两个来源不同的服务都出现在 mcp-prod;Router 账号只有运行时读取权限;Agent 通过 Router 能调用两个目录项;版本切换、单实例下线和重新注册都能得到与预期一致的可观察结果。

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

目录与阅读设置

阅读设置

17

记录一个想法

完成内部 MCP 目录综合演练

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

登录哪都通