Visão geral do servidor NextPDF Connect

Visão geral rápida

O NextPDF Connect é o pacote nextpdf/server, um serviço de longa duração que expõe o motor PDF 2.0 do NextPDF para agentes de IA e para clientes HTTP. Ele usa três transportes: Model Context Protocol (MCP) sobre stdio, uma API REST e gRPC. Os três transportes usam um único registro de ferramentas e um único portão de confirmação com intervenção humana (HITL).

Instalação

composer require nextpdf/server

A restrição do Composer é nextpdf/core: ^3.0 com php: >=8.4 <9.0. Para o procedimento completo, consulte /connect/install/. Essa página também aborda dois complementos opcionais: a extensão ext-redis e o pacote nextpdf/premium.

Visão geral conceitual

nextpdf/server adapta o núcleo do NextPDF, independente de framework, para uma superfície de serviço. Ele não reconstrói a geração de PDF. Em vez disso, encapsula cada capacidade do motor como uma ferramenta nomeada com seu próprio schema e, em seguida, disponibiliza esse catálogo por meio de vários protocolos de comunicação.

Três conceitos sustentam todo o design:

O registro de ferramentas. O NextPDF\Server\ToolRegistry encontra e registra as ferramentas na inicialização. Um conjunto básico acompanha o pacote e está sempre disponível. Os provedores Pro e Enterprise registram mais ferramentas, mas somente quando os pacotes correspondentes estão instalados. O número de ferramentas expostas é uma propriedade de tempo de execução da implantação, não uma constante fixa. Consulte /connect/tool-catalog/.
Os transportes. O mesmo registro é servido de três maneiras. O MCP roda sobre stdio para clientes de IA locais. O REST roda sobre um pipeline de middleware PSR-15 em um pool de workers do RoadRunner para clientes em rede. O gRPC roda em um worker gRPC do Spiral RoadRunner para clientes tipados e de streaming. Cada transporte tem seu próprio processo e seu próprio ponto de entrada. Consulte /transports/mcp/, /transports/rest/ e /transports/grpc/.
O portão de confirmação. Toda ferramenta declara um nível de risco. Uma ferramenta no nível mais alto exige uma confirmação humana explícita antes de ser executada. O portão emite um token de desafio de uso único. O agente deve repassar esse token a um humano e, em seguida, chamar a ferramenta novamente com o token. Consulte /connect/hitl-risk-tiers/.

O diagrama abaixo mostra como um único registro atende aos três transportes. Ele também mostra onde o portão de confirmação fica no caminho da requisição.

NextPDF Connect component architecture

O pacote é licenciado sob Apache-2.0, em alinhamento com o nextpdf/core. A versão implementada do protocolo MCP é a revisão 2025-06-18, versionada por data. Um documento OpenAPI 3.1 descreve a superfície REST. O pacote Protocol Buffers nextpdf.connect.v1 descreve a superfície gRPC.

Superfície da API

Os pontos de entrada públicos são as três classes de servidor. Cada uma delas tem um wrapper de interface de linha de comando (CLI):

Ponto de entrada	Classe	Transporte
`bin/nextpdf-mcp`	`NextPDF\Server\Mcp\McpServer`	MCP sobre stdio
`bin/nextpdf-server`	`NextPDF\Server\Http\HttpServer`	REST sobre RoadRunner HTTP
`bin/nextpdf-grpc`	`NextPDF\Server\Grpc\GrpcServer`	gRPC sobre RoadRunner gRPC
`bin/generate-skills`	`NextPDF\Server\Skills\SkillsDumper`	Exportação do catálogo de ferramentas

McpServer::create(), HttpServer::create() e GrpcServer::create() constroem, cada um, um servidor totalmente configurado a partir de entradas de ambiente e configuração. O registro, o armazenamento de documentos, a política de segurança e o portão de confirmação são conceitos compartilhados pelos três servidores.

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

