Transporte MCP do NextPDF Connect

Visão geral

O transporte do Model Context Protocol (MCP) executa bin/nextpdf-mcp como um subprocesso local. Ele usa JSON-RPC 2.0 pela entrada e saída padrão. O servidor implementa a revisão datada 2025-06-18 do MCP.

Instalação

composer require nextpdf/server

Visão conceitual

No modelo stdio do MCP, o cliente inicia o servidor como subprocesso. O cliente troca mensagens JSON-RPC delimitadas por quebra de linha: uma mensagem por linha, sem quebras de linha incorporadas, em UTF-8. O servidor grava apenas mensagens MCP válidas na saída padrão e envia os logs para o erro padrão. A implementação direciona o registrador de auditoria para o erro padrão, de modo que as linhas de log nunca corrompam o fluxo do protocolo. A especificação oficial do MCP, revisão 2025-06-18, define esse enquadramento. Essa especificação não faz parte do corpus restrito de normas, portanto é citada por URL: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports.

O NextPDF Connect implementa o transporte stdio. A especificação do MCP também define um transporte Streamable HTTP. A especificação afirma que os clientes devem oferecer suporte a stdio sempre que possível, e que um servidor pode implementar apenas stdio. Para acessar as mesmas ferramentas pela rede, use o transporte REST ou gRPC; consulte /transports/rest/ e /transports/grpc/.

Superfície da API

Métodos

Método	Comportamento
`initialize`	Retorna a versão do protocolo, os recursos e as informações do servidor
`notifications/initialized`	Uma notificação (sem `id`); aceita sem resposta
`tools/list`	Lista as ferramentas registradas com um filtro `params.category` opcional
`tools/call`	Executa uma ferramenta por `params.name` com `params.arguments`

Qualquer outro método retorna erro de método não encontrado (-32601). Uma mensagem que não é JSON-RPC 2.0 válida retorna requisição inválida (-32600); entrada não analisável retorna erro de análise (-32700). Um id de requisição duplicado retorna a resposta anterior armazenada em cache em um buffer de 64 entradas, sem executar novamente.

A resposta do initialize

O resultado de initialize retorna protocolVersion 2025-06-18, serverInfo.name: NextPDF Connect e um objeto capabilities. Além da capacidade padrão tools, o servidor inclui um bloco capabilities.nextpdf:

tiers — contagens em tempo real das ferramentas registradas por nível (core / pro / enterprise).
tool_count — o número total de ferramentas registradas, calculado em tempo de execução.
risk_model_version — a versão do modelo de risco que o servidor aplica.
hitl_enabled — true; o controle de confirmação está ativo.

tool_count é o número definitivo para esta implantação. É uma contagem calculada em tempo de execução, não uma constante documentada; consulte /connect/tool-catalog/.

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

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

Exemplo de código — Produção

Um filtro de categoria restringe o catálogo a um único domínio:

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

Os valores de categoria vêm da categoria declarada em cada ferramenta (por exemplo, document, diagnostic).

Casos extremos e pontos de atenção

Sem chave de API. O transporte stdio não tem ouvinte de rede nem token de portador. Trate a fronteira de processo do sistema operacional como a fronteira de confiança, conforme o modelo stdio do MCP. Não o conecte a uma rede.
Os desafios de confirmação são in-band. Uma ferramenta ApprovalRequired retorna uma resposta JSON-RPC bem-sucedida. O conteúdo da resposta é o texto do desafio e um token de uso único, não um erro. Consulte /connect/hitl-risk-tiers/.
As notificações são silenciosas. Uma mensagem sem id não produz resposta. O handshake é initialize (com id), depois a notificação initialized e, em seguida, as chamadas com id.

Desempenho

O servidor MCP é executado como um único processo e trata uma requisição por vez por meio de pipes. Não há ida e volta pela rede; a latência é dominada pela operação subjacente do mecanismo.

Notas de segurança

O transporte herda a confiança do cliente que o inicia. Mantenha o subprocesso local. As ferramentas de alto risco ainda exigem confirmação humana, mesmo sem chave de API. Consulte /connect/security-and-operations/.

Conformidade

O enquadramento stdio e o comportamento de initialize/lifecycle estão em conformidade com a especificação oficial do Model Context Protocol, revisão 2025-06-18:

Transportes: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
Ciclo de vida: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

A especificação do MCP não está no corpus restrito de normas, portanto não tem reference_id; as URLs oficiais acima são a citação de referência.

Contexto comercial

tools/list retorna as ferramentas Pro e Enterprise somente quando nextpdf/premium está instalado junto com o servidor. O transporte em si é o mesmo, independentemente dos níveis instalados.

Veja também

/connect/quickstart/ — o handshake executável
/connect/tool-catalog/ — o que tools/list retorna e por que as contagens variam
/connect/hitl-risk-tiers/ — o formato do desafio de confirmação
/transports/rest/ · /transports/grpc/ — alternativas em rede
/connect/migrating-to-multi-transport/ — migrar uma integração somente MCP para REST/gRPC