Pro edição

Ferramentas MCP

Visão geral

O NextPDF Pro acrescenta oito ferramentas Model Context Protocol (MCP) que permitem a um agente de IA executar operações avançadas de PDF por meio do NextPDF Server. As ferramentas aparecem automaticamente quando tanto o nextpdf/pro quanto o nextpdf/server estão instalados — nenhuma etapa de registro separada é necessária.

Disponibilidade e licenciamento

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

A superfície MCP base — criação de documentos, texto, tabelas, diagnósticos — vem com o NextPDF Server open-source e não precisa de licença. As oito ferramentas desta página exigem uma licença Pro e só se registram quando o pacote nextpdf/pro é resolvido na inicialização. O tier de ferramentas pro controla o conjunto inteiro: cada ferramenta declara seu tier explicitamente, e não há sinalizador por ferramenta — instalar o nextpdf/pro ao lado do nextpdf/server habilita o conjunto.

Contrato de comportamento

As oito ferramentas MCP do Pro registram-se automaticamente quando tanto o nextpdf/pro quanto o nextpdf/server são resolvidos na inicialização, sob o tier pro, por meio do fluxo MCP padrão tools/list e tools/call. Não há sinalizador por ferramenta nem alteração de código na aplicação consumidora.
Cada ferramenta aceita um PDF por meio de um document_id de uma chamada create_pdf anterior, uma source inline (caminho de arquivo, base64 ou URI data:) ou — para compare_pdfs — duas dessas fontes. As ferramentas retornam JSON estruturado.
Toda ferramenta declara uma classe de risco HITL que o servidor impõe: safe (execução automática, somente leitura), review (saída que poderia ser mal utilizada) e approval-required. sign_pdf é approval-required e fica retida até que um humano a confirme. Um operador só pode tornar a classe de risco de uma ferramenta mais restrita, nunca relaxá-la.
sign_pdf produz apenas uma assinatura PAdES B-B (baseline) — sem carimbo de tempo confiável e sem material de validação de longo prazo. Perfis de longo prazo (B-LT / B-LTA), custódia de chaves em hardware e assinatura com trilha de auditoria são do tier Enterprise e não são fornecidos por estas ferramentas; o B-T (uma assinatura com carimbo de tempo) está disponível no motor Core quando um provedor de carimbo de tempo estiver configurado.
redact_pii realiza detecção e mascaramento de padrões na camada de texto, não tarjamento visual; check_accessibility é uma heurística estrutural, não um veredito de conformidade PDF/UA ou WCAG. O schema autoritativo de entrada/saída é a resposta tools/list ao vivo do servidor, não esta página.

Visão conceitual

O NextPDF Server é a camada de execução MCP determinística do NextPDF. Ele descobre provedores de ferramentas na inicialização usando uma sonda de existência de classe, de modo que o pacote Pro não precisa estar listado nas dependências do servidor. Quando o pacote Pro está presente, o servidor registra suas oito ferramentas sob o tier pro e as expõe por meio do fluxo MCP padrão tools/list e tools/call sobre qualquer transporte que você tenha configurado.

Cada ferramenta do Pro aceita um PDF de uma de três fontes: um document_id retornado por uma chamada create_pdf anterior, uma source inline (caminho de arquivo, string base64 ou URI data:) ou — para a ferramenta de comparação — duas dessas fontes. As ferramentas retornam resultados JSON estruturados: texto extraído, regiões de diff, texto mascarado, árvores de segmentos, achados de acessibilidade ou um PDF assinado.

Toda ferramenta do Pro carrega uma classificação de risco que o servidor usa para a imposição human-in-the-loop (HITL). As ferramentas de análise somente leitura são classificadas como safe e executam automaticamente. As ferramentas que geram saída que um chamador poderia usar de forma indevida são classificadas como review. A ferramenta de assinatura é classificada como approval-required, então o servidor a mantém retida até que um humano a confirme. A própria ferramenta declara essa classificação; um operador só pode torná-la mais restrita em tempo de execução — nunca afrouxá-la.

A superfície de ferramentas MCP é intencionalmente separada do motor de PDF do Pro. As ferramentas são adaptadores finos: elas validam as entradas, resolvem o PDF, delegam a um componente do motor do Pro e serializam o resultado. Elas não são uma segunda API para o motor e não fazem parte da API pública PHP do Pro — o ponto de integração suportado é o protocolo MCP exposto pelo NextPDF Server.

Catálogo de ferramentas (oito ferramentas do Pro)

As oito ferramentas MCP do Pro, pelo nome do protocolo MCP. Os níveis de risco seguem o modelo HITL do servidor: safe (execução automática, somente leitura), review (gera saída que poderia ser mal utilizada; com aviso nas instruções do agente) e approval-required (precisa ser confirmada por um humano).

