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

Обзор

Пространство имён NextPDF\Enterprise\Mcp поставляет уровень Enterprise каталога MCP-инструментов NextPDF. Его публичная поверхность — это одиннадцать классов инструментов, одна фабрика клиентов и одно типизированное исключение. Каждый инструмент реализует контракт NextPDF\Server\Tools\ToolInterface из среды выполнения nextpdf/server и объявляет ToolTier::Enterprise. Шесть инструментов анализируют один PDF в рамках процесса. Четыре инструмента делегируют пакетные и RAG-нагрузки sidecar-компоненту Spectrum через NextPDF\Enterprise\Mcp\SpectrumClientFactory. Один инструмент читает внедрённый через конструктор журнал аудита мутаций AST вместо байтов PDF. Каждый инструмент самоописывает своё имя MCP, входные данные по JSON Schema, аннотации клиента, RiskLevel и категорию.

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

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

Публичная поверхность API

Символ	Параметры	Поведение по умолчанию	Возвращает	Выбрасывает или завершается с ошибкой	Примечания
ForensicAnalyzeTool::execute	array $arguments, InMemoryDocumentStore $store; аргументы: document_id или source	Выполняет криминалистический анализ: ревизии, инкрементальные обновления, подписи	ToolResult (JSON-отчёт)	Ошибочный ToolResult; исключения перехватываются, никогда не пробрасываются повторно	Инструмент forensic_analyze; RiskLevel::Safe; только чтение, идемпотентен; категория document; начиная с 2.0.0
BatchForensicAnalyzeTool::execute	аргументы: workspace_token, documents[] (каждый id + path)	Пакетный криминалистический анализ через sidecar Spectrum	ToolResult со status по каждому документу, счётчиками успешных и неудачных	Ошибочный ToolResult (отсутствующие аргументы, сбой sidecar)	Инструмент batch_forensic_analyze; RiskLevel::Safe; категория document; начиная с 2.1.0
ComplianceCheckTool::execute	аргументы: policy (перечисление из 12 значений), document_id или source	Оценивает PDF по одной именованной политике соответствия	ToolResult с findings, pass/fail, duration_ms и полем disclaimer	Ошибочный ToolResult; неизвестная политика возвращает ошибку со списком поддерживаемых ключей	Инструмент compliance_check; RiskLevel::Review; категория document; начиная с 2.0.0
BatchComplianceCheckTool::execute	аргументы: workspace_token, documents[], policies (pdfa, pades, zugferd; по умолчанию ["pdfa"])	Пакетные проверки соответствия через sidecar Spectrum	ToolResult со счётчиками соответствующих / несоответствующих	Ошибочный ToolResult; каждый элемент documents[] проверяется на непустые id и path	Инструмент batch_compliance_check; RiskLevel::Safe; категория document; начиная с 2.1.0
LtvHealthCheckTool::execute	аргументы: document_id или source	Выполняет политику состояния LTV над подписанным PDF	ToolResult с findings и pass/fail	Ошибочный ToolResult	Инструмент ltv_health_check; RiskLevel::Safe; категория document; начиная с 2.0.0
AiReadyCertifyTool::execute	аргументы: document_id или source	Оценка готовности к ИИ только для чтения по четырём критериям	ToolResult с certification_level (certified, partial, not_certified) и булевыми значениями по каждому критерию	Ошибочный ToolResult	Инструмент ai_ready_certify; RiskLevel::Review; только чтение; категория document; начиная с 2.0.0
CertifyAiReadyTool::execute	аргументы: document_id или source, return_stamped_pdf (по умолчанию true)	Оценивает три критерия и добавляет XMP-штамп происхождения	ToolResult; включает stamped_pdf_base64, если не отключено или не not_certified	Ошибочный ToolResult	Инструмент certify_ai_ready; RiskLevel::Review; не только чтение; категория document; начиная с 3.0.0
AstAwareChunkTool::execute	аргументы: document_id или source, max_chunk_chars (по умолчанию 1500), overlap_chars (по умолчанию 150)	Строит AST и выдаёт фрагменты с привязкой цитат и происхождением	ToolResult с chunk_count и по каждому фрагменту: ID узла, индекс страницы, bbox, тип узла	Ошибочный ToolResult	Инструмент ast_aware_chunk; RiskLevel::Review; категория extraction; начиная с 3.0.0
AuditAstMutationsTool::__construct	AstAuditTrailInterface $auditTrail	Внедряет бэкенд журнала аудита	экземпляр	—	Зависимость, внедряемая через конструктор; начиная с 3.0.0
AuditAstMutationsTool::execute	аргументы: document_source_hash (SHA-256 hex, обязательный)	Возвращает все зафиксированные события мутаций AST для этого документа	ToolResult с entries[] и count	Ошибочный ToolResult, когда аргумент отсутствует или пуст	Инструмент audit_ast_mutations; RiskLevel::Review; категория document; начиная с 3.0.0
EmbedDocumentsTool::execute	аргументы: collection_id, workspace_token, documents[] (все обязательны)	Загружает PDF в RAG-коллекцию через sidecar Spectrum	ToolResult со счётчиками успешных / всего / неудачных	Ошибочный ToolResult	Инструмент embed_documents; RiskLevel::Caution; не только чтение, не идемпотентен; категория extraction; начиная с 2.1.0
SearchDocumentsTool::execute	аргументы: collection_id, query (обязательный), top_k (по умолчанию 10, ограничен 1–100), mode (hybrid, bm25, semantic)	Гибридный поиск по загруженной коллекции	ToolResult с ранжированными фрагментами и оценками релевантности	Ошибочный ToolResult; mode вне списка разрешённых отклоняется	Инструмент search_documents; RiskLevel::Safe; категория extraction; начиная с 2.1.0
SpectrumClientFactory::create	нет (читает SPECTRUM_URL, SPECTRUM_TIMEOUT, SPECTRUM_AUTH_TOKEN, SPECTRUM_APP_SECRET)	Создаёт и кэширует один общий для процесса клиент sidecar	SpectrumClient	InvalidArgumentException, когда SPECTRUM_URL некорректен или указывает на заблокированный адрес	Конечная точка по умолчанию http://127.0.0.1:7800; тайм-аут 30.0 с; начиная с 2.1.0
SpectrumClientFactory::reset	нет	Очищает кэшированный экземпляр клиента	void	—	Предназначено для тестов
SpectrumClientFactory::createRequest	string $method, $uri (string или UriInterface)	Строит PSR-7 запрос из HTTP-классов Core	RequestInterface	—	Реализация PSR-17 RequestFactoryInterface
SpectrumClientFactory::createStream	string $content = ''	Строит PSR-7 поток в памяти	StreamInterface	—	Реализация PSR-17 StreamFactoryInterface
SpectrumClientFactory::createStreamFromFile	string $filename, string $mode = 'r'	Открывает файл и оборачивает его как поток	StreamInterface	McpStreamException, когда файл не удаётся открыть	McpStreamException расширяет RuntimeException
SpectrumClientFactory::createStreamFromResource	$resource (ресурс PHP)	Оборачивает существующий ресурс как поток	StreamInterface	—	Реализация PSR-17 StreamFactoryInterface
McpStreamException	—	Типизированный сбой получения потока	—	—	final class, расширяет RuntimeException; исходный код документирует совместимость с PSR-17 §1.5; исходный код помечает его @since 3.2.0 (присутствует в текущей dev-линии с алиасом 3.1.0)

Каждый инструмент также предоставляет методы самоописания ToolInterface: name, description, inputSchema, annotations, riskLevel, tier и category. Их значения по каждому инструменту приведены в столбце «Примечания» выше.

Сигнатуры точек входа, дословно из исходного кода:

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function __construct(private readonly AstAuditTrailInterface $auditTrail)
public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

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

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

• Каждый инструмент реализует NextPDF\Server\Tools\ToolInterface и явно объявляет ToolTier::Enterprise. Уровень никогда не выводится из пространства имён или упаковки.
• execute не выбрасывает исключений. Каждый сбой перехватывается и возвращается как ошибочный ToolResult с сообщением о сбое.
• Инструменты для одного документа получают байты PDF с фиксированным приоритетом. Сначала document_id ищется в InMemoryDocumentStore. В противном случае source интерпретируется как URI data:, затем как сырой base64 (более 256 символов), затем как путь к файлу.
• Пути source в файловой системе по умолчанию отключены. Они активируются только тогда, когда переменная окружения NEXTPDF_MCP_INPUT_DIR задаёт ограниченный входной каталог. Разрешённый реальный путь должен оставаться внутри этого каталога. Всё остальное завершается с отказом по умолчанию.
• Схемы обёрток потоков (phar://, php://, file:// и любая другая схема) и нулевые байты в пути к файлу source отклоняются до любого обращения к файловой системе. Обход каталогов и выход по символическим ссылкам не проходят проверку ограничения по реальному пути.
• Инструменты на базе sidecar (embed_documents, search_documents, batch_compliance_check, batch_forensic_analyze) получают свой клиент от SpectrumClientFactory::create. Фабрика проверяет не-localhost SPECTRUM_URL по диапазонам частных и зарезервированных адресов перед использованием. Явный localhost разрешён для режима локального sidecar.
• ai_ready_certify выводит свой уровень из четырёх критериев: криминалистическая целостность, наличие подписи, действительность LTV и отсутствие шифрования. Прохождение всех четырёх даёт certified; от одного до трёх — partial; ноль — not_certified. Криминалистическая целостность — это структурная эвристика над цепочкой ревизий, а не криптографическая проверка байтовой целостности. Проверка шифрования исследует только область trailer.
• certify_ai_ready оценивает три критерия и добавляет XMP-штамп происхождения. Штампованные байты возвращаются в кодировке base64, если только return_stamped_pdf не равно false или уровень не not_certified.
• compliance_check принимает ровно двенадцать ключей политик: pdfa4, pdfa4e, pdfa4f, pades-baseline, ltv-health, eidas-qualified, zugferd, fda-part11, sec-17a4, sec-17a4-compatible, sec-17a4-structural, sec-17a4-pre-sign. Неизвестный ключ возвращает ошибочный результат с именами поддерживаемого набора.
• audit_ast_mutations читает только внедрённый AstAuditTrailInterface. Сам он ничего не записывает.

Граничные случаи и режимы отказа

• Не указаны ни document_id, ни source: ошибочный результат с указанием вызывающей стороне предоставить один из них.
• Неизвестный document_id: ошибочный результат с именем ID и указанием на create_pdf.
• Путь source в файловой системе при неустановленном NEXTPDF_MCP_INPUT_DIR: отклоняется с сообщением, называющим поддерживаемые каналы.
• Путь source, разрешающийся за пределы настроенного входного каталога, в том числе через символическую ссылку: отклоняется. Сравнение происходит по границе разделителя каталогов, поэтому соседние каталоги с общим префиксом имени не могут пройти.
• URI data: без разделителя-запятой или с недействительной полезной нагрузкой base64: ошибочный результат.
• top_k в search_documents вне диапазона 1–100: ограничивается, а не отклоняется. Нецелочисленный top_k откатывается к настроенному значению конвейера по умолчанию.
• mode в search_documents вне hybrid, bm25, semantic: ошибочный результат из списка разрешённых конвейера.
• Элемент documents[] в batch_compliance_check без id или path либо с пустыми строками: ошибочный результат с указанием проблемного индекса. batch_forensic_analyze проверяет только форму внешнего массива; дефекты элементов проявляются на уровне пакетного слоя.
• SpectrumClientFactory::create с некорректным SPECTRUM_URL или указывающим на частный, link-local или адрес метаданных: InvalidArgumentException. Внутри execute инструмента это проявляется как ошибочный результат.
• SpectrumClientFactory::createStreamFromFile на нечитаемом пути: McpStreamException.
• Пустые переменные окружения трактуются как неустановленные и откатываются к значениям по умолчанию.

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

NextPDF не имеет сертификации и не предоставляет её. MCP-инструменты сообщают оценки на уровне возможностей; поддержка не является соответствием, а соответствие не является сертификацией. Значения certification_level, возвращаемые ai_ready_certify и certify_ai_ready, — это собственный отчётный словарь инструментов. Они не составляют аттестацию третьей стороны. Ответы compliance_check включают поле disclaimer, формируемое лежащим в основе отчётом по той же причине. Ссылки на пункты политик — например, основа политики LTV, которую исходный код продукта указывает как ISO 32000-2:2020 §12.8.4.3, — приводятся в описаниях инструментов и полях clause по каждому finding; эта страница не добавляет независимых заявлений о стандартах. Соответствует ли проверенный документ нормативному требованию — это определяется оператором и его оценщиками.

Заметки по разработке

• SpectrumClientFactory::create кэширует один клиент на процесс. Вызывайте SpectrumClientFactory::reset в настройке тестов, чтобы принудительно создать свежий клиент.
• Чтения окружения обращаются к $_ENV, затем $_SERVER, затем getenv и трактуют пустые строки как отсутствующие.
• RiskLevel управляет обработкой на стороне хоста в среде выполнения сервера: Safe выполняется автоматически, Caution и выше журналируются в аудите, а ApprovalRequired требует подтверждения человеком. Ни один MCP-инструмент Enterprise не объявляет ApprovalRequired. Переопределения оператора могут повысить объявленный уровень, но никогда не понизить его.
• Значения annotations (readOnlyHint, idempotentHint) — это подсказки клиента MCP, а не принуждение. Ограничение и валидация происходят на стороне сервера независимо от подсказок.
• Инструменты сообщают значения category document или extraction для фильтрации в tools/list.
• AuditAstMutationsTool — единственный инструмент, требующий внедрения через конструктор; регистрируйте его с конкретной реализацией AstAuditTrailInterface.

См. также

• MCP (страница возможности)
• Accelerator — глубокий справочник — поверхность клиента sidecar Spectrum.
• Forensics — глубокий справочник — анализатор за forensic_analyze.
• Compliance — глубокий справочник — политики за compliance_check.
• AST — глубокий справочник — разбиение и журнал аудита мутаций.
• Validation — глубокий справочник

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

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