Интеграция NextPDF Connect

Кратко

Интегрируйте NextPDF Connect, запустив его как сервер. Библиотеку не нужно подключать к хост-приложению. Выберите транспорт, затем настройте аутентификацию для любого сетевого транспорта. Инструменты движка остаются за шлюзом подтверждения человеком.

Установка

composer require nextpdf/server

Composer ограничивает зависимости: nextpdf/core: ^3.0 при php: >=8.4 <9.0. О необязательной настройке ext-redis и nextpdf/premium см. /connect/install/.

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

Пакет работает как самостоятельный сервис. В хост-фреймворке не нужно регистрировать поставщика сервисов, бандл или модуль контейнера. Точка интеграции — запускаемый вами процесс. У каждого транспорта своя точка входа; каждый запускается независимо. См. /connect/boot-and-discovery/.

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

Точка входа	Транспорт	Профиль
bin/nextpdf-mcp	MCP через stdio	(нет — прямой подпроцесс)
bin/nextpdf-server	REST через RoadRunner HTTP	.rr.yaml
bin/nextpdf-grpc	gRPC через RoadRunner gRPC	.rr.grpc.yaml
оба сетевых транспорта	REST + gRPC	.rr.full.yaml

Запуск и автообнаружение

Реестр всегда обнаруживает core-уровень. Затем он добавляет поставщиков Pro и Enterprise, если их классы разрешаются, а после них — поставляемых в комплекте поставщиков абстрактного синтаксического дерева (AST) и мутаций, которыми управляют переменные окружения. Список разрешённых инструментов enabled_tools фильтрует их все, поэтому открытый каталог соответствует именно этому развёртыванию. См. /connect/tool-catalog/ и /connect/boot-and-discovery/.

Привязки контейнера

Нет. Каждая фабрика сервера явно строит собственный граф объектов. Внедряемые точки расширения предназначены для тестов, а не для связывания приложения.

Публикация конфигурации

Сервер MCP принимает необязательный YAML-файл (--config=PATH, секция nextpdf_mcp) и переопределения через переменные окружения NEXTPDF_MCP_*. Серверы REST и gRPC читают переменные окружения NEXTPDF_*. Подробнее см. /connect/configuration/.

Доступность транспортов (MCP / REST / gRPC)

Все три транспорта обслуживают один и тот же реестр:

• MCP — локальный подпроцесс, JSON-RPC 2.0 через stdio, без API-ключа, ревизия MCP 2025-06-18. См. /transports/mcp/.
• REST — пул HTTP-воркеров RoadRunner, контракт OpenAPI 3.1, bearer-ключ API, маршруты с разграничением по уровню. См. /transports/rest/.
• gRPC — пул gRPC-воркеров RoadRunner, Protobuf-сервис nextpdf.connect.v1, серверно-потоковые RPC, аутентификация bearer-токеном в метаданных, взаимный TLS в совмещённом профиле. См. /transports/grpc/.

Транспорт считается “доступным”, если запущена его точка входа или профиль RoadRunner. Транспорты не запускают друг друга автоматически.

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

Каждый инструмент объявляет один из четырёх уровней риска: safe, caution, review, approval_required. Инструменты уровня approval_required не выполняются при первом вызове. Шлюз подтверждения выдаёт одноразовый токен подтверждения, который должен авторизовать человек. Переопределение в конфигурации может только повысить риск инструмента, но никогда не снижает риск инструмента уровня approval_required. Эта модель одинаково применяется для каждого транспорта, управляющего инструментами. См. /connect/hitl-risk-tiers/.

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

Проверка шлюза возвращает одну из двух JSON-структур. Разрешённый вызов:

{ "allowed": true }

Запрос подтверждения:

{
  "allowed": false,
  "challenge": "<human-readable text naming the operation, its description, an overwrite warning when applicable, and the re-invocation instruction>",
  "token": "confirm_<nonce>"
}

Токен связан с именем инструмента, случайным nonce и 300-секундным TTL, но не с аргументами. Чтобы продолжить, вызывающая сторона повторно вызывает тот же инструмент и передаёт выданный токен в аргументе _confirmation_token. Запрос подтверждения — это обычный пояснительный текст и токен; обёртка не подписана криптографически. См. /connect/hitl-risk-tiers/.

Дымовая проверка сервиса

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

Эта команда инициализирует реестр и определение уровня, затем выводит открытые инструменты без обслуживания трафика. Используйте её, чтобы убедиться, что интеграция подключена, и проверить, какой каталог формирует эта установка.

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

• Нет хуков фреймворка. Не ищите поставщика сервисов или бандл. Работающий процесс и есть интеграция.
• Отсутствие уровня не является ошибкой. Установка только с core-уровнем запускается и обслуживает свой core-каталог.
• Сетевым транспортам нужен ключ. Без аутентификации доступны только /healthz и /readyz (REST) и health-RPC (gRPC).

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

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

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

Сетевые транспорты аутентифицируются bearer-ключом npk_live_, проверяемым за постоянное время; шлюз требует подтверждения человеком для разрушающих операций независимо от транспорта. Завершайте TLS перед REST и используйте взаимный TLS для gRPC в недоверенных сетях. См. /connect/security-and-operations/.

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

Ссылки на протоколы и безопасность приведены на /transports/mcp/, /transports/rest/, /transports/grpc/ и /connect/security-and-operations/.

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

Установите nextpdf/premium в ту же установку сервера, чтобы зарегистрировать дополнительные инструменты Pro и Enterprise в том же работающем сервере. Отдельный процесс для этого не нужен.

См. также

• /connect/overview/ — архитектура
• /connect/quickstart/ — первый рабочий обмен
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — справочник по каждому транспорту
• /connect/hitl-risk-tiers/ — шлюз подтверждения в деталях
• /connect/tool-catalog/ — каталог, зависящий от среды выполнения
• /connect/security-and-operations/ — аутентификация и модель угроз