Início rápido com o NextPDF Connect

Visão geral

Esta página executa a menor troca útil com os dois transportes: Model Context Protocol (MCP) e Representational State Transfer (REST). Cada requisição usa exatamente o formato de transmissão implementado pelo servidor. Você não precisa de um software development kit (SDK).

Instalação

composer require nextpdf/server

Visão conceitual

O transporte MCP usa JSON-RPC 2.0 pela entrada e saída padrão. Você deve enviar a sequência em ordem. Primeiro envie initialize. Em seguida, envie a confirmação notifications/initialized. Depois envie tools/list e tools/call. O servidor lê uma mensagem JSON por linha. Cada linha deve terminar com uma quebra de linha. O servidor escreve uma resposta por linha.

O transporte REST expõe as mesmas capacidades do motor na forma de operações de Hypertext Transfer Protocol (HTTP). Uma renderização única e sem estado é um POST /api/v1/render com um array ordenado de operações. O corpo da resposta é o arquivo Portable Document Format (PDF).

Exemplo de código — Início rápido (MCP via stdio)

Inicie o servidor e envie o handshake para ele via pipe. Estas três requisições usam os nomes de método verificados roteados pelo manipulador de protocolo:

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

A resposta de initialize informa a versão do protocolo 2025-06-18, o nome do servidor NextPDF Connect e um bloco capabilities.nextpdf. Esse bloco inclui as contagens de tier em tempo real, o tool_count de runtime, a versão do modelo de risco e hitl_enabled: true. A resposta de tools/list lista as ferramentas exatas registradas para esta instalação. A linha de notificação não produz resposta intencionalmente.

Agora chame uma ferramenta segura. A ferramenta diagnostic.doctor executa uma verificação de ambiente somente leitura. Ela não precisa de documento nem de confirmação:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"quickstart","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 — Início rápido (REST)

Inicie o servidor REST e, em seguida, renderize um PDF de uma linha. O servidor exige uma chave de application programming interface (API) em cada endpoint que não seja de health, por isso defina uma primeiro:

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

Em outro shell, envie uma requisição de renderização. O corpo é um RenderRequest. Essa requisição contém um array operations ordenado de operações tipadas.

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

O corpo de uma resposta 200 é o PDF (Content-Type: application/pdf) gravado em hello.pdf. As verificações de health não precisam de chave:

curl -sS http://localhost:8080/healthz

Casos de borda e pegadinhas

A ordem do handshake importa. O manipulador de protocolo trata uma mensagem sem id como uma notificação e não retorna nada. Envie initialize com um id, depois a notificação initialized e então as requisições que incluem um id.
Um id de requisição repetido é desduplicado. O manipulador armazena em cache as respostas recentes em um buffer circular de 64 entradas. Para um id duplicado, ele retorna a resposta em cache sem executar a ferramenta novamente. Use ids novos.
Uma ferramenta de alto risco responde com um desafio, não com um resultado. Chamar output_pdf com um file_path retorna um desafio de confirmação em vez de executar a ferramenta. Invoque-a novamente com o _confirmation_token emitido. O modo de saída base64, sem file_path, não requer confirmação. Consulte /connect/hitl-risk-tiers/.
Uma requisição REST não autorizada recebe 401. Um cabeçalho Authorization: Bearer ausente ou malformado retorna um corpo de problem-details com um cabeçalho WWW-Authenticate: Bearer. As verificações /healthz e /readyz são os únicos endpoints anônimos.

Desempenho

Ambos os caminhos de início rápido usam uma única requisição. O caminho REST também paga o custo de cold-start do pool de workers do RoadRunner na primeira requisição após rr serve. As requisições seguintes reutilizam workers já aquecidos.

Notas de segurança

A chave npk_live_ acima é um valor de demonstração descartável. Gere chaves reais com entropia suficiente, armazene-as fora do controle de versão e prefira o armazenamento de chaves baseado em arquivo para rotação. O transporte stdio do MCP não tem chave de API porque é um subprocesso local no qual o cliente que o inicia confia, dentro do modelo de transporte do MCP. Consulte /connect/security-and-operations/.

Conformidade

Os formatos de transmissão exibidos correspondem à revisão MCP implementada 2025-06-18 e ao contrato REST OpenAPI 3.1. As citações normativas de protocolo e autenticação estão fixadas em /transports/mcp/, /transports/rest/ e /connect/security-and-operations/.

Veja também

/transports/mcp/ — a referência completa do transporte MCP
/transports/rest/ — a referência completa do transporte REST e da renderização OpenAPI
/connect/tool-catalog/ — quais ferramentas tools/list retorna e por quê
/connect/hitl-risk-tiers/ — como funciona um desafio de confirmação
/connect/configuration/ — como restringir o catálogo e ajustar o servidor