`extract_text`

Finalidade: Extração de texto. Extrai a camada de texto de um PDF, opcionalmente limitada a um intervalo de páginas com índice começando em 1.
Entradas: Um PDF (document_id ou source); page_start e page_end opcionais.
Saídas: O texto extraído e a contagem total de páginas.
Risco: Safe. Somente leitura e idempotente.
Limite: Extrai a camada de texto existente. Não realiza OCR em páginas digitalizadas ou somente de imagem.

`segment_document`

Finalidade: Segmentação estrutural. Divide um PDF em seções lógicas — título, cabeçalhos, corpo, tabelas, figuras.
Entradas: Um PDF (document_id ou source).
Saídas: Uma contagem de segmentos e uma lista estruturada de segmentos.
Risco: Safe. Somente leitura e idempotente.
Limite: Segmentação estrutural baseada em análise de layout; não é um sumário semântico nem uma árvore de estrutura de PDF marcado.

`compare_pdfs`

Finalidade: Diff estrutural. Compara dois PDFs e retorna um diff estruturado do conteúdo de texto deles.
Entradas: Dois PDFs (source_a e source_b, cada um um caminho, base64, URI data ou document_id).
Saídas: Um sinalizador de identidade, contagem total de mudanças, contagens de páginas por documento e uma lista de regiões alteradas com índices de página e de linha.
Risco: Safe. Somente leitura e idempotente.
Limite: Diff de conteúdo de texto. Não faz diff de renderização visual, fontes incorporadas ou estrutura binária.

`redact_pii`

Finalidade: Detecção e mascaramento de PII. Detecta informações de identificação pessoal na camada de texto de um PDF e retorna uma visualização mascarada do texto.
Entradas: Um PDF (document_id ou source); um filtro types opcional (email, phone, ssn, credit_card).
Saídas: Um sinalizador de presença de PII, contagem detectada, texto mascarado e a lista de tipos verificados.
Risco: Review. A saída mascarada poderia ser mal utilizada se tratada como um documento sanitizado.
Limite: Isto é detecção e mascaramento de padrões na camada de texto, não tarjamento visual. Não remove nem sobrescreve glifos no PDF renderizado, e a correspondência de padrões não garante que toda instância de dado sensível seja encontrada. Não trate sua saída como uma garantia de remoção completa de PII. Para tarjamento em nível de documento que destrói o conteúdo subjacente, use a superfície de tarjamento dedicada nas ferramentas open-source do servidor ou na edição Enterprise.

`fill_form`

Finalidade: Dados de preenchimento de AcroForm. Gera dados XFDF (ISO 19444-1) que preenchem os campos AcroForm de um PDF a partir de um mapa de nomes de campo para valores.
Entradas: Um mapa fields de nome de campo para valor de string; um pdf_filename opcional incorporado como a referência do XFDF.
Saídas: O documento XFDF gerado e a contagem de campos.
Risco: Review. Produz dados de formulário destinados a serem aplicados a um documento.
Limite: Produz XFDF em conformidade com o padrão; ela própria não grava os valores de volta em um PDF. Aplique o XFDF com qualquer leitor ou ferramenta de processamento compatível.

`extract_form_data`

Finalidade: Leitura de AcroForm. Extrai nomes e valores de campos AcroForm do XFDF incorporado em um PDF.
Entradas: Um PDF (document_id ou source).
Saídas: Uma contagem de campos e um mapa de nomes de campo para valores; uma nota explícita quando não há dados de formulário incorporados.
Risco: Safe. Somente leitura e idempotente.
Limite: Lê streams XFDF (ISO 19444-1) incorporados. Um PDF que mantém valores de formulário apenas em objetos AcroForm sem XFDF incorporado retorna um resultado vazio.

`check_accessibility`

Finalidade: Análise estrutural de acessibilidade. Analisa a acessibilidade estrutural de um PDF — cabeçalhos, parágrafos, tabelas e imagens — e relata prováveis problemas com referências WCAG.
Entradas: Um PDF (document_id ou source).
Saídas: Uma pontuação estrutural (0–100), uma lista de problemas e um resumo de segmentos.
Risco: Safe. Somente leitura e idempotente.
Limite: Isto é uma heurística estrutural, não um veredito de conformidade. O teste completo de conformidade PDF/UA e WCAG — árvore de tags, ordem de leitura, contraste de cores — requer um motor de acessibilidade dedicado. Uma pontuação alta não é uma declaração de conformidade PDF/UA.

`sign_pdf`

