NextPDF Connect configureren

In het kort

NextPDF Connect heeft twee configuratievlakken. De Model Context Protocol (MCP)-server leest een YAML-bestand en NEXTPDF_MCP_*-variabelen. De REST- en gRPC-servers lezen NEXTPDF_*-omgevingsvariabelen. De configuratie ligt vast zodra de server is opgestart.

Installatie

composer require nextpdf/server

Conceptueel overzicht

De MCP-server bepaalt de configuratie in een vaste prioriteitsvolgorde. De bron met de hoogste prioriteit wint:

Omgevingsvariabelen (NEXTPDF_MCP_*).
De sectie nextpdf_mcp van het YAML-configuratiebestand.
Ingebouwde standaardwaarden.

Geef het YAML-bestand mee met --config=PATH. Als je het weglaat, gebruikt de server uitsluitend standaardwaarden en omgevingsvariabelen. De resulterende McpConfig is een readonly value object. Geen enkele instelling kan na het opstarten nog worden gewijzigd.

De REST- en gRPC-servers lezen HttpConfig bij het opstarten uit de omgeving. Ze ondersteunen NEXTPDF_BIND, NEXTPDF_WORKER_COUNT, NEXTPDF_SESSIONS_ENABLED en NEXTPDF_CORS_ENABLED als overrides via omgevingsvariabelen. Voor de overige bovengrenzen gelden veilige standaardwaarden.

API-oppervlak

MCP-configuratie (`nextpdf-mcp`)

YAML-bestand, sectie 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)

Overrides via omgevingsvariabelen voor de MCP-server:

Variabele	Configuratiesleutel	Standaard
`NEXTPDF_MCP_ENABLED_TOOLS`	`enabled_tools`	alle tools toegestaan
`NEXTPDF_MCP_TEMP_DIR`	`temp_directory`	systeemtemp + `/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` seconden
`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`	(beperkt `parse_pdf`)	niet ingesteld (uitgeschakeld)
`NEXTPDF_AST_TOOLS_ENABLED`	(beperkt AST-tools)	ingeschakeld
`NEXTPDF_MUTATION_TOOLS_ENABLED`	(beperkt AST-mutatietools)	niet ingesteld (uitgeschakeld)

REST- en gRPC-configuratie

Variabele	Standaard	Effect
`NEXTPDF_BIND`	`0.0.0.0:8080`	REST-luisteradres
`NEXTPDF_WORKER_COUNT`	`4`	Aantal RoadRunner PHP-workers
`NEXTPDF_SESSIONS_ENABLED`	`false`	Stateful sessie-endpoints inschakelen
`NEXTPDF_CORS_ENABLED`	`false`	CORS-responsheaders inschakelen
`NEXTPDF_API_KEYS`	niet ingesteld	Inline API-sleuteldefinities
`NEXTPDF_API_KEYS_FILE`	niet ingesteld	Pad naar een bestand met API-sleutels
`NEXTPDF_JOB_STORE_PATH`	systeem-temp	Pad naar de SQLite-jobopslag
`NEXTPDF_REDIS_HOST`	niet ingesteld	Schakelt Redis-gebaseerde opslag in als dit is ingesteld

De REST-server gebruikt Redis wanneer NEXTPDF_REDIS_HOST is ingesteld en ext-redis is geladen:

Variabele	Standaard
`NEXTPDF_REDIS_PORT`	`6379`
`NEXTPDF_REDIS_PASSWORD`	leeg
`NEXTPDF_REDIS_DATABASE`	`0`
`NEXTPDF_REDIS_PREFIX`	`nextpdf:`
`NEXTPDF_REDIS_CONNECT_TIMEOUT`	`2.0` seconden
`NEXTPDF_REDIS_READ_TIMEOUT`	`2.0` seconden

Codevoorbeeld — Snel starten

Start de MCP-server met een expliciet configuratiebestand:

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

Codevoorbeeld — Productie

Beperk de MCP-catalogus tot een expliciete allowlist en verhoog het risiconiveau van een tool:

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

Wanneer enabled_tools niet leeg is, laat het beveiligingsbeleid alleen de vermelde toolnamen toe. Het register filtert stilzwijgend alle andere tools weg. Een lege of ontbrekende lijst laat alle beschikbare tools toe.

Randgevallen en valkuilen

De twee kritieke tools kunnen niet worden gedegradeerd. output_pdf en sign_pdf zijn by design aan goedkeuring gebonden: een risk_level_overrides-vermelding die een van beide tools onder ApprovalRequired brengt, veroorzaakt bij het laden een InvalidArgumentException, waardoor de server niet opstart. Je kunt het risiconiveau van elke andere tool verhogen of verlagen; toets daarom elke degradatie aan je eigen dreigingsmodel. Zie /connect/hitl-risk-niveaus/.
enabled_tools filtert; het voegt niets toe. Als je een Pro-toolnaam vermeldt terwijl nextpdf/premium ontbreekt, maakt dat die tool niet beschikbaar. De effectieve allowlist is de doorsnede van die lijst en de tools die het register daadwerkelijk heeft ontdekt.
Omgevingsvariabelen winnen van YAML voor de MCP-server. Een NEXTPDF_MCP_*-variabele overschrijft dezelfde sleutel in het YAML-bestand. De REST- en gRPC-servers lezen het MCP-YAML-bestand helemaal niet.
parse_pdf is opt-in. De server registreert de tool parse_pdf alleen wanneer NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED true of 1 is. Standaard is de tool afwezig, zelfs in de core-catalogus.

Prestaties

De configuratie wordt eenmalig bij het opstarten geparseerd. De instellingen max_documents en document_ttl begrenzen de in-memory-documentopslag. Lagere waarden verminderen het piekgeheugen, maar verkorten de levensduur van documenten. Het aantal workers en de payload-bovengrenzen per niveau zijn parameters waarmee je de implementatie afstemt; /connect/deployment/ behandelt ze.

Beveiligingsnotities

Behandel enabled_tools als deny-by-default-controle voor least-privilege-implementaties: vermeld alleen de tools die een bepaalde integratie nodig heeft.
Bewaar API-sleutels nooit in het YAML-bestand. Gebruik NEXTPDF_API_KEYS_FILE met een bestand dat als Docker- of Kubernetes-secret is aangekoppeld. De server gebruikt bij voorkeur hot-reloading bestandsopslag, zodat sleutels zonder herstart kunnen roteren. Zie /connect/security-and-operations/.
De temp_directory is de afgedwongen basismap voor bestandsuitvoer. De server canonicaliseert uitvoerpaden en weigert alles waarvan het pad buiten die map uitkomt.

Conformiteit

Deze pagina beschrijft de werking van de configuratie. Conformiteitsverwijzingen voor authenticatie en transportbeveiliging zijn vastgelegd in /connect/security-and-operations/.

Commerciële context

Payload- en time-outbovengrenzen per niveau (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit en de bijbehorende time-outs) gelden voor het REST-transport op basis van het niveau van de geauthenticeerde API-sleutel. Ze gelden alleen wanneer Pro- of Enterprise-tools zijn geïnstalleerd en de sleutel daarvoor is geautoriseerd.

Zie ook

/connect/install/ — installatie en optionele pakketten
/connect/boot-and-discovery/ — hoe de configuratie de opstartsequentie aanstuurt
/connect/hitl-risk-niveaus/ — het risicomodel en de upgrade-only override
/connect/security-and-operations/ — API-sleutelconfiguratie en transportbeveiliging
/connect/deployment/ — aantal workers, Redis en bovengrenzen per niveau in productie