Configure o NextPDF Connect

Visão geral

O NextPDF Connect tem duas superfícies de configuração. O servidor Model Context Protocol (MCP) lê um arquivo YAML e as variáveis NEXTPDF_MCP_*. Os servidores REST e gRPC leem as variáveis de ambiente NEXTPDF_*. A configuração se torna imutável assim que o servidor inicializa.

Instalação

composer require nextpdf/server

Visão conceitual

O servidor MCP resolve a configuração em uma ordem fixa de prioridade. A fonte com prioridade mais alta vence:

Variáveis de ambiente (NEXTPDF_MCP_*).
A seção nextpdf_mcp do arquivo de configuração YAML.
Valores padrão internos.

Passe o arquivo YAML com --config=PATH. Se você omiti-lo, o servidor usará apenas os valores padrão e as variáveis de ambiente. O McpConfig resultante é um value object readonly. Nenhuma configuração pode mudar depois da inicialização.

Os servidores REST e gRPC leem HttpConfig a partir do ambiente na inicialização. Eles oferecem suporte a NEXTPDF_BIND, NEXTPDF_WORKER_COUNT, NEXTPDF_SESSIONS_ENABLED e NEXTPDF_CORS_ENABLED como substituições de ambiente. Os demais limites usam valores padrão seguros.

Superfície da API

Configuração do MCP (`nextpdf-mcp`)

Arquivo YAML, seção nextpdf_mcp:

nextpdf_mcp:
  enabled_tools: []          # empty/absent = all available tools allowed
  temp_directory: /tmp/nextpdf-mcp
  max_documents: 50
  document_ttl: 1800
  max_file_size_bytes: 104857600
  allow_file_output: true
  compress: true
  risk_level_overrides:
    fill_form: 3             # raise fill_form to ApprovalRequired (see below)

Substituições de ambiente para o servidor MCP:

Variável	Chave de configuração	Padrão
`NEXTPDF_MCP_ENABLED_TOOLS`	`enabled_tools`	todas as ferramentas permitidas
`NEXTPDF_MCP_TEMP_DIR`	`temp_directory`	temp do sistema + `/nextpdf-mcp`
`NEXTPDF_MCP_MAX_FILE_SIZE`	`max_file_size_bytes`	`104857600` (100 MB)
`NEXTPDF_MCP_MAX_DOCUMENTS`	`max_documents`	`50`
`NEXTPDF_MCP_DOCUMENT_TTL`	`document_ttl`	`1800` segundos
`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`	(controla `parse_pdf`)	não definido (desabilitado)
`NEXTPDF_AST_TOOLS_ENABLED`	(controla ferramentas de AST)	habilitado
`NEXTPDF_MUTATION_TOOLS_ENABLED`	(controla ferramentas de mutação de AST)	não definido (desabilitado)

Configuração de REST e gRPC

Variável	Padrão	Efeito
`NEXTPDF_BIND`	`0.0.0.0:8080`	Endereço de escuta REST
`NEXTPDF_WORKER_COUNT`	`4`	Contagem de workers PHP do RoadRunner
`NEXTPDF_SESSIONS_ENABLED`	`false`	Habilita endpoints de sessão com estado
`NEXTPDF_CORS_ENABLED`	`false`	Habilita os cabeçalhos de resposta CORS
`NEXTPDF_API_KEYS`	não definido	Definições embutidas de chave de API
`NEXTPDF_API_KEYS_FILE`	não definido	Caminho para um arquivo de chaves de API
`NEXTPDF_JOB_STORE_PATH`	temp do sistema	Caminho do armazenamento de jobs SQLite
`NEXTPDF_REDIS_HOST`	não definido	Habilita os armazenamentos baseados em Redis quando está definido

O Redis é usado pelo servidor REST quando NEXTPDF_REDIS_HOST está definido e ext-redis está carregado:

Variável	Padrão
`NEXTPDF_REDIS_PORT`	`6379`
`NEXTPDF_REDIS_PASSWORD`	vazio
`NEXTPDF_REDIS_DATABASE`	`0`
`NEXTPDF_REDIS_PREFIX`	`nextpdf:`
`NEXTPDF_REDIS_CONNECT_TIMEOUT`	`2.0` segundos
`NEXTPDF_REDIS_READ_TIMEOUT`	`2.0` segundos

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

