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.

Документация API

Обзор

API MinerU MCP Server предоставляет агентам LLM доступ к мощностям парсинга документов через стандартизированный протокол Model Context Protocol. Основной функционал инкапсулирован в единственном инструменте parse_document, который абстрагирует сложность асинхронного взаимодействия с MinerU.

Сервер использует транспорт Streamable HTTP, что позволяет эффективно работать как с короткими запросами, так и с длинными операциями парсинга без разрыва соединения.

Инструмент: parse_document

Этот инструмент извлекает текст, таблицы и структуру из различных форматов документов (PDF, изображения, DOCX, PPTX, XLSX). Он выполняет полный цикл обработки: от получения файла до возврата результата, скрывая от клиента детали внутренней асинхронной работы.

Реализация инструмента находится в файле mcp_tools.py.

Синтаксис вызова

{
  "method": "tools/call",
  "params": {
    "name": "parse_document",
    "arguments": {
      "source_type": "...",
      "source": "...",
      "filename": "...",
      "include_structured_data": ...
    }
  }
}

Параметры

Параметр	Тип	Обязательно	Описание
source_type	string	✅ Да	Метод предоставления файла. Допустимые значения: "url" или "base64".
source	string	✅ Да	Данные файла. URL-адрес (если source_type="url") или строка Base64 (если source_type="base64").
filename	string	✅ Да	Имя файла с расширением (например, report.pdf). Используется для сохранения временного файла и передачи в MinerU.
include_structured_data	boolean	❌ Нет	Определяет формат вывода. По умолчанию false (возвращает только Markdown). Если true, включает сырые структурированные данные (content_list).

Форматы ответов

Ответ возвращается в формате JSON-RPC. Содержимое результата зависит от параметра include_structured_data.

1. Только Markdown (по умолчанию)

Если include_structured_data равен false (или не передан), инструмент возвращает чистый Markdown-текст. Это оптимальный формат для большинства LLM-агентов, так как он занимает меньше места в контексте и легко читается.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Заголовок документа\n\nЗдесь содержится извлеченный текст..."
      }
    ],
    "isError": false
  }
}

2. Markdown + Структурированные данные

Если include_structured_data равен true, в поле text возвращается Markdown, а в поле structuredData (или аналогичном, в зависимости от реализации парсера MinerU) может присутствовать JSON-представление таблиц, заголовков и блоков.

Примечание: Точная структура структурированных данных зависит от версии MinerU и выбранного бэкенда. Сервер MCP обрабатывает ответ MinerU v3.x, где результаты представлены в виде словаря. См. подробности в разделе Архитектура.

Ошибки

В случае неудачи инструмент вернет ошибку с описанием проблемы.

Код ошибки	Описание	Возможная причина
NetworkError	Не удалось загрузить файл	URL недоступен, таймаут сети или неверный Base64.
MinerUError	Ошибка на стороне MinerU	MinerU недоступен, неверный MINERU_URL или проблема с файлом.
TimeoutError	Превышено время ожидания	Документ слишком большой, увеличьте MCP_TIMEOUT_SECONDS.

Пример ответа об ошибке:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Failed to download file from URL: Connection timeout"
  }
}

Поток выполнения

Процесс обработки запроса parse_document состоит из следующих этапов:

1. Прием запроса: MCP-сервер получает вызов инструмента через Streamable HTTP.
2. Подготовка файла:
   • Если source_type="url", файл загружается из интернета с помощью download_file_from_url().
   • Если source_type="base64", строка декодируется функцией decode_base64_string().
   • Содержимое сохраняется во временный файл через save_to_temp_file().
3. Отправка задачи: Файл отправляется на MinerU API через submit_parse_task(). Возвращается task_id.
4. Поллинг статуса: Сервер периодически опрашивает MinerU о статусе задачи, пока она не завершится. Интервал задается переменной MCP_POLL_INTERVAL_SECONDS (см. Конфигурация).
5. Получение результата: Готовый результат запрашивается через wait_for_task_completion().
6. Форматирование: Сырой ответ MinerU преобразуется в читаемый формат функцией format_result().
7. Очистка: Временный файл удаляется с диска.
8. Возврат: Результат отправляется клиенту.

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

Пример 1: Парсинг публичного PDF

Предположим, у вас есть публичный PDF-файл. Это самый простой способ, так как не требует кодирования файла клиентом.

{
  "source_type": "url",
  "source": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
  "filename": "dummy.pdf",
  "include_structured_data": false
}

Пример 2: Парсинг локального файла через Base64

Если файл находится на локальной машине агента или в закрытой сети, используйте Base64.

{
  "source_type": "base64",
  "source": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKPD4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovUmVzb3VyY2VzIDw8Ci9Gb250IDw8Ci9GMSA0IDAgUgo+Pgo+PgovTWVkaWFCb3ggWzAgMCA2MTIgNzkyXQovQ29udGVudHMgNSAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUxCi9CYXNlRm9udCAvSGVsdmV0aWNhCj4+CmVuZG9iago1IDAgb2JqCjw8Ci9MZW5ndGggNDQKPj4Kc3RyZWFtCkJUCi9GMSAxMiBUZgoxMDAgNzAwIFRkCihIZWxsbyBXb3JsZCkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iagp4cmVmCjAgNgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA1OCAwMDAwMCBuIAowMDAwMDAwMTE1IDAwMDAwIG4gCjAwMDAwMDAyNDUgMDAwMDAgbiAKMDAwMDAwMDMxNiAwMDAwMCBuIAp0cmFpbGVyCjw8Ci9TaXplIDYKL1Jvb3QgMSAwIFIKPj4Kc3RhcnR4cmVmCjQxNAolJUVPRgo=",
  "filename": "hello_world.pdf",
  "include_structured_data": false
}

Интеграция

Для подключения к этому API рекомендуется использовать LiteLLM в качестве шлюза. Пример настройки см. в разделе Интеграция с LiteLLM.

Если вы разрабатываете собственный клиент, убедитесь, что вы правильно управляете сессиями MCP. Подробнее об этом см. в разделе Устранение неполадок.

См. также

• Быстрый старт — Как запустить сервер.
• Конфигурация — Как настроить таймауты и бэкенды.
• Архитектура — Как данные проходят через систему.
• Тестирование — Как проверить работоспособность API вручную.