Pro редакция

Инструменты MCP

Краткий обзор

NextPDF Pro добавляет восемь инструментов Model Context Protocol (MCP), которые позволяют ИИ-агенту выполнять расширенные операции с PDF через NextPDF Server. Инструменты появляются автоматически, когда установлены и nextpdf/pro, и nextpdf/server — отдельный шаг регистрации не требуется.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Pro (nextpdf/pro) и активируется лицензионным конвертом уровня Pro. Развёртывание без этого права не загружает классы возможности. Сравнить редакции и получить лицензию.

Базовая поверхность MCP — создание документов, текст, таблицы, диагностика — поставляется с открытым NextPDF Server и не требует лицензии. Восьми инструментам на этой странице нужна лицензия Pro, и они регистрируются только тогда, когда пакет nextpdf/pro разрешается при загрузке. Уровень инструментов pro управляет всем набором: каждый инструмент явно объявляет свой уровень, и пофункционального флага нет — установка nextpdf/pro рядом с nextpdf/server включает набор.

Контракт поведения

Восемь инструментов Pro MCP регистрируются автоматически, когда при загрузке разрешаются и nextpdf/pro, и nextpdf/server, на уровне pro, через стандартный поток MCP tools/list и tools/call. Пофункционального флага нет, и в приложении-потребителе не требуется изменений кода.
Каждый инструмент принимает PDF через document_id из предыдущего вызова create_pdf, встроенный source (путь к файлу, base64 или URI data:) или — для compare_pdfs — два таких источника. Инструменты возвращают структурированный JSON.
Каждый инструмент объявляет класс риска HITL, который применяет сервер: safe (автоисполнение, только чтение), review (вывод, который можно использовать во вред) и approval-required. sign_pdf относится к approval-required и удерживается, пока человек его не подтвердит. Оператор может только ужесточить класс риска инструмента, но никогда не ослабить.
sign_pdf создаёт только подпись PAdES B-B (baseline) — без доверенной метки времени и без материалов долгосрочной проверки. Долгосрочные профили (B-LT / B-LTA), аппаратное хранение ключей и подписание с аудит-трейлом относятся к уровню Enterprise и этими инструментами не предоставляются; B-T (подпись с меткой времени) доступна в движке Core, когда настроен поставщик меток времени.
redact_pii выполняет шаблонное обнаружение и маскирование в текстовом слое, а не визуальное редактирование; check_accessibility — это структурная эвристика, а не вердикт о соответствии PDF/UA или WCAG. Авторитетной схемой входных и выходных данных является «живой» ответ сервера tools/list, а не эта страница.

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

NextPDF Server — это детерминированный уровень исполнения MCP для NextPDF. При загрузке он обнаруживает поставщиков инструментов с помощью проверки существования класса, поэтому пакет Pro не нужно указывать в зависимостях сервера. Когда пакет Pro присутствует, сервер регистрирует его восемь инструментов на уровне pro и предоставляет их через стандартный поток MCP tools/list и tools/call поверх любого настроенного вами транспорта.

Каждый инструмент Pro принимает PDF из одного из трёх источников: document_id, возвращённый предыдущим вызовом create_pdf, встроенный source (путь к файлу, строка base64 или URI data:) или — для инструмента сравнения — два таких источника. Инструменты возвращают структурированные результаты JSON: извлечённый текст, области различий, замаскированный текст, деревья сегментов, находки по доступности или подписанный PDF.

Каждый инструмент Pro несёт классификацию риска, которую сервер использует для контроля «человек в контуре» (HITL). Инструменты анализа только для чтения относятся к safe и исполняются автоматически. Инструменты, которые порождают вывод, способный быть использованным во вред вызывающей стороной, относятся к review. Инструмент подписания относится к approval-required, поэтому сервер удерживает его, пока человек его не подтвердит. Сам инструмент объявляет эту классификацию; оператор может во время выполнения только ужесточить её — но никогда не ослабить.

Поверхность инструментов MCP намеренно отделена от движка PDF Pro. Инструменты — тонкие адаптеры: они проверяют входные данные, разрешают PDF, делегируют компоненту движка Pro и сериализуют результат. Они не являются вторым API движка и не входят в публичный PHP API Pro — поддерживаемая точка интеграции — это протокол MCP, предоставляемый NextPDF Server.

