MCP 工具接口文档

本文仅描述当前 Gateway 注册的工具接口。实际可用工具是本地注册集合与服务端启用列表的交集；员工、公司、权限和数据范围由当前设备会话决定。

订单与轨迹

query_order（订单兼容搜索）

路由：POST /mcp/tools/queryOrder

中文参数名	参数名	类型	必填	默认/约束
搜索关键词	`keyword`	string	是	非空；仅用户明确接受跨字段搜索时使用
页码	`page`	integer	否	最小 1
每页数量	`limit`	integer	否	1-100

query_order_exact（订单精准筛选）

路由：POST /mcp/tools/queryOrderExact

中文参数名	参数名	类型	必填	默认/约束
订单号 / 客户参考号 / 快递单号 / 排舱单号 / 柜号 / SO号 / Shipment ID	`order_number`、`reference_number`、`tracking_number`、`outbound_number`、`container_code`、`so_number`、`shipment_id`	string	否	单值精准条件；号码类型必须明确
收货国家	`receiver_country`	string	否	国家代码，值来自订单筛选项
入库开始日期 / 入库结束日期	`inbound_date_start`、`inbound_date_end`	string	否	`YYYY-MM-DD`
出库开始日期 / 出库结束日期	`outbound_date_start`、`outbound_date_end`	string	否	`YYYY-MM-DD`
产品ID / 客户ID / 仓库ID	`product_ids`、`customer_ids`、`warehouse_ids`	integer[]	否	ID 数组，值来自订单筛选项
订单号数组 / 客户参考号数组 / 快递单号数组 / 排舱单号数组 / 柜号数组 / SO号数组	`order_numbers`、`reference_numbers`、`tracking_numbers`、`outbound_numbers`、`container_codes`、`so_numbers`	string[]	否	同类号码批量查询；不能与对应单值字段混用
销售人员ID / 事业部ID	`sales_id`、`department_id`	integer	否	最小 1，值来自订单筛选项
页码	`page`	integer	否	1-100
每页数量	`limit`	integer	否	1-100

至少提供一个业务筛选条件。

query_order_detail（订单详情）

路由：POST /mcp/tools/queryOrderDetail

中文参数名	参数名	类型	必填	默认/约束
订单号	`order_number`	string	是	非空，最长 100；只接受订单号
详情模块	`section`	string	否	默认“全部”；可选订单概览、箱单信息、箱单商品、DW授权信息、附件信息、入库信息、查验信息、订单轨迹、操作日志、应收与结算日志、派送信息、全部
页码	`page`	integer	否	默认 1，1-100
每页数量	`limit`	integer	否	默认 20，1-100

query_track（物流轨迹）

路由：POST /mcp/tools/queryTrack

中文参数名	参数名	类型	必填	默认/约束
内部订单ID	`order_id`	integer	否	最小 1；仅可信系统上下文可用
订单号	`order_number`	string	否	用户明确提供订单号时使用
快递/物流跟踪号	`tracking_number`	string	否	用户明确提供跟踪号时使用
页码	`page`	integer	否	默认 1，最小 1
每页数量	`limit`	integer	否	默认 5，1-100

三种定位参数应选择一种，不能猜测号码类型。

query_order_receivable_cost_details（订单应收费用明细）

路由：POST /mcp/tools/queryOrderReceivableCostDetails

中文参数名	参数名	类型	必填	默认/约束
订单号	`order_number`	string	是	非空，最长 100
页码	`page`	integer	否	默认 1，1-100
每页数量	`limit`	integer	否	默认 20，1-100

query_receivable_cost_list（应收费用单列表）

路由：POST /mcp/tools/queryReceivableCostList

中文参数名	参数名	类型	必填	默认/约束
参考号 / 跟踪号 / 订单号 / 账单号数组	`reference_numbers`、`tracking_numbers`、`order_numbers`、`bill_numbers`	string[]	条件必填	同类 OR、不同类 AND；合计最多 200 项，每项最长 100；号码类型必须明确
业务日期开始 / 结束	`business_date_start`、`business_date_end`	string	条件必填	无号码数组时必须成对提供；员工时区 `YYYY-MM-DD` 闭区间，最多 31 天
主客户 / 子客户	`customer_id`、`sub_customer_id`	integer	否	严格正整数；子客户要求同时提供主客户
出账状态	`billing_status`	integer	否	`0` 未出账（DB 0/1）、`1` 已出账（DB 1/2）
核销状态	`verification_status`	integer	否	`-1`、`0`、`1`
单据类型 / 费用项	`document_type`、`cost_type_id`	integer	否	单据类型可为 0；费用项为正整数；值来自筛选工具
页码	`page`	integer	否	默认 1，1-100
每页数量	`limit`	integer	否	默认 20，1-100

