mcp/tools/query_freightower_track.py

class QueryFreightowerTrackTool:
    name = 'query_freightower_track'
    route_path = '/mcp/tools/queryFreightowerTrack'

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

    def metadata(self):
        number = {
            'type': 'string',
            'minLength': 1,
            'maxLength': 100,
        }
        return {
            'name': self.name,
            'description': (
                '使用场景：用户明确要查看飞驼现场船期和集装箱节点时使用，'
                '返回船名、航次、预计离港、预计到达、中转港/目的港/交货地，'
                '以及已经发生的轨迹节点。提单号、柜号至少提供一个；'
                '号码类型不明确时必须先询问用户是提单号还是柜号，确认前不得调用。'
                '不得根据号码格式猜测，不得跨字段或跨工具试查。'
                '禁止使用：系统里已经保存的轨迹用 query_track；'
                '本工具不导出文件，不修改干线到达或提柜状态。'
            ),
            'input_schema': {
                'type': 'object',
                'properties': {
                    'bl_number': dict(number, description=(
                        '提单号。仅当用户明确说明是提单号时使用，'
                        '不得放入其他类型号码。'
                    )),
                    'container_code': dict(number, description=(
                        '柜号。仅当用户明确说明是柜号时使用，'
                        '不得放入其他类型号码。'
                    )),
                },
                'additionalProperties': False,
            },
        }

    def call(
        self,
        bl_number='',
        container_code='',
        request_id='rq_query_freightower_track',
        **_ignored,
    ):
        if self.api_client is None:
            raise RuntimeError(
                'api client is required for query_freightower_track'
            )
        payload = {}
        bl_number = self._number(bl_number, 'bl_number')
        container_code = self._number(container_code, 'container_code')
        if bl_number:
            payload['bl_number'] = bl_number
        if container_code:
            payload['container_code'] = container_code
        if not payload:
            raise ValueError('bl_number or container_code is required')
        return self.api_client.call_tool(
            self.name,
            self.route_path,
            payload,
            request_id,
        )

    @staticmethod
    def _number(value, field):
        if value in (None, ''):
            return ''
        if not isinstance(value, str):
            raise ValueError(field + ' must be a string')
        value = value.strip()
        if len(value) > 100:
            raise ValueError(field + ' must contain at most 100 characters')
        return value