Каталог инструментов (восемь инструментов Pro)

Восемь инструментов Pro MCP, по имени в протоколе MCP. Уровни риска следуют HITL-модели сервера: safe (автоисполнение, только чтение), review (порождает вывод, который можно использовать во вред; предупреждается в инструкциях агента) и approval-required (должен быть подтверждён человеком).

`extract_text`

Назначение: извлечение текста. Извлекает текстовый слой PDF, при необходимости ограниченный диапазоном страниц с индексацией от 1.
Входные данные: PDF (document_id или source); необязательные page_start и page_end.
Выходные данные: извлечённый текст и общее количество страниц.
Риск: safe. Только чтение и идемпотентно.
Граница: извлекает существующий текстовый слой. Он не выполняет OCR для отсканированных или только изображённых страниц.

`segment_document`

Назначение: структурная сегментация. Разбивает PDF на логические разделы — заголовок, рубрики, основной текст, таблицы, иллюстрации.
Входные данные: PDF (document_id или source).
Выходные данные: количество сегментов и структурированный список сегментов.
Риск: safe. Только чтение и идемпотентно.
Граница: структурная сегментация на основе анализа разметки; это не семантический план и не дерево структуры тегированного PDF.

`compare_pdfs`

Назначение: структурное сравнение. Сравнивает два PDF и возвращает структурированное различие их текстового содержимого.
Входные данные: два PDF (source_a и source_b, каждый — путь, base64, URI data или document_id).
Выходные данные: флаг идентичности, общее число изменений, количество страниц по каждому документу и список изменённых областей с индексами страниц и строк.
Риск: safe. Только чтение и идемпотентно.
Граница: различие текстового содержимого. Оно не сравнивает визуальный рендеринг, встроенные шрифты или двоичную структуру.

`redact_pii`

Назначение: обнаружение и маскирование PII. Обнаруживает персональные данные в текстовом слое PDF и возвращает замаскированное представление текста.
Входные данные: PDF (document_id или source); необязательный фильтр types (email, phone, ssn, credit_card).
Выходные данные: флаг наличия PII, число обнаруженных вхождений, замаскированный текст и список просканированных типов.
Риск: review. Замаскированный вывод можно использовать во вред, если воспринимать его как очищенный документ.
Граница: это шаблонное обнаружение и маскирование в текстовом слое, а не визуальное редактирование. Оно не удаляет и не перезаписывает глифы в отрисованном PDF, а сопоставление по шаблону не гарантирует, что найдено каждое вхождение конфиденциальных данных. Не воспринимайте его вывод как гарантию полного удаления PII. Для редактирования на уровне документа, разрушающего исходное содержимое, используйте выделенную поверхность редактирования в открытых инструментах сервера или редакцию Enterprise.

`fill_form`

Назначение: данные заполнения AcroForm. Генерирует данные XFDF (ISO 19444-1), заполняющие поля AcroForm PDF из карты «имя поля → значение».
Входные данные: карта fields «имя поля → строковое значение»; необязательное pdf_filename, встраиваемое как ссылка XFDF.
Выходные данные: сгенерированный документ XFDF и число полей.
Риск: review. Он порождает данные формы, предназначенные для применения к документу.
Граница: он порождает XFDF, соответствующий стандарту; сам он не записывает значения обратно в PDF. Примените XFDF любым совместимым средством чтения или обработки.

`extract_form_data`

Назначение: обратное чтение AcroForm. Извлекает имена и значения полей AcroForm из XFDF, встроенного в PDF.
Входные данные: PDF (document_id или source).
Выходные данные: число полей и карта «имя поля → значение»; явная пометка, когда встроенных данных формы нет.
Риск: safe. Только чтение и идемпотентно.
Граница: читает встроенные потоки XFDF (ISO 19444-1). PDF, который хранит значения формы только в объектах AcroForm без встроенного XFDF, возвращает пустой результат.

`check_accessibility`