客户与回款

query_customer_list（客户列表）

路由：POST /mcp/tools/queryCustomerList

中文参数名	参数名	类型	必填	默认/约束
客户ID / 事业部ID / 商务经理ID / 客户经理ID	`customer_id`、`department_id`、`sales_id`、`merchandiser_id`	integer	否	最小 1；ID 来自客户筛选项
页码	`page`	integer	否	默认 1，1-100
每页数量	`limit`	integer	否	默认 20，1-100

query_customer_payment_followup（客户回款跟进）

路由：POST /mcp/tools/queryCustomerPaymentFollowup

中文参数名	参数名	类型	必填	默认/约束
客户ID / 事业部ID / 商务经理ID / 客户经理ID	`customer_id`、`department_id`、`sales_id`、`merchandiser_id`	integer	否	最小 1，值来自客户筛选项
仅看有未核销应收	`has_unverified_receivable_only`	boolean	否	默认 `true`
页码	`page`	integer	否	默认 1，1-100
每页数量	`limit`	integer	否	默认 20，1-100

query_customer_unverified_bill_details（未核销账单明细）

路由：POST /mcp/tools/queryCustomerUnverifiedBillDetails

中文参数名	参数名	类型	必填	默认/约束
客户ID	`customer_id`	integer	是	最小 1，先从客户筛选项取得
页码	`page`	integer	否	默认 1，1-100
每页数量	`limit`	integer	否	默认 20，1-100

query_customer_payment_records（客户逐笔回款记录）

路由：POST /mcp/tools/queryCustomerPaymentRecords

中文参数名	参数名	类型	必填	默认/约束
客户ID	`customer_id`	integer	是	最小 1，先从客户名称筛选取得
收款开始日期 / 收款结束日期	`receive_date_start`、`receive_date_end`	string	否	`YYYY-MM-DD`；闭区间最多 366 天
页码	`page`	integer	否	默认 1，1-100
每页数量	`limit`	integer	否	默认 20，1-100

list_customer_filter_options（客户筛选项）

路由：POST /mcp/tools/listCustomerFilterOptions

中文参数名	参数名	类型	必填	默认/约束
筛选类型	`filter_type`	string	是	客户名称、事业部、商务经理、客户经理
关键词	`keyword`	string	否	最长 100
页码	`page`	integer	否	默认 1，1-100
每页数量	`limit`	integer	否	默认 20，1-100

list_receivable_cost_filter_options（应收费用单筛选项）

路由：POST /mcp/tools/listReceivableCostFilterOptions

中文参数名	参数名	类型	必填	默认/约束
筛选类型	`filter_type`	string	是	主客户、子客户、出账状态、核销状态、单据类型、费用项
主客户ID	`customer_id`	integer	条件必填	`filter_type=子客户` 时必填，其他类型禁止传入
关键词	`keyword`	string	否	最长 100
页码	`page`	integer	否	默认 1，1-100
每页数量	`limit`	integer	否	默认 20，1-100

排舱与报关

query_outbound_list（排舱列表）

路由：POST /mcp/tools/queryOutboundList

中文参数名	参数名	类型	必填	默认/约束
排舱阶段	`outbound_status`	integer	是	枚举 20、30、60、70、80、90、100、110、120；必须明确阶段
排舱单号数组 / 订单号数组 / 柜号数组 / SO号数组 / 提单号数组	`outbound_numbers`、`order_numbers`、`container_codes`、`so_numbers`、`bl_numbers`	string[]	否	各 1-100 项；号码类型必须明确
运输方式	`shipping_method`	integer	否	枚举 1、2、3
集货仓库	`warehouse_id`	integer/string	否	值来自排舱筛选项
是否直送柜	`is_direct_send`	integer	否	枚举 0、1
拖车方式 / 报关方式 / 清关方式	`trailer_types`、`declaration_types`、`clearance_types`	integer[]	否	每项 1-2 个
截关时间、预计装柜时间、创建时间、装柜时间（开始/结束）	`closing_time_start`、`closing_time_end`、`est_loading_time_start`、`est_loading_time_end`、`create_date_start`、`create_date_end`、`loading_time_start`、`loading_time_end`	string	否	时间字符串最长 19
页码	`page`	integer	否	默认 1，1-100
每页数量	`limit`	integer	否	默认 20，1-100

query_outbound_detail（排舱详情）

路由：POST /mcp/tools/queryOutboundDetail

