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

映射参数与返回结构

映射参数与返回结构

这一节处理存量 API 转成 MCP Tool 时最容易出错的契约映射:把 path、query、body 参数准确放进工具输入定义,并把后端响应收敛成稳定结果,使模型少猜字段、网关少做隐式转换。

学习目标

  • 能把 path、query 与 body 参数映射到统一的 Tool inputSchema
  • 能正确设置参数类型、必填项和描述,降低模型误填概率
  • 能用请求与响应模板核对协议转换前后的契约是否一致

先把 HTTP 契约列清楚

假设订单接口为 POST /api/v1/customers/{customerId}/orders,查询参数 dryRun 控制是否只校验不落单,请求体包含 sku 与 quantity。先直接调用后端,得到一份可以对照的真实契约。

bash
curl -sS -X POST "http://<HOST>:<PORT>/api/v1/customers/C-100/orders?dryRun=true" \
  -H "Content-Type: application/json" \
  -d '{"sku":"SKU-42","quantity":2}'

预期输出

json
{"orderId":"O-1001","status":"accepted","total":198}

<HOST> 与 <PORT> 替换为实际地址;orderId 和金额会随请求变化,但字段结构应保持稳定。

把不同位置收敛成工具参数

对 Agent 来说,四个值都只是 Tool 参数;对 HTTP 网关来说,它们却要回到不同位置。customerId 必须替换 path 占位符,dryRun 进入 query,sku 与 quantity 进入 JSON body。映射层的职责就是保留这种差异,而不是让模型自己猜。

MCP 工具参数到 HTTP 请求与响应的映射

Tool 参数 HTTP 位置 类型 是否必填 描述重点
customerId path string 是 客户 ID,必须能构造 URL
dryRun query boolean 否 是否仅校验,不实际创建订单
sku body string 是 商品 SKU
quantity body integer 是 正整数购买数量

Path 参数通常不能缺省,因为缺少它就无法形成有效 URL;Query 参数是否必填则应以真实后端契约为准,不要为了“让模型更谨慎”随意改成必填。

定义类型、必填项与位置

下面的片段示例把 Tool 输入定义和协议转换配置放在一起。inputSchema 负责约束模型提交的参数,argsPosition 负责告诉转换层每个参数属于 HTTP 的哪个位置,两者必须使用同一组名称。

json
{
  "inputSchema": {
    "type": "object",
    "properties": {
      "customerId": {
        "type": "string",
        "description": "客户 ID,例如 C-100"
      },
      "dryRun": {
        "type": "boolean",
        "description": "true 表示只校验订单,不实际创建"
      },
      "sku": {
        "type": "string",
        "description": "商品 SKU,例如 SKU-42"
      },
      "quantity": {
        "type": "integer",
        "minimum": 1,
        "description": "购买数量,必须为正整数"
      }
    },
    "required": ["customerId", "sku", "quantity"],
    "additionalProperties": false
  },
  "requestTemplate": {
    "url": "/api/v1/customers/{customerId}/orders",
    "method": "POST",
    "headers": [
      {
        "key": "Content-Type",
        "value": "application/json"
      }
    ]
  },
  "argsPosition": {
    "customerId": "path",
    "dryRun": "query",
    "sku": "body",
    "quantity": "body"
  },
  "responseTemplate": {
    "body": "orderId={{.orderId}}; status={{.status}}; total={{.total}}"
  }
}

配置生效后,转换层应把同一次 Tool 调用组装成与前面 curl 等价的 HTTP 请求。验证时重点观察 path 是否被替换、布尔值是否进入 query、两个 body 字段是否保持 JSON 类型,以及返回模板引用的字段是否确实存在。

避免三类契约漂移

第一类是名称漂移:schema 写 customer_id,模板却找 customerId。第二类是类型漂移:后端要求整数,Tool 却声明成 string,模型可能生成 "2" 而不是 2。第三类是必填性漂移:后端允许省略 dryRun,Tool 却把它放进 required,会无意义地阻塞调用。另一个容易踩的模板边界是:一旦显式编写 requestTemplate.body,就应由该模板完整构造请求体,不要再同时依赖 argsPosition 的 body 映射。

返回结构同样要保持克制。若后端响应很大,只保留 Agent 后续推理真正需要的字段;若字段可能缺失,不要在模板里假设它永远存在。先用真实响应样本验证模板,再把新版本发布给 Agent 使用。

用一次调用完成验收

验收时使用一组固定参数,例如 customerId=C-100、dryRun=true、sku=SKU-42、quantity=2,对照原 HTTP 调用与 MCP 转换后的请求。两边应在方法、路径、query、body 类型和关键返回字段上等价。

如果后端接口将来把 quantity 改成对象、把 dryRun 改成必填,不能只修改工具描述;应同步更新 inputSchema、位置映射和模板,并发布新的兼容版本。参数映射的目标不是“能调通一次”,而是让 Agent、目录和真实 API 长期共享同一份契约。

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

目录与阅读设置

阅读设置

17

记录一个想法

映射参数与返回结构

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

登录哪都通