Устранение неполадок NextPDF Connect

Кратко

Большинство сбоев укладывается в один из пяти шаблонов: некорректное рукопожатие JSON-RPC, отсутствующий ключ API, инструмент, недоступный на данном уровне, оставшийся без ответа запрос на подтверждение или хранилище, не общее для воркеров. У каждого шаблона есть характерная сигнатура.

Установка

composer require nextpdf/server

Концептуальный обзор

Транспорт Model Context Protocol (MCP) возвращает объекты ошибок JSON-RPC 2.0 со стандартными кодами. Транспорт Representational State Transfer (REST) возвращает документы с подробностями об ошибках по Request for Comments (RFC) 7807. Каждый документ содержит URL type, идентифицирующий условие. При проблемах со средой начните с инструментов диагностики (diagnostic.doctor, diagnostic.capabilities). Эти инструменты всегда находятся в каталоге core.

Поверхность API

Коды ошибок JSON-RPC MCP

Код	Название	Причина
`-32700`	Ошибка разбора	Строка не является корректным JSON
`-32600`	Недопустимый запрос	Сообщение не соответствует JSON-RPC 2.0 (отсутствует `jsonrpc`/`method`)
`-32601`	Метод не найден	Метод не является одним из `initialize`, `tools/list`, `tools/call`
`-32602`	Недопустимые параметры	В `tools/call` отсутствует `params.name`
`-32603`	Внутренняя ошибка	Инструмент выбросил исключение при выполнении

Если инструмент штатно завершается ошибкой, он не использует эти коды. Вместо этого он возвращает успешный ответ JSON-RPC с isError: true в результате и текстовым пояснением: неизвестный инструмент, отключён политикой или недопустимые аргументы.

Типы подробностей об ошибках REST

HTTP	`type` слаг	Причина
`401`	`unauthorized`	Ключ API отсутствует, недопустим, отключён или просрочен
`403`	`capability-denied`	У уровня ключа нет права на эту операцию
`413`	`payload-too-large` / `tier-payload-exceeded`	Тело превышает глобальный предел или предел уровня
`422`	`validation-failed`	Тело запроса не прошло проверку схемы
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	Превышен лимит частоты запросов
`404`	`not-found`	Неизвестный маршрут или идентификатор job/session
`504`	(тайм-аут запроса)	Операция превысила тайм-аут для уровня

Пример кода — быстрый старт

Запустите проверку работоспособности среды. Для неё не нужны документ или подтверждение:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"diag","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"diagnostic.doctor","arguments":{}}}
EOF

Пример кода — производственный

Прежде чем отлаживать “отсутствующий инструмент”, проверьте, какие инструменты предоставляет это развёртывание:

./vendor/bin/generate-skills --dry-run --list-tools

или для запущенного сервера REST:

curl -sS http://localhost:8080/api/v1/capabilities \
  -H "Authorization: Bearer $NEXTPDF_KEY"

Граничные случаи и подводные камни

“Неизвестный инструмент” для инструмента Pro/Enterprise. Пакет инструмента не установлен. Реестр проверяет наличие классов-провайдеров и пропускает отсутствующие уровни без предупреждения. Это ожидаемое поведение, а не ошибка. Установите nextpdf/premium вместе с сервером или используйте инструмент core. Сообщение об ошибке содержит путь установки.
Инструмент, который я настроил в enabled_tools, не появляется. Список разрешённых инструментов пересекается с обнаруженными инструментами. Он не может добавить инструмент, который реестр не нашёл. Проверьте установку уровня и любые ограничения среды. Например, parse_pdf включается отдельно через NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED.
tools/call вернул текст с запросом токена. Это запрос на подтверждение, а не ошибка. Вызовите инструмент повторно в течение 300 секунд, указав в _confirmation_token выданный токен. См. /connect/hitl-risk-tiers/.
Строка уведомления не дала вывода. Это ожидаемо. Сообщение JSON-RPC без id является уведомлением, и обработчик ничего не возвращает. Отправляйте запросы с id, чтобы получать ответы.
Повторное использование идентификатора запроса вернуло устаревший ответ. Обработчик подавляет дубликаты по идентификатору запроса в буфере на 64 записи. Используйте новый id для каждого логического запроса.
Ограничения частоты странно работают между воркерами. Хранилище в памяти существует для каждого воркера отдельно. Чтобы счётчики были общими, задайте NEXTPDF_REDIS_HOST и установите ext-redis. См. /connect/deployment/.
Документы исчезают между запросами. Хранилище документов в памяти существует для каждого воркера отдельно и ограничено временем жизни (document_ttl, по умолчанию 1800 с). Чтобы документы сохранялись между воркерами, используйте хранилище на базе Redis, конечные точки сеансов или выполняйте весь набор операций в одной синхронной отрисовке.
Сервер переключился на хранилище в памяти, несмотря на конфигурацию Redis. Сервер REST переключается автоматически, если соединение с Redis не устанавливается при запуске. Проверьте доступность Redis и убедитесь, что ext-redis присутствует в запущенном образе. Не считайте, что Redis используется, пока не проверите.
Сервер отказывается запускаться с ошибкой конфигурации. В risk_level_overrides задано понижение уровня инструмента ApprovalRequired. Загрузчик намеренно отклоняет такую конфигурацию. Удалите понижение; переопределения могут только повышать уровень риска.

Производительность

Если отрисовка замедляется под нагрузкой, убедитесь, что пул воркеров не перегружен. Проверьте конечную точку метрик RoadRunner. Затем перенесите длительные отрисовки на путь асинхронных заданий, чтобы они не занимали воркеры. См. /connect/production-usage/.

Примечания по безопасности

Не обходите 401, открывая неаутентифицированный транспорт MCP в сеть; это полностью убирает аутентификацию. Вместо этого исправьте ключ API. Не повышайте детализацию журналов, чтобы проверить аргументы инструментов в общей среде; содержимое аргументов может быть конфиденциальным. См. /connect/security-and-operations/.

Соответствие

Эта страница содержит рекомендации по эксплуатации. Ссылки по протоколу и безопасности приведены на /transports/mcp/, /transports/rest/ и /connect/security-and-operations/.

См. также

/connect/tool-catalog/ — что входит в каталог core и почему количество меняется
/connect/hitl-risk-tiers/ — подробно о запросах на подтверждение
/connect/deployment/ — Redis, пулы воркеров и совместное использование хранилищ
/connect/security-and-operations/ — сбои аутентификации и состояние защиты