服务注册与分布式协调 / 系统课时
用管理 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 开启鉴权,请改用具备该命名空间读权限的凭据。
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、描述、版本和能力数组取决于已注册服务。
{"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。
{
"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 的组合;出现权限失败则先确认调用身份是否拥有对应命名空间的读权限。把这三类问题分开处理,能避免把“查错环境”“名称没匹配”和“没有访问权”都误判成“目录没有服务”。