Configurazione di NextPDF Connect

In breve

NextPDF Connect espone due superfici di configurazione. Il server MCP legge un file YAML e le variabili NEXTPDF_MCP_*. I server REST e gRPC leggono le variabili d’ambiente NEXTPDF_*. Dopo l’avvio del server, la configurazione è immutabile.

Installazione

composer require nextpdf/server

Panoramica concettuale

Il server MCP risolve la configurazione secondo un ordine di priorità fisso. Prevale l’origine con priorità più alta:

Variabili d’ambiente (NEXTPDF_MCP_*).
La sezione nextpdf_mcp del file di configurazione YAML.
Valori predefiniti incorporati.

Passare il file YAML con --config=PATH. In assenza del file, il server usa solo i valori predefiniti e le variabili d’ambiente. L’oggetto McpConfig risultante è un value object readonly. Dopo l’avvio nessuna impostazione cambia.

I server REST e gRPC leggono HttpConfig dall’ambiente all’avvio. Gli override tramite ambiente supportati sono NEXTPDF_BIND, NEXTPDF_WORKER_COUNT, NEXTPDF_SESSIONS_ENABLED e NEXTPDF_CORS_ENABLED. Gli altri limiti massimi usano valori predefiniti sicuri.

Superficie API

Configurazione MCP (`nextpdf-mcp`)

File YAML, sezione 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)

Override tramite ambiente per il server MCP:

Variabile	Chiave di configurazione	Valore predefinito
`NEXTPDF_MCP_ENABLED_TOOLS`	`enabled_tools`	tutti gli strumenti consentiti
`NEXTPDF_MCP_TEMP_DIR`	`temp_directory`	temp di 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` secondi
`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`	(controlla l’accesso a `parse_pdf`)	non impostato (disabilitato)
`NEXTPDF_AST_TOOLS_ENABLED`	(controlla l’accesso agli strumenti AST)	abilitato
`NEXTPDF_MUTATION_TOOLS_ENABLED`	(controlla l’accesso agli strumenti di mutazione AST)	non impostato (disabilitato)

Configurazione REST e gRPC

Variabile	Valore predefinito	Effetto
`NEXTPDF_BIND`	`0.0.0.0:8080`	Indirizzo di ascolto per REST
`NEXTPDF_WORKER_COUNT`	`4`	Numero di worker PHP di RoadRunner
`NEXTPDF_SESSIONS_ENABLED`	`false`	Abilita gli endpoint di sessione stateful
`NEXTPDF_CORS_ENABLED`	`false`	Abilita le intestazioni di risposta CORS
`NEXTPDF_API_KEYS`	non impostato	Definizioni di chiavi API inline
`NEXTPDF_API_KEYS_FILE`	non impostato	Percorso di un file di chiavi API
`NEXTPDF_JOB_STORE_PATH`	temp di sistema	Percorso dello store dei job SQLite
`NEXTPDF_REDIS_HOST`	non impostato	Se impostato, abilita gli archivi basati su Redis

Redis (usato dal server REST quando NEXTPDF_REDIS_HOST è impostato e ext-redis è caricato):

Variabile	Valore predefinito
`NEXTPDF_REDIS_PORT`	`6379`
`NEXTPDF_REDIS_PASSWORD`	vuoto
`NEXTPDF_REDIS_DATABASE`	`0`
`NEXTPDF_REDIS_PREFIX`	`nextpdf:`
`NEXTPDF_REDIS_CONNECT_TIMEOUT`	`2.0` secondi
`NEXTPDF_REDIS_READ_TIMEOUT`	`2.0` secondi

Esempio di codice — Avvio rapido

Eseguire il server MCP con un file di configurazione esplicito:

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

Esempio di codice — Produzione

Limitare il catalogo MCP a un’allowlist esplicita e aumentare il livello di rischio di uno strumento:

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

Quando enabled_tools non è vuoto, i criteri di sicurezza consentono solo i nomi degli strumenti elencati. Ogni altro strumento viene rimosso dal registro senza messaggi. Un elenco vuoto o assente consente tutti gli strumenti disponibili.

Casi limite e insidie

I due strumenti critici non possono essere declassati. output_pdf e sign_pdf sono soggetti ad approvazione per scelta progettuale: una voce risk_level_overrides che abbassi uno di questi due strumenti al di sotto di ApprovalRequired genera un’eccezione InvalidArgumentException al momento del caricamento e il server si rifiuta di avviarsi. Per ogni altro strumento, il livello di rischio può essere aumentato o abbassato; esaminare quindi ogni declassamento in base al proprio modello di minaccia. Vedere /connect/hitl-risk-tiers/.
enabled_tools filtra, non aggiunge. Elencare il nome di uno strumento Pro quando nextpdf/premium è assente non lo fa comparire. L’allowlist viene intersecata con gli strumenti effettivamente individuati dal registro.
L’ambiente prevale su YAML per il server MCP. Una variabile NEXTPDF_MCP_* esegue l’override della stessa chiave nel file YAML. I server REST e gRPC non leggono affatto il file YAML di MCP.
parse_pdf è opt-in. Lo strumento parse_pdf viene registrato solo quando NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED è true o 1. È assente per impostazione predefinita, anche nel catalogo core.

Prestazioni

La configurazione viene analizzata una sola volta all’avvio. Le impostazioni max_documents e document_ttl delimitano l’archivio dei documenti in memoria. Ridurle abbassa il picco di memoria, a costo di una vita utile più breve per i documenti. Il numero di worker e i limiti massimi di payload per livello sono leve di ottimizzazione del deployment, trattate in /connect/deployment/.

Note sulla sicurezza

Considerare enabled_tools come una superficie di controllo a negazione predefinita per i deployment a privilegio minimo: elencare solo gli strumenti necessari a una determinata integrazione.
Non archiviare mai le chiavi API nel file YAML. Usare NEXTPDF_API_KEYS_FILE con un file montato come secret Docker o Kubernetes. Il server privilegia un archivio su file con ricaricamento a caldo, così le chiavi possono essere ruotate senza riavvio. Vedere /connect/security-and-operations/.
La temp_directory è la directory di base imposta per l’output dei file. Il server canonicalizza i percorsi di output e rifiuta qualsiasi elemento che si risolva al di fuori di essa.

Conformità

Questa pagina descrive i meccanismi di configurazione. Le citazioni di conformità relative all’autenticazione e alla sicurezza del trasporto sono riportate in /connect/security-and-operations/.

Contesto commerciale

I limiti massimi per livello relativi a payload e timeout (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit e i timeout corrispondenti) si applicano al trasporto REST in base al livello della chiave API autenticata. Hanno effetto solo quando gli strumenti Pro o Enterprise sono installati e la chiave è abilitata al loro uso.

Vedere anche

/connect/install/ — installazione e pacchetti facoltativi
/connect/boot-and-discovery/ — come la configurazione guida la sequenza di avvio
/connect/hitl-risk-tiers/ — il modello di rischio e l’override solo in aumento
/connect/security-and-operations/ — configurazione delle chiavi API e sicurezza del trasporto
/connect/deployment/ — numero di worker, Redis e limiti massimi per livello in produzione