服务注册与分布式协调 / 系统课时
映射参数与返回结构
映射参数与返回结构
这一节处理存量 API 转成 MCP Tool 时最容易出错的契约映射:把 path、query、body 参数准确放进工具输入定义,并把后端响应收敛成稳定结果,使模型少猜字段、网关少做隐式转换。
学习目标
- 能把 path、query 与 body 参数映射到统一的 Tool
inputSchema - 能正确设置参数类型、必填项和描述,降低模型误填概率
- 能用请求与响应模板核对协议转换前后的契约是否一致
先把 HTTP 契约列清楚
假设订单接口为 POST /api/v1/customers/{customerId}/orders,查询参数 dryRun 控制是否只校验不落单,请求体包含 sku 与 quantity。先直接调用后端,得到一份可以对照的真实契约。
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}'预期输出
{"orderId":"O-1001","status":"accepted","total":198}<HOST> 与 <PORT> 替换为实际地址;orderId 和金额会随请求变化,但字段结构应保持稳定。
把不同位置收敛成工具参数
对 Agent 来说,四个值都只是 Tool 参数;对 HTTP 网关来说,它们却要回到不同位置。customerId 必须替换 path 占位符,dryRun 进入 query,sku 与 quantity 进入 JSON body。映射层的职责就是保留这种差异,而不是让模型自己猜。

| Tool 参数 | HTTP 位置 | 类型 | 是否必填 | 描述重点 |
|---|---|---|---|---|
customerId |
path | string | 是 | 客户 ID,必须能构造 URL |
dryRun |
query | boolean | 否 | 是否仅校验,不实际创建订单 |
sku |
body | string | 是 | 商品 SKU |
quantity |
body | integer | 是 | 正整数购买数量 |
Path 参数通常不能缺省,因为缺少它就无法形成有效 URL;Query 参数是否必填则应以真实后端契约为准,不要为了“让模型更谨慎”随意改成必填。
定义类型、必填项与位置
下面的片段示例把 Tool 输入定义和协议转换配置放在一起。inputSchema 负责约束模型提交的参数,argsPosition 负责告诉转换层每个参数属于 HTTP 的哪个位置,两者必须使用同一组名称。
{
"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 长期共享同一份契约。