Solução de problemas do NextPDF Connect

Visão geral

A maioria das falhas se enquadra em um destes cinco padrões: handshake JavaScript Object Notation Remote Procedure Call (JSON-RPC) malformado, chave de application programming interface (API) ausente, ferramenta não instalada neste tier, desafio de confirmação sem resposta ou store não compartilhado pelos workers. Cada padrão tem uma assinatura própria.

Instalação

composer require nextpdf/server

Visão conceitual

O transporte do Model Context Protocol (MCP) retorna objetos de erro JSON-RPC 2.0 com códigos padrão. O transporte do Representational State Transfer (REST) retorna documentos de detalhes de problema (problem-details) Request for Comments (RFC) 7807. Cada documento contém uma URL type que identifica a condição. Para problemas de ambiente, comece pelas ferramentas de diagnóstico (diagnostic.doctor, diagnostic.capabilities). Essas ferramentas sempre fazem parte do catálogo core.

Superfície da API

Códigos de erro JSON-RPC do MCP

Código	Nome	Causa
`-32700`	Erro de parse	A linha não era um JSON válido
`-32600`	Requisição inválida	A mensagem não é JSON-RPC 2.0 (falta `jsonrpc`/`method`)
`-32601`	Método não encontrado	Método diferente de `initialize`, `tools/list`, `tools/call`
`-32602`	Parâmetros inválidos	Falta `params.name` em `tools/call`
`-32603`	Erro interno	A ferramenta lançou uma exceção durante a execução

Uma ferramenta que falha de forma controlada não usa esses códigos. Em vez disso, retorna uma resposta JSON-RPC bem-sucedida com isError: true no resultado e uma explicação em texto, por exemplo ferramenta desconhecida, desabilitada por política ou argumentos inválidos.

Tipos de detalhes de problema (problem-details) do REST

HTTP	`type` (slug)	Causa
`401`	`unauthorized`	Chave de API ausente/inválida/desabilitada/expirada
`403`	`capability-denied`	O tier da chave não dá direito à operação
`413`	`payload-too-large` / `tier-payload-exceeded`	O corpo excede o limite global ou do tier
`422`	`validation-failed`	O corpo da requisição não passou na validação de schema
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	Um limite de taxa foi excedido
`404`	`not-found`	Rota desconhecida ou id de job/session não encontrado
`504`	(timeout da requisição)	A operação excedeu o timeout do tier

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

Execute a verificação de integridade do ambiente. Ela não exige documento nem confirmação:

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

Exemplo de código — Produção

Antes de depurar uma “ferramenta ausente”, confirme quais ferramentas esta implantação está expondo:

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

ou, para um servidor REST em execução:

curl -sS http://localhost:8080/api/v1/capabilities \
  -H "Authorization: Bearer $NEXTPDF_KEY"

Casos extremos e armadilhas

“Ferramenta desconhecida” para uma ferramenta Pro/Enterprise. O pacote da ferramenta não está instalado. O registry verifica as classes de provider e ignora, sem aviso, os tiers ausentes. Isso é esperado, não um bug. Instale o nextpdf/premium junto com o servidor ou use uma ferramenta core. A mensagem de erro inclui o caminho de instalação.
Uma ferramenta que configurei em enabled_tools não aparece. A allowlist é aplicada como interseção sobre as ferramentas descobertas. Ela não pode adicionar uma ferramenta que o registry não encontrou. Verifique a instalação do tier e quaisquer gates de ambiente. Por exemplo, parse_pdf é opt-in por meio de NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED.
tools/call retornou texto pedindo um token. Isso é um desafio de confirmação, não um erro. Chame a ferramenta novamente dentro de 300 segundos com _confirmation_token definido como o token emitido. Consulte /connect/hitl-risk-tiers/.
A linha de notificação não produziu saída. Isso é esperado. Uma mensagem JSON-RPC sem id é uma notificação, e o handler não retorna nada. Envie requisições com um id para obter respostas.
Um id de requisição repetido retornou uma resposta obsoleta. O handler elimina duplicatas por id de requisição em um buffer de 64 entradas. Use um id novo para cada requisição lógica.
Os limites de taxa se comportam de forma estranha entre os workers. O store em memória é isolado por worker. Para compartilhar a contagem, defina NEXTPDF_REDIS_HOST e instale o ext-redis. Consulte /connect/deployment/.
Documentos desaparecem entre as requisições. O store de documentos em memória é isolado por worker e limitado por um time to live (document_ttl, padrão 1800 s). Para manter a continuidade de documentos entre workers, use o store baseado em Redis, os endpoints de sessão ou mantenha todo o conjunto de operações em uma única renderização síncrona.
O servidor voltou a usar memória apesar da configuração do Redis. O servidor REST volta automaticamente para memória se a conexão com o Redis falhar na inicialização (boot). Confirme que o Redis está acessível e que o ext-redis está presente na imagem em execução. Não presuma que o Redis está em uso sem verificar.
O servidor se recusa a inicializar com um erro de configuração. Uma entrada de risk_level_overrides tentou rebaixar uma ferramenta ApprovalRequired. O loader rejeita isso por design. Remova o rebaixamento; os overrides só podem aumentar o risco.

Desempenho

Se as renderizações estiverem lentas sob carga, confirme se o pool de workers não está saturado. Verifique o endpoint de métricas do RoadRunner. Em seguida, mova as renderizações longas para o caminho de job assíncrono para que elas não ocupem os workers. Consulte /connect/production-usage/.

Notas de segurança

Não contorne um 401 expondo o transporte MCP não autenticado em uma rede; isso remove a autenticação por completo. Em vez disso, corrija a chave de API. Não aumente a verbosidade dos logs para inspecionar argumentos de ferramentas em um ambiente compartilhado; os payloads de argumentos podem ser sensíveis. Consulte /connect/security-and-operations/.

Conformidade

Esta página fornece orientação operacional. As citações de protocolo e segurança estão registradas em /transports/mcp/, /transports/rest/ e /connect/security-and-operations/.

Consulte também

/connect/tool-catalog/ — o que o catálogo core contém e por que a contagem varia
/connect/hitl-risk-tiers/ — desafios de confirmação em detalhes
/connect/deployment/ — Redis, pools de workers e compartilhamento do store
/connect/security-and-operations/ — falhas de autenticação e postura de segurança