Execute o servidor MCP com um arquivo de configuração explícito:

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml

Exemplo de código — Produção

Restrinja o catálogo do MCP a uma allowlist explícita e eleve o risco de uma ferramenta:

nextpdf_mcp:
  enabled_tools:
    - create_pdf
    - add_text
    - output_pdf
    - diagnostic.doctor
  temp_directory: /var/lib/nextpdf/tmp
  max_file_size_bytes: 26214400
  risk_level_overrides:
    add_text: 2          # upgrade add_text from caution to review

Com um enabled_tools não vazio, a política de segurança permite apenas os nomes de ferramentas listados. O registro descarta silenciosamente todas as demais ferramentas. Uma lista vazia ou ausente permite todas as ferramentas disponíveis.

Casos extremos e armadilhas

As duas ferramentas críticas não podem ser rebaixadas. output_pdf e sign_pdf exigem aprovação por design: uma entrada risk_level_overrides que rebaixe qualquer uma dessas ferramentas para abaixo de ApprovalRequired lança uma InvalidArgumentException no momento do carregamento, e o servidor se recusa a inicializar. Você pode elevar ou rebaixar o nível de risco de qualquer outra ferramenta, então avalie qualquer rebaixamento em relação ao seu próprio modelo de ameaças. Consulte /connect/hitl-risk-tiers/.
enabled_tools filtra, não adiciona. Listar o nome de uma ferramenta Pro enquanto nextpdf/premium está ausente não faz com que ela apareça. A allowlist é cruzada com as ferramentas que o registro realmente descobriu.
O ambiente prevalece sobre o YAML para o servidor MCP. Uma variável NEXTPDF_MCP_* substitui a mesma chave no arquivo YAML. Os servidores REST e gRPC não leem o arquivo YAML do MCP de forma alguma.
parse_pdf é opt-in. O servidor registra a ferramenta parse_pdf apenas quando NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED é true ou 1. Ela permanece ausente por padrão, mesmo no catálogo core.

Desempenho

A configuração é analisada uma única vez na inicialização. As configurações max_documents e document_ttl limitam o armazenamento de documentos em memória. Reduzi-las diminui o pico de memória, mas encurta a vida útil dos documentos. A contagem de workers e os limites de payload por tier são controles de ajuste da implantação, abordados em /connect/deployment/.

Notas de segurança

Trate enabled_tools como um controle de negação por padrão para implantações de privilégio mínimo: liste apenas as ferramentas de que uma determinada integração precisa.
Nunca armazene chaves de API no arquivo YAML. Use NEXTPDF_API_KEYS_FILE com um arquivo montado como um secret do Docker ou do Kubernetes. O servidor dá preferência a um armazenamento em arquivo com recarga a quente, de modo que as chaves possam ser rotacionadas sem reiniciar. Consulte /connect/security-and-operations/.
O temp_directory é o diretório base imposto para a saída de arquivos. O servidor canonicaliza os caminhos de saída e rejeita qualquer caminho resolvido fora dele.

Conformidade

Esta página descreve a mecânica de configuração. As citações de conformidade sobre autenticação e segurança de transporte estão fixadas em /connect/security-and-operations/.

Contexto comercial

Os limites de payload e de timeout por tier (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit e os timeouts correspondentes) aplicam-se ao transporte REST de acordo com o tier da chave de API autenticada. Eles entram em vigor apenas quando as ferramentas Pro ou Enterprise estão instaladas e a chave tem direito a usá-las.

Veja também

/connect/install/ — instalação e pacotes opcionais
/connect/boot-and-discovery/ — como a configuração orienta a sequência de inicialização
/connect/hitl-risk-tiers/ — o modelo de risco e a substituição apenas para elevação
/connect/security-and-operations/ — configuração de chaves de API e segurança de transporte
/connect/deployment/ — contagem de workers, Redis e limites de tier em produção