中文参数名	参数名	类型	必填	默认/约束
排舱单号	`outbound_number`	string	是	非空，最长 100
页码	`page`	integer	否	默认 1，1-100
每页数量	`limit`	integer	否	默认 10，1-20

query_customs_declaration_files（报关资料文件）

路由：POST /mcp/tools/queryCustomsDeclarationFiles

中文参数名	参数名	类型	必填	默认/约束
订单号数组	`order_numbers`	string[]	条件必填	与排舱单号数组二选一；1-100 项
排舱单号数组	`outbound_numbers`	string[]	条件必填	与订单号数组二选一；1-100 项
页码	`page`	integer	否	默认 1，1-100
每页数量	`limit`	integer	否	默认 20，1-100

list_outbound_filter_options（排舱筛选项）

路由：POST /mcp/tools/listOutboundFilterOptions

中文参数名	参数名	类型	必填	默认/约束
筛选类型	`filter_type`	string	是	排舱阶段、运输方式、集货仓库、是否直送柜、拖车方式、报关方式、清关方式
关键词	`keyword`	string	否	最长 100
页码	`page`	integer	否	默认 1，1-100
每页数量	`limit`	integer	否	默认 20，1-100

list_order_filter_options（订单筛选项）

路由：POST /mcp/tools/listOrderFilterOptions

中文参数名	参数名	类型	必填	默认/约束
筛选类型	`filter_type`	string	是	`country`、`product`、`customer`、`sales`、`warehouse`、`department`
关键词	`keyword`	string	否	关键词
页码	`page`	integer	否	最小 1
每页数量	`limit`	integer	否	1-100

导出

export_pending_outbound_orders（未排舱订单异步导出）

路由：POST /mcp/tools/exportPendingOutboundOrders

所有字段均为非必填；筛选名称或 ID 必须先通过 list_pending_outbound_export_filter_options 获取。

中文参数名	参数名	类型	必填	默认/约束
订单号或客户参考号	`number`	string	否	多值用空格、英文逗号或换行分隔
产品分类ID / 集货仓库ID / 进口商ID	`product_type_id`、`order_warehouse_id`、`importer_id`	integer	否	筛选 ID
物流产品ID数组 / 订单状态数组	`product_id`、`status`	integer[]	否	筛选数组
目的国 / 派送地址 / 入库时间范围 / 合并报关单号 / 货物类型	`receiver_country`、`address`、`inbound_date`、`merge_declare_number`、`packing_type`	string	否	入库时间格式 `YYYY-MM-DD - YYYY-MM-DD`
是否装柜剔除	`is_remove`	integer	否	枚举 0、1
商品属性（带电、带磁、带木、其它、FDA、玩具、超长超重、敏感货、食品、无属性）	`is_battery`、`is_magnetic`、`is_wood`、`is_other`、`is_fda`、`is_toy`、`is_ultra_limit`、`is_sensitive`、`is_food`、`no_property`	string	否	选中时传 `Y`

export_out_of_province_port_data（省外进港资料异步导出）

路由：POST /mcp/tools/exportOutOfProvincePortData

中文参数名	参数名	类型	必填	默认/约束
资料类型	`file_type`	string	是	`NB` 宁波、`SH` 上海、`MS` 美森
排舱单号数组 / 柜号数组 / 提单号数组 / SO号数组	`outbound_numbers`、`container_codes`、`bl_numbers`、`so_numbers`	string[]	条件必填	四选一；每项 1-100 个；号码类型必须明确

query_export_task（查询导出任务）

路由：POST /mcp/tools/queryExportTask

中文参数名	参数名	类型	必填	默认/约束
导出任务引用	`task_ref`	string	是	只能使用导出工具返回值，1-512 字符

list_pending_outbound_export_filter_options（未排舱导出筛选项）

路由：POST /mcp/tools/listPendingOutboundExportFilterOptions

中文参数名	参数名	类型	必填	默认/约束
筛选项类型	`filter_type`	string	是	`product_type`、`product`、`warehouse`、`country`、`importer`、`packing_type`、`order_status`、`goods_attribute`、`is_remove`
产品分类ID	`product_type_id`	integer	否	查询物流产品时使用
关键词	`keyword`	string	否	名称或编码关键词
页码	`page`	integer	否	默认 1，最小 1
每页数量	`limit`	integer	否	默认 20，1-100

返回参数

展示字段以 services/output_presenter.py 白名单为准：除 query_order 外，其余工具只暴露白名单中文键；未知字段关闭失败。成功结果位于 tools/call 的 result.structuredContent（另有文本 content），并带 _meta.request_id。