O servidor MCP mínimo precisa de um único comando. Você não precisa escrever nenhum código PHP de cola:

./vendor/bin/nextpdf-mcp

O servidor lê requisições JSON-RPC na entrada padrão e escreve respostas na saída padrão. Para ver uma troca executável com initialize e tools/list, além da requisição REST correspondente, consulte /connect/quickstart/.

Casos de borda e armadilhas

A contagem de ferramentas não é 33, nem qualquer outro número fixo. O servidor conta as ferramentas em tempo de execução como count(ToolRegistry::all()), após a filtragem por política e a detecção de nível. Qualquer documentação que cite um total fixo está desatualizada. Para obter a contagem oficial, consulte o servidor em execução. Use a resposta initialize do MCP ou o endpoint REST /api/v1/capabilities.

O número de ferramentas expostas depende dos pacotes instalados e da política ativa. Leia-o do servidor em execução, em tempo de execução. Um número fixo no código ou na documentação ficará desatualizado.
Um pacote Pro ou Enterprise ausente não é um erro. O registro verifica as classes de provedor com class_exists() e, em seguida, ignora silenciosamente qualquer nível que esteja ausente. Uma implantação somente de código aberto inicializa e disponibiliza seu catálogo básico normalmente.
Os três transportes não compartilham um processo. Executar o servidor MCP não inicia o servidor REST nem o servidor gRPC. O inverso também é verdadeiro. Uma implantação combinada executa o supervisor do RoadRunner com uma configuração que inicia os dois pools de workers, o pool HTTP e o pool gRPC. Consulte /connect/deployment/.

Desempenho

Cada transporte é baseado em workers. Um worker atende uma requisição por vez. Os servidores REST e gRPC rodam em pools de workers do RoadRunner, e a configuração define o tamanho do pool. O padrão é quatro workers HTTP. O supervisor do RoadRunner limita a memória de cada worker. O front-matter performance_budget nesta página descreve um envelope de cold boot e descoberta. Ele não é uma meta por requisição. A operação subjacente do motor determina a maior parte do custo da requisição.

Notas de segurança

Todos os transportes em rede se autenticam com um token bearer de API key. O transporte stdio do MCP é um subprocesso local no qual o cliente que o inicia confia, conforme o modelo de transporte do MCP. Ferramentas de alto risco permanecem bloqueadas por confirmação humana em todos os transportes. Para o modelo de ameaças completo, o modelo de autenticação e a configuração de segurança de transporte, consulte /connect/security-and-operations/.

Conformidade

Esta página faz apenas afirmações de arquitetura. As citações normativas de protocolo e segurança estão fixadas nas páginas que especificam o comportamento: /connect/security-and-operations/, /transports/mcp/, /transports/rest/ e /transports/grpc/. A referência do ciclo de vida do MCP é a especificação oficial em modelcontextprotocol.io (revisão 2025-06-18). As páginas de transporte registram essa referência com a respectiva URL, porque a especificação do MCP não faz parte do corpus restrito de normas.

Contexto comercial

O catálogo básico é completo para criação, inspeção e diagnóstico de documentos. Ferramentas de assinatura, redação, certificação de conformidade e análise forense aparecem somente quando o nextpdf/premium está instalado junto com o servidor. Isso é uma fronteira de empacotamento, não uma mensagem de venda adicional em tempo de execução. O servidor nunca emite conteúdo de marketing.

Veja também

/connect/install/ — instalação e pacotes opcionais
/connect/quickstart/ — primeira troca executável com MCP e REST
/connect/tool-catalog/ — o conjunto básico verificado de ferramentas e como a contagem depende do tempo de execução
/connect/hitl-risk-tiers/ — o portão de confirmação e o modelo de risco
/transports/mcp/, /transports/rest/, /transports/grpc/ — configuração por transporte
/connect/security-and-operations/ — autenticação, segurança de transporte e modelo de ameaças
/connect/deployment/ — RoadRunner, Docker e implantação com transportes combinados