mcp/tools/export_container_timeliness_report.py

from tools.query_container_timeliness_list import QueryContainerTimelinessListTool


class ExportContainerTimelinessReportTool:
    name = 'export_container_timeliness_report'
    route_path = '/mcp/tools/exportContainerTimelinessReport'

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

    def metadata(self):
        date_field = {
            'type': 'string',
            'format': 'date',
            'pattern': '^\\d{4}-\\d{2}-\\d{2}$',
        }
        number_array = {
            'type': 'array',
            'minItems': 1,
            'maxItems': 200,
            'items': {
                'type': 'string',
                'minLength': 1,
                'maxLength': 100,
                'pattern': '.*\\S.*',
            },
        }
        return {
            'name': self.name,
            'description': (
                '本工具只提交异步导出任务，不会在本次调用中等待文件生成，也禁止在一次调用内'
                '轮询任务状态。成功后返回任务引用(task_ref)和建议等待时间'
                '(retry_after_seconds)。稍后单独使用 query_export_task 查询任务状态或下载链接。'
                '使用场景：只有用户明确要求导出柜子时效统计报表并需要下载文件时才可调用。'
                '必须提供柜号数组、提单号数组或最多31个起运港当地日历日的干线实际出发时间闭区间；'
                '没有号码时干线实际出发时间必填，有号码时时间可选。柜号与提单号可同时传入并按AND收窄。'
                '号码类型不明确时必须先询问用户；用户没有明确号码类型时必须先询问：'
                '“请确认使用哪种号码导出：柜号还是提单号？”确认前不得调用。'
                '禁止使用：查看柜子时效表格、排舱列表、混用出库时间或其他后台页面筛选、'
                '一次调用内轮询 query_export_task。看表格改走 query_container_timeliness_list。'
                '不得根据号码格式猜测，不得跨字段或跨工具试查。'
                '参数名仅用于工具调用；向用户回答时只能使用中文业务名称，'
                '不得展示内部参数名。'
            ),
            'input_schema': {
                'type': 'object',
                'properties': {
                    'container_codes': dict(
                        number_array,
                        description=(
                            '柜号数组。仅当用户明确说柜号时使用；'
                            '不得放入其他类型号码。'
                        ),
                    ),
                    'bl_numbers': dict(
                        number_array,
                        description=(
                            '提单号数组。仅当用户明确说提单号时使用；'
                            '不得放入其他类型号码。'
                        ),
                    ),
                    'departure_time_start': dict(
                        date_field,
                        description='干线实际出发时间开始日期，起运港当地日历日 YYYY-MM-DD。',
                    ),
                    'departure_time_end': dict(
                        date_field,
                        description=(
                            '干线实际出发时间结束日期，起运港当地日历日 YYYY-MM-DD，'
                            '且与开始日期跨度不超过31个日历日。'
                        ),
                    ),
                },
                'required': [],
                'additionalProperties': False,
            },
        }

    def call(
        self,
        container_codes=None,
        bl_numbers=None,
        departure_time_start=None,
        departure_time_end=None,
        request_id='rq_export_container_timeliness_report',
    ):
        if self.api_client is None:
            raise RuntimeError(
                'api client is required for export_container_timeliness_report'
            )
        payload = QueryContainerTimelinessListTool._locator_payload(
            container_codes,
            bl_numbers,
            departure_time_start,
            departure_time_end,
        )
        return self.api_client.call_tool(
            self.name, self.route_path, payload, request_id,
        )