mcp/tools/query_headhaul_document_list.py

from tools.headhaul_document_common import (
    NUMBER_FIELDS,
    bounded_integer,
    number_list,
    number_properties,
)


class QueryHeadhaulDocumentListTool:
    name = 'query_headhaul_document_list'
    route_path = '/mcp/tools/queryHeadhaulDocumentList'

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

    def metadata(self):
        properties = {
            'document_type_id': {
                'type': 'integer',
                'minimum': 1,
                'description': (
                    '文档类型。必须先调用list_headhaul_document_filter_options'
                    '并选择“查询文档类型”取得可传值。'
                ),
            },
            'original_name': {
                'type': 'string',
                'minLength': 1,
                'maxLength': 255,
                'description': '完整原始文件名，精确匹配，不是模糊搜索。',
            },
        }
        properties.update(number_properties())
        properties['page'] = {
            'type': 'integer', 'minimum': 1, 'maximum': 100, 'default': 1,
        }
        properties['limit'] = {
            'type': 'integer', 'minimum': 1, 'maximum': 100, 'default': 20,
        }
        return {
            'name': self.name,
            'description': (
                '使用场景：用户要看头程文档列表时，必须先有文档类型、完整文件名'
                '或已经标明种类的录入单号之一，再查询当前页。对照后台'
                'admin/document/index，一行一份文件或外链。号码类型不明确时必须先询问用户，'
                '不得根据号码格式猜测，不得跨字段或跨工具试查，也不得改走'
                'query_customs_declaration_files或订单附件。'
                '禁止使用：空扫全表、混查单号框、行内编辑、把文件放进工具参数。'
                '参数只用于工具内部调用；最终回答只能展示中文业务名称；'
                '描述筛选条件时不得展示筛选字段的英文参数名。'
            ),
            'input_schema': {
                'type': 'object',
                'properties': properties,
                'additionalProperties': False,
            },
        }

    def call(
        self,
        document_type_id=None,
        original_name=None,
        page=1,
        limit=20,
        request_id='rq_query_headhaul_document_list',
        **numbers
    ):
        if self.api_client is None:
            raise RuntimeError(
                'api client is required for query_headhaul_document_list'
            )
        payload = {}
        if document_type_id is not None:
            if isinstance(document_type_id, bool) or not isinstance(
                document_type_id, int
            ) or document_type_id < 1:
                raise ValueError('document_type_id is invalid')
            payload['document_type_id'] = document_type_id
        if original_name is not None:
            name = str(original_name).strip()
            if not name or len(name) > 255:
                raise ValueError('original_name is invalid')
            payload['original_name'] = name
        for field in NUMBER_FIELDS:
            if field in numbers and numbers[field] is not None:
                payload[field] = number_list(numbers[field], field)
        if (
            'document_type_id' not in payload
            and 'original_name' not in payload
            and not any(field in payload for field in NUMBER_FIELDS)
        ):
            raise ValueError('locator is required')
        payload['page'] = bounded_integer(page, 'page')
        payload['limit'] = bounded_integer(limit, 'limit')
        return self.api_client.call_tool(
            self.name, self.route_path, payload, request_id,
        )