Integração com o NextPDF Connect

Visão geral

Integre o NextPDF Connect executando-o como servidor. Você não conecta uma biblioteca a uma aplicação hospedeira. Escolha um transporte e, em seguida, configure a autenticação para cada transporte em rede. As ferramentas do engine permanecem por trás do portão de confirmação.

Instalação

composer require nextpdf/server

A restrição do Composer é nextpdf/core: ^3.0 com php: >=8.4 <9.0. Para configurar opcionalmente ext-redis e nextpdf/premium, consulte /connect/install/.

Visão conceitual

O pacote é executado como um serviço autônomo. Você não registra um service provider, bundle ou módulo de container em um framework hospedeiro. O ponto de integração é o processo que você executa. Cada transporte tem seu próprio ponto de entrada e é inicializado de forma independente. Consulte /connect/boot-and-discovery/.

Superfície da API

Ponto de entrada	Transporte	Perfil
bin/nextpdf-mcp	MCP sobre stdio	(nenhum — subprocesso direto)
bin/nextpdf-server	REST sobre RoadRunner HTTP	.rr.yaml
bin/nextpdf-grpc	gRPC sobre RoadRunner gRPC	.rr.grpc.yaml
ambos os transportes em rede	REST + gRPC	.rr.full.yaml

Inicialização e descoberta automática

O registro sempre descobre o tier core. Em seguida, adiciona os providers Pro e Enterprise quando as respectivas classes são resolvidas, seguidos dos providers incluídos de abstract syntax tree (AST) e de mutação, conforme os controles de ambiente. A allowlist de segurança enabled_tools filtra todos eles, de modo que o catálogo exposto corresponda a este deployment. Consulte /connect/tool-catalog/ e /connect/boot-and-discovery/.

Bindings de container

Nenhum. Cada factory de servidor constrói explicitamente o próprio grafo de objetos. Os pontos de injeção existem para dar suporte a testes, não para conectar aplicações.

Publicação de configuração

O servidor MCP aceita um arquivo YAML opcional (--config=PATH, seção nextpdf_mcp) e sobrescritas de ambiente NEXTPDF_MCP_*. Os servidores REST e gRPC leem as variáveis de ambiente NEXTPDF_*. Para obter mais detalhes, consulte /connect/configuration/.

Disponibilidade de transporte (MCP / REST / gRPC)

Os três transportes usam o mesmo registro:

• MCP — subprocesso local, JSON-RPC 2.0 sobre stdio, sem chave de API, revisão MCP 2025-06-18. Consulte /transports/mcp/.
• REST — pool de workers HTTP do RoadRunner, contrato OpenAPI 3.1, chave de API bearer, rotas controladas por tier. Consulte /transports/rest/.
• gRPC — pool de workers gRPC do RoadRunner, serviço Protobuf nextpdf.connect.v1, RPCs com streaming do servidor, autenticação bearer nos metadados, TLS mútuo no perfil combinado. Consulte /transports/grpc/.

Um transporte está “disponível” quando o ponto de entrada ou o perfil RoadRunner correspondente está em execução. Os transportes não iniciam uns aos outros automaticamente.

Tier de risco HITL

Cada ferramenta declara um de quatro níveis de risco: safe, caution, review, approval_required. As ferramentas classificadas como approval_required não são executadas na primeira chamada. O portão de confirmação emite um token de desafio de uso único que um humano deve autorizar. Uma sobrescrita de configuração só pode elevar o risco de uma ferramenta; nunca rebaixar uma ferramenta approval_required. O modelo se aplica da mesma forma em qualquer transporte que acione ferramentas. Consulte /connect/hitl-risk-tiers/.

Envelope JSON do portão de confirmação

A verificação do portão retorna um dos dois formatos JSON. Permitido:

{ "allowed": true }

Desafio:

{
  "allowed": false,
  "challenge": "<human-readable text naming the operation, its description, an overwrite warning when applicable, and the re-invocation instruction>",
  "token": "confirm_<nonce>"
}

O token vincula o nome da ferramenta, um nonce aleatório e um TTL de 300 segundos, mas não os argumentos. Para prosseguir, o chamador invoca a mesma ferramenta novamente com um argumento _confirmation_token definido como o token emitido. O desafio é um texto instrucional simples acompanhado do token; não é um envelope assinado criptograficamente. Consulte /connect/hitl-risk-tiers/.

Teste de fumaça do serviço

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

Esse comando inicializa o registro e a detecção de tier e, em seguida, imprime as ferramentas expostas sem servir tráfego. Use-o para confirmar que a integração está conectada e para verificar qual catálogo esta instalação produz.

Casos de borda e armadilhas

• Sem hooks de framework. Não procure um service provider ou bundle. O processo em execução é a integração.
• Um tier ausente não é um erro. Uma instalação somente core inicializa e serve o respectivo catálogo core.
• Transportes em rede exigem uma chave. Apenas /healthz e /readyz (REST) e os RPCs de saúde (gRPC) são anônimos.

Desempenho

O custo de inicialização corresponde à varredura do registro e à detecção de tier, uma vez por processo. O custo por requisição vem da operação do engine. Dimensione os pools de workers do RoadRunner com base na latência de renderização observada. Consulte /connect/production-usage/.

Notas de segurança

Os transportes em rede fazem autenticação com uma chave bearer npk_live_ validada em tempo constante; o portão impõe confirmação humana para operações destrutivas, independentemente do transporte. Faça a terminação de TLS antes do REST e use TLS mútuo para gRPC em redes não confiáveis. Consulte /connect/security-and-operations/.

Conformidade

As citações de protocolo e segurança estão fixadas em /transports/mcp/, /transports/rest/, /transports/grpc/ e /connect/security-and-operations/.

Contexto comercial

Instale o nextpdf/premium junto com o servidor para registrar as ferramentas Pro e Enterprise adicionais no mesmo servidor em execução. Nenhum processo separado está envolvido.

Veja também

• /connect/overview/ — a arquitetura
• /connect/quickstart/ — a primeira troca executável
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — referência por transporte
• /connect/hitl-risk-tiers/ — o portão de confirmação em detalhes
• /connect/tool-catalog/ — o catálogo dependente do runtime
• /connect/security-and-operations/ — autenticação e modelo de ameaças