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. Если вы столкнулись с ошибкой, сначала проверьте соответствующий раздел ниже.

Ошибки импорта и установки

ImportError: cannot import name 'StreamableHTTPServer'

Если при запуске вы видите ошибку импорта компонентов MCP, убедитесь, что вы используете корректную версию MCP SDK.

Причина: Несоответствие версии библиотеки mcp требованиям проекта.

Решение:

1. Проверьте установленную версию:

   pip show mcp
   

2. Убедитесь, что версия находится в диапазоне >=1.0.0,<2.0.0, как указано в requirements.txt.
3. Если версия другая, переустановите зависимости:

   pip install -r requirements.txt
   

TypeError: FastMCP.run() got an unexpected keyword argument 'host'

Причина: Попытка использовать метод .run() из старых версий MCP SDK или неверный способ запуска сервера. В текущей архитектуре мы используем ASGI-приложение с Hypercorn.

Решение: Не вызывайте FastMCP.run() напрямую с аргументами хоста. Вместо этого используйте точку входа, определенную в src/mineru_mcp/main.py, которая настраивает Hypercorn для обслуживания ASGI-приложения.

При локальном запуске используйте команду:

python -m mineru_mcp.main

Управление сессиями и протокол MCP

Bad Request: Missing session ID

Причина: Протокол MCP Streamable HTTP требует инициализации сессии перед вызовом инструментов. Сервер ожидает заголовок Mcp-Session-Id.

Решение:

1. Сначала выполните вызов метода initialize.
2. Скопируйте значение Mcp-Session-Id из заголовков ответа.
3. Передавайте этот ID в заголовке Mcp-Session-Id для всех последующих запросов (например, tools/call).

Пример инициализации:

curl -X POST http://localhost:8001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "test", "version": "1.0"}
    }
  }'

Примечание: Если вы используете Интеграцию с LiteLLM, LiteLLM автоматически управляет сессиями, и вам не нужно делать этого вручную.

Not Acceptable: Client must accept both application/json and text/event-stream

Причина: Клиент отправил запрос с заголовком Accept, который не включает оба требуемых формата.

Решение: Убедитесь, что в заголовке Accept указаны оба типа MIME:

Accept: application/json, text/event-stream

Это требование протокола MCP Streamable HTTP, так как сервер может возвращать либо мгновенный JSON-ответ, либо поток событий (SSE).

Таймауты и производительность

TimeoutError при парсинге больших документов

Причина: Процесс парсинга занял больше времени, чем разрешено переменной окружения MCP_TIMEOUT_SECONDS. По умолчанию это 600 секунд (10 минут).

Решение: Увеличьте таймаут в конфигурации.

1. Откройте docker-compose.yml.
2. Найдите переменную MCP_TIMEOUT_SECONDS в секции environment сервиса mineru-mcp.
3. Увеличьте значение (например, до 1200 для 20 минут):

   environment:
     - MCP_TIMEOUT_SECONDS=1200
   

4. Перезапустите контейнер:

   docker-compose up -d --force-recreate mineru-mcp
   

Подробнее о настройке таймаутов см. в разделе Конфигурация.

Высокое потребление памяти или зависание

Причина: Накопление временных файлов или утечка ресурсов в сессиях.

Решение:

1. Проверьте логи сервера на наличие ошибок очистки:

   docker-compose logs -f mineru-mcp
   

2. Убедитесь, что функция очистки в src/mineru_mcp/mcp_tools.py выполняется корректно (временные файлы должны удаляться в блоке finally).
3. Если проблема сохраняется, попробуйте перезапустить контейнер, чтобы очистить /tmp.

Ошибки доступа к URL и файлам

404 Not Found / Connection Error при source_type='url'

Причина:

1. URL не является публичным и недоступен из сети, где запущен Docker-контейнер MCP-сервера.
2. Файл был удален или перемещен.
3. Проблемы с сетью между контейнером MCP и внешним интернетом.

Решение:

1. Проверьте доступность URL: Убедитесь, что URL открывается в браузере.
2. Используйте Base64: Если файл находится на вашем локальном компьютере или во внутренней сети, не используйте source_type='url'. Вместо этого закодируйте файл в Base64 и используйте source_type='base64'.

   {
     "source_type": "base64",
     "source": "JVBERi0xLjQKJeLjz9M...",
     "filename": "document.pdf"
   }
   

3. Локальная разработка: Если вы запускаете MCP локально (не в Docker) и пытаетесь скачать файл с localhost, убедитесь, что порт открыт. В Docker-среде localhost внутри контейнера относится к самому контейнеру, а не к хост-машине. Используйте host.docker.internal или публичный URL.

Ошибка декодирования Base64

Причина: Неверный формат строки Base64 (например, присутствуют переносы строк, пробелы или символы, не входящие в алфавит Base64).

Решение:

1. Убедитесь, что строка Base64 чистая (без префиксов типа data:application/pdf;base64,).
2. Проверьте целостность данных.
3. Посмотрите логи функции decode_base64_string в src/mineru_mcp/file_handler.py.

Ошибки авторизации

401 Unauthorized

Причина: Неверный или отсутствующий API-ключ, если включена защита MCP_API_KEY.

Решение:

1. Убедитесь, что переменная MCP_API_KEY задана в docker-compose.yml.
2. При запросе передавайте правильный токен в заголовке Authorization: Bearer YOUR_KEY.
3. Если вы не планируете использовать авторизацию, убедитесь, что MCP_API_KEY не задана (оставлена пустой или закомментирована), чтобы отключить проверку.

См. реализацию middleware в src/mineru_mcp/main.py.

Ошибки взаимодействия с MinerU

MinerU недоступен (Connection Refused)

Причина: Сервер MinerU не запущен или адрес MINERU_URL указан неверно.

Решение:

1. Проверьте статус контейнера MinerU:

   docker ps
   

2. Убедитесь, что переменная MINERU_URL в docker-compose.yml указывает на правильный адрес. Если MinerU и MCP находятся в одной сети Docker, используйте имя сервиса (например, http://mineru:8000).
3. Проверьте логи MinerU на наличие ошибок запуска.

Ошибка формата результата MinerU

Причина: MinerU вернул ответ в неожиданном формате, который не удалось распарсить.

Решение:

1. Проверьте логи MCP-сервера на наличие сообщений об ошибке парсинга JSON.
2. Убедитесь, что вы используете совместимую версию MinerU (проект ориентирован на MinerU v3.x).
3. Функция форматирования результатов находится в src/mineru_mcp/mineru_client.py. Если структура ответа MinerU изменилась, возможно, потребуется обновление кода.

Дополнительные ресурсы

• Быстрый старт — Проверка базовой настройки.
• Тестирование — Запуск тестов для диагностики проблем.
• Архитектура — Понимание потока данных для поиска узких мест.
• Конфигурация — Полный список переменных окружения.