mcp/tools/query_track.py

class QueryTrackTool:
    name = 'query_track'
    route_path = '/mcp/tools/queryTrack'

    def __init__(self, api_client=None):
        self.api_client = api_client

    def metadata(self):
        return {
            'name': self.name,
            'description': (
                '使用场景：用户明确要查看物流轨迹时使用，只返回轨迹节点、地点、时间、'
                '内容、跟踪号和Shipment ID。应只选择一种定位方式：用户明确说订单号或'
                '排舱单号时使用订单号参数，明确说跟踪号、柜号或快递单号时使用快递单号'
                '参数；内部订单ID只可使用可信系统上下文中已有的值，不得向用户索取或'
                '自行推断。号码类型不明确时必须先询问用户是订单号、排舱单号、跟踪号、'
                '柜号还是快递单号，确认前不得调用。禁止使用：不得用本工具查询订单资料、'
                '排舱列表、排舱详情、报关资料文件或导出结果。不得根据号码格式猜测，'
                '不得跨字段或跨工具试查，查询无结果后不得换号码类型重试。'
                '参数名仅用于工具调用；向用户回答时只能使用“订单号”、“排舱单号”、'
                '“跟踪号”、“柜号”、“快递单号”等业务名称，不得展示内部参数名。'
            ),
            'input_schema': {
                'type': 'object',
                'properties': {
                    'order_id': {
                        'type': 'integer', 'minimum': 1,
                        'description': '可信系统上下文中已有的内部订单ID；不得向用户索取或猜测。',
                    },
                    'order_number': {
                        'type': 'string',
                        'description': '订单号或排舱单号；仅当用户明确说明是订单号或排舱单号时使用。',
                    },
                    'tracking_number': {
                        'type': 'string',
                        'description': '跟踪号、柜号或快递单号；仅当用户明确说明该类型时使用。',
                    },
                    'page': {'type': 'integer', 'minimum': 1, 'default': 1},
                    'limit': {'type': 'integer', 'minimum': 1, 'maximum': 100, 'default': 5},
                },
            },
        }

    def call(self, order_id=None, order_number=None, tracking_number=None, page=1, limit=5, request_id='rq_query_track'):
        if self.api_client is None:
            raise RuntimeError('api client is required for query_track')

        if order_id is None and not order_number and not tracking_number:
            raise ValueError('order_id, order_number or tracking_number is required')

        payload = {
            'page': max(1, int(page)),
            'limit': max(1, min(100, int(limit))),
        }

        if order_id is not None:
            order_id = int(order_id)
            if order_id <= 0:
                raise ValueError('order_id must be greater than 0')
            payload['order_id'] = order_id

        if order_number:
            payload['order_number'] = str(order_number).strip()

        if tracking_number:
            payload['tracking_number'] = str(tracking_number).strip()

        return self.api_client.call_tool(self.name, self.route_path, payload, request_id)