雁巢集运运费助手

概述

雁巢运费测算 (YANCHAO Freight Quote)

通过雁巢官方 Freight MCP Server 完成运费试算、路线推荐、可寄性判断。所有数据来自雁巢后台实时线路配置，不要凭通用知识估算运费——必须调用工具取数。

连接配置

• MCP 端点: https://mcpapi.gonest.cn/mcp（Streamable HTTP，公网可直连，当前免鉴权）
• 若返回 401（日后启用鉴权），需在请求头加 X-API-Key: <向雁巢申请的密钥>

Claude Code 添加：

claude mcp add --transport http yanchao-freight https://mcpapi.gonest.cn/mcp

Cursor / 通用 mcp.json：

{
  "mcpServers": {
    "yanchao-freight": { "url": "https://mcpapi.gonest.cn/mcp" }
  }
}

没有 MCP 客户端时：用 curl 按 MCP 协议直连（initialize → initialized → tools/call 三步），完整命令和编码注意事项见 references/api-reference.md。该域名只开放 /mcp 路径，没有 REST 接口。

工具速查

通用可选参数（quote/recommend 共享）：areaId、countryKeyword、lengthCm、widthCm、heightCm、volume、goodsTypeIds、zip；recommend 另有 limit（默认 2）。

报价类工具返回自带中文 summary（如 "共 7 条线路；参考最低价：美国经济海运普货专线【1KG起】 185.00，时效 30-35天"），可直接用于快速回答；明细在 lines / result 里。

参数约定（防错关键）

• 重量 weightKg 单位是千克(kg)。用户说"2斤"= 1 kg，"500克"= 0.5 kg，先换算再传。
• 尺寸 lengthCm/widthCm/heightCm 单位是厘米(cm)。优先传三维尺寸，服务端自动算体积重。
• volume 单位是立方米(m³)，仅在拿不到三维尺寸而用户直接给了体积时使用；能给尺寸就别传 volume。
• 计费重 = max(实际重量, 体积重)，返回的 fee.realWeight 即计费重(kg)。轻抛货（大而轻）会按体积重计费——用户质疑价格时用这一点解释。
• 目的地二选一：已知 areaId 直接传；否则传 countryKeyword（如 "美国"），服务端自动解析。只有当关键词歧义或解析失败时才先调 search_destination。
• goodsTypeIds 取自 list_goods_categories 返回的 id（字符串数组）。用户提到特殊品类（带电、液体、膏体、食品、化妆品）时先查品类表再报价，否则可不传。

典型工作流

① 运费查询（"寄 3 公斤衣服到美国多少钱？"）

1. quote_shipping { countryKeyword: "美国", weightKg: 3 }
2. 用 summary 给结论，再从 lines 挑 2-3 条列明细：线路名、总价 fee.totalFee、时效 cycle、首重/续重单价。命中用户物品的 ban（禁运说明）要提示。
3. 用户给了尺寸就带上 lengthCm/widthCm/heightCm，并检查 fee.realWeight 是否大于实重（体积重生效），是则向用户说明。

② 路线推荐（"到加拿大哪条线路划算？"）

1. recommend_routes { countryKeyword: "加拿大", weightKg: <若用户给了重量> }
2. 默认返回前 2 条；用户要更多传 limit。传了 weightKg 结果里带试算总价，直接对比报给用户。
3. result.hasRoutes=false 时转述 result.noRoutesTip，有 wecomKfImageUrl 一并给用户（客服二维码）。

③ 可寄性判断（"锂电池能寄到日本吗？"）

1. check_item_shippability { itemDescription: "锂电池", countryKeyword: "日本", weightKg: <估重或用户给的> }
2. 转述 summary（能否寄+限制原因）；result.lines 里已含可承运线路的报价，能寄时顺手给 1-2 条。

输出要求

• 报价以人民币元为单位（接口返回即元）；报给用户时列：线路名、总价、时效、首重/续重构成。
• 首重/续重档位接口返回是克（firstWeightG: 500），展示时换算：如 "首重 ¥47/0.5kg，续重 ¥28/0.5kg"。
• 不要杜撰线路或价格。返回空 lines / hasRoutes:false = 该目的地/品类暂无可用线路，如实告知并转述 noRoutesTip。
• 工具返回 ERROR: 前缀文本：多为参数问题（漏 weightKg、目的地解析失败），修正后重试一次；仍失败则如实告知用户。

深入参考

• references/api-reference.md — curl 直连 MCP 协议三步流程（含中文参数 UTF-8 编码坑）、各工具请求/返回完整字段字典、错误处理。MCP 客户端不可用、需要调试原始响应、或要向用户解释某个返回字段时读它。