Pro edição

Ferramentas MCP — Referência Profunda

Disponibilidade e licenciamento

Este recurso é distribuído no NextPDF Pro (nextpdf/pro) e é ativado com um envelope de licença de nível Pro. Uma implantação sem esse direito não carrega as classes do recurso. Compare edições e obtenha uma licença.

Não há sinalizador de licença por recurso. O código é distribuído com a edição Pro, e as oito ferramentas se registram sob o nível pro quando o pacote Pro é resolvido na inicialização ao lado de nextpdf/server.

Contrato de comportamento

O NextPDF Server descobre os níveis na inicialização, sondando a classe provedora de ferramentas do Pro; se ela for resolvida, o servidor registra as oito ferramentas sob o nível pro. O pacote Pro não é uma dependência rígida do servidor, de modo que as ferramentas do Pro são estritamente opcionais por coinstalação. O registro de níveis é independente: um nível ausente ou excluído por política nunca bloqueia os demais.
Cada ferramenta declara um de quatro níveis de risco (safe, caution, review, approval-required). Uma substituição opcional do operador só pode elevar o nível de uma ferramenta, nunca reduzi-lo; o servidor registra em log de auditoria qualquer execução em caution ou acima. sign_pdf é approval-required.
A entrada de PDF é resolvida em uma ordem fixa: document_id do repositório em memória, depois source como um URI data:, caminho do sistema de arquivos ou base64 bruto. Uma entrada ausente retorna um erro de validação em vez de processar um documento vazio.
sign_pdf produz apenas uma assinatura baseline PAdES B-B — sem carimbo de tempo, sem validação de longo prazo. Os algoritmos suportados e o envelope de transporte de chave AES-GCM são detalhados a seguir; a descriptografia falha de forma fechada e a ferramenta nunca usa o texto cifrado como material de chave.
Veja as seções abaixo para o detalhe completo de descoberta, risco, resolução de origem, por ferramenta e de assinatura. Esta página descreve apenas o comportamento observável externamente e o contrato de ferramenta publicado.

Escopo

Esta página é a referência de operador e integrador para as oito ferramentas MCP do Pro. Ela cobre o modelo de descoberta, a semântica de risco/HITL que o servidor aplica, as regras de resolução de origem, o envelope de transporte de chave de assinatura e o comportamento de falha de cada ferramenta. Ela descreve apenas o comportamento observável externamente e o contrato de ferramenta publicado. Para o catálogo voltado ao usuário, consulte a página pública de MCP.

Modelo de descoberta e registro

O NextPDF Server descobre os provedores de nível na inicialização. Ele detecta o nível Pro sondando a classe provedora de ferramentas do Pro; se a classe for resolvida, o servidor instancia o provedor e registra cada ferramenta que ele retorna sob o nível pro. O pacote Pro intencionalmente não é uma dependência rígida do servidor — isto mantém o servidor open-source instalável sem o pacote proprietário e torna as ferramentas do Pro estritamente opcionais por coinstalação.

O servidor isola o registro por nível. Se o pacote Pro estiver ausente, as ferramentas do Core ainda se registram; um provedor de nível presente não bloqueia outros níveis. O registro de ferramentas também está sujeito à lista de permissão da política de segurança do servidor: uma ferramenta excluída por política simplesmente não é registrada e não é contabilizada no resumo do nível. O servidor expõe uma contagem por nível (core / pro / enterprise) para diagnóstico e logging.

O provedor retorna as oito ferramentas em uma ordem fixa: extração de texto, segmentação, comparação, mascaramento de PII, preenchimento de formulário, releitura de formulário, análise de acessibilidade, assinatura. A ordem é estável, mas os chamadores não devem depender dela — resolva as ferramentas pelo nome de protocolo MCP delas.

Modelo de risco e semântica de HITL

Cada ferramenta declara um de quatro níveis de risco. O servidor usa o nível declarado para a aplicação de human-in-the-loop:

