This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Архитектура

MinerU MCP Server — это асинхронный микросервис, написанный на Python, который выступает в роли шлюза между LLM-агентами (через протокол MCP) и сервером парсинга документов MinerU.

Сервер реализует паттерн "Атомарный инструмент с внутренней оркестрацией". Для клиента (агента) процесс выглядит как однократный синхронный вызов функции, тогда как внутри сервер выполняет сложную цепочку асинхронных операций: скачивание файла, постановка задачи в очередь MinerU, ожидание выполнения (поллинг) и агрегация результатов.

Обзор потока данных

Поток данных начинается с вызова инструмента parse_document через Streamable HTTP и заканчивается возвратом Markdown-текста.

sequenceDiagram
    participant Agent as LLM Agent
    participant MCP as MCP Server
    participant FS as File Handler
    participant Client as MinerU Client
    participant MinerU as MinerU API

    Agent->>MCP: Call parse_document
    MCP->>FS: Download or Decode File
    FS-->>MCP: Temp file path
    MCP->>Client: Submit Parse Task
    Client->>MinerU: POST /tasks
    MinerU-->>Client: Task ID
    loop Poll for Status
        MCP->>Client: Check Task Status
        Client->>MinerU: GET /tasks/{id}
        MinerU-->>Client: Status (pending/completed)
    end
    Client->>MinerU: GET /tasks/{id}/result
    MinerU-->>Client: Result Data
    Client->>MCP: Formatted Markdown
    MCP->>FS: Cleanup Temp File
    MCP-->>Agent: Return markdown result

Ключевые компоненты

Архитектура разделена на четыре основных модуля для обеспечения чистоты кода и тестируемости.

1. MCP Tools (mcp_tools.py)

Точка входа для внешних запросов. Определяет инструменты, доступные агенту.

• Файл: src/mineru_mcp/mcp_tools.py
• Ответственность:
  • Декорирование функций как MCP-инструменты.
  • Валидация входных параметров (source_type, source, filename).
  • Координация вызовов file_handler и mineru_client.
  • Обработка исключений и возврат понятных ошибок агенту.

2. File Handler (file_handler.py)

Управляет жизненным циклом файла-документа.

• Файл: src/mineru_mcp/file_handler.py
• Ключевые функции:
  • download_file_from_url(): Асинхронная загрузка файла по публичному URL через httpx.
  • decode_base64_string(): Декодирование строки Base64 в байты.
  • save_to_temp_file(): Сохранение байтов во временный файл с уникальным именем (UUID) для предотвращения коллизий.

3. MinerU Client (mineru_client.py)

Ядро взаимодействия с внешним сервисом MinerU. Реализует логику асинхронного ожидания.

• Файл: src/mineru_mcp/mineru_client.py
• Ключевые функции:
  • submit_parse_task(): Отправка файла на сервер MinerU (POST /tasks). Возвращает task_id.
  • wait_for_task_completion(): Реализует внутренний поллинг. В цикле проверяет статус задачи каждые MCP_POLL_INTERVAL_SECONDS (настраивается через конфиг). При статусе completed запрашивает результат.
  • format_result(): Преобразует сырой JSON-ответ MinerU v3.x в читаемый Markdown. Обрабатывает специфичную структуру results (словарь по именам файлов).

4. Configuration (config.py)

Централизованное управление параметрами окружения.

• Файл: src/mineru_mcp/config.py
• Ключевые переменные:
  • MINERU_URL: Адрес API MinerU.
  • MCP_TIMEOUT_SECONDS: Общий лимит времени на выполнение задачи.
  • MCP_POLL_INTERVAL_SECONDS: Частота опроса статуса.
  • MINERU_BACKEND: Выбор движка парсинга (hybrid-engine, pipeline и др.).

Взаимодействие с MinerU

Сервер строго следует API MinerU v3.x. Важно понимать различия в структуре ответов между версиями.

Специфика MinerU v3.x

В версии 3.x MinerU возвращает результаты не в виде плоского списка, а в виде словаря, где ключами являются имена файлов.

Пример структуры ответа MinerU:

{
  "task_id": "...",
  "status": "completed",
  "result": {
    "report.pdf": {
      "md_content": "# Заголовок\n\nТекст документа...",
      "content_list": [...]
    }
  }
}

Функция format_result() специально адаптирована для распаковки этого словаря. Если флаг include_structured_data равен False, она извлекает только поле md_content, игнорируя тяжеловесные метаданные, что экономит токены контекста LLM.

Внутренний поллинг

Поскольку парсинг документов может занимать от нескольких секунд до минут, MinerU использует асинхронную модель задач. MCP-сервер скрывает эту асинхронность от агента, используя механизм поллинга.

1. Запуск: После отправки задачи сервер получает task_id.
2. Ожидание: Запускается цикл while True с проверкой таймаута (MCP_TIMEOUT_SECONDS).
3. Опрос: Каждые MCP_POLL_INTERVAL_SECONDS сервер делает запрос GET /tasks/{task_id}.
4. Проверка статуса:
   • pending / processing: Продолжить ожидание.
   • completed: Сделать запрос GET /tasks/{task_id}/result и завершить работу.
   • failed: Поднять исключение с текстом ошибки MinerU.

Этот подход гарантирует, что агент не потеряет сессию и получит результат в рамках одного вызова инструмента, даже если парсинг занял длительное время.

Связи с другими модулями

• Конфигурация: Все параметры таймаутов и URL загружаются из config.py. Изменение поведения сервера (например, увеличение интервала опроса) осуществляется через переменные окружения, описанные в этой странице.
• Документация API: Модуль mcp_tools.py реализует контракт, описанный в разделе API. Параметры source_type и filename валидируются здесь.
• Устранение неполадок: Логирование в mineru_client.py помогает диагностировать проблемы с поллингом и недоступностью MinerU.

Пример использования архитектуры

При вызове инструмента:

{
  "name": "parse_document",
  "arguments": {
    "source_type": "url",
    "source": "https://example.com/doc.pdf",
    "filename": "doc.pdf"
  }
}

1. mcp_tools.py принимает запрос.
2. file_handler.py скачивает doc.pdf в /tmp/uuid_doc.pdf.
3. mineru_client.py отправляет файл в MinerU, получает task_123.
4. mineru_client.py ждет 10 секунд, проверяет статус, видит completed.
5. mineru_client.py получает Markdown, очищает /tmp/uuid_doc.pdf.
6. mcp_tools.py возвращает Markdown агенту.