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

描述端点、工具与资源

描述端点、工具与资源

这一节把 MCP Server 从“有一个目录项”补成“Agent 能理解和选择的能力描述”。你会拆分 endpoint、tool 与 resource 的职责,写清工具参数契约,并通过查询结果检查服务级元数据与能力级描述是否一致。

学习目标

  • 区分服务级元数据、端点、工具契约与资源描述的职责。
  • 用清晰的名称、描述和参数 Schema 提高 Agent 选工具的准确性。
  • 核对 Nacos 中保存的能力描述与 MCP Server 运行时暴露内容是否一致。

把四层信息分开

MCP Server 的名称、版本和描述回答“这是什么服务”;endpoint 回答“到哪里连接”;tool 回答“可以执行什么动作、需要哪些参数”;resource 回答“可以读取什么上下文数据”。Nacos AI Registry 把 MCP Server、工具、资源和端点放进统一目录,而 MCP 客户端会进一步通过工具列表和资源列表理解具体能力。([Nacos 官网][1])

MCP Server 端点工具资源关系图

这四层不要互相代替。尤其不要把“天气服务”这种宽泛说明只写在 Server 描述里,却把工具描述留空;模型真正选择工具时,最直接看到的是工具的 name、description 和 inputSchema。([Nacos 官网][2])

写清工具契约

以 get_weather 为例,名称应稳定且表达动作;描述要说明返回什么,而不是重复名称;inputSchema 要把参数类型、必填项和语义写清。Nacos 的 MCP 工具模型包含 name、description 与 inputSchema,工具还可以通过扩展元数据控制启用状态等行为。([Nacos 官网][5])

片段示例:下面是字段建模对照稿,不是可以直接提交给 Nacos API 的完整请求体;它用于在控制台编辑时检查各层信息是否放对位置。

json
{
  "server": {
    "name": "weather-mcp",
    "description": "提供城市天气查询与支持城市数据"
  },
  "endpoint": {
    "protocol": "streamable",
    "address": "<HOST>",
    "port": "<PORT>"
  },
  "tool": {
    "name": "get_weather",
    "description": "根据城市标识查询当前天气",
    "inputSchema": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "城市标识,例如 hangzhou"
        }
      },
      "required": ["city"]
    }
  },
  "resource": {
    "uri": "weather://cities/supported",
    "name": "supported_cities",
    "description": "返回天气服务支持的城市标识集合",
    "mimeType": "application/json"
  }
}

这里的 Tool Schema 使用 JSON Schema 描述输入;Resource 则用稳定 URI 标识可读取内容,并补充名称、描述和 MIME 类型。这些字段能让客户端在调用前知道“参数怎么给”和“资源是什么”。([MCP Python SDK][6])

在 Nacos 中补齐并核对

回到 weather-mcp 的详情或编辑页,把 endpoint 与真实服务保持一致,在工具区域新增 get_weather,复制同样的描述与参数约束,并开启该工具。资源能力是否能在控制台直接编辑取决于具体 Nacos 3.x 次版本;如果当前版本没有资源明细编辑区,不要自行编造未支持的字段,而应先保证运行时 MCP Server 的资源列表确实暴露 weather://cities/supported,再核对目录对象声明了相应能力。Nacos 稳定版管理模型会返回 capabilities,其中可包含 TOOL、PROMPT 和 RESOURCE。([Nacos 官网][3])

保存后,用只读查询确认工具已经进入目录。<TOKEN> 需要具备对应命名空间的读取权限。

bash
curl -sS 'http://<HOST>:<PORT>/nacos/v3/admin/ai/mcp?namespaceId=public&mcpName=weather-mcp' -H 'Authorization: Bearer <TOKEN>' | jq '{capabilities: .data.capabilities, tools: [.data.toolSpec.tools[] | {name, description, inputSchema}]}'

预期结果

json
{
  "capabilities": [
    "TOOL",
    "RESOURCE"
  ],
  "tools": [
    {
      "name": "get_weather",
      "description": "根据城市标识查询当前天气",
      "inputSchema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "城市标识,例如 hangzhou"
          }
        },
        "required": [
          "city"
        ]
      }
    }
  ]
}

能力数组的顺序可能不同,但应至少看到你实际启用的能力;工具的名称、描述和参数 Schema 应与服务端契约一致。若 toolSpec 为空,先检查目录项是否声明了 TOOL 能力、工具是否保存成功,以及当前查询的版本是否正确。([Nacos 官网][3])

让描述真正帮助 Agent 选择

工具描述要写成“什么时候用 + 做什么”,参数描述要消除单位、格式和枚举歧义。get_weather 比 weather 更像一个可执行动作,“根据城市标识查询当前天气”也比“天气工具”更能帮助模型判断调用时机。

Resource 则更适合暴露可读取、可复用的上下文,例如支持城市清单、配置说明或静态知识;不要把本应执行副作用的动作伪装成 Resource。最终以运行时 MCP Server 实际返回的工具与资源列表为准,再让 Nacos 目录中的描述保持同步,这样 Agent 才不会“发现得到、调用不对”。

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

目录与阅读设置

阅读设置

17

记录一个想法

描述端点、工具与资源

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

登录哪都通