mcp/tools/query_order.py

class QueryOrderTool:
    name = 'query_order'
    route_path = '/mcp/tools/queryOrder'

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

    def metadata(self):
        return {
            'name': self.name,
            'description': (
                '使用场景：仅兼容旧版跨字段通用搜索；只有用户明确要求把同一号码'
                '同时作为订单号、客户参考号、快递单号、排舱单号、柜号和SO号搜索，'
                '并且目标是查看订单列表时使用。禁止使用：用户已明确号码类型时必须'
                '改用 query_order_exact；用户只说“单号”“这个号码”或号码类型不明确时'
                '必须先询问用户，确认前不得调用。不得根据号码格式猜测，不得并行调用'
                '候选工具，不得跨字段或跨工具试查，查询无结果后也不得换字段重试。'
                '本工具返回订单列表，不返回排舱列表、排舱详情、物流轨迹、报关资料文件'
                '或导出文件。'
            ),
            'input_schema': {
                'type': 'object',
                'properties': {
                    'keyword': {
                        'type': 'string',
                        'description': (
                            '旧版跨字段通用搜索值。只有用户明确接受同时搜索订单号、'
                            '客户参考号、快递单号、排舱单号、柜号和SO号时才可传入。'
                        ),
                    },
                    'page': {'type': 'integer', 'minimum': 1},
                    'limit': {'type': 'integer', 'minimum': 1, 'maximum': 100},
                },
                'required': ['keyword'],
            },
        }

    def call(self, keyword, page=1, limit=20, request_id='rq_query_order'):
        if self.api_client is None:
            raise RuntimeError('api client is required for query_order')
        keyword = str(keyword).strip()
        if not keyword:
            raise ValueError('keyword is required')
        page = max(1, int(page))
        limit = max(1, min(100, int(limit)))
        payload = {
            'keyword': keyword,
            'page': page,
            'limit': limit,
        }
        return self.api_client.call_tool(self.name, self.route_path, payload, request_id)