mcp/tools/export_out_of_province_port_data.py

class ExportOutOfProvincePortDataTool:
    name = 'export_out_of_province_port_data'
    route_path = '/mcp/tools/exportOutOfProvincePortData'

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

    def metadata(self):
        return {
            'name': self.name,
            'description': (
                '导出后台排舱单列表中的省外进港资料，并返回可下载文件 URL。'
                '只能在用户明确要求导出省外进港资料，并明确提供排舱单号和'
                '宁波、上海或美森资料类型时调用。排舱单号不是系统订单号、'
                '客户参考号、快递单号、柜号、SO 号或 Shipment ID；不得根据'
                '号码格式猜测。号码类型或资料类型不明确时先询问用户。'
                '一次只能选择一种资料类型；用户要求多个类型时应分别调用。'
            ),
            'input_schema': {
                'type': 'object',
                'properties': {
                    'outbound_numbers': {
                        'type': 'array',
                        'items': {
                            'type': 'string',
                            'minLength': 1,
                            'maxLength': 100,
                        },
                        'minItems': 1,
                        'maxItems': 100,
                        'uniqueItems': True,
                        'description': (
                            '要导出的排舱单号数组。排舱单号是后台排舱单列表中的'
                            '业务单号，不是系统订单号、客户参考号、快递单号、柜号、'
                            'SO号或Shipment ID。只能使用用户明确提供并确认类型为'
                            '排舱单号的值，不得根据号码格式猜测。'
                        ),
                        'examples': [[
                            'PC202607140001',
                            'PC202607140002',
                        ]],
                    },
                    'file_type': {
                        'type': 'string',
                        'enum': ['NB', 'SH', 'MS'],
                        'description': (
                            '进港资料类型：NB=宁波进港资料，SH=上海进港资料，'
                            'MS=美森进港资料。必须根据用户明确选择传值；'
                            '用户未说明时先询问，不得默认选择。'
                        ),
                        'examples': ['NB'],
                    },
                },
                'required': ['outbound_numbers', 'file_type'],
                'additionalProperties': False,
            },
        }

    def call(
        self,
        outbound_numbers,
        file_type,
        request_id='rq_export_out_of_province_port_data',
    ):
        if self.api_client is None:
            raise RuntimeError(
                'api client is required for export_out_of_province_port_data'
            )

        numbers = self._normalize_outbound_numbers(outbound_numbers)
        normalized_type = str(file_type or '').strip().upper()
        if normalized_type not in ('NB', 'SH', 'MS'):
            raise ValueError('file_type must be NB, SH, or MS')

        return self.api_client.call_tool(
            self.name,
            self.route_path,
            {
                'outbound_numbers': numbers,
                'file_type': normalized_type,
            },
            request_id,
        )

    @staticmethod
    def _normalize_outbound_numbers(values):
        if not isinstance(values, list):
            raise ValueError('outbound_numbers must be an array')

        numbers = []
        for value in values:
            if not isinstance(value, str):
                raise ValueError('outbound_numbers must contain strings')
            value = value.strip()
            if not value:
                continue
            if len(value) > 100:
                raise ValueError('outbound number is too long')
            if value not in numbers:
                numbers.append(value)

        if not numbers or len(numbers) > 100:
            raise ValueError('outbound_numbers must contain 1 to 100 values')
        return numbers