通用分页（多数表格工具）：

展示名	字段	类型	说明
页码	`page`	integer	当前页，1-100
每页数量	`limit`	integer	当前页大小
是否还有更多	`has_more`	boolean	是否还有下一页

订单详情工具内的分页键为中文：页码、每页数量、是否还有更多。

query_order

兼容旧格式，不经 Presenter 白名单：columns（列名数组）、records（记录数组）；具体列由后端旧接口决定。

query_order_exact

结构：summary（可选文本）、headers、rows、pagination、tips（可选）。rows 与 headers 列序一一对应；后端可返回白名单子集。

展示名	后端字段	说明
订单号	`order_number`
客户参考号	`reference_number`
状态	`status_txt_name`
是否已查验	`check_status_txt_name`
客户名称	`customer_name`
客户属性	`customer_account_type_name`
入库时间	`inbound_date`
未完成工单	`wo_num`
物流产品	`product_name`
件数	`inbound_pieces`
体积(CBM)	`inbound_volume`
重量(KG)	`inbound_weight`
品名	`pro_cn_name`
报关方式	`export_declaration_type`
合并报关单号	`merge_declare_number`
派送地址	`delivery_address`
柜号	`container_code`
排舱单状态	`out_status_txt`
目的港	`hinge_of_destination`
ETD	`etd`
ATD	`atd`
ETA	`eta`
ATA	`ata`
清关放行时间	`release_time`
海外入库时间	`oversea_inbound_date`
APPT时间	`appt_time`
预计装柜时间	`est_loading_time`
海外提柜时间	`pickup_time`
派送方式	`delivery_way_title`
快递单号	`tracking_number`	header 可带 description：承运商跟踪号码
Shipment ID	`shipment_id`
商品属性	`goods_attribute`
SKU	`sku`
商务经理	`sales_user`
客户经理	`service_user`
事业部	`department_name`
订单备注	`remark`
进口商	`importer_name`
交货仓库	`warehouse_name`
付款状态	`paid_status_name`

query_track

结构：headers、rows、pagination、tips（可选）。

展示名	后端字段	说明
轨迹节点	`status`	轨迹状态，如开始集港、离港放行等
轨迹地点	`location`	发生地点
时间	`time`	已转换为用户时区
轨迹内容	`content`	详细描述
跟踪号	`tracking_number`	快递单号
Shipment ID	`shipment_id`	包裹 ID

query_customs_declaration_files

结构：headers、rows、pagination、tips（可选）。

展示名	后端字段	说明
排舱单号	`outbound_number`
订单号	`order_number`
文件名	`file_name`
文件类型	`file_type`
文件链接	`file_url`	安全下载/预览链接

query_outbound_list

结构：headers、rows、pagination、tips（可选）。固定白名单 31 列（后端返回子集时按实际列展示）。

展示名	后端字段	说明
排舱单号	`outbound_number`
直送柜	`direct_send`
备注	`remark`
超长超重	`cargo_type`
集货仓库	`warehouse_name`
状态	`status`
SO号	`so_number`
柜号	`container_code`
封条号	`seal_number`
柜型	`container_type`
运输方式	`shipping_method`
体积(CBM)	`total_volume`
重量(KG)	`total_weight`
船期	`ship_schedule`
截关时间	`closing_time`
预计装柜时间	`est_loading_time`
操作人	`operator`
拖报清方式	`operation_modes`
操作时间	`operation_time`
船司	`ship_company`
船名航次	`vessel_name`
截SI时间	`cutoff_time_si`
清关口岸	`clearance_port`
起运港	`loading_port`
目的港	`destination_port`
中转港	`transit_port`
ETD	`etd`
ETA	`eta`
是否含FDA认证商品	`has_fda`
是否含CPSC商品	`has_cpsc`
是否含食品	`has_food`

query_outbound_detail

结构：

顶层键	说明
`summary.headers` / `summary.row`	排舱汇总：11 项，headers 与 row 一一对应
`details.headers` / `details.rows`	订单明细表
`details.pagination`	明细分页（英文键）
`details.tips`	可选提示

汇总字段：

展示名	后端字段
提单号	`bl_number`
柜号	`container_code`
柜型	`container_type`
总体积	`total_volume`
总重量	`total_weight`
总件数	`total_pieces`
SKU	`sku`
买单报关数量	`buy_declaration_count`
一般贸易报关数量	`general_declaration_count`
必装单量/体积	`must_load`
备装单量/体积	`backup_load`

明细字段：