Назначение: анализ структурной доступности. Анализирует структурную доступность PDF — рубрики, абзацы, таблицы и изображения — и сообщает о вероятных проблемах со ссылками на WCAG.
Входные данные: PDF (document_id или source).
Выходные данные: структурная оценка (0–100), список проблем и сводка по сегментам.
Риск: safe. Только чтение и идемпотентно.
Граница: это структурная эвристика, а не вердикт о соответствии. Полное тестирование соответствия PDF/UA и WCAG — дерево тегов, порядок чтения, контрастность цвета — требует выделенного движка доступности. Высокая оценка не является заявлением о соответствии PDF/UA.

`sign_pdf`

Назначение: цифровая подпись PAdES B-B. Применяет цифровую подпись PAdES B-B (baseline) к PDF, используя локальный сертификат X.509 и закрытый ключ.
Входные данные: PDF (document_id или source); сертификат PEM и закрытый ключ PKCS#8; необязательный алгоритм (по умолчанию RSA-SHA256, RSA + SHA-3 256/384/512 или Ed25519); необязательные имя подписанта и причина; необязательный транспортный конверт AES-GCM вокруг полезной нагрузки закрытого ключа.
Выходные данные: подписанный PDF, число подписей, флаг завершения, а также использованные алгоритм, OID и дайджест.
Риск: approval-required. Подписание — юридически значимая, разрушительная операция; сервер требует явного подтверждения человеком перед её запуском.
Граница: этот инструмент создаёт подпись PAdES B-B (baseline) — он не встраивает доверенную метку времени или материалы долгосрочной проверки. Долгосрочные профили (B-LT / B-LTA), аппаратное хранение ключей и подписание с аудит-трейлом входят в редакцию Enterprise; B-T (подпись с меткой времени) доступна в движке Core, когда настроен поставщик меток времени. О более широких возможностях подписания пакета Pro см. поверхность подписи Pro, а о B-LT/B-LTA — редакцию Enterprise.

Как инструменты появляются

composer require nextpdf/pro
composer require nextpdf/server

Когда оба пакета установлены, запустите NextPDF Server с выбранным вами транспортом. При загрузке сервер обнаруживает уровень Pro, и восемь инструментов появляются в ответе MCP tools/list на уровне pro рядом с открытыми инструментами Core. Вашему приложению не нужны изменения кода — обнаружение выполняется автоматически, и отсутствующий уровень никогда не мешает загрузке остальных.

Авторитетной схемой входных и выходных данных каждого инструмента является схема, которую сервер публикует в ответе tools/list. Считайте этот ответ — а не эту страницу — контрактом: этот каталог описывает назначение и границы; «живая» схема описывает точные имена и типы полей.

Образец кода — быстрый старт

Инструменты Pro потребляются по протоколу MCP, а не через PHP API Pro. Интеграция на стороне хоста — это запуск NextPDF Server. При наличии nextpdf/pro восемь инструментов регистрируются через обнаружение во время выполнения — без пофункциональной обвязки — и хост затем предоставляет их агентам.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;

require __DIR__ . '/vendor/autoload.php';

// Runtime discovery registers the Pro tier when nextpdf/pro is installed
// alongside nextpdf/server. The consuming application changes no code.
$server = McpServer::create();

// A Pro tool name resolves only when the Pro package is present.
$signTool = $server->getToolRegistry()->get('sign_pdf');

\fwrite(\STDERR, $signTool !== null
    ? "Pro MCP tools active.\n"
    : "Pro MCP tools unavailable; install nextpdf/pro.\n");

// Serve the MCP protocol over stdio (Claude Desktop, Cursor, local agents).
$server->run();

Образец кода — продакшен

Укрепите путь загрузки. Загрузите явный файл политики, откажитесь запускаться при недопустимом переопределении уровня риска и подтвердите появление уровня Pro перед обслуживанием. Обвязка в McpServer::create() выбрасывает InvalidArgumentException, когда блок risk_level_overrides пытается ослабить инструмент уровня approval-required, такой как sign_pdf, поэтому неправильно настроенная политика отказывает в закрытое состояние до цикла обслуживания.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;
use NextPDF\Server\Tools\ToolInterface;

require __DIR__ . '/vendor/autoload.php';

// A downgrade of an approval-required tool's HITL gate is rejected at boot,
// never silently applied — the server refuses to start on such a policy.
try {
    $server = McpServer::create(__DIR__ . '/nextpdf-mcp.yaml');
} catch (\InvalidArgumentException $e) {
    \fwrite(\STDERR, 'Refusing to start: invalid MCP policy. ' . $e->getMessage() . "\n");
    exit(1);
}

