Каталог инструментов NextPDF Connect

Кратко

NextPDF Connect не предоставляет фиксированное число инструментов. Сервер вычисляет это число во время выполнения на основе установленных пакетов, списка разрешённых инструментов в конфигурации и переменных окружения, управляющих доступом. На этой странице описаны проверенный основной набор и механизм, по которому определяется итоговое число.

Установка

composer require nextpdf/server

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

NextPDF\Server\ToolRegistry строит каталог при загрузке в следующем порядке:

Основной уровень. Фиксированный набор основных инструментов регистрируется безусловно. Ещё два инструмента регистрируются только при соблюдении предварительного условия.
Уровень Pro. Инструменты Pro регистрируются, когда класс провайдера Pro разрешается, что происходит при установленном nextpdf/premium. Если класс не разрешается, сервер молча пропускает этот шаг.
Уровень Enterprise. Провайдер Enterprise следует той же схеме, что и провайдер Pro.
Встроенные расширенные уровни. Провайдеры инструментов AST и мутаций поставляются в составе пакета сервера и регистрируются на уровне Pro. У каждого провайдера есть своя переменная окружения, и каждый провайдер корректно деградирует, когда базовая поддержка в ядре отсутствует.
Фильтр политики безопасности. Сервер сверяет каждую регистрацию со списком разрешённых enabled_tools. Непустой список разрешённых отбрасывает любой инструмент, которого в нём нет. Счётчик уровня учитывает только инструменты, допущенные политикой.

Ответ initialize протокола Model Context Protocol (MCP) сообщает итоговое tool_count и число инструментов по уровням для запущенного сервера. Это значение авторитетно. Любое фиксированное итоговое число в тексте считайте устаревшим.

Состав API

Проверенные всегда доступные основные инструменты

Эти двенадцать инструментов всегда регистрируются на основном уровне. Сервер считывает уровень риска и поведенческую подсказку MCP каждого инструмента из его реализации.

Имя инструмента	Категория	Описание	Риск
`create_pdf`	документ	Создаёт PDF-документ и возвращает `document_id`	caution
`add_text`	документ	Добавляет текстовое содержимое в PDF-документ	caution
`add_image`	документ	Добавляет изображение из пути к файлу или данных в base64	caution
`add_table`	документ	Добавляет HTML-таблицу в PDF-документ	caution
`set_font`	документ	Задаёт шрифт для последующих операций с текстом	caution
`add_page`	документ	Добавляет новую страницу в PDF-документ	caution
`output_pdf`	документ	Завершает формирование PDF как файла или base64	approval_required
`preview_layout`	документ	Возвращает сводку макета в формате JSON без отрисовки	safe
`diagnostic.doctor`	диагностика	Выполняет проверку работоспособности и структурированную диагностику окружения	safe
`diagnostic.capabilities`	диагностика	Перечисляет возможности с указанием уровня и статуса	safe
`diagnostic.inspect`	диагностика	Анализирует PDF и возвращает структурные метаданные	safe
`diagnostic.verify`	диагностика	Проверяет целостность PDF и дополнительно проверяет PDF/A или PDF/UA	caution

Условно регистрируемые основные инструменты

Имя инструмента	Условие
`generate_barcode`	Регистрируется, если установленный `nextpdf/core` включает реестр кодировщиков штрихкодов ядра
`parse_pdf`	Регистрируется, только когда `NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED` равно `true` или `1`

output_pdf — единственный инструмент основного уровня с уровнем риска approval_required. Запись файла проходит через контрольную точку с участием человека; вывод в base64 — нет. См. /connect/hitl-risk-tiers/.

Инструменты, добавляемые только при установке дополнительных пакетов

Сервер проверяет классы провайдеров с помощью class_exists():

Инструменты Pro регистрируются, если установлен nextpdf/premium и разрешается провайдер Pro.
Инструменты Enterprise регистрируются, если установлен nextpdf/premium и разрешается провайдер Enterprise. Инструменты конфиденциальности (редактирование, обезличивание, зональное редактирование) — это обёртки над классами Enterprise. Они регистрируются на уровне Enterprise только тогда, когда эти классы доступны для автозагрузки.
Инструменты AST и мутаций поставляются вместе с сервером и регистрируются на уровне Pro. Ими управляют переменные окружения NEXTPDF_AST_TOOLS_ENABLED и NEXTPDF_MUTATION_TOOLS_ENABLED, и обе по умолчанию включены.

Точные перечни инструментов Pro и Enterprise определяет пакет Premium, а не сервер; они документируются вместе с этим пакетом. Контракт сервера — это механизм регистрации, а не фиксированный список Premium.

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

Выведите инструменты, которые предоставляет эта установка, не запуская сервер:

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

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

Запросите у запущенного сервера достоверное число через MCP:

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

Сервер вычисляет capabilities.nextpdf.tool_count и tiers в ответе initialize для запущенного процесса. В REST-запросе GET /api/v1/capabilities возвращается эквивалентная интроспекция.

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

Нет фиксированных “33 инструментов”, как и любого другого фиксированного итога. В старых материалах приводится одно число, но это число не является контрактом. Число меняется в зависимости от установленных пакетов, списка разрешённых enabled_tools и переменных окружения parse_pdf, AST и мутаций. Всегда считывайте его с запущенного сервера.
Список разрешённых инструментов только исключает, но никогда не добавляет. Указание инструмента Pro в enabled_tools не зарегистрирует его, если nextpdf/premium отсутствует.
Отсутствующий уровень — ожидаемое поведение без ошибки. Установка только из пакетов с открытым исходным кодом обслуживает основной набор и сообщает о нуле инструментов Pro и нуле инструментов Enterprise. Такой результат — это корректная работа, а не сбой.
Уровень в каталоге — это объявленный инвариант. Каждый инструмент объявляет собственный уровень и риск в коде. Реестр никогда не выводит уровень из пространства имён или пакета.

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

Сканирование реестра и определение уровней выполняются один раз при загрузке. Их ограничивает параметр страницы performance_budget. Стоимость вызова инструмента зависит от операции базового движка, а не от поиска в каталоге, который выполняется за O(1) по имени инструмента.

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

Используйте enabled_tools для реализации принципа минимальных привилегий: предоставляйте только те инструменты, которые нужны интеграции. Каталог никогда не включает инструмент, отклонённый политикой безопасности, а счётчик уровня отражает только допущенные инструменты. Инструменты высокого риска остаются под защитой подтверждения человеком независимо от того, входят ли они в каталог. См. /connect/security-and-operations/.

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

На этой странице описан механизм работы реестра. Ссылки на протокол для интерфейсов tools/list и initialize приведены на /transports/mcp/. Модель рисков описана на /connect/hitl-risk-tiers/.

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

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

См. также

/connect/hitl-risk-tiers/ — что означает столбец риска и как применяется политика
/connect/boot-and-discovery/ — полная последовательность загрузки и обнаружения
/connect/configuration/ — enabled_tools и переменные окружения
/transports/mcp/ — tools/list и initialize в формате транспорта
/connect/overview/ — почему каталог по замыслу зависит от времени выполнения