Catálogo de ferramentas do NextPDF Connect

Visão geral

O NextPDF Connect não expõe uma quantidade fixa de ferramentas. O servidor calcula a contagem em tempo de execução com base nos pacotes instalados, na allowlist de configuração e nos gates de ambiente. Esta página documenta o conjunto core verificado e o método que determina o total.

Instalação

composer require nextpdf/server

Visão conceitual

NextPDF\Server\ToolRegistry monta o catálogo durante o boot, nesta ordem:

Tier core. Um conjunto fixo de ferramentas core é registrado incondicionalmente. Outras duas ferramentas são registradas apenas quando uma pré-condição é atendida.
Tier Pro. As ferramentas Pro são registradas quando a classe do provedor Pro é resolvida, o que ocorre quando nextpdf/premium está instalado. O servidor ignora esta etapa silenciosamente quando a classe não pode ser resolvida.
Tier Enterprise. O provedor Enterprise segue o mesmo padrão do provedor Pro.
Tiers estendidos incluídos. Os provedores das ferramentas de AST e mutação acompanham o pacote do servidor e são registrados no tier Pro. Um gate de ambiente controla cada provedor, e cada provedor degrada de forma controlada quando o suporte core subjacente está ausente.
Filtro de política de segurança. O servidor faz a interseção de cada registro com a allowlist enabled_tools. Uma allowlist não vazia descarta qualquer ferramenta que não esteja nela. A contagem do tier inclui somente as ferramentas admitidas pela política.

A resposta initialize do Model Context Protocol (MCP) informa o tool_count resultante e as contagens por tier do servidor em execução. Esse valor é a referência definitiva. Considere qualquer total fixo no texto como desatualizado.

Superfície da API

Ferramentas core verificadas e sempre disponíveis

Estas doze ferramentas são sempre registradas no tier core. O servidor lê de cada implementação de ferramenta o nível de risco e cada dica de comportamento MCP.

Nome da ferramenta	Categoria	Descrição	Risco
`create_pdf`	documento	Cria um documento PDF e retorna um `document_id`	caution
`add_text`	documento	Adiciona conteúdo de texto a um documento PDF	caution
`add_image`	documento	Adiciona uma imagem a partir de um caminho de arquivo ou de dados em base64	caution
`add_table`	documento	Adiciona uma tabela HTML a um documento PDF	caution
`set_font`	documento	Define a fonte para as operações de texto subsequentes	caution
`add_page`	documento	Adiciona uma nova página ao documento PDF	caution
`output_pdf`	documento	Finaliza o PDF como arquivo ou em base64	approval_required
`preview_layout`	documento	Retorna um resumo do layout em JSON sem renderizar	safe
`diagnostic.doctor`	diagnóstico	Executa uma verificação de integridade; diagnósticos estruturados do ambiente	safe
`diagnostic.capabilities`	diagnóstico	Lista os recursos com tier e status	safe
`diagnostic.inspect`	diagnóstico	Inspeciona um PDF e retorna metadados estruturais	safe
`diagnostic.verify`	diagnóstico	Verifica a integridade do PDF com verificações opcionais de PDF/A ou PDF/UA	caution

Ferramentas core registradas condicionalmente

Nome da ferramenta	Condição
`generate_barcode`	É registrada quando o `nextpdf/core` instalado inclui o registry core de codificadores de barcode
`parse_pdf`	É registrada somente quando `NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED` é `true` ou `1`

output_pdf é a única ferramenta core no nível de risco approval_required. A gravação de arquivo passa pelo gate human-in-the-loop; a saída em base64 não passa. Consulte /connect/hitl-risk-tiers/.

Ferramentas adicionadas apenas quando pacotes extras estão instalados

O servidor verifica as classes de provedor com class_exists():

As ferramentas Pro são registradas quando nextpdf/premium está instalado e o provedor Pro é resolvido.
As ferramentas Enterprise são registradas quando nextpdf/premium está instalado e o provedor Enterprise é resolvido. As ferramentas de privacidade (redação, de-identificação, redação por zona) encapsulam classes Enterprise. Elas são registradas no tier Enterprise somente quando essas classes são carregáveis pelo autoload.
As ferramentas de AST e mutação acompanham o servidor e são registradas no tier Pro. Os gates NEXTPDF_AST_TOOLS_ENABLED e NEXTPDF_MUTATION_TOOLS_ENABLED as controlam, e ambos os gates estão habilitados por padrão.

É o pacote Premium, e não o servidor, que define os inventários exatos de ferramentas Pro e Enterprise e os documenta junto com esse pacote. O contrato do servidor é o mecanismo de registro, não uma lista Premium fixa.

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

Liste as ferramentas que esta instalação expõe sem iniciar um servidor:

./vendor/bin/generate-skills --dry-run --list-tools

Exemplo de código — Produção

Consulte o servidor em execução para obter a contagem definitiva via MCP:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

O servidor calcula capabilities.nextpdf.tool_count e tiers no resultado de initialize para o processo em execução. Em REST, GET /api/v1/capabilities retorna uma introspecção equivalente.

Casos extremos e armadilhas

Não existe um número fixo de “33 tools” — nem qualquer total fixo. Materiais mais antigos citam um único número, mas ele não é um contrato. A contagem muda conforme os pacotes instalados, a allowlist enabled_tools e os gates de ambiente de parse_pdf, AST e mutação. Sempre leia esse valor do servidor em execução.
A allowlist subtrai, nunca adiciona. Listar uma ferramenta Pro em enabled_tools não a registra quando nextpdf/premium está ausente.
A ausência de um tier é silenciosa e esperada. Uma instalação somente open-source expõe o conjunto core e informa zero ferramentas Pro e zero ferramentas Enterprise. Esse resultado é a operação correta, não uma falha.
O tier no catálogo é um invariante declarado. Cada ferramenta declara seu próprio tier e risco no código. O registry nunca infere um tier a partir do namespace ou do pacote.

Desempenho

A varredura do registry e a detecção de tier são executadas uma única vez no boot. O performance_budget da página limita essas operações. O custo por ferramenta vem da operação subjacente do engine, não da consulta ao catálogo, que é O(1) por nome de ferramenta.

Notas de segurança

Use enabled_tools como controle de privilégio mínimo: exponha apenas as ferramentas de que uma integração precisa. O catálogo nunca inclui uma ferramenta rejeitada pela política de segurança, e o contador do tier reflete apenas as ferramentas admitidas. As ferramentas de alto risco continuam protegidas por confirmação humana, independentemente de constarem no catálogo. Consulte /connect/security-and-operations/.

Conformidade

Esta página descreve o mecanismo do registry. As citações de protocolo das superfícies tools/list e initialize estão fixadas em /transports/mcp/. O modelo de risco é especificado em /connect/hitl-risk-tiers/.

Contexto comercial

O catálogo core cobre criação, inspeção e diagnósticos. As ferramentas de assinatura, redação, conformidade e perícia aparecem somente quando nextpdf/premium está instalado junto com o servidor. Esse limite de empacotamento é aplicado no momento do composer require, nunca por meio de um prompt em tempo de execução.

Veja também

/connect/hitl-risk-tiers/ — o que a coluna de risco significa e como a aplicação funciona
/connect/boot-and-discovery/ — a sequência completa de boot e descoberta
/connect/configuration/ — enabled_tools e os gates de ambiente
/transports/mcp/ — os tools/list e initialize em formato de transmissão
/connect/overview/ — por que o catálogo depende do tempo de execução por design