NextPDF Connect: inicialização e descoberta

Visão geral

Cada transporte tem seu próprio ponto de entrada e sua própria sequência de inicialização. Os transportes compartilham registro, configuração e gate como conceitos. Eles são executados como processos independentes; portanto, iniciar um deles não inicia os demais.

Instalação

composer require nextpdf/server

Visão conceitual

Sequência de inicialização do MCP

McpServer::create() inicializa o servidor do Model Context Protocol (MCP) em uma ordem fixa. Primeiro, ele carrega a configuração, monta a política de segurança a partir dela, constrói o registro de ferramentas e executa a descoberta de camadas. Em seguida, constrói o armazenamento de documentos em memória a partir do tempo de vida (TTL) e da capacidade configurados, cria o transporte stdio e monta o manipulador do protocolo JSON-RPC com o gate de confirmação e o registrador de auditoria. Então o servidor entra no laço de leitura-processamento-escrita e é executado até que a entrada padrão chegue ao fim do arquivo.

Sequência de inicialização do REST

HttpServer::create() lê HttpConfig a partir do ambiente e aplica as substituições da linha de comando (CLI). Em seguida, ele resolve o armazenamento de chaves da API nesta ordem de preferência: primeiro o armazenamento em arquivo com recarregamento dinâmico, depois o arquivo estático e, por fim, o ambiente. Depois, resolve os armazenamentos de limite de taxa e de idempotência. Eles usam o Redis quando o Redis está configurado e acessível; caso contrário, recorrem ao armazenamento em memória. A partir daí, o servidor abre o armazenamento de tarefas compartilhado em SQLite, monta os serviços da aplicação e constrói a tabela de rotas. Como a tabela de rotas é construída a partir das camadas detectadas, ela reflete os pacotes instalados. Então o RoadRunner conduz o laço de requisições do worker.

Sequência de inicialização do gRPC

GrpcServer::create() resolve o mesmo armazenamento de chaves, monta os mesmos serviços da aplicação e registra o serviço nextpdf.connect.v1 com o worker gRPC do Spiral. Quando a dependência do engine está indisponível, o servidor gRPC ainda assim inicia e atende consultas de saúde e de capacidade. Nesse estado, o processo não aborta a inicialização; em vez disso, as chamadas de procedimento remoto (RPCs) que carregam dados falham de forma limpa.

Descoberta de ferramentas

A descoberta é a etapa padrão em que as ferramentas são registradas. A camada core registra primeiro. Os provedores Pro e Enterprise registram em seguida, se suas classes forem resolvidas por class_exists(). Depois, os provedores incluídos de Abstract Syntax Tree (AST) e de mutação registram sob a camada Pro, sujeitos aos seus gates de ambiente. Cada registro é filtrado pela lista de permissões de segurança enabled_tools, e a resposta initialize do MCP informa as contagens resultantes por camada. Consulte /connect/tool-catalog/.

Descoberta de transportes

Não existe uma configuração isolada que “habilite transportes.” Cada transporte é um ponto de entrada separado. REST e gRPC têm, cada um, um perfil separado do RoadRunner. Uma implantação escolhe os transportes pelo perfil que executa: .rr.yaml para REST, .rr.grpc.yaml para gRPC ou .rr.full.yaml para ambos. Os transportes são executados como processos independentes. A ausência de um cliente MCP nunca bloqueia o servidor REST, e a ausência de um cliente REST nunca bloqueia o MCP. Consulte /connect/deployment/.

Ordem de resolução da configuração

O servidor MCP resolve a configuração nesta ordem de precedência: o ambiente (NEXTPDF_MCP_*) tem prioridade sobre a seção nextpdf_mcp do arquivo YAML, que tem prioridade sobre os padrões internos. Os servidores REST e gRPC leem HttpConfig a partir das variáveis de ambiente NEXTPDF_* com padrões seguros. Eles não leem o arquivo YAML do MCP. Consulte /connect/configuration/.

Vinculações de container

Não há container de injeção de dependência nem service provider para registrar. Cada fábrica create() constrói explicitamente o próprio grafo de objetos de forma determinística. Há dois pontos de injeção — o transporte e a fábrica de workers — e ambos servem para testes, não para a montagem da aplicação.

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

Inspecione o resultado da descoberta sem atender tráfego:

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

Exemplo de código — Produção

Inicialize os transportes combinados sob um único supervisor:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

Casos extremos e armadilhas

• Uma camada ausente não faz a inicialização falhar. A descoberta de camadas ignora silenciosamente um pacote Pro ou Enterprise ausente. O servidor inicializa com o catálogo core.

• Uma substituição que rebaixa o risco faz a inicialização falhar. Uma entrada de risk_level_overrides que enfraquece uma ferramenta approval_required lança uma exceção durante o carregamento da configuração; o servidor se recusa a iniciar. Isso é intencional.

• A falha do Redis degrada, não trava. Se o Redis estiver configurado, mas inacessível na inicialização, o servidor REST recorre aos armazenamentos em memória. Verifique a saúde do Redis em vez de presumir que o Redis está em uso.

Desempenho

O custo de inicialização vem da análise da configuração, da varredura do registro e da detecção de camadas. O performance_budget da página limita esse custo. Esse custo é pago uma vez a cada início de processo, não por requisição.

Notas de segurança

A política de segurança é montada antes do registro; portanto, a lista de permissões enabled_tools restringe a descoberta desde o primeiro registro. As chaves de API nunca são lidas do arquivo YAML do MCP; os transportes em rede resolvem as chaves a partir de um arquivo de segredo ou do ambiente. Consulte /connect/security-and-operations/.

Conformidade

Esta página descreve a mecânica de inicialização. As citações de protocolo e de segurança estão mantidas em /transports/mcp/, /transports/rest/, /transports/grpc/ e /connect/security-and-operations/.

Contexto comercial

A detecção de camadas durante a inicialização é o único ponto em que nextpdf/premium contribui com suas ferramentas Pro e Enterprise para o catálogo, quando nextpdf/premium está instalado junto com o servidor.

Veja também

• /connect/tool-catalog/ — o que a descoberta registra e por que a contagem varia
• /connect/configuration/ — a ordem de resolução em detalhe
• /connect/deployment/ — escolhendo transportes por meio de perfis do RoadRunner
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — detalhe por transporte