Pro редакция

MCP Tools — глубокий справочник

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

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

Отдельного лицензионного флага возможности нет. Код поставляется с редакцией Pro, и восемь инструментов регистрируются под уровнем pro, когда пакет Pro разрешается при загрузке вместе с nextpdf/server.

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

NextPDF Server обнаруживает уровни при загрузке, проверяя наличие класса-провайдера инструментов Pro; если он разрешается, сервер регистрирует восемь инструментов под уровнем pro. Пакет Pro не является жёсткой зависимостью сервера, поэтому инструменты Pro строго опциональны через совместную установку. Регистрация уровней независима: отсутствующий или исключённый политикой уровень никогда не блокирует остальные.
Каждый инструмент объявляет один из четырёх уровней риска (safe, caution, review, approval-required). Опциональное переопределение оператора может только повысить уровень инструмента, но никогда не понизить; сервер записывает в аудит-журнал любое выполнение на уровне caution и выше. sign_pdf имеет уровень approval-required.
Ввод PDF разрешается в фиксированном порядке: document_id из хранилища в памяти, затем source как URI data:, путь в файловой системе или необработанный base64. Отсутствующий ввод возвращает ошибку проверки, а не обрабатывает пустой документ.
sign_pdf создаёт только базовую подпись PAdES B-B — без метки времени, без долгосрочной проверки. Поддерживаемые алгоритмы и конверт переноса ключа AES-GCM описаны ниже; расшифровка терпит отказ закрыто, и инструмент никогда не использует шифротекст как ключевой материал.
Полные сведения об обнаружении, риске, разрешении источника, по каждому инструменту и о подписании см. в разделах ниже. Эта страница описывает только внешне наблюдаемое поведение и опубликованный контракт инструментов.

Область применения

Эта страница — справочник для операторов и интеграторов по восьми инструментам Pro MCP. Она охватывает модель обнаружения, семантику риска/HITL, которую применяет сервер, правила разрешения источника, конверт переноса ключа для подписания и поведение при отказе по каждому инструменту. Она описывает только внешне наблюдаемое поведение и опубликованный контракт инструментов. Каталог для пользователей см. на публичной странице MCP.

Модель обнаружения и регистрации

NextPDF Server обнаруживает провайдеры уровней при загрузке. Он определяет уровень Pro, проверяя наличие класса-провайдера инструментов Pro; если класс разрешается, сервер инстанцирует провайдер и регистрирует каждый возвращаемый им инструмент под уровнем pro. Пакет Pro намеренно не является жёсткой зависимостью сервера — это сохраняет возможность установки открытого сервера без проприетарного пакета и делает инструменты Pro строго опциональными через совместную установку.

Сервер изолирует регистрацию по уровням. Если пакет Pro отсутствует, инструменты Core всё равно регистрируются; присутствующий провайдер уровня не блокирует другие уровни. Регистрация инструментов также подчиняется списку разрешённого политики безопасности сервера: инструмент, исключённый политикой, молча не регистрируется и не учитывается в сводке уровня. Сервер предоставляет число по каждому уровню (core / pro / enterprise) для диагностики и логирования.

Провайдер возвращает восемь инструментов в фиксированном порядке: извлечение текста, сегментация, сравнение, маскирование PII, заполнение формы, обратное чтение формы, анализ доступности, подписание. Порядок стабилен, но вызывающие стороны не должны на него полагаться — разрешайте инструменты по их имени в протоколе MCP.

Модель риска и семантика HITL

Каждый инструмент объявляет один из четырёх уровней риска. Сервер использует объявленный уровень для применения участия человека в цикле (human-in-the-loop):

Safe — только чтение, без побочных эффектов. Выполняется автоматически.
Caution — создаёт или изменяет состояние в памяти. Выполняется автоматически с записью в аудит-журнал.
Review — производит вывод, который можно использовать не по назначению. Выполняется автоматически, но инструкции навыка агента помечают его, чтобы агент предупредил пользователя.
Approval-required — разрушающий, юридически или конфиденциально критичный. Сервер требует явного подтверждения человеком перед выполнением.

Классификации инструментов Pro: пять инструментов извлечения/анализа (extract_text, segment_document, compare_pdfs, extract_form_data, check_accessibility) — safe; redact_pii и fill_form — review; sign_pdf — approval-required.

Уровень риска происходит ровно из двух источников: собственного объявления инструмента и опционального переопределения оператора во время выполнения. Переопределение может только повысить уровень риска инструмента (ужесточить применение); понизить его оно не может никогда. Сервер записывает в аудит-журнал любое выполнение на уровне caution и выше. Модель риска несёт версию; сервер сообщает эту версию в своём ответе на инициализацию, чтобы клиенты могли обнаружить несовместимое изменение.

Порядок разрешения источника

Каждый инструмент, принимающий PDF, принимает его через одну из трёх форм ввода, разрешаемых в этом порядке:

document_id — сервер извлекает байты из своего хранилища документов в памяти. Неизвестный id терпит отказ с явной ошибкой, указывающей вызывающей стороне сначала создать документ.
source как URI data: — инструмент декодирует тело base64 после запятой.
source как путь в файловой системе — инструмент читает с диска, когда путь разрешается в файл.
source как необработанная строка base64 — инструмент принимает и декодирует только достаточно длинный ввод в форме base64.

compare_pdfs применяет то же разрешение независимо к source_a и source_b и дополнительно принимает значение document_id в любом из слотов источника. Если не указаны ни document_id, ни source, инструмент возвращает ошибку проверки, а не обрабатывает пустой документ.

Справочник по каждому инструменту

Инструмент	Риск	Входы	Поля результата	Поведенческая граница
`extract_text`	safe	PDF; опционально `page_start` / `page_end` с индексом от 1	текст, общее число страниц	Только текстовый слой; диапазоны ограничиваются реальным числом страниц; без OCR
`segment_document`	safe	PDF	число сегментов, список сегментов	Сегменты, выведенные из макета; не дерево структуры тегированного PDF
`compare_pdfs`	safe	два PDF	флаг идентичности, общее число изменений, число страниц по документам, области (тип, текст, индекс страницы, индекс строки, опционально текст соответствующей стороны)	Сравнение текстового содержимого; не визуальное и не двоичное
`redact_pii`	review	PDF; опционально `types` (`email`, `phone`, `ssn`, `credit_card`)	флаг наличия PII, число обнаруженных, маскированный текст, просканированные типы	Обнаружение/маскирование в текстовом слое; не визуальная редакция; на основе шаблонов, не исчерпывающее
`fill_form`	review	карта `fields`; опционально `pdf_filename`	документ XFDF, число полей	Производит XFDF (ISO 19444-1); не записывает значения в PDF
`extract_form_data`	safe	PDF	число полей, карта полей, явная пометка при отсутствии	Читает только встроенный XFDF
`check_accessibility`	safe	PDF	структурный балл (0–100), проблемы, сводка по сегментам	Структурная эвристика со ссылками на WCAG; не вердикт о соответствии
`sign_pdf`	approval-required	PDF; сертификат PEM + ключ PKCS#8; опционально алгоритм, имя подписавшего, причина, конверт переноса	подписанный PDF, число подписей, флаг завершения, алгоритм, OID, дайджест	Только базовый PAdES B-B; без метки времени, без LTV

Подписание: алгоритмы и перенос ключа

sign_pdf создаёт базовую подпись PAdES B-B. Поддерживаемые алгоритмы, принимаемые как в написании с подчёркиванием, так и через дефис:

RSA с SHA-256 (по умолчанию).
RSA с SHA-3 256 / 384 / 512 — требует сборки OpenSSL с поддержкой SHA-3.
Ed25519 — требует расширения libsodium; ключ должен быть PKCS#8 PEM, оборачивающим закрытый ключ Ed25519.

Инструмент отклоняет неподдерживаемые идентификаторы и возвращает список принимаемых значений.

Опциональный конверт шифрования переноса позволяет вызывающей стороне туннелировать закрытый ключ через транспорт, который не является сквозно конфиденциальным. Конверт — только AES-GCM:

Симметричный ключ: 16, 24 или 32 байта (AES-128/192/256), в кодировке base64.
Nonce: ровно 12 байт, в кодировке base64.
Опциональные дополнительные аутентифицируемые данные, в кодировке base64.
Полезная нагрузка private_key — это шифротекст base64 с завершающим 16-байтовым тегом аутентификации GCM.

Расшифровка терпит отказ закрыто: несовпадение тега аутентификации или некорректная полезная нагрузка возвращает ошибку расшифровки, и инструмент никогда не использует шифротекст как ключевой материал. Инструмент отклоняет неверные размеры ключа или nonce до любой криптографической работы.

Граничные случаи и режим FIPS

extract_text: инструмент ограничивает конец диапазона страниц, превышающий документ, а не отклоняет его, и нормализует начало ниже первой страницы к первой странице.
compare_pdfs: отсутствующий source_a или source_b возвращает ошибку проверки; идентичные документы возвращают явный идентичный результат с нулём изменений.
extract_form_data: PDF без встроенного потока XFDF возвращают результат с нулём полей и пояснительной пометкой, а не ошибку.
redact_pii: нераспознанная запись в types игнорируется; полностью нераспознанный список даёт пустое сканирование, а не отказ.
sign_pdf: отсутствующий сертификат или закрытый ключ терпит отказ до любой работы по подписанию; инструмент проверяет требования алгоритма (поддержка SHA-3 в OpenSSL, libsodium для Ed25519) во время подписания и сообщает о них как о явных ошибках.
Режим FIPS: доступность алгоритма следует сборке OpenSSL/libsodium на хосте. В сборке с ограничениями FIPS неодобренные алгоритмы терпят отказ на криптографической границе с явной ошибкой, а не молча понижаются. Слой MCP не добавляет и не ослабляет криптографическую политику — он сообщает решение криптографического провайдера хоста.

Заметки по эксплуатационному руководству

Держите sign_pdf на уровне approval-required. Убедитесь, что нет переопределения оператора, которое непреднамеренно повышает риск на безопасных инструментах — переопределения только ужесточают, поэтому случайное переопределение ухудшает доступность, а не безопасность.
Хранение аудита: каждое выполнение на уровне review и выше записывается сервером в аудит-журнал. Рассчитайте срок хранения журналов на объём вызовов redact_pii, fill_form и sign_pdf.
Выбор транспорта: при работе по транспорту, который не является сквозно конфиденциальным, требуйте конверт переноса ключа AES-GCM для sign_pdf и обращайтесь с материалом закрытого ключа как с секретом в политике логирования вызовов инструментов вашего агента.
Числа по уровням: используйте число сервера по каждому уровню, чтобы при развёртывании утверждать, что уровень Pro зарегистрировал восемь инструментов; число ноль указывает, что пакет Pro не разрешился.

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

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

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

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