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 — это микросервис, разработанный для обеспечения бесшовной интеграции между системами на базе больших языковых моделей (LLM) и инструментом извлечения данных MinerU. Проект реализует спецификацию Model Context Protocol (MCP), позволяя LLM-агентам использовать возможности MinerU для анализа документов как стандартные инструменты.

Назначение

Основная цель проекта — абстрагировать сложность взаимодействия с асинхронным API MinerU и предоставить LLM-агентам простой, стандартизированный интерфейс.

MinerU MCP Server решает следующие задачи:

1. Стандартизация взаимодействия: Преобразует специфичные запросы к MinerU в инструменты MCP, понятные любым совместимым LLM-клиентам (например, через LiteLLM).
2. Управление состоянием задач: Внутренне обрабатывает асинхронность MinerU (отправка задачи, ожидание выполнения, получение результата), представляя это для агента как единую атомарную операцию parse_document.
3. Гибкая работа с файлами: Поддерживает загрузку документов как по публичным URL, так и через кодировку Base64, что критично для работы в изолированных или локальных сетях.

Архитектура и Компоненты

Проект построен по принципам микросервисной архитектуры и разделен на несколько ключевых модулей:

1. Точка входа и Транспорт (main.py)

• Реализует ASGI-приложение с использованием сервера Hypercorn.
• Поддерживает транспорт Streamable HTTP, являющийся современным стандартом для MCP.
• Включает middleware для проверки аутентификации (Bearer Token), если настроена переменная MCP_API_KEY.

2. Инструменты MCP (mcp_tools.py)

• Определяет доступные для LLM-агента функции.
• Основной инструмент: parse_document.
  • Принимает параметры: тип источника (url/base64), данные, имя файла и флаг возврата структурированных данных.
  • Обрабатывает безопасность транспорта (настройки DNS rebinding для Docker-окружений).

3. Клиент MinerU (mineru_client.py)

• Отвечает за коммуникацию с внешним сервисом MinerU.
• Реализует логику отправки файлов на парсинг.
• Выполняет поллинг (опрос) статуса задачи с настраиваемым интервалом, пока задача не завершится или не истечет таймаут.
• Парсирует ответы MinerU v3.x, корректно обрабатывая структуру словарей results.

4. Обработчик файлов (file_handler.py)

• Скачивает файлы по предоставленным URL.
• Декодирует строки Base64.
• Управляет созданием и удалением временных файлов, обеспечивая чистоту файловой системы сервера после завершения задачи.

5. Конфигурация (config.py)

• Централизованное управление переменными окружения.
• Настройка подключений (MINERU_URL), бэкендов парсинга (MINERU_BACKEND), списков языков (MINERU_LANG_LIST) и параметров производительности (таймауты, порты).

Связи и Интеграция

MinerU MCP Server выступает связующим звеном в следующей цепочке:

graph LR
    Agent[LLM Агент / Клиент] -->|MCP Protocol| LiteLLM[LiteLLM Gateway]
    LiteLLM -->|HTTP/SSE| Server[MinerU MCP Server]
    Server -->|REST API| MinerU[MinerU Service]

1. LLM Агент: Отправляет запрос на выполнение инструмента parse_document.
2. LiteLLM (Опционально): Часто используется как шлюз, управляющий сессиями MCP и маршрутизацией запросов к различным MCP-серверам.
3. MinerU MCP Server:
   • Принимает запрос.
   • Сохраняет файл во временное хранилище.
   • Отправляет задачу в MinerU.
   • Ожидает завершения обработки.
   • Возвращает итоговый Markdown или структурированные данные обратно агенту.
4. MinerU: Внешний сервис, выполняющий тяжелую работу по распознаванию текста (OCR), извлечению таблиц и структурированию документа.

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

• Атомарность: Агенту не нужно управлять циклами ожидания или проверять статус задачи вручную.
• Надежность: Встроенная обработка ошибок и повторных попыток при общении с MinerU.
• Безопасность: Запуск от непривилегированного пользователя (non-root) в Docker, возможность ограничения доступа через API-ключи.
• Гибкость: Легкая настройка под различные типы документов и языков через переменные окружения без изменения кода.