Создание первого PDF с помощью NextPDF Connect

Кратко

Этот рецепт показывает кратчайший путь от пустой сессии до готового PDF с помощью NextPDF Connect. Вы создаёте одностраничный документ A4, добавляете заголовок и подзаголовок, а затем получаете файл в формате base64. Работу выполняют три инструмента Core: create_pdf, add_text и output_pdf. Шрифты, изображения и лицензионный уровень не требуются.

Транспорт Connect отправляет каждый вызов инструмента как запрос и возвращает результат инструмента как ответ. Транспортный уровень не меняется в зависимости от результата, который сообщает инструмент (PSR-18 §p2).

Установка

Установите NextPDF Server и настройте транспорт:

composer require nextpdf/server

Запустите сервер с тем транспортом, который ожидает ваш хост: Model Context Protocol через stdio, REST или gRPC. См. раздел Доступность транспортов ниже. Инструменты из этого рецепта относятся к Core. Они входят в состав сервера, поэтому пакет Pro или Enterprise не нужен.

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

Сессия Connect — это серверное хранилище документов, где ключом служит document_id. create_pdf открывает сессию и возвращает этот идентификатор. Каждый последующий вызов инструмента использует этот идентификатор. Документ начинается с одной пустой страницы. Дерево страниц — это структура, по которой средство чтения получает доступ к каждой странице (ISO 32000-2 §7.7.3). output_pdf отрисовывает сессию в PDF. По умолчанию после этого он уничтожает сессию, чтобы освободить память.

Когда вы вызываете add_text без явного x или y, текст размещается автоматически. Размещение начинается от текущего курсора, и после каждого вызова курсор смещается дальше.

Интерфейс API

Реестр инструментов делает эти инструменты доступными при запуске сервера. Показанные здесь имена — это протокольные имена из реестра. Эталонный источник — объединённый каталог инструментов. Доступные инструменты зависят от установленного уровня, но эти три всегда присутствуют в Core.

Инструмент	Роль	Уровень риска
create_pdf	Открывает сессию документа	Безопасно
add_text	Записывает текст в документ	Внимание
output_pdf	Отрисовывает и возвращает PDF	Approval Required (режим файла) / Review (base64)

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

Хост выполняет три вызова инструментов. По порядку:

1. Вызовите create_pdf с параметрами page_size: "A4", orientation: "portrait", а также укажите заголовок и автора документа. Сервер возвращает document_id.
2. Вызовите add_text с этим document_id, текстом заголовка, крупным font_size, width: 0 (полная ширина содержимого) и alignment: "center".
3. Вызовите output_pdf с document_id. Без file_path сервер возвращает PDF в формате base64 и уничтожает сессию.

Минимальный объект аргументов create_pdf:

{
  "page_size": "A4",
  "orientation": "portrait",
  "title": "Hello World",
  "author": "NextPDF Cookbook"
}

Ответ содержит document_id, количество страниц и геометрию страницы. Считайте идентификатор непрозрачным значением и не выводите из него никакого смысла.

Пример кода — продакшен

Код в продакшене проверяет каждый ответ, прежде чем выполнить следующий вызов. Он никогда не использует повторно document_id после того, как output_pdf уничтожил сессию.

1. create_pdf — убедитесь, что ответ содержит document_id. Если сервер возвращает ошибку из-за лимита сессий, освободите неиспользуемые сессии и повторите попытку.
2. add_text (заголовок) — убедитесь, что ответ содержит position.
3. add_text (подзаголовок) — используйте меньший font_size; курсор смещается ниже заголовка.
4. output_pdf — прочитайте поле base64 и декодируйте его в байты. Флаг destroyed подтверждает, что сессия удалена.

Файл возвращается прямо в ответе (режим base64), поэтому не возникает ни побочного эффекта для файловой системы, ни шлюза подтверждения человеком. См. Уровень риска HITL.

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

• Уничтоженная сессия. После того как output_pdf выполнится со значением по умолчанию destroy: true, document_id больше недействителен. Любой последующий вызов с этим идентификатором возвращает ошибку неизвестного документа. Вместо этого создайте новую сессию.
• Неизвестный размер страницы. Сервер отклоняет page_size, который не распознаёт, и возвращает понятную ошибку. Используйте документированный размер (A3, A4, A5, A6, Letter, Legal, Tabloid).
• Пустой текст. Пустой text создаёт текстовую запись нулевой ширины, а не ошибку. Проверяйте входные данные перед вызовом.
• Лимит сессий. Хранилище в памяти ограничивает количество одновременно активных сессий. Своевременно освобождайте сессии с помощью output_pdf.

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

Одна страница только с текстом с большим запасом укладывается в бюджет страницы, а размер вывода обычно составляет 1–3 КБ. В этом рецепте используется профиль воспроизводимости structural с двойной отрисовкой. PDF содержит трейлерный /ID и метки времени, которые меняются между запусками, поэтому точным считается структурное (нормализованное) сравнение.

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

Вывод через base64 не имеет побочного эффекта для файловой системы. Вывод в файл имеет такой эффект и защищён шлюзом. См. раздел HITL. Считайте возвращаемый base64 содержимым документа, а не доверенным каналом. Это ровно те байты, которые произвели инструменты.

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

Утверждение	Спецификация	Пункт	reference_id (идентификатор ссылки)
Транспорт отправляет запрос и получает ответ независимо от результата.	PSR-18	§p2
Доступ к страницам осуществляется через дерево страниц документа.	ISO 32000-2	§7.7.3

Этот рецепт описывает, как сервер формирует вывод. Он не заявляет соответствие профилю.

Коммерческий контекст

Не применимо — все три инструмента относятся к Core.

Доступность транспортов

Транспорт	Доступен	Примечания
MCP через stdio	Да	Вызовы инструментов сопоставляются с MCP tools/call.
REST	Да	Каждый инструмент — это операция REST; результат становится телом ответа.
gRPC	Да	Каждый инструмент — это унарный вызов.

Результат инструмента одинаков для всех транспортов; отличается только обёртка. Неуспешный результат — это по-прежнему обычный ответ, а не сбой транспорта (PSR-18 §p2).

Уровень риска HITL

Сервер помещает каждый вызов инструмента на шкалу риска “человек в контуре” (HITL): Safe (0) → Caution (1) → Review (2) → Approval Required (3). create_pdf относится к Safe, а add_text — к Caution. output_pdf относится к Approval Required, но в режиме base64 (без file_path) понижается до Review и выполняется без подтверждения человеком. Запись в файл оставляет его на уровне Approval Required. См. output-approval и справочник по уровням риска HITL.

JSON-конверт шлюза подтверждения

Этот рецепт остаётся в режиме base64, поэтому шлюз подтверждения возвращает конверт разрешения:

{ "allowed": true }

Конверт запроса (allowed: false, со строкой challenge и одноразовым token) описан в output-approval.

См. также

• Многостраничный документ
• Встраивание изображений
• Каталог инструментов
• Уровни риска HITL