// Confirm the Pro tier surfaced before advertising it to agents.
$signTool = $server->getToolRegistry()->get('sign_pdf');

if (!$signTool instanceof ToolInterface) {
    \fwrite(\STDERR, "nextpdf/pro is not resolving; Pro MCP tools are unavailable.\n");
    exit(1);
}

// sign_pdf is approval-required; the server holds it for human confirmation.
$risk = $signTool->riskLevel()->label();
\fwrite(\STDERR, "Pro MCP tools ready. sign_pdf risk: {$risk}.\n");

$server->run();

Граничные случаи

Диапазоны страниц extract_text индексируются от 1 и ограничиваются реальным количеством страниц документа; конец вне диапазона не вызывает ошибку.
compare_pdfs требует оба источника; передача одного возвращает понятную ошибку валидации, а не частичное различие.
extract_form_data возвращает заполненный, явный результат «нет встроенных данных формы», а не ошибку, для PDF без встроенного XFDF.
sign_pdf отклоняет неподдерживаемые идентификаторы алгоритмов вместе со списком поддерживаемых значений; Ed25519 требует расширения libsodium, а варианты SHA-3 требуют сборки OpenSSL с поддержкой SHA-3.
check_accessibility намеренно низко оценивает PDF только из изображений — он отмечает отсутствие читаемого текстового слоя, а не завершается с ошибкой.

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

Инструмент подписания — единственный инструмент approval-required; сервер не исполняет его автоматически.
Необязательный конверт AES-GCM вокруг закрытого ключа аутентифицирует полезную нагрузку; несовпадение тега приводит к отказу в закрытое состояние с ошибкой расшифровки и никогда не откатывается к использованию шифротекста.
redact_pii не изменяет исходный PDF; он возвращает замаскированное текстовое представление. Это не замена разрушению содержимого.
Инструмент проверяет входные данные до любой работы движка; он отклоняет некорректные источники, URI data и полезные нагрузки base64 с явными ошибками.

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

Инструменты форм порождают и потребляют XFDF согласно ISO 19444-1:2019 (XML Forms Data Format).
sign_pdf создаёт подпись PAdES baseline (B-B), согласованную с семейством PAdES ETSI EN 319 142; долгосрочные профили — возможность Enterprise, а B-T доступна в движке Core, когда настроен поставщик меток времени.
check_accessibility сообщает находки со ссылками на критерии успеха WCAG (например 1.1.1, 1.3.1, 2.4.6) как эвристическое руководство, а не как аттестацию о соответствии.

Граница редакции

NextPDF Pro вносит ровно восемь инструментов MCP, все на уровне pro. Редакция Enterprise поставляет собственный, отдельный набор инструментов MCP на уровне enterprise — он охватывает проверку соответствия требованиям, криминалистический анализ, состояние материалов долгосрочной проверки, сертификацию готовности к ИИ, а также поиск и встраивание документов. Эти инструменты, их входные данные и их внутреннее устройство выходят за рамки этой страницы; см. инструменты MCP Enterprise. Собственная документация сервера охватывает инструменты Core (открытые), которые с ним поставляются. Сервер обнаруживает три уровня независимо, и отсутствующий уровень никогда не отключает остальные.

Граница с Enterprise

Pro вносит ровно восемь инструментов MCP на уровне pro. Редакция Enterprise поставляет отдельный набор инструментов MCP на уровне enterprise (проверка соответствия требованиям, криминалистический анализ, состояние материалов долгосрочной проверки, сертификация готовности к ИИ, поиск и встраивание документов) и профили подписей с меткой времени/долгосрочные; они не предоставляются уровнем Pro. Полную разбивку по уровням см. в разделе Граница редакции выше.

Резервный вариант / альтернатива в Core

Открытый NextPDF Server даёт любому ИИ-агенту детерминированный набор инструментов PDF Core (создание документов, текст, таблицы, диагностика) без лицензии. Восемь продвинутых инструментов на этой странице — дополнения Pro. См. /connect/tools/.

Граница публикации

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