展示名	后端字段	说明
订单号	`order_number`
超长超重	`cargo_type`
报关资料	`customs_files`	数组，每项含 `文件名称`、`文件类型`、`文件链接`
客户参考号	`reference_number`
客户名称	`customer_name`
报关方式	`declaration_type`
合并报关单号	`merge_declare_number`
订单备注	`order_remark`
提单号	`bl_number`
柜号	`container_code`
客户经理	`customer_service`
预计入库时间	`est_inbound_date`
实际入库时间	`inbound_date`
状态	`status`
预报件数 / 入库件数	`pieces`
预报实重(KG) / 入库实重(KG)	`weight`
预报体积(m³) / 入库体积(m³)	`volume`
交货地	`pickup_place`
物流产品	`product_name`
品名	`goods_name`
截关时间	`closing_time`
报关备注	`clearance_remark`
清关备注	`import_clearance_remark`
派送地址	`delivery_address`
派送类型	`delivery_type`
派送方式	`delivery_way`
派送渠道	`channel`
目的国	`country_name`
进口商	`importer_name`
清关税号	`vat_type`
货物类型	`packing_type`
是否问题件	`is_abnormal`
包装类型	`package_method`
到货回复	`order_reply`
订单是否必装	`is_must_load`
是否含FDA认证商品	`has_fda`
是否含CPSC商品	`has_cpsc`
是否含食品	`has_food`

query_order_detail

顶层固定：订单号、详情模块；再按 section 展开中文模块。分页键为 页码 / 每页数量 / 是否还有更多。

section 入参	详情模块展示名	主要返回块
`overview`	订单概览	`状态节点`、`订单信息`、`货运信息`、`箱单汇总`、`进出口商`
`packages`	箱单信息	`明细`、`分页`
`package_items`	箱单商品	`明细`、`分页`
`dw_auth`	DW授权信息	`明细`、`分页`
`attachments`	附件信息	`明细`、`分页`
`inbound`	入库信息	`入库概况`、`明细`、`分页`
`checks`	查验信息	`明细`、`分页`
`tracks`	订单轨迹	`明细`、`分页`
`operation_logs`	操作日志	`明细`、`分页`
`cost_logs`	应收与结算日志	`明细`、`分页`
`delivery`	派送信息	`派送汇总`、`明细`、`分页`
`all`	全部	`订单概览` + 上表其余各模块

状态节点字段：

展示名	后端字段	说明
阶段	`stage`
节点	`label`
状态	`state`	映射为：已完成 / 进行中 / 待完成 / 不展示
时间	`occurred_at`
时间类型	`time_kind`	映射为：实际 / 预计 / 暂无

订单概览 — 订单信息：

展示名	后端字段
订单号	`order_number`
客户参考号	`reference_number`
客户名称	`customer_name`
起运国	`departure_country`
目的国	`destination_country`
包装类型	`package_method`
物流产品	`product_name`
预报件重体	`forecast_pwv`
入库件重体	`inbound_pwv`
应收计费重/体积	`receivable_charge_weight`
结算计费重/体积	`settlement_charge_weight`
报关类型	`declaration_type`
是否需要预录单	`pre_recording`
企业/个人姓名	`idcard_name`
社会信用代码/身份证号	`idcard_number`
排舱单号	`outbound_number`
直送柜/拼柜	`container_mode`
是否可查看轨迹地图	`track_map_available`
购买保险	`insurance`
派送方式	`delivery_way`
退运附加	`return_shipping_surcharge`
工单数量	`work_order_count`
账单备注	`bill_remark`
订单备注	`remark`

订单概览 — 货运信息：

展示名	后端字段
预计入库时间	`estimated_inbound_time`
货物类型	`cargo_type`
交货方式	`pickup_way`
交货仓库	`warehouse`
提货地址	`pickup_address`
提货联系人	`pickup_contact`
提货联系电话	`pickup_phone`
派送类型	`delivery_type`
派送地址	`delivery_address`
派送备注	`delivery_remark`
海外仓	`oversea_warehouse`

订单概览 — 箱单汇总：

展示名	后端字段
箱数	`box_count`
重量	`total_weight`
重量单位	`weight_unit`
体积	`total_volume`
SKU数量	`sku_count`
清关总价	`clearance_total_price`
清关币种	`clearance_currency`
采购总价	`purchase_total_price`
采购币种	`purchase_currency`

订单概览 — 进出口商：

展示名	后端字段
出口商	`exporter`
进口商	`importer`
是否做产地证	`coo_required`

箱单信息明细：

