Enterprise edição

Ferramentas MCP

Visão geral

O NextPDF Enterprise adiciona onze ferramentas MCP ao servidor NextPDF Connect. Elas dão a assistentes de IA e frameworks de agentes acesso direto e tipado ao engine Enterprise: verificações de política de conformidade, forense de PDF, verificações de saúde de LTV, carimbo de prontidão para IA, chunking com reconhecimento de AST e ingestão e busca RAG. Cada ferramenta declara seu próprio nível de risco e postura somente leitura, para que seu host MCP possa restringir, registrar e auditar a atividade dos agentes com confiança. Falhas nunca aparecem como exceções; os agentes sempre recebem um resultado estruturado e parseável.

Disponibilidade e licenciamento

Este recurso vem no NextPDF Enterprise (nextpdf/enterprise) e é ativado com um envelope de licença de nível Enterprise. Uma implantação sem essa titularidade não carrega as classes do recurso. Compare edições e obtenha uma licença.

Instalação

composer require nextpdf/enterprise:^3

O host MCP em si é o NextPDF Connect, fornecido no pacote nextpdf/server; consulte Instalação do Connect. Quando ambos os pacotes estão presentes, o registro de ferramentas do servidor descobre NextPDF\Enterprise\McpToolProvider automaticamente e registra as onze ferramentas Enterprise. Nenhum código de conexão é necessário. Se nextpdf/server estiver ausente, o arquivo do provider retorna cedo e nada é carregado.