Finalidade: Assinatura digital PAdES B-B. Aplica uma assinatura digital PAdES B-B (baseline) a um PDF usando um certificado X.509 local e uma chave privada.
Entradas: Um PDF (document_id ou source); um certificado PEM e uma chave privada PKCS#8; um algoritmo opcional (RSA-SHA256 por padrão, RSA + SHA-3 256/384/512 ou Ed25519); nome e motivo do signatário opcionais; um envelope de transporte AES-GCM opcional ao redor do payload da chave privada.
Saídas: O PDF assinado, a contagem de assinaturas, o sinalizador de conclusão e o algoritmo, o OID e o digest usados.
Risco: Approval-required. A assinatura é uma operação juridicamente significativa e destrutiva; o servidor exige confirmação humana explícita antes de executá-la.
Limite: Esta ferramenta produz uma assinatura PAdES B-B (baseline) — ela não incorpora um carimbo de tempo confiável nem material de validação de longo prazo. Perfis de longo prazo (B-LT / B-LTA), custódia de chaves baseada em hardware e assinatura com trilha de auditoria fazem parte da edição Enterprise; o B-T (uma assinatura com carimbo de tempo) está disponível no motor Core quando um provedor de carimbo de tempo estiver configurado. Consulte a superfície de assinatura do Pro para os recursos de assinatura mais amplos do pacote Pro e a edição Enterprise para B-LT/B-LTA.

Como as ferramentas aparecem

composer require nextpdf/pro
composer require nextpdf/server

Com ambos os pacotes instalados, inicie o NextPDF Server com o transporte de sua escolha. O servidor descobre o tier Pro na inicialização e as oito ferramentas aparecem na resposta MCP tools/list sob o tier pro, ao lado das ferramentas Core open-source. Sua aplicação não precisa de alteração de código — a descoberta é executada automaticamente e um tier ausente nunca impede os demais de carregar.

O schema autoritativo de entrada e saída de cada ferramenta é o schema que o servidor publica em sua resposta tools/list. Trate essa resposta — não esta página — como o contrato: este catálogo descreve intenção e limites; o schema ao vivo descreve os nomes e tipos exatos dos campos.

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

As ferramentas do Pro são consumidas pelo protocolo MCP, não por uma API PHP do Pro. A integração no lado do host é a inicialização do NextPDF Server. Com o nextpdf/pro presente, as oito ferramentas registram-se por descoberta em tempo de execução — sem fiação por ferramenta — e o host então as serve aos agentes.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;

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

// Runtime discovery registers the Pro tier when nextpdf/pro is installed
// alongside nextpdf/server. The consuming application changes no code.
$server = McpServer::create();

// A Pro tool name resolves only when the Pro package is present.
$signTool = $server->getToolRegistry()->get('sign_pdf');

\fwrite(\STDERR, $signTool !== null
    ? "Pro MCP tools active.\n"
    : "Pro MCP tools unavailable; install nextpdf/pro.\n");

// Serve the MCP protocol over stdio (Claude Desktop, Cursor, local agents).
$server->run();

Exemplo de código — Produção

Fortaleça o caminho de inicialização. Carregue um arquivo de política explícito, recuse-se a iniciar diante de uma sobreposição de nível de risco inválida e confirme que o tier Pro apareceu antes de servir. A fiação em McpServer::create() lança InvalidArgumentException quando um bloco risk_level_overrides tenta enfraquecer uma ferramenta approval-required como sign_pdf, de modo que uma política mal configurada falha de forma segura (fail-closed) antes do loop de serviço.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;
use NextPDF\Server\Tools\ToolInterface;

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

// A downgrade of an approval-required tool's HITL gate is rejected at boot,
// never silently applied — the server refuses to start on such a policy.
try {
    $server = McpServer::create(__DIR__ . '/nextpdf-mcp.yaml');
} catch (\InvalidArgumentException $e) {
    \fwrite(\STDERR, 'Refusing to start: invalid MCP policy. ' . $e->getMessage() . "\n");
    exit(1);
}

// Confirm the Pro tier surfaced before advertising it to agents.
$signTool = $server->getToolRegistry()->get('sign_pdf');

if (!$signTool instanceof ToolInterface) {
    \fwrite(\STDERR, "nextpdf/pro is not resolving; Pro MCP tools are unavailable.\n");
    exit(1);
}

// sign_pdf is approval-required; the server holds it for human confirmation.
$risk = $signTool->riskLevel()->label();
\fwrite(\STDERR, "Pro MCP tools ready. sign_pdf risk: {$risk}.\n");

$server->run();

Orientação para produção

