Enterprise редакция

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

Кратко

NextPDF Enterprise добавляет одиннадцать инструментов MCP к серверу NextPDF Connect. Они дают ИИ-ассистентам и агентным фреймворкам прямой типизированный доступ к движку Enterprise: проверки политик соответствия, криминалистику PDF, проверки состояния LTV, штампование готовности к ИИ, чанкинг с учётом AST и приём и поиск RAG. Каждый инструмент объявляет собственный уровень риска и позицию «только чтение», так что ваш MCP-хост может уверенно ограничивать, логировать и аудировать активность агентов. Сбои никогда не всплывают в виде исключений; агенты всегда получают структурированный, разбираемый результат.

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

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

Установка

composer require nextpdf/enterprise:^3

Сам MCP-хост — это NextPDF Connect, поставляемый в пакете nextpdf/server; см. Установку Connect. Когда присутствуют оба пакета, реестр инструментов сервера автоматически обнаруживает NextPDF\Enterprise\McpToolProvider и регистрирует одиннадцать инструментов Enterprise. Код связывания не требуется. Если nextpdf/server отсутствует, файл провайдера завершает работу заранее и ничего не загружается.

Инструменты batch и RAG дополнительно требуют sidecar Spectrum. Настройте его через переменные окружения, читаемые NextPDF\Enterprise\Mcp\SpectrumClientFactory: SPECTRUM_URL (по умолчанию http://127.0.0.1:7800), SPECTRUM_TIMEOUT (по умолчанию 30.0 секунд), SPECTRUM_AUTH_TOKEN и SPECTRUM_APP_SECRET.

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

Model Context Protocol (MCP) — это открытый протокол, позволяющий ИИ-ассистентам и агентным фреймворкам вызывать типизированные инструменты, предоставляемые сервером. Вместо того чтобы вставлять байты PDF в промпт и надеяться, агент вызывает именованный инструмент с полезной нагрузкой, проверенной по JSON-схеме, и получает детерминированный структурированный результат. NextPDF Connect — это такой сервер для PDF; пакет Enterprise расширяет его каталог инструментами ниже. Каждый инструмент — это тонкая обёртка над теми же API Enterprise, которые ваш PHP-код вызывает напрямую, поэтому проверка, запущенная агентом, и проверка, запущенная кодом, дают один и тот же вердикт.

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

Инструмент MCP	Класс	Что делает	Риск	Только чтение
`compliance_check`	`ComplianceCheckTool`	Проверяет один PDF по именованной политике: `pdfa4`, `pdfa4e`, `pdfa4f`, `pades-baseline`, `ltv-health`, `eidas-qualified`, `zugferd`, `fda-part11` и четыре варианта `sec-17a4`.	Review	да
`batch_compliance_check`	`BatchComplianceCheckTool`	Проверяет множество PDF по политикам `pdfa`, `pades` или `zugferd` в одном пакете sidecar Spectrum.	Safe	да
`forensic_analyze`	`ForensicAnalyzeTool`	Сообщает историю ревизий, инкрементальные обновления и события модификации для обнаружения подделки.	Safe	да
`batch_forensic_analyze`	`BatchForensicAnalyzeTool`	Выполняет криминалистический анализ множества PDF в одном пакете sidecar.	Safe	да
`ltv_health_check`	`LtvHealthCheckTool`	Проверяет подписанный PDF на материал долгосрочной валидации: словарь DSS, ответы OCSP, записи CRL, записи VRI и хранилища сертификатов.	Safe	да
`ai_ready_certify`	`AiReadyCertifyTool`	Вердикт готовности к ИИ, определённый продуктом, только для чтения, по четырём критериям: криминалистическая целостность, наличие подписи, валидность LTV, отсутствие шифрования.	Review	да
`certify_ai_ready`	`CertifyAiReadyTool`	Вердикт готовности, определённый продуктом, по трём критериям (четыре критерия инструмента только для чтения минус криминалистическая целостность — по замыслу, поскольку этот инструмент переписывает штампуемый файл) и добавляет XMP-штамп происхождения; возвращает штампованный PDF как base64.	Review	нет
`ast_aware_chunk`	`AstAwareChunkTool`	Разбивает PDF на привязанные к цитатам чанки по границам заголовков, с ID узла, индексом страницы и ограничивающим прямоугольником для каждого чанка.	Review	да
`audit_ast_mutations`	`AuditAstMutationsTool`	Извлекает журнал аудита мутаций AST для документа по хешу-источнику SHA-256.	Review	да
`embed_documents`	`EmbedDocumentsTool`	Принимает PDF в коллекцию RAG: разбор, чанкинг, эмбеддинг, индексация. Изменяет состояние коллекции.	Caution	нет
`search_documents`	`SearchDocumentsTool`	Гибридное извлечение (ключевые слова BM25 плюс семантика) по принятой коллекции, с ранжированными оценёнными чанками.	Safe	да

Инструменты «certify» выдают вердикт готовности, определённый продуктом (certified, partial или not_certified). Этот вердикт — результат технической проверки, а не сертификация каким-либо аккредитующим органом.

Ограничение одобрения и позиция аудита

Каждый инструмент объявляет уровень риска из четырёхуровневой модели Connect. Инструменты Safe выполняются автоматически. Инструменты Caution выполняются автоматически с записью в журнал аудита. Инструменты Review несут предупреждение для инструкций вызывающего агента. Инструменты ApprovalRequired требуют подтверждения человеком; ни один инструмент Enterprise MCP в настоящее время не объявляет этот уровень, поскольку ни один не является деструктивным. Конфигурация во время выполнения может только повысить уровень риска инструмента, но никогда не понизить. Инструменты также публикуют аннотации поведения MCP (readOnlyHint, idempotentHint), поэтому совместимый клиент может применять собственное ограничение поверх. См. Уровни риска HITL для полной модели.

Почему это работает именно так

Несущее решение состоит в том, что инструменты — это тонкие детерминированные обёртки с самообъявленным управлением: каждый инструмент указывает собственный уровень риска и уровень как доменный инвариант, никогда не выводимый из пространства имён или упаковки. Это делает решение об ограничении аудируемым на хосте без доверия к транспорту. Инструменты не содержат собственного интеллекта работы с документами; они делегируют тем же API Enterprise, которые вызывает ваш код, поэтому существует ровно одно поведение для тестирования и один вердикт, которому можно доверять. Ошибки возвращаются по каналу ошибок MCP, а не убегают как исключения, потому что агент не может перехватить исключение PHP, но всегда может ветвиться по isError. Ввод, который может затронуть файловую систему, по умолчанию отказоустойчиво-закрыт, поскольку аргументы MCP по определению достижимы для атакующего.

Проектный фон: API, который отказывается угадывать.

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

Все одиннадцать инструментов реализуют контракт NextPDF\Server\Tools\ToolInterface из nextpdf/server и разделяют одну и ту же публичную поверхность. Сигнатуры ниже показаны один раз на NextPDF\Enterprise\Mcp\ComplianceCheckTool как представителе:

public function name(): string
public function description(): string
public function inputSchema(): array
public function annotations(): array
public function riskLevel(): RiskLevel
public function tier(): ToolTier
public function category(): string
public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

Выбрасывает или завершается с ошибкой: execute() никогда не выбрасывает исключение. Он перехватывает Throwable внутренне и возвращает ToolResult::error() с isError = true. Недопустимые аргументы (отсутствующий workspace_token, некорректные записи documents, неизвестный document_id, небезопасный source) всплывают как сообщения InvalidArgumentException на этом канале ошибок.

Инструмент журнала аудита принимает свой бэкенд хранения через инъекцию в конструктор:

public function __construct(private readonly AstAuditTrailInterface $auditTrail)

Провайдер, который регистрирует каталог:

public function getTier(): string
public function getTools(): array

getTier() возвращает 'enterprise'. getTools() возвращает одиннадцать экземпляров инструментов; audit_ast_mutations по умолчанию связан с NextPDF\Enterprise\Ast\InMemoryAstAuditTrail.

Фабрика клиента sidecar Spectrum, которая также является фабрикой запросов и потоков PSR-17:

public static function create(): SpectrumClient
public static function reset(): void
public function createRequest(string $method, $uri): RequestInterface
public function createStream(string $content = ''): StreamInterface
public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface
public function createStreamFromResource($resource): StreamInterface

Выбрасывает или завершается с ошибкой: create() выбрасывает InvalidArgumentException, когда SPECTRUM_URL некорректен или когда настроенная конечная точка нацелена на известный частный или зарезервированный адрес (кроме localhost). Это ограничение на этапе конфигурации, а не контроль на сетевом уровне: всё равно применяйте политику исходящего трафика, обработку редиректов и DNS-пиннинг в среде хоста. createStreamFromFile() выбрасывает NextPDF\Enterprise\Mcp\McpStreamException (подкласс RuntimeException, согласно контракту PSR-17), когда файл не может быть открыт.

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

Запустите проверку соответствия PDF/A-4 ровно так, как это сделал бы агент, используя канал URI data: в памяти:

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Mcp\ComplianceCheckTool;
use NextPDF\Enterprise\Mcp\McpStreamException;
use NextPDF\Enterprise\Mcp\SpectrumClientFactory;
use NextPDF\Server\Document\InMemoryDocumentStore;

$streams = new SpectrumClientFactory(); // PSR-17 stream factory from this module

try {
    $pdfBytes = (string) $streams->createStreamFromFile(__DIR__ . '/invoice.pdf');
} catch (McpStreamException $e) {
    fwrite(STDERR, 'Cannot read PDF: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

$tool   = new ComplianceCheckTool();
$result = $tool->execute(
    [
        'source' => 'data:application/pdf;base64,' . base64_encode($pdfBytes),
        'policy' => 'pdfa4',
    ],
    new InMemoryDocumentStore(),
);

// Tool failures arrive on the MCP error channel, never as exceptions.
if ($result->isError) {
    fwrite(STDERR, $result->content[0]['text'] . PHP_EOL);
    exit(1);
}

echo $result->content[0]['text'] . PHP_EOL;

Ожидаемый вывод для соответствующего файла (число находок зависит от документа):

Compliance check (PDF/A-4): PASS — 0 finding(s)

Полный машиночитаемый отчёт, включая серьёзность по каждой находке, ID правила, пункт и предложение, доступен на $result->structured.

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

Проверьте sidecar заранее, примените объявленную позицию риска, затем запустите пакетную проверку соответствия:

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Mcp\BatchComplianceCheckTool;
use NextPDF\Enterprise\Mcp\SpectrumClientFactory;
use NextPDF\Server\Document\InMemoryDocumentStore;

// 1. Fail fast on sidecar misconfiguration before accepting agent traffic.
//    The factory validates SPECTRUM_URL and rejects private/reserved targets.
try {
    SpectrumClientFactory::create();
} catch (InvalidArgumentException $e) {
    fwrite(STDERR, 'Spectrum sidecar rejected: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

$tool = new BatchComplianceCheckTool();
$risk = $tool->riskLevel();

// 2. Enforce the declared risk posture before execution.
if ($risk->requiresHumanConfirmation()) {
    // Route to your approval queue instead of executing.
    exit(0);
}

if ($risk->requiresAuditLog()) {
    error_log(sprintf('[mcp-audit] tool=%s risk=%s', $tool->name(), $risk->label()));
}

// 3. Execute the batch.
$result = $tool->execute(
    [
        'workspace_token' => (string) getenv('SPECTRUM_WORKSPACE_TOKEN'),
        'documents'       => [
            ['id' => 'contract-001', 'path' => '/var/pdf-inbox/contract-001.pdf'],
            ['id' => 'contract-002', 'path' => '/var/pdf-inbox/contract-002.pdf'],
        ],
        'policies'        => ['pdfa', 'pades'],
    ],
    new InMemoryDocumentStore(),
);

echo $result->content[0]['text'] . PHP_EOL;

Ожидаемый вывод (число отражает ваши документы):

Batch compliance check complete: 1 compliant, 1 non-compliant

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

Пути source в файловой системе отключены по умолчанию. Без переменной окружения NEXTPDF_MCP_INPUT_DIR source в форме пути отклоняется с результатом-ошибкой. Используйте вместо этого document_id, URI data: или сырой base64.
Сырой base64 распознаётся только свыше 256 символов. Более короткий blob base64 трактуется как путь к файлу и отклоняется. Оборачивайте малые полезные нагрузки в URI data:application/pdf;base64,.
Неизвестные значения document_id завершаются с подсказкой. Текст ошибки: Unknown document_id: ... Call create_pdf first. Документы в хранилище в памяти также истекают по TTL хранилища, поэтому устаревший ID завершается так же.
compliance_check отклоняет неизвестные ключи политик и перечисляет поддерживаемый набор в сообщении об ошибке.
Инструментам batch и RAG нужен sidecar. batch_compliance_check, batch_forensic_analyze, embed_documents и search_documents требуют доступной конечной точки Spectrum и workspace_token. Фабрика кеширует один клиент на процесс; вызывайте SpectrumClientFactory::reset() в тестах.
search_documents ограничивает top_k диапазоном 1–100; нецелые значения откатываются к серверному значению по умолчанию 10.
Значения по умолчанию ast_aware_chunk — 1500 символов на чанк с перекрытием 150 символов.
certify_ai_ready опускает штампованные байты, когда return_stamped_pdf равно false или вердикт not_certified. Когда присутствует, полезная нагрузка base64 примерно на треть больше самого PDF.
Журнал аудита AST по умолчанию хранится в памяти. Записи, зафиксированные через стандартную связку провайдера, не сохраняются между процессами; внедрите постоянную реализацию AstAuditTrailInterface для долговечных журналов аудита.

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

Отказоустойчиво-закрытое разрешение источника. MCP-вызывающие полностью контролируют аргументы инструмента, поэтому резолвер трактует их как враждебные. Обёртки потоков (phar://, php://, file:// и любая схема) и нулевые байты отклоняются до любого вызова файловой системы. Обход путей отклоняется. Сырые пути к файлам работают только когда установлена NEXTPDF_MCP_INPUT_DIR, и канонизированная через realpath цель должна разрешаться строго внутри этого каталога, сравниваясь по границе разделителя для блокировки побегов через путаницу префиксов.
Защита от SSRF на конечной точке sidecar. SpectrumClientFactory разрешает localhost для режима локального sidecar и проверяет каждый другой SPECTRUM_URL по частным, зарезервированным, link-local диапазонам и диапазонам метаданных облака, выбрасывая InvalidArgumentException на заблокированном адресе. Это ограничение на этапе конфигурации на настроенной конечной точке, а не контроль на сетевом уровне — сохраняйте политику исходящего трафика, обработку редиректов и DNS-пиннинг в среде хоста.
Секреты остаются в окружении. Токен-носитель sidecar (SPECTRUM_AUTH_TOKEN) и секрет подписи HMAC (SPECTRUM_APP_SECRET) читаются из переменных окружения и никогда не появляются в полезных нагрузках или результатах инструментов.
Нерефлективные ошибки. Сообщения об отклонении пути по замыслу обобщённые (Source path is not permitted.), так что зондирующий вызывающий не узнаёт ничего о файловой системе хоста.
Переопределения риска идут только вверх. Конфигурация оператора может повысить объявленный уровень риска инструмента, но никогда не понизить его ниже собственного объявления инструмента.

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

Поддержка — это не соответствие, а соответствие — это не сертификация. NextPDF не имеет сертификации и не предоставляет её. Инструменты соответствия проверяют структуру документа по именованным профилям политик и сообщают находки со ссылками на пункты; отчёт compliance_check дополнительно несёт собственную оговорку движка о том, что это техническая проверка структуры для справки, а не юридический совет или подтверждение соответствия. Вердикты ai_ready_certify и certify_ai_ready — это уровни готовности, определённые продуктом, а не аттестация каким-либо органом стандартизации. MCP — это открытый протокол, опубликованный его вендором-распорядителем, а не стандарт SDO; эта страница документирует поведение реализации NextPDF и не делает независимых заявлений о соответствии протоколу или сертификации.

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

Сбои инструментов возвращаются как результаты-ошибки (isError = true с сообщением); исключения никогда не пересекают границу MCP.
Успешные результаты несут однострочную человекочитаемую сводку плюс структурированную полезную нагрузку JSON со стабильным документированным набором полей для каждого инструмента.
Каждый инструмент сообщает tier() = ToolTier::Enterprise и объявленный RiskLevel; риск не может быть понижен во время выполнения.
Инструменты только для чтения объявляют readOnlyHint: true и не изменяют хранилище документов, исходный PDF или какую-либо коллекцию.
certify_ai_ready никогда не изменяет входной документ на месте; штамп применяется к возвращаемой копии.
Отчёты соответствия и LTV включают временную метку валидации и число находок по серьёзности; полезная нагрузка compliance_check дополнительно включает строку юридической оговорки движка.

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

Сам MCP-хост не требует Enterprise. NextPDF Connect (nextpdf/server, Apache-2.0) работает с открытым движком Core и обслуживает свой каталог инструментов уровня Core: создание документов, операции с текстом и содержимым и извлечение. См. каталог инструментов. Один только Core не предоставляет проверки политик соответствия, криминалистический анализ, проверки состояния LTV, штампование готовности к ИИ, чанкинг с учётом AST, журналы аудита мутаций или инструменты batch и RAG; эти одиннадцать инструментов регистрируются только при установленном и лицензированном nextpdf/enterprise.

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

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