Быстрый старт NextPDF Connect

Кратко

На этой странице показан минимальный полезный обмен для обоих транспортов: Model Context Protocol (MCP) и Representational State Transfer (REST). Каждый запрос использует ровно тот сетевой формат, который реализует сервер. Комплект средств разработки (SDK) не нужен.

Установка

composer require nextpdf/server

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

Транспорт MCP использует JSON-RPC 2.0 поверх стандартного ввода и вывода. Сообщения в этой последовательности отправляйте по порядку. Сначала отправьте initialize, затем подтверждение notifications/initialized, после этого — tools/list и tools/call. Сервер читает по одному JSON-сообщению на строку. Каждая строка должна заканчиваться символом новой строки. Сервер записывает по одному ответу на строку.

Транспорт REST предоставляет те же возможности движка как операции Hypertext Transfer Protocol (HTTP). Одна отрисовка без сохранения состояния — это один запрос POST /api/v1/render с упорядоченным массивом операций. Тело ответа — файл Portable Document Format (PDF).

Пример кода — быстрый старт (MCP через stdio)

Запустите сервер и передайте ему рукопожатие через конвейер. В этих трёх запросах указаны проверенные имена методов, которые маршрутизирует обработчик протокола:

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

Ответ initialize сообщает версию протокола 2025-06-18, имя сервера NextPDF Connect и блок capabilities.nextpdf. В этом блоке есть текущие счётчики уровней, runtime-значение tool_count, версия модели рисков и hitl_enabled: true. Ответ tools/list перечисляет точный набор инструментов, зарегистрированных для этой установки. На строку уведомления ответ намеренно не возвращается.

Теперь вызовите безопасный инструмент. diagnostic.doctor выполняет проверку окружения только для чтения. Для него не нужны ни документ, ни подтверждение:

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

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

Запустите сервер REST, затем отрисуйте PDF с одной строкой. Сервер требует ключ API для каждой конечной точки, кроме проверок работоспособности, поэтому сначала задайте его:

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

Во втором окне оболочки отправьте запрос на отрисовку. Тело запроса — это RenderRequest. Запрос содержит упорядоченный массив operations с типизированными операциями.

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

Ответ с кодом 200 содержит PDF (Content-Type: application/pdf), который записывается в hello.pdf. Для проверок работоспособности ключ не нужен:

curl -sS http://localhost:8080/healthz

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

Порядок рукопожатия имеет значение. Обработчик протокола трактует сообщение без id как уведомление и ничего не возвращает. Отправьте initialize с id, затем уведомление initialized, а затем запросы, содержащие id.
Повторяющийся id запроса дедуплицируется. Обработчик кэширует недавние ответы в кольцевом буфере на 64 записи. Для дублирующегося id он возвращает кэшированный ответ и не запускает инструмент повторно. Используйте новые идентификаторы.
Инструмент высокого риска отвечает запросом на подтверждение, а не результатом. При вызове output_pdf с file_path сервер возвращает запрос на подтверждение, а не выполняет инструмент сразу. Вызовите инструмент повторно с выданным _confirmation_token. Режим вывода base64 без file_path не требует подтверждения. См. /connect/hitl-risk-tiers/.
Неавторизованный REST-запрос получает 401. Если заголовок Authorization: Bearer отсутствует или некорректен, сервер возвращает тело problem-details с заголовком WWW-Authenticate: Bearer. Проверки /healthz и /readyz — единственные анонимные конечные точки.

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

Оба пути быстрого старта используют один запрос. В сценарии REST также есть затраты на холодный старт пула воркеров RoadRunner при первом запросе после rr serve. Последующие запросы повторно используют прогретые воркеры.

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

Ключ npk_live_ выше — это одноразовое демонстрационное значение. Генерируйте реальные ключи с достаточной энтропией, храните их вне системы контроля версий, а для ротации предпочитайте файловое хранилище ключей. Транспорт MCP через stdio не использует ключ API, поскольку это локальный подпроцесс, которому доверяет запускающий его клиент в рамках транспортной модели MCP. См. /connect/security-and-operations/.

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

Показанные сетевые форматы соответствуют реализованной редакции MCP 2025-06-18 и REST-контракту OpenAPI 3.1. Нормативные ссылки на протокол и аутентификацию приведены на /transports/mcp/, /transports/rest/ и /connect/security-and-operations/.

См. также

/transports/mcp/ — полный справочник по транспорту MCP
/transports/rest/ — полный справочник по транспорту REST и отрисовке OpenAPI
/connect/tool-catalog/ — какие инструменты возвращает tools/list и почему
/connect/hitl-risk-tiers/ — как выглядит запрос на подтверждение
/connect/configuration/ — как ограничить каталог и настроить сервер