Gating HITL. Mantenha sign_pdf por trás de confirmação humana. O servidor impõe isso a partir do nível de risco declarado da ferramenta; não configure seu agente para contorná-lo. Um operador só pode tornar o nível de risco de uma ferramenta mais restrito, nunca relaxá-lo.
Tratamento de fontes. Prefira document_id para documentos já presentes na sessão. Para dados inline, as ferramentas aceitam base64 e URIs data:; payloads inline muito grandes são executados mais lentamente do que um documento referenciado.
Expectativas de PII. Defina explicitamente as expectativas do chamador: redact_pii é um auxílio de detecção e mascaramento, não uma garantia de sanitização. Para remoção irreversível, encaminhe para uma superfície de tarjamento dedicada.
Chaves de assinatura. Forneça as chaves por meio do envelope de criptografia de transporte quando o transporte não for confidencial de ponta a ponta. Trate o material de chave privada como um segredo na política de logging de chamadas de ferramenta do seu agente.
Logging de auditoria. As ferramentas acima do nível safe têm seu uso registrado em auditoria pelo servidor. Garanta que sua implantação retenha esses logs conforme seus requisitos de conformidade.

Casos extremos

Os intervalos de página de extract_text têm índice começando em 1 e são limitados à contagem real de páginas do documento; um final fora do intervalo não gera erro.
compare_pdfs exige ambas as fontes; passar uma retorna um erro de validação claro em vez de um diff parcial.
extract_form_data retorna um resultado preenchido e explícito de “nenhum dado de formulário incorporado” em vez de um erro para PDFs sem XFDF incorporado.
sign_pdf rejeita identificadores de algoritmo não suportados com a lista de valores suportados; Ed25519 requer a extensão libsodium e as variantes SHA-3 requerem uma build do OpenSSL com suporte a SHA-3.
check_accessibility pontua mal PDFs somente de imagem por design — ele sinaliza a ausência de uma camada de texto legível em vez de falhar.

Notas de segurança

A ferramenta de assinatura é a única approval-required; o servidor não a executará automaticamente.
O envelope AES-GCM opcional ao redor da chave privada autentica o payload; uma incompatibilidade de tag falha de forma segura (fail-closed) com um erro de descriptografia e nunca recorre ao uso do texto cifrado.
redact_pii não altera o PDF de origem; ele retorna uma representação de texto mascarada. Não é um substituto para a destruição de conteúdo.
A ferramenta valida as entradas antes de qualquer trabalho do motor; ela rejeita fontes malformadas, URIs data e payloads base64 com erros explícitos.

Conformidade

As ferramentas de formulário produzem e consomem XFDF conforme a ISO 19444-1:2019 (XML Forms Data Format).
sign_pdf produz uma assinatura PAdES baseline (B-B) alinhada com a família PAdES da ETSI EN 319 142; os perfis de longo prazo são um recurso do Enterprise, e o B-T está disponível no motor Core quando um provedor de carimbo de tempo estiver configurado.
check_accessibility relata achados com referências a critérios de sucesso WCAG (por exemplo, 1.1.1, 1.3.1, 2.4.6) como orientação heurística, não como um atestado de conformidade.

Limite de edição

O NextPDF Pro contribui com exatamente oito ferramentas MCP, todas no tier pro. A edição Enterprise fornece seu próprio conjunto separado de ferramentas MCP no tier enterprise — abrangendo verificação de conformidade, análise forense, integridade da validação de longo prazo, certificação pronta para IA e busca e embedding de documentos. Essas ferramentas, suas entradas e seus detalhes internos estão fora do escopo desta página; consulte as ferramentas MCP do Enterprise. A documentação do próprio servidor cobre as ferramentas Core (open-source) que o acompanham. O servidor descobre os três tiers de forma independente, e um tier ausente nunca desabilita os demais.

Nota sobre o limite do Enterprise

O Pro contribui com exatamente oito ferramentas MCP no tier pro. A edição Enterprise fornece um conjunto separado de ferramentas MCP no tier enterprise (verificação de conformidade, análise forense, integridade da validação de longo prazo, certificação pronta para IA, busca e embedding de documentos) e os perfis de assinatura com carimbo de tempo/de longo prazo; esses não são fornecidos pelo tier Pro. Consulte a seção Limite de edição acima para o detalhamento completo dos tiers.

Fallback / alternativa do Core

O NextPDF Server open-source dá a qualquer agente de IA um conjunto de ferramentas de PDF Core determinístico (criação de documentos, texto, tabelas, diagnósticos) sem licença. As oito ferramentas avançadas desta página são adições do Pro. Consulte /connect/tools/.

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 arquivos de runbook e prefixos de tickets estão fora do escopo.