Safe — somente leitura, sem efeitos colaterais. Executa automaticamente.
Caution — cria ou modifica estado em memória. Executa automaticamente com uma entrada de log de auditoria.
Review — produz saída que poderia ser mal utilizada. Executa automaticamente, mas as instruções da skill do agente a sinalizam, de modo que o agente avisa o usuário.
Approval-required — destrutiva, jurídica ou crítica para a privacidade. O servidor exige confirmação humana explícita antes da execução.

Classificações das ferramentas do Pro: as cinco ferramentas de extração/análise (extract_text, segment_document, compare_pdfs, extract_form_data, check_accessibility) são safe; redact_pii e fill_form são review; sign_pdf é approval-required.

O nível de risco vem de exatamente duas fontes: a própria declaração da ferramenta e uma substituição opcional do operador em tempo de execução. A substituição só pode elevar o nível de risco de uma ferramenta (apertar a aplicação); ela nunca pode reduzi-lo. O servidor registra em log de auditoria qualquer execução em nível caution ou acima. O modelo de risco carrega uma versão; o servidor anuncia essa versão em sua resposta de inicialização, de modo que os clientes possam detectar uma mudança incompatível.

Ordem de resolução de origem

Toda ferramenta que recebe um PDF o aceita por meio de uma de três formas de entrada, resolvidas nesta ordem:

document_id — o servidor recupera os bytes do seu repositório de documentos em memória. Um id desconhecido falha com um erro explícito que direciona o chamador a criar o documento primeiro.
source como um URI data: — a ferramenta decodifica o corpo base64 após a vírgula.
source como um caminho do sistema de arquivos — a ferramenta lê do disco quando o caminho é resolvido para um arquivo.
source como uma string base64 bruta — a ferramenta aceita e decodifica apenas entradas suficientemente longas e com formato base64.

compare_pdfs aplica a mesma resolução de forma independente a source_a e source_b e, além disso, aceita um valor document_id em qualquer um dos campos de origem. Se nem um document_id nem um source forem fornecidos, a ferramenta retorna um erro de validação em vez de processar um documento vazio.

Referência por ferramenta

Ferramenta	Risco	Entradas	Campos de resultado	Limite comportamental
`extract_text`	safe	PDF; `page_start` / `page_end` opcionais, indexados a partir de 1	texto, contagem total de páginas	Apenas camada de texto; intervalos limitados à contagem real de páginas; sem OCR
`segment_document`	safe	PDF	contagem de segmentos, lista de segmentos	Segmentos derivados do layout; não é uma árvore de estrutura de PDF marcado
`compare_pdfs`	safe	dois PDFs	sinalizador idêntico, total de mudanças, contagens de páginas por documento, regiões (tipo, texto, índice de página, índice de linha, texto da contraparte opcional)	Diff de conteúdo textual; não visual nem binário
`redact_pii`	review	PDF; `types` opcional (`email`, `phone`, `ssn`, `credit_card`)	sinalizador de presença de PII, contagem detectada, texto mascarado, tipos varridos	Detecção/mascaramento na camada de texto; não é redação visual; baseado em padrões, não exaustivo
`fill_form`	review	mapa de `fields`; `pdf_filename` opcional	documento XFDF, contagem de campos	Produz XFDF (ISO 19444-1); não escreve valores em um PDF
`extract_form_data`	safe	PDF	contagem de campos, mapa de campos, nota explícita quando não há nenhum	Lê apenas XFDF incorporado
`check_accessibility`	safe	PDF	pontuação estrutural (0–100), problemas, resumo de segmentos	Heurística estrutural com referências WCAG; não é um veredito de conformidade
`sign_pdf`	approval-required	PDF; certificado PEM + chave PKCS#8; algoritmo, nome do signatário, motivo e envelope de transporte opcionais	PDF assinado, contagem de assinaturas, sinalizador de conclusão, algoritmo, OID, digest	Apenas baseline PAdES B-B; sem carimbo de tempo, sem LTV

Assinatura: algoritmos e transporte de chave

