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 (Large Language Models) и парсером документов MinerU через стандартный протокол Model Context Protocol (MCP).

Сервер предназначен для того, чтобы дать LLM-агентам способность «читать» файлы. Он скрывает сложность асинхронного API MinerU, предоставляя агенту простой синхронный интерфейс: агент вызывает инструмент, а сервер самостоятельно управляет загрузкой файла, ожиданием выполнения задачи и возвратом результата.

Назначение

В современном стеке разработки LLM-агентов часто возникает необходимость обрабатывать документы (PDF, изображения, DOCX, PPTX, XLSX). MinerU — мощный инструмент для этой задачи, работающий в фоновом режиме. Однако прямая интеграция с ним требует от агента сложной логики управления состоянием (отправка задачи, опрос статуса, получение результата).

MinerU MCP Server решает следующие проблемы:

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

Ключевые возможности

• Стриминговый транспорт: Реализация на базе Streamable HTTP, позволяющая эффективно передавать данные и события между клиентом и сервером.
• Единая точка входа: Единственный инструмент parse_document инкапсулирует весь жизненный цикл обработки документа.
• Асинхронность под капотом: Сервер использует внутренний механизм поллинга (опроса) для отслеживания статуса задач MinerU, освобождая LLM от необходимости ждать или опрашивать статус вручную.
• Оптимизация контекста: По умолчанию сервер возвращает чистый Markdown, что идеально подходит для анализа LLM. Структурированные данные (JSON/списки) доступны опционально.
• Безопасность и надежность:
  • Поддержка Bearer-токенов для защиты эндпоинтов.
  • Автоматическая очистка временных файлов после обработки.
  • Запуск от непривилегированного пользователя (non-root) в Docker.

Основные компоненты

Проект имеет четкую модульную архитектуру, расположенную в директории src/mineru_mcp/:

1. src/mineru_mcp/mcp_tools.py Определяет инструменты, доступные LLM-агенту. Здесь зарегистрирована основная функция parse_document, которая является интерфейсом взаимодействия с внешним миром.

2. src/mineru_mcp/mineru_client.py Клиентская часть для общения с API MinerU. Отвечает за отправку файлов, циклический опрос статуса задачи (wait_for_task_completion) и парсинг ответа MinerU v3.x.

3. src/mineru_mcp/file_handler.py Утилиты для работы с данными: скачивание файлов по URL, декодирование Base64-строк и сохранение данных во временные файлы с уникальными именами.

4. src/mineru_mcp/config.py Централизованное управление конфигурацией. Чтение переменных окружения (MINERU_URL, TIMEOUTS, LANG_LIST и др.).

5. src/mineru_mcp/main.py Точка входа приложения. Инициализирует ASGI-приложение на базе Hypercorn и настраивает middleware для авторизации.

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

Сервер не работает изолированно. Его корректная настройка и использование зависят от следующих компонентов:

• MinerU Backend: Сервер требует наличия работающего экземпляра MinerU. Адрес задается переменной MINERU_URL (см. Конфигурация).
• LiteLLM: Часто используется как шлюз (Gateway) между LLM-приложением и MCP-сервером. Подробнее об этом см. в разделе Интеграция с LiteLLM.
• Docker Compose: Основной способ развертывания, описанный в Быстрый старт.

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

Ниже приведен пример того, как LLM-агент взаимодействует с сервером через протокол MCP.

Запрос от агента (вызов инструмента):

{
  "name": "parse_document",
  "arguments": {
    "source_type": "base64",
    "source": "JVBERi0xLjQKJeLjz9M...",
    "filename": "report.pdf",
    "include_structured_data": false
  }
}

Ответ сервера:

# Отчет о продажах

## Введение
В данном отчете представлены данные за Q1...

Для подробного описания параметров инструмента и структуры ответов обратитесь к Документации API.

Дальнейшие шаги

• Чтобы начать работу с проектом, следуйте инструкции в разделе Быстрый старт.
• Для изучения деталей взаимодействия компонентов см. Архитектура.
• Если вы планируете модифицировать код, ознакомьтесь с Руководством разработчика.