展示名	后端字段
SHIPMENT ID	`shipment_id`
REFERENCE ID	`reference_id`
SKU	`sku_summary`
商品名	`product_name_summary`
箱数	`box_quantity`
单箱长(CM)	`box_length_cm`
单箱宽(CM)	`box_width_cm`
单箱高(CM)	`box_height_cm`
单箱毛重量(KG)	`gross_weight_kg`
单箱净重量(KG)	`net_weight_kg`
长度是否超限	`is_over_length`
宽度是否超限	`is_over_width`
高度是否超限	`is_over_height`
重量是否超限	`is_over_weight`

箱单商品明细：

展示名	后端字段
SHIPMENT ID	`shipment_id`
REFERENCE ID	`reference_id`
箱规	`box_specification`
箱规单位	`box_specification_unit`
箱单单箱毛重(KG)	`package_gross_weight_kg`
箱单单箱净重(KG)	`package_net_weight_kg`
查验结果	`inspection_result`
异常原因	`exception_reason`
查验图片数量	`inspection_photo_count`
SKU	`sku`
单箱个数	`units_per_box`
报关类型	`declaration_type`
箱号	`box_number`
商品单箱毛重量(KG)	`item_gross_weight_kg`
商品单箱净重量(KG)	`item_net_weight_kg`
中文品名	`chinese_name`
英文名称	`english_name`
品牌类型	`brand_type`
品牌	`brand`
型号	`model`
材质（CN）	`material_cn`
材质（EN）	`material_en`
用途	`purpose_cn`
商品属性	`goods_attributes`
报关编码	`declaration_hs_code`
清关编码	`clearance_hs_code`
材质占比	`material_ratio`
清关单价	`clearance_unit_price`
清关币种	`clearance_currency`
采购单价	`purchase_unit_price`
采购币种	`purchase_currency`
商品图片数量	`product_image_count`
备注	`remark`

DW授权信息明细：

展示名	后端字段
FBAID	`fba_id`
DW开始时间	`dw_start`
DW结束时间	`dw_end`
DW	`dw_display`
客户授权状态	`authorization_status`

附件信息明细：

展示名	后端字段
附件分类	`category`
文件名称	`file_name`
文件类型	`file_extension`
是否图片	`is_image`
预览链接	`preview_url`
下载链接	`download_url`
收费项目	`cost_name`

入库概况：

展示名	后端字段
入库状态	`inbound_status`
入库时间	`inbound_time`
操作人	`inbound_operator`
仓库	`warehouse`
异常原因	`abnormal_reason`
入库图片数量	`inbound_photo_count`
预报件重体	`forecast_pwv_summary`
入库件重体	`inbound_pwv_summary`

入库明细：

展示名	后端字段	说明
是否贴标	`has_label`
SHIPMENT ID	`shipment_id`
入库件数	`inbound_quantity`
测量图片数量	`measurement_photo_count`
入库箱规	`box_specification`
单箱入库重量 / 总重量KG	`weight`	由 `weight_mode`=`single_box`/`total` 决定展示键名
重量单位	`weight_unit`
长度是否超限	`is_over_length`
宽度是否超限	`is_over_width`
高度是否超限	`is_over_height`
重量是否超限	`is_over_weight`
操作时间	`operated_at`

查验信息明细：

展示名	后端字段
货件编号	`shipment_id`
SKU	`sku`
箱号	`box_number`
箱数	`box_quantity`
箱规	`box_specification`
查验结果	`inspection_result`
查验图片数量	`inspection_photo_count`
备注	`remark`
查验人	`inspector`
查验时间	`inspected_at`

订单轨迹明细：

展示名	后端字段
轨迹类型	`track_type`
轨迹节点	`status`
轨迹地点	`location`
时间	`occurred_at`
跟踪号	`tracking_number`
SHIPMENT ID	`shipment_id`
轨迹内容	`content`

操作日志 / 应收与结算日志明细：

展示名	后端字段
操作时间	`operated_at`
操作内容	`content`
操作人	`operator`

派送汇总：

展示名	后端字段
主跟踪号	`master_tracking_number`
子单数量	`sub_order_count`

派送明细：

展示名	后端字段
子跟踪号	`sub_tracking_number`

query_order_receivable_cost_details

结构：headers、rows、pagination。固定 13 列。

展示名	后端字段
订单号	`order_number`
客户名称	`customer_name`
费用项	`cost_name`
费用客户	`cost_customer_name`
计费重	`charge_weight`
计费单价	`unit_price`
原币币种	`quote_currency`
应收原币	`receivable_original_amount`
应收金额（CNY）	`receivable_amount_cny`
结算金额（CNY）	`settlement_amount_cny`
费用确认状态	`cost_confirmation_status`
关账状态	`closing_status`
核销状态	`verification_status`