sign_pdf produz uma assinatura baseline PAdES B-B. Algoritmos suportados, aceitos tanto na grafia com sublinhado quanto com hífen:

RSA com SHA-256 (padrão).
RSA com SHA-3 256 / 384 / 512 — requer um build do OpenSSL com suporte a SHA-3.
Ed25519 — requer a extensão libsodium; a chave deve ser um PEM PKCS#8 que encapsula a chave privada Ed25519.

A ferramenta rejeita identificadores não suportados e retorna a lista de valores aceitos.

O envelope opcional de criptografia de transporte permite que um chamador tunele a chave privada por um transporte que não é confidencial de ponta a ponta. O envelope é apenas AES-GCM:

Chave simétrica: 16, 24 ou 32 bytes (AES-128/192/256), codificada em base64.
Nonce: exatamente 12 bytes, codificado em base64.
Dados autenticados adicionais opcionais, codificados em base64.
O payload private_key é o texto cifrado em base64 com uma tag de autenticação GCM de 16 bytes ao final.

A descriptografia falha de forma fechada: uma incompatibilidade da tag de autenticação ou um payload malformado retorna um erro de descriptografia, e a ferramenta nunca usa o texto cifrado como material de chave. A ferramenta rejeita tamanhos errados de chave ou de nonce antes de qualquer trabalho criptográfico.

Casos extremos e modo FIPS

extract_text: a ferramenta limita um final de intervalo de páginas que exceda o documento, em vez de rejeitá-lo, e normaliza um início abaixo da primeira página para a primeira página.
compare_pdfs: um source_a ou source_b ausente retorna um erro de validação; documentos idênticos retornam um resultado idêntico explícito, com zero mudanças.
extract_form_data: PDFs sem um fluxo XFDF incorporado retornam um resultado de zero campos com uma nota explicativa, não um erro.
redact_pii: uma entrada não reconhecida em types é ignorada; uma lista totalmente não reconhecida produz uma varredura vazia em vez de uma falha.
sign_pdf: um certificado ou chave privada ausente falha antes de qualquer trabalho de assinatura; a ferramenta verifica os requisitos de algoritmo (suporte a SHA-3 no OpenSSL, libsodium para Ed25519) no momento da assinatura e os expõe como erros explícitos.
Modo FIPS: a disponibilidade de algoritmos segue o build de OpenSSL/libsodium do host. Em um build com restrições de FIPS, algoritmos não aprovados falham no limite criptográfico com um erro explícito, em vez de fazer um downgrade silencioso. A camada MCP não adiciona nem flexibiliza a política criptográfica — ela expõe a decisão do provedor criptográfico do host.

Notas de runbook do operador

Mantenha sign_pdf como approval-required. Confirme que não há nenhuma substituição do operador que eleve o risco das ferramentas safe involuntariamente — as substituições só apertam, de modo que uma substituição acidental degrada a disponibilidade, não a segurança.
Retenção de auditoria: toda execução em nível review ou acima é registrada em log de auditoria pelo servidor. Dimensione a retenção dos seus logs para o volume de chamadas de redact_pii, fill_form e sign_pdf.
Escolha de transporte: ao executar sobre um transporte que não é confidencial de ponta a ponta, exija o envelope de transporte de chave AES-GCM para sign_pdf e trate o material de chave privada como um segredo na política de logging de chamadas de ferramenta do seu agente.
Contagens de nível: use a contagem por nível do servidor para afirmar, no momento da implantação, que o nível Pro registrou oito ferramentas; uma contagem de zero indica que o pacote Pro não foi resolvido.

Limite de edição

O nível Pro contribui exatamente com oito ferramentas MCP. A edição Enterprise entrega um nível MCP separado com suas próprias ferramentas — conformidade, forense, saúde de validação de longo prazo, certificação AI-ready e busca/embedding de documentos. As entradas, saídas e detalhes internos das ferramentas do Enterprise estão fora do escopo aqui e são documentados com a edição Enterprise. O servidor descobre os níveis de forma independente; um nível ausente nunca desativa outro.

Limite de publicação

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