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

用管理 API 查询目录

用管理 API 查询目录

当服务门户、Agent 平台和运维脚本都要读取同一份 MCP 目录时,最稳妥的做法是直接消费 Nacos AI 的管理接口。本篇完成分页查询、命名空间与名称筛选,并把原始返回字段收敛成便于上层复用的目录数据。

学习目标

  • 调用 MCP 服务列表管理 API,并正确设置分页参数。
  • 用 namespaceId、mcpName 和 search 控制查询范围。
  • 识别目录返回中的核心字段,并设计稳定的上层数据契约。

先确定查询边界

MCP 服务列表使用 GET /nacos/v3/admin/ai/mcp/list。该运维接口自 Nacos 3.0.1 起提供,调用方需要目标命名空间的读权限;pageNo 从 1 开始,pageSize 最大为 500,namespaceId 不传时默认为 public。([Nacos 官网][1])

参数 用途 建议
pageNo 当前页 显式传入,从 1 开始
pageSize 每页数量 门户常用 20~100,批处理不要超过 500
namespaceId 限定目录范围 生产环境不要依赖默认值
mcpName 按名称筛选 精确查询传完整名称
search blur 或 accurate 模糊查询配合 *,精确查询用 accurate

命名空间应当先于名称筛选确定。若测试、预发、生产使用不同 namespace,同名 MCP 也应被视为不同目录项,避免门户把跨环境结果混在一起。

发起分页和名称筛选

下面的命令查询 public 命名空间中名称包含 weather 的 MCP 服务。示例假设当前环境已允许该请求;若 Nacos 开启鉴权,请改用具备该命名空间读权限的凭据。

bash
NACOS_BASE="http://127.0.0.1:8848"

curl -sS -G \
  -w '\nHTTP_STATUS:%{http_code}\n' \
  "$NACOS_BASE/nacos/v3/admin/ai/mcp/list" \
  --data-urlencode "pageNo=1" \
  --data-urlencode "pageSize=20" \
  --data-urlencode "namespaceId=public" \
  --data-urlencode "mcpName=*weather*" \
  --data-urlencode "search=blur"

预期结果:目录中存在匹配项时,HTTP 状态为 200,统一响应体的 code 为 0,分页数据位于 data 下;实际 ID、描述、版本和能力数组取决于已注册服务。

text
{"code":0,"message":"success","data":{"totalCount":1,"pageNumber":1,"pagesAvailable":1,"pageItems":[{"id":"<ID>","name":"weather-mcp","protocol":"<PROTOCOL>","description":"<DESCRIPTION>","latestPublishedVersion":"<VERSION>","capabilities":["TOOL"]}]}}
HTTP_STATUS:200

若只查确定名称,把 mcpName 改为完整服务名并设置 search=accurate。模糊模式下可以使用 *,而精确模式更适合 Agent 在绑定固定服务时做存在性检查。([Nacos 官网][1])

整理成可复用的目录字段

列表响应同时包含分页元数据和服务条目。Nacos 当前返回的目录项可包含 id、name、protocol、frontProtocol、description、repository、版本信息、远端或本地服务配置以及 capabilities。([Nacos 官网][1])

上层门户不应把整份原始对象无差别透传。更稳定的做法是固定一个“小目录模型”:保留 id、name、protocol、description、latestPublishedVersion、capabilities,需要进入详情页时再按 id 查询完整配置。分页则统一保留 totalCount、pageNumber、pagesAvailable。

json
{
  "total": 1,
  "page": 1,
  "pages": 1,
  "items": [
    {
      "id": "<ID>",
      "name": "weather-mcp",
      "protocol": "<PROTOCOL>",
      "description": "<DESCRIPTION>",
      "version": "<VERSION>",
      "capabilities": ["TOOL"]
    }
  ]
}

这段 JSON 是上层数据契约示例,不是 Nacos 原始响应。字段归一化后,服务门户负责展示,Agent 平台负责选择和绑定,运维脚本负责批量检查,三者都可以复用同一个目录读取层,而不必各自理解 Nacos 的完整返回结构。

处理分页和空结果

连续翻页时,以 pagesAvailable 判断是否结束,而不是用“本页数量小于 pageSize”猜测。这样即使服务在查询期间发生增删,也能让翻页逻辑与服务端给出的分页状态保持一致。

查询为空时先检查 namespaceId,再检查 search 与 mcpName 的组合;出现权限失败则先确认调用身份是否拥有对应命名空间的读权限。把这三类问题分开处理,能避免把“查错环境”“名称没匹配”和“没有访问权”都误判成“目录没有服务”。

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

目录与阅读设置

阅读设置

17

记录一个想法

用管理 API 查询目录

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

登录哪都通