query_receivable_cost_list

结构：headers、rows、pagination。固定 24 列；四个金额字段为 {"amount": number, "currency": string}。

展示名	后端字段
主客户	`main_customer_name`
子客户	`sub_customer_name`
客户属性	`customer_attribute`
事业部	`department_name`
单据类型	`document_type`
仓库	`warehouse_name`
业务单号	`business_number`
参考号	`reference_number`
费用项	`cost_name`
原币金额	`original_amount`
总金额	`total_amount`
已出账金额	`billed_amount`
未出账金额	`unbilled_amount`
账单编号	`bill_number`
核销状态	`verification_status`
收款水单号	`receipt_number`
收款日期	`receipt_date`
商务经理	`sales_name`
客户经理	`merchandiser_name`
引流人	`drainage_user_name`
头程订单状态	`first_leg_order_status`
结算模式	`settlement_mode`
费用发生时间	`cost_occurred_at`
业务发生时间	`business_occurred_at`

query_customer_list

结构：summary、headers、rows、pagination、display_rules。固定 17 列，须完整展示。

展示名	后端字段	说明
客户名称	`customer_name`
客户代码	`customer_code`
开户时间	`create_time`
业务类型	`business_type`
客户属性	`customer_attribute`
客户来源	`customer_source`
首次成交时间	`first_inbound_date`
最后一次走货时间	`last_inbound_date`
活跃状态	`active_status`
合同状态	`contract_status`
合同有效期	`contract_validity`
信用额度	`credit_limit`
结算币种	`currency_code`
结算模式（分业务类型）	`billing_modes`	数组，每项含 `业务类型`、`结算模式`
商务经理	`sales_name`
客户经理	`merchandiser_name`
事业部	`department_name`

query_customer_payment_followup

结构：headers、rows、pagination、display_rules。固定 14 列。

展示名	后端字段	说明
客户名称	`customer_name`
结算币种	`settlement_currency`
已出账未核销金额	`billed_unverified_amount`	number
未出账金额	`unbilled_amount`	number
逾期未回款金额	`overdue_unpaid_amount`	number
已出账未核销金额（人民币）	`billed_unverified_amount_cny`	number
未出账金额（人民币）	`unbilled_amount_cny`	number
逾期未回款金额（人民币）	`overdue_unpaid_amount_cny`	number
未回款月份汇总	`unverified_receivable_monthly_summary`	见下表
收款单未核销金额	`receipt_unverified_amount`	number
当前余额	`current_balance`	number
信用额度	`credit_limit`	number
坏账合计	`bad_debt_total`	number
合同状态	`contract_status`

未回款月份汇总子项：

展示名	后端字段	类型
应收月份	`receivable_month`	string
未核销金额	`unverified_amount`	number
是否逾期	`is_overdue`	boolean

query_customer_unverified_bill_details

结构：headers、rows、pagination。固定 6 列。

展示名	后端字段
账单月份	`bill_month`
账单号	`bill_no`
业务类型	`business_type`
结算模式	`settlement_mode`
未核销金额	`unverified_amount`
客户应收款日期	`customer_receivable_date`

query_customer_payment_records

结构：headers、rows、pagination。固定 8 列。

展示名	后端字段
客户名称	`customer_name`
收款水单号	`payment_reference`
原币到账金额	`original_received_amount`
实际收款金额	`actual_received_amount`
收款日期	`receive_date`
已核销金额	`verified_amount`
未核销金额	`unverified_amount`
收款审核状态	`payment_approval_status`

筛选项工具

list_customer_filter_options、list_order_filter_options、list_outbound_filter_options、list_pending_outbound_export_filter_options、list_receivable_cost_filter_options 结构相同：headers、rows、pagination。应收费用单筛选的 value 可合法为 0 或 -1。

展示名	说明
可传值	后续业务工具可直接传入的 value
显示名称	给人看的名称
业务编码	辅助识别编码，可能为空

export_pending_outbound_orders / export_out_of_province_port_data

只提交异步任务，不返回文件。结构：

展示名	字段	说明
提示文案	`message`	固定为「导出任务已提交」
任务	`task.task_ref`	不透明任务引用，供 `query_export_task` 使用
状态	`task.status`	固定 `queued`
建议等待秒数	`task.retry_after_seconds`	正整数

query_export_task

状态	返回结构
`queued` / `running`	`message`、`task.task_ref`、`task.status`、`task.retry_after_seconds`
`failed`	`message`（导出任务失败，请重新提交）、`task.task_ref`、`task.status`
`completed`	`message`（文件已生成）、`task`、`files[]`

files 每项：

展示名	字段	说明
文件名称	`label`
安全下载链接	`url`	仅 http/https

返回结果示例

示例值均为虚构数据；业务数据在 structuredContent。

表格工具

{
  "content": [{"type": "text", "text": "订单查询结果"}],
  "structuredContent": {
    "headers": [{"label": "订单号"}, {"label": "客户名称"}],
    "rows": [["ORD202607290001", "示例客户"]],
    "pagination": {"page": 1, "limit": 20, "has_more": false}
  },
  "_meta": {"request_id": "rq_demo_001"}
}

query_outbound_detail

{
  "summary": {
    "headers": [{"label": "提单号"}, {"label": "柜号"}, {"label": "总体积"}],
    "row": ["BL001", "MSCU1234567", 12.5]
  },
  "details": {
    "headers": [{"label": "订单号"}, {"label": "客户名称"}],
    "rows": [["ORD202607290001", "示例客户"]],
    "pagination": {"page": 1, "limit": 10, "has_more": false}
  }
}

query_order_detail

{
  "订单号": "ORD202607290001",
  "详情模块": "全部",
  "订单概览": {
    "状态节点": [{"阶段": "入库", "节点": "已入库", "状态": "已完成", "时间": "2026-07-29 10:00:00", "时间类型": "实际"}],
    "订单信息": {"订单号": "ORD202607290001", "客户名称": "示例客户"}
  },
  "订单轨迹": {
    "明细": [{"轨迹节点": "已入库", "时间": "2026-07-29 10:00:00"}],
    "分页": {"页码": 1, "每页数量": 20, "是否还有更多": false}
  }
}

筛选项

{
  "headers": [
    {"label": "可传值"},
    {"label": "显示名称"},
    {"label": "业务编码"}
  ],
  "rows": [[101, "示例仓库", "WH001"]],
  "pagination": {"page": 1, "limit": 20, "has_more": false}
}

异步导出

提交：

{
  "message": "导出任务已提交",
  "task": {
    "task_ref": "TASK202607290001",
    "status": "queued",
    "retry_after_seconds": 5
  }
}

查询完成：

{
  "message": "文件已生成",
  "task": {"task_ref": "TASK202607290001", "status": "completed"},
  "files": [
    {"label": "未排舱订单.xlsx", "url": "https://download.example.com/signed-url"}
  ]
}

通用返回规则

业务成功数据位于 JSON-RPC result.structuredContent；表格工具为 headers + rows + pagination。
展示名来自 Presenter 白名单；rows 单元格按 headers 列序排列，不是对象字典。
异步导出提交返回 message + task，稍后调用 query_export_task 获取状态和下载链接。
后端业务失败使用 result.isError=true；协议、参数、未知工具错误使用 JSON-RPC error，参数错误码为 -32602。
不向调用方返回数据库、Redis、Token、内部 ID 或异常堆栈等敏感内部信息。

mcp-api.md 37 KB Cronologia Originale

MCP 工具接口文档

订单与轨迹

query_order（订单兼容搜索）

query_order_exact（订单精准筛选）

query_order_detail（订单详情）

query_track（物流轨迹）

query_order_receivable_cost_details（订单应收费用明细）

query_receivable_cost_list（应收费用单列表）

客户与回款

query_customer_list（客户列表）

query_customer_payment_followup（客户回款跟进）

query_customer_unverified_bill_details（未核销账单明细）

query_customer_payment_records（客户逐笔回款记录）

list_customer_filter_options（客户筛选项）

list_receivable_cost_filter_options（应收费用单筛选项）

排舱与报关

query_outbound_list（排舱列表）

query_outbound_detail（排舱详情）

query_customs_declaration_files（报关资料文件）

list_outbound_filter_options（排舱筛选项）

list_order_filter_options（订单筛选项）

导出

export_pending_outbound_orders（未排舱订单异步导出）

export_out_of_province_port_data（省外进港资料异步导出）

query_export_task（查询导出任务）

list_pending_outbound_export_filter_options（未排舱导出筛选项）

返回参数

query_order

query_order_exact

query_track

query_customs_declaration_files

query_outbound_list

query_outbound_detail

query_order_detail

query_order_receivable_cost_details

query_receivable_cost_list

query_customer_list

query_customer_payment_followup

query_customer_unverified_bill_details

query_customer_payment_records

筛选项工具

export_pending_outbound_orders / export_out_of_province_port_data

query_export_task

返回结果示例

表格工具

query_outbound_detail

query_order_detail

筛选项

异步导出

通用返回规则

mcp-api.md 37 KB

Cronologia Originale