Перейти к содержимому
NextPDF

Обзор сервера NextPDF Connect

Кратко

Заголовок раздела «Кратко»

NextPDF Connect — это пакет nextpdf/server, долго работающий сервис, который открывает ИИ-агентам и HTTP-клиентам доступ к движку NextPDF PDF 2.0. Он использует три транспорта: Model Context Protocol (MCP) поверх stdio, REST API и gRPC. Все три транспорта используют общий реестр инструментов и общий шлюз подтверждения с участием человека (HITL).

Установка

Заголовок раздела «Установка»
Окно терминала
composer require nextpdf/server

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

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

Заголовок раздела «Концептуальный обзор»

nextpdf/server превращает независимое от фреймворка ядро NextPDF в сервисный интерфейс. Он не реализует генерацию PDF заново. Вместо этого он оборачивает каждую возможность движка в именованный инструмент с собственной схемой, а затем публикует этот каталог через несколько сетевых протоколов.

Архитектура опирается на три концепции:

  • Реестр инструментов. NextPDF\Server\ToolRegistry находит и регистрирует инструменты при загрузке. Базовый набор поставляется с пакетом и доступен всегда. Провайдеры Pro и Enterprise регистрируют дополнительные инструменты, но только когда установлены соответствующие пакеты. Количество доступных инструментов — это свойство развёртывания во время выполнения, а не фиксированная константа. См. /connect/tool-catalog/.

  • Транспорты. Один и тот же реестр публикуется тремя способами. MCP работает поверх stdio для локальных ИИ-клиентов. REST работает через конвейер промежуточного ПО PSR-15 на пуле воркеров RoadRunner для сетевых клиентов. gRPC работает на воркере Spiral RoadRunner gRPC для типизированных или потоковых клиентов. Каждый транспорт — это отдельный процесс с собственной точкой входа. См. /transports/mcp/, /transports/rest/ и /transports/grpc/.

  • Шлюз подтверждения. Каждый инструмент объявляет уровень риска. Инструмент с максимальным уровнем риска требует явного подтверждения человеком перед запуском. Шлюз выдаёт одноразовый токен вызова. Агент должен передать этот токен человеку, а затем повторно вызвать инструмент с этим токеном. См. /connect/hitl-risk-tiers/.

Приведённая ниже диаграмма показывает, как один реестр обслуживает три транспорта. Она также показывает, где на пути запроса находится шлюз подтверждения.

NextPDF Connect component architectureOne tool registry is served over three transports, and high-risk tool calls pass through a single human-in-the-loop confirmation gate before reaching the engine.

stdio

HTTP

gRPC

No

Yes

class_exists probe

Local AI client

MCP server

Networked client

REST server

Typed or streaming client

gRPC server

Tool registry

High risk?

NextPDF PDF 2.0 engine

Human confirmation token

Pro and Enterprise providers

NextPDF Connect component architecture

Пакет лицензирован под Apache-2.0, что соответствует nextpdf/core. Реализованная версия протокола MCP соответствует ревизии, датированной 2025-06-18. Документ OpenAPI 3.1 описывает REST-интерфейс. Пакет Protocol Buffers nextpdf.connect.v1 описывает gRPC-интерфейс.

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

Заголовок раздела «Поверхность API»

Публичные точки входа представлены тремя серверными классами. У каждого есть обёртка интерфейса командной строки (CLI):

Точка входаКлассТранспорт
bin/nextpdf-mcpNextPDF\Server\Mcp\McpServerMCP поверх stdio
bin/nextpdf-serverNextPDF\Server\Http\HttpServerREST поверх RoadRunner HTTP
bin/nextpdf-grpcNextPDF\Server\Grpc\GrpcServergRPC поверх RoadRunner gRPC
bin/generate-skillsNextPDF\Server\Skills\SkillsDumperЭкспорт каталога инструментов

McpServer::create(), HttpServer::create() и GrpcServer::create() — каждый метод собирает полностью настроенный сервер из переменных окружения и входной конфигурации. Реестр, хранилище документов, политика безопасности и шлюз подтверждения общие для всех трёх серверов.

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

Заголовок раздела «Пример кода — быстрый старт»

Для минимального сервера MCP достаточно одной команды. Связующий код на PHP писать не нужно:

Окно терминала
./vendor/bin/nextpdf-mcp

Сервер читает запросы JSON-RPC со стандартного ввода и пишет ответы в стандартный вывод. Пример обмена с initialize и tools/list, а также соответствующий REST-запрос см. в /connect/quickstart/.

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

Заголовок раздела «Граничные случаи и подводные камни»

  • Число инструментов не равно 33 или любому другому фиксированному числу. Сервер подсчитывает инструменты во время выполнения как count(ToolRegistry::all()), после фильтрации по политике и назначения уровня. Документация, в которой указан фиксированный итог, устарела. Чтобы получить достоверное число, обратитесь к работающему серверу. Используйте ответ MCP initialize или конечную точку REST /api/v1/capabilities.

  • Отсутствие пакета Pro или Enterprise не является ошибкой. Реестр проверяет наличие классов провайдеров через class_exists(), а затем без ошибки пропускает отсутствующий уровень. Развёртывание только с открытым исходным кодом загружается и обслуживает свой базовый каталог в обычном режиме.

  • Три транспорта не разделяют один процесс. Запуск сервера MCP не запускает сервер REST или сервер gRPC. И наоборот. Совмещённое развёртывание запускает супервизор RoadRunner с конфигурацией, которая запускает оба пула воркеров — пул HTTP и пул gRPC. См. /connect/deployment/.

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

Заголовок раздела «Производительность»

Каждый транспорт работает на воркерах. Воркер обрабатывает один запрос за раз. Серверы REST и gRPC работают на пулах воркеров RoadRunner, а конфигурация задаёт размер пула. По умолчанию используется четыре воркера HTTP. Супервизор RoadRunner ограничивает объём памяти каждого воркера. Поле фронтматтера performance_budget на этой странице описывает пределы холодной загрузки и обнаружения. Это не целевой показатель для отдельного запроса. Большую часть затрат на запрос определяет нижележащая операция движка.

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

Заголовок раздела «Замечания по безопасности»

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

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

Заголовок раздела «Соответствие»

Эта страница содержит только архитектурные утверждения. Нормативные ссылки на протоколы и безопасность зафиксированы на страницах, где задаётся это поведение: /connect/security-and-operations/, /transports/mcp/, /transports/rest/ и /transports/grpc/. Эталоном жизненного цикла MCP является официальная спецификация на modelcontextprotocol.io (ревизия 2025-06-18). Страницы транспортов фиксируют эту ссылку вместе с её URL, поскольку спецификация MCP не входит в закрытый корпус стандартов.

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

Заголовок раздела «Коммерческий контекст»

Базовый каталог полностью покрывает создание, проверку и диагностику документов. Инструменты для подписания, редактирования с удалением данных, сертификации соответствия и криминалистического анализа появляются только если nextpdf/premium установлен вместе с сервером. Это граница упаковки, а не требование повысить тариф во время выполнения. Сервер никогда не показывает маркетинговый контент.

См. также

Заголовок раздела «См. также»
  • /connect/install/ — установка и необязательные пакеты
  • /connect/quickstart/ — первый готовый к запуску обмен MCP и REST
  • /connect/tool-catalog/ — проверенный базовый набор инструментов и почему число зависит от среды выполнения
  • /connect/hitl-risk-tiers/ — шлюз подтверждения и модель рисков
  • /transports/mcp/, /transports/rest/, /transports/grpc/ — настройка для каждого транспорта
  • /connect/security-and-operations/ — аутентификация, безопасность транспорта, модель угроз
  • /connect/deployment/ — RoadRunner, Docker и совмещённое развёртывание транспортов