As ferramentas de batch e RAG requerem, adicionalmente, o sidecar Spectrum. Configure-o por meio de variáveis de ambiente lidas por NextPDF\Enterprise\Mcp\SpectrumClientFactory: SPECTRUM_URL (padrão http://127.0.0.1:7800), SPECTRUM_TIMEOUT (padrão 30.0 segundos), SPECTRUM_AUTH_TOKEN e SPECTRUM_APP_SECRET.

Visão conceitual

O Model Context Protocol (MCP) é um protocolo aberto que permite que assistentes de IA e frameworks de agentes chamem ferramentas tipadas expostas por um servidor. Em vez de colar bytes de PDF em um prompt e torcer, um agente chama uma ferramenta nomeada com um payload validado por JSON-schema e recebe um resultado determinístico e estruturado. O NextPDF Connect é esse servidor para PDFs; o pacote Enterprise estende seu catálogo com as ferramentas a seguir. Cada ferramenta é um wrapper fino sobre as mesmas APIs Enterprise que seu código PHP chama diretamente, de modo que uma verificação executada por agente e uma verificação executada por código produzem o mesmo veredito.

Catálogo de ferramentas

Ferramenta MCP	Classe	O que faz	Risco	Somente leitura
`compliance_check`	`ComplianceCheckTool`	Valida um PDF contra uma política nomeada: `pdfa4`, `pdfa4e`, `pdfa4f`, `pades-baseline`, `ltv-health`, `eidas-qualified`, `zugferd`, `fda-part11` e quatro variantes `sec-17a4`.	Review	sim
`batch_compliance_check`	`BatchComplianceCheckTool`	Verifica muitos PDFs contra políticas `pdfa`, `pades` ou `zugferd` em um único batch do sidecar Spectrum.	Safe	sim
`forensic_analyze`	`ForensicAnalyzeTool`	Relata histórico de revisões, atualizações incrementais e eventos de modificação para detecção de adulteração.	Safe	sim
`batch_forensic_analyze`	`BatchForensicAnalyzeTool`	Executa análise forense sobre muitos PDFs em um único batch do sidecar.	Safe	sim
`ltv_health_check`	`LtvHealthCheckTool`	Verifica em um PDF assinado o material de validação de longo prazo: dicionário DSS, respostas OCSP, entradas CRL, entradas VRI e stores de certificados.	Safe	sim
`ai_ready_certify`	`AiReadyCertifyTool`	Veredito somente leitura, definido pelo produto, de prontidão para IA sobre quatro critérios: integridade forense, presença de assinatura, validade de LTV, sem criptografia.	Review	sim
`certify_ai_ready`	`CertifyAiReadyTool`	Veredito de prontidão definido pelo produto sobre três critérios (os quatro da ferramenta somente leitura menos a integridade forense — por design, já que esta ferramenta reescreve o arquivo que carimba) e anexa um carimbo de proveniência XMP; retorna o PDF carimbado como base64.	Review	não
`ast_aware_chunk`	`AstAwareChunkTool`	Divide um PDF em chunks ancorados em citações ao longo dos limites de cabeçalho, com ID de nó, índice de página e bounding box por chunk.	Review	sim
`audit_ast_mutations`	`AuditAstMutationsTool`	Recupera a trilha de auditoria de mutações de AST de um documento pelo source hash SHA-256.	Review	sim
`embed_documents`	`EmbedDocumentsTool`	Ingere PDFs em uma coleção RAG: parse, chunk, embed, index. Modifica o estado da coleção.	Caution	não
`search_documents`	`SearchDocumentsTool`	Recuperação híbrida (palavra-chave BM25 mais semântica) sobre uma coleção ingerida, com chunks ranqueados e pontuados.	Safe	sim

As ferramentas “certify” emitem um veredito de prontidão definido pelo produto (certified, partial ou not_certified). Esse veredito é um resultado de verificação técnica, não uma certificação por qualquer órgão de acreditação.

Restrição por aprovação e postura de auditoria

Cada ferramenta declara um nível de risco a partir do modelo Connect de quatro níveis. Ferramentas Safe executam automaticamente. Ferramentas Caution executam automaticamente com uma entrada no log de auditoria. Ferramentas Review carregam um aviso para as instruções do agente chamador. Ferramentas ApprovalRequired exigem confirmação humana; nenhuma ferramenta MCP Enterprise declara atualmente esse nível, porque nenhuma é destrutiva. A configuração em tempo de execução só pode elevar o nível de risco de uma ferramenta, nunca reduzi-lo. As ferramentas também publicam anotações de comportamento MCP (readOnlyHint, idempotentHint), para que um cliente em conformidade possa aplicar sua própria restrição por cima. Consulte Níveis de risco HITL para o modelo completo.

Por que funciona assim

A decisão estrutural é que as ferramentas são wrappers finos e determinísticos com governança autodeclarada: cada ferramenta declara seu próprio nível de risco e nível como um invariante de domínio, nunca inferido do namespace ou do empacotamento. Isso mantém a decisão de restrição auditável no host sem confiar no transporte. As ferramentas não contêm inteligência de documento própria; elas delegam às mesmas APIs Enterprise que seu código chama, de modo que há exatamente um comportamento a testar e um veredito em que confiar. Erros retornam no canal de erro MCP em vez de escaparem como exceções, porque um agente não pode capturar uma exceção PHP, mas sempre pode ramificar com base em isError. Entrada que poderia tocar o sistema de arquivos é fail-closed por padrão, já que argumentos MCP são, por definição, alcançáveis por atacantes.

Contexto de design: Uma API que se recusa a adivinhar.

Superfície de API

Todas as onze ferramentas implementam o contrato NextPDF\Server\Tools\ToolInterface de nextpdf/server e compartilham a mesma superfície pública. As assinaturas abaixo são mostradas uma vez em NextPDF\Enterprise\Mcp\ComplianceCheckTool como representativas:

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

Lança ou falha com: execute() nunca lança. Ele captura Throwable internamente e retorna ToolResult::error() com isError = true. Argumentos inválidos (workspace_token ausente, entradas documents malformadas, document_id desconhecido, source inseguro) aparecem como mensagens de InvalidArgumentException nesse canal de erro.

A ferramenta de trilha de auditoria recebe seu backend de armazenamento por injeção via construtor:

public function __construct(private readonly AstAuditTrailInterface $auditTrail)

O provider que registra o catálogo:

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

getTier() retorna 'enterprise'. getTools() retorna as onze instâncias de ferramenta; audit_ast_mutations é conectada com NextPDF\Enterprise\Ast\InMemoryAstAuditTrail por padrão.

A factory de cliente do sidecar Spectrum, que também é uma factory PSR-17 de request e stream:

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

Lança ou falha com: create() lança InvalidArgumentException quando SPECTRUM_URL está malformado ou quando o endpoint configurado aponta para um endereço privado ou reservado conhecido (exceto localhost). Este é um controle em tempo de configuração, não um controle na camada de rede: ainda assim, aplique política de egress, tratamento de redirecionamentos e DNS pinning no ambiente do host. createStreamFromFile() lança NextPDF\Enterprise\Mcp\McpStreamException (uma subclasse de RuntimeException, conforme o contrato PSR-17) quando o arquivo não pode ser aberto.

Exemplo de código — Início rápido

Execute uma verificação de conformidade PDF/A-4 exatamente como um agente faria, usando o canal de URI data: em memória:

<?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;

Saída esperada para um arquivo conforme (as contagens de findings variam por documento):

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

O relatório completo e legível por máquina, incluindo severidade por finding, ID de regra, cláusula e sugestão, está disponível em $result->structured.

Exemplo de código — Produção

Faça o preflight do sidecar, aplique a postura de risco declarada e então execute uma verificação de conformidade em batch:

<?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;

Saída esperada (as contagens refletem seus documentos):

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

Casos extremos e pegadinhas

Caminhos de source no sistema de arquivos são desabilitados por padrão. Sem a variável de ambiente NEXTPDF_MCP_INPUT_DIR, um source em formato de caminho é rejeitado com um resultado de erro. Use document_id, um URI data: ou base64 bruto.
Base64 bruto é reconhecido apenas acima de 256 caracteres. Um blob base64 mais curto é tratado como caminho de arquivo e rejeitado. Envolva payloads pequenos em um URI data:application/pdf;base64,.
Valores de document_id desconhecidos falham com orientação. O texto de erro é Unknown document_id: ... Call create_pdf first. Documentos no store em memória também expiram pelo TTL do store, então um ID obsoleto falha da mesma forma.
compliance_check rejeita chaves de política desconhecidas e lista o conjunto suportado na mensagem de erro.
Ferramentas de batch e RAG precisam do sidecar. batch_compliance_check, batch_forensic_analyze, embed_documents e search_documents requerem um endpoint Spectrum acessível e um workspace_token. A factory faz cache de um cliente por processo; chame SpectrumClientFactory::reset() nos testes.
search_documents limita top_k a 1–100; valores não inteiros recorrem ao padrão do servidor de 10.
Os padrões de ast_aware_chunk são 1500 caracteres por chunk com 150 caracteres de overlap.
certify_ai_ready omite os bytes carimbados quando return_stamped_pdf é false ou o veredito é not_certified. Quando presente, o payload base64 é cerca de um terço maior que o próprio PDF.
A trilha de auditoria de AST padrão é em memória. Entradas registradas por meio da conexão padrão do provider não persistem entre processos; injete uma implementação persistente de AstAuditTrailInterface para trilhas de auditoria duráveis.

Notas de segurança

Resolução de source fail-closed. Os chamadores MCP controlam totalmente os argumentos da ferramenta, então o resolvedor os trata como hostis. Stream wrappers (phar://, php://, file:// e qualquer esquema) e null bytes são rejeitados antes de qualquer chamada ao sistema de arquivos. Path traversal é rejeitado. Caminhos de arquivo brutos funcionam apenas quando NEXTPDF_MCP_INPUT_DIR está definido, e o alvo canonicalizado por realpath deve resolver estritamente dentro desse diretório, comparado em um limite de separador para bloquear escapes por confusão de prefixo.
Guarda de SSRF no endpoint do sidecar. SpectrumClientFactory permite localhost para o modo de sidecar local e valida todo outro SPECTRUM_URL contra faixas privadas, reservadas, link-local e de metadados de nuvem, lançando InvalidArgumentException em um endereço bloqueado. Este é um controle em tempo de configuração sobre o endpoint configurado, não um controle na camada de rede — mantenha política de egress, tratamento de redirecionamentos e DNS pinning no ambiente do host.
Segredos permanecem no ambiente. O bearer token do sidecar (SPECTRUM_AUTH_TOKEN) e o segredo de assinatura HMAC (SPECTRUM_APP_SECRET) são lidos de variáveis de ambiente e nunca aparecem em payloads ou resultados de ferramentas.
Erros não reflexivos. As mensagens de rejeição de caminho são genéricas por design (Source path is not permitted.), de modo que um chamador sondando não aprende nada sobre o sistema de arquivos do host.
Overrides de risco só sobem. A configuração do operador pode elevar o nível de risco declarado de uma ferramenta, mas nunca pode reduzi-lo abaixo da própria declaração da ferramenta.

Conformidade

Suporte não é conformidade, e conformidade não é certificação. O NextPDF não possui certificação e não concede nenhuma. As ferramentas de conformidade verificam a estrutura do documento contra os perfis de política nomeados e relatam findings com referências de cláusula; o relatório compliance_check carrega adicionalmente o próprio disclaimer do engine de que se trata de uma verificação técnica de estrutura para referência, não aconselhamento jurídico nem endosso de conformidade. Os vereditos ai_ready_certify e certify_ai_ready são níveis de prontidão definidos pelo produto, não uma atestação por qualquer órgão de normas. MCP é um protocolo aberto publicado por seu steward vendedor, não uma norma de SDO; esta página documenta o comportamento de implementação do NextPDF e não faz nenhuma alegação independente de conformidade de protocolo ou de certificação.

Contrato de comportamento

Falhas de ferramenta são retornadas como resultados de erro (isError = true com uma mensagem); exceções nunca cruzam a fronteira MCP.
Resultados bem-sucedidos carregam um resumo legível por humanos de uma linha mais um payload JSON estruturado com um conjunto de campos estável e documentado por ferramenta.
Cada ferramenta reporta tier() = ToolTier::Enterprise e um RiskLevel declarado; o risco não pode ser reduzido em tempo de execução.
Ferramentas somente leitura declaram readOnlyHint: true e não modificam o document store, o PDF de origem nem qualquer coleção.
certify_ai_ready nunca altera o documento de entrada in-place; o carimbo é aplicado a uma cópia retornada.
Relatórios de conformidade e LTV incluem um timestamp de validação e contagens de findings por severidade; o payload de compliance_check inclui adicionalmente a string de disclaimer jurídico do engine.

Alternativa do Core

O host MCP em si não requer o Enterprise. O NextPDF Connect (nextpdf/server, Apache-2.0) roda com o engine Core aberto e serve seu catálogo de ferramentas de nível core: criação de documentos, operações de texto e conteúdo, e extração. Consulte o catálogo de ferramentas. O Core sozinho não fornece verificações de política de conformidade, análise forense, verificações de saúde de LTV, carimbo de prontidão para IA, chunking com reconhecimento de AST, trilhas de auditoria de mutações, nem as ferramentas de batch e RAG; essas onze ferramentas registram-se apenas com nextpdf/enterprise instalado e licenciado.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície de API pública suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de ticket estão fora de escopo.