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.

Локальный запуск

Для разработки и отладки без использования Docker выполните следующие шаги. Это позволяет быстро перекомпилировать код и видеть логи в реальном времени.

1. Подготовка окружения

Убедитесь, что у вас установлен Python версии 3.11 или выше.

Создайте виртуальное окружение и активируйте его:

python3 -m venv .venv
source .venv/bin/activate  # Для Linux/macOS
# .venv\Scripts\activate   # Для Windows

2. Установка зависимостей

Установите необходимые библиотеки из файла requirements.txt:

pip install -r requirements.txt

3. Настройка переменных окружения

Сервер требует наличия запущенного экземпляра MinerU. Настройте переменные окружения перед запуском:

export MINERU_URL=http://localhost:8000
export MINERU_BACKEND=hybrid-engine
export MCP_PORT=8001
export LOG_LEVEL=DEBUG  # Рекомендуется для разработки

Важно: Если MinerU запущен в Docker, а вы запускаете MCP локально, убедитесь, что порт 8000 проброшен на хост (-p 8000:8000), иначе локальный Python не сможет достучаться до контейнера.

4. Запуск сервера

Запустите приложение, указав путь к исходникам в PYTHONPATH:

PYTHONPATH=src python -m mineru_mcp.main

Сервер начнет слушать порт 8001 (или значение переменной MCP_PORT).

---

Структура проекта (Src Layout)

Проект использует профессиональную структуру src layout, которая разделяет исходный код и корневой каталог. Это предотвращает конфликты имен пакетов при тестировании и упрощает установку пакета в режиме разработки.

Основные компоненты расположены в директории src/mineru_mcp/:

• config.py Модуль конфигурации. Здесь определяется класс Settings, который считывает переменные окружения (MINERU_URL, MCP_TIMEOUT_SECONDS и др.). Изменяемые настройки централизуются здесь.

• file_handler.py Утилиты для работы с файлами. Содержит функции:

  • download_file_from_url(): Асинхронная загрузка файлов из интернета.
  • decode_base64_string(): Декодирование base64-строк в байты.
  • save_to_temp_file(): Сохранение контента во временный файл с уникальным именем (UUID) для передачи в MinerU.

• mineru_client.py Клиент для взаимодействия с API MinerU. Ключевые функции:

  • submit_parse_task(): Отправка файла на обработку.
  • wait_for_task_completion(): Реализует внутренний цикл поллинга (опроса статуса задачи), скрывая асинхронность MinerU от MCP-инструмента.
  • format_result(): Парсинг ответа MinerU v3.x (структура results как словарь).

• mcp_tools.py Точка интеграции с протоколом MCP. Здесь регистрируется основной инструмент parse_document с помощью декоратора @mcp.tool(). Именно здесь происходит связывание входящих параметров с логикой клиента и обработчика файлов.

• main.py Точка входа. Инициализирует ASGI-приложение, настраивает логирование и запускает сервер через Hypercorn. Также содержит middleware для проверки Bearer-токена (если включена защита через MCP_API_KEY).

---

Руководство по добавлению новых инструментов

Чтобы добавить новый функционал (например, распознавание текста только со страницы или конвертацию в другой формат), следуйте этому алгоритму.

Шаг 1: Реализация бизнес-логики

Добавьте необходимую функцию в соответствующий модуль.

• Если требуется новая логика запросов к MinerU, добавьте метод в mineru_client.py.
• Если требуется новая обработка файлов, добавьте метод в file_handler.py.

Шаг 2: Регистрация MCP инструмента

Откройте файл src/mineru_mcp/mcp_tools.py и добавьте новую функцию.

Пример шаблона нового инструмента:

@mcp.tool()
async def extract_tables_only(
    source_type: str,
    source: str,
    filename: str
) -> str:
    """
    Извлекает только таблицы из документа, игнорируя текст.
    
    Args:
        source_type: Тип источника ('url' или 'base64')
        source: Данные файла
        filename: Имя файла
    """
    # 1. Получить временный файл
    if source_type == 'url':
        content = await file_handler.download_file_from_url(source)
    else:
        content = file_handler.decode_base64_string(source)
    
    temp_path = file_handler.save_to_temp_file(content, filename)
    
    try:
        # 2. Вызвать клиент MinerU (предположим, мы добавили флаг в существующий метод)
        task_id = await mineru_client.submit_parse_task(temp_path, tables_only=True)
        result = await mineru_client.wait_for_task_completion(task_id)
        
        # 3. Вернуть результат в формате, понятном LLM
        return mineru_client.format_result(result, include_structured_data=True)
    finally:
        # 4. Очистка
        if os.path.exists(temp_path):
            os.remove(temp_path)

Шаг 3: Написание тестов

Добавьте тесты в директорию tests/. Используйте библиотеку respx для мокирования HTTP-запросов, чтобы тесты не зависели от реального сервера MinerU.

Пример создания теста:

1. Создайте файл tests/test_new_tool.py.
2. Используйте фикстуры из conftest.py.
3. Проверьте, что ваш инструмент корректно вызывает методы клиента и обрабатывает ответы.

Запуск тестов:

PYTHONPATH=src pytest tests/ -v

Шаг 4: Проверка работы

Запустите сервер локально и проверьте доступность нового инструмента через инициализацию сессии MCP (см. раздел Тестирование или используйте Интеграцию с LiteLLM).

---

Полезные советы для разработчиков

1. Логирование: Используйте встроенный модуль logging. В режиме разработки установите LOG_LEVEL=DEBUG, чтобы видеть детали поллинга и сырые ответы от MinerU.
2. Async/Await: Весь код в проекте асинхронный. Не используйте блокирующие операции (например, синхронные requests или time.sleep) внутри функций инструментов.
3. Обработка ошибок: MCP-инструменты должны возвращать текстовое описание ошибки, а не падать с исключением. Используйте try-except блоки для перехвата сетевых ошибок и возврата понятного сообщения агенту.
4. Структура MinerU: Помните, что MinerU v3.x возвращает результаты в виде словаря {filename: result_data}. Всегда проверяйте наличие ключа перед обращением к данным (см. format_result).