NextPDF Connect konfigurieren

Auf einen Blick

NextPDF Connect verfügt über zwei Konfigurationsbereiche. Der MCP-Server liest eine YAML-Datei sowie NEXTPDF_MCP_*-Variablen. Die REST- und gRPC-Server lesen NEXTPDF_*-Umgebungsvariablen. Nach dem Serverstart ist die Konfiguration unveränderlich.

Installation

composer require nextpdf/server

Konzeptioneller Überblick

Der MCP-Server löst die Konfiguration in einer festen Prioritätsreihenfolge auf. Die Quelle mit der höchsten Priorität gewinnt:

Umgebungsvariablen (NEXTPDF_MCP_*).
Der nextpdf_mcp-Abschnitt der YAML-Konfigurationsdatei.
Eingebaute Standardwerte.

Übergeben Sie die YAML-Datei mit --config=PATH. Ist keine Datei angegeben, verwendet der Server nur Standardwerte und Umgebungsvariablen. Das resultierende McpConfig ist ein readonly Value Object. Nach dem Start bleibt jede Einstellung unverändert.

Die REST- und gRPC-Server lesen HttpConfig beim Start aus der Umgebung ein. Die unterstützten Umgebungs-Overrides sind NEXTPDF_BIND, NEXTPDF_WORKER_COUNT, NEXTPDF_SESSIONS_ENABLED und NEXTPDF_CORS_ENABLED. Für alle übrigen Obergrenzen gelten sichere Standardwerte.

API-Oberfläche

MCP-Konfiguration (`nextpdf-mcp`)

YAML-Datei, nextpdf_mcp-Abschnitt:

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)

Umgebungs-Overrides für den MCP-Server:

Variable	Konfigurationsschlüssel	Standard
`NEXTPDF_MCP_ENABLED_TOOLS`	`enabled_tools`	alle Tools erlaubt
`NEXTPDF_MCP_TEMP_DIR`	`temp_directory`	System-Temp + `/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` Sekunden
`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`	(steuert `parse_pdf`)	nicht gesetzt (deaktiviert)
`NEXTPDF_AST_TOOLS_ENABLED`	(steuert AST-Tools)	aktiviert
`NEXTPDF_MUTATION_TOOLS_ENABLED`	(steuert AST-Mutation-Tools)	nicht gesetzt (deaktiviert)

REST- und gRPC-Konfiguration

Variable	Standard	Wirkung
`NEXTPDF_BIND`	`0.0.0.0:8080`	REST-Listen-Adresse
`NEXTPDF_WORKER_COUNT`	`4`	Anzahl der RoadRunner-PHP-Worker
`NEXTPDF_SESSIONS_ENABLED`	`false`	Zustandsbehaftete Session-Endpunkte aktivieren
`NEXTPDF_CORS_ENABLED`	`false`	CORS-Response-Header aktivieren
`NEXTPDF_API_KEYS`	nicht gesetzt	Inline-API-Key-Definitionen
`NEXTPDF_API_KEYS_FILE`	nicht gesetzt	Pfad zu einer API-Keys-Datei
`NEXTPDF_JOB_STORE_PATH`	System-Temp	Pfad zum SQLite-Job-Store
`NEXTPDF_REDIS_HOST`	nicht gesetzt	Aktiviert Redis-gestützte Stores, sobald gesetzt

Redis (vom REST-Server verwendet, wenn NEXTPDF_REDIS_HOST gesetzt und ext-redis geladen ist):

Variable	Standard
`NEXTPDF_REDIS_PORT`	`6379`
`NEXTPDF_REDIS_PASSWORD`	leer
`NEXTPDF_REDIS_DATABASE`	`0`
`NEXTPDF_REDIS_PREFIX`	`nextpdf:`
`NEXTPDF_REDIS_CONNECT_TIMEOUT`	`2.0` Sekunden
`NEXTPDF_REDIS_READ_TIMEOUT`	`2.0` Sekunden

Codebeispiel — Schnellstart

Starten Sie den MCP-Server mit einer expliziten Konfigurationsdatei:

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

Codebeispiel — Produktion

Beschränken Sie den MCP-Katalog auf eine explizite Allowlist und heben Sie das Risiko eines Tools an:

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

Wenn enabled_tools nicht leer ist, lässt die Sicherheitsrichtlinie nur die aufgeführten Tool-Namen zu. Alle anderen Tools werden stillschweigend aus der Registry entfernt. Eine leere oder fehlende Liste lässt alle verfügbaren Tools zu.

Randfälle und Stolperfallen

Die beiden kritischen Tools lassen sich nicht herabstufen. output_pdf und sign_pdf sind designbedingt approval-gated: Ein risk_level_overrides-Eintrag, der eines der beiden unter ApprovalRequired absenkt, löst beim Laden eine InvalidArgumentException aus; der Server verweigert den Start. Das Risiko jedes anderen Tools lässt sich anheben oder absenken; prüfen Sie daher jede Herabstufung gegen Ihr eigenes Bedrohungsmodell. Siehe /connect/hitl-risk-tiers/.
enabled_tools filtert, es fügt nichts hinzu. Ein aufgeführter Pro-Tool-Name erscheint nicht, wenn nextpdf/premium fehlt. Die Allowlist wird mit den tatsächlich von der Registry gefundenen Tools geschnitten.
Beim MCP-Server hat die Umgebung Vorrang vor YAML. Eine NEXTPDF_MCP_*-Variable überschreibt denselben Schlüssel in der YAML-Datei. Die REST- und gRPC-Server lesen die MCP-YAML-Datei überhaupt nicht.
parse_pdf ist Opt-in. Das parse_pdf-Tool wird nur registriert, wenn NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED true oder 1 ist. Standardmäßig fehlt es selbst im Core-Katalog.

Performance

Die Konfiguration wird beim Start einmal geparst. Die Einstellungen max_documents und document_ttl begrenzen den In-Memory-Dokument-Store. Niedrigere Werte reduzieren den Spitzenspeicher, verkürzen aber die Dokumentlebensdauer. Worker-Anzahl und Payload-Obergrenzen pro Stufe sind Deployment-Tuning-Hebel und werden unter /connect/deployment/ behandelt.

Sicherheitshinweise

Behandeln Sie enabled_tools in Deployments mit minimalen Rechten als standardmäßig verweigernde Steuerungsfläche: Listen Sie nur die Tools auf, die eine bestimmte Integration benötigt.
Speichern Sie API-Keys niemals in der YAML-Datei. Nutzen Sie NEXTPDF_API_KEYS_FILE mit einer Datei, die als Docker- oder Kubernetes-Secret eingebunden ist. Der Server verwendet bevorzugt einen Hot-Reloading-File-Store, damit Keys ohne Neustart rotiert werden können. Siehe /connect/security-and-operations/.
Das temp_directory dient als erzwungenes Basisverzeichnis für die Dateiausgabe. Der Server kanonisiert Ausgabepfade und lehnt alles ab, was außerhalb davon aufgelöst wird.

Konformität

Diese Seite beschreibt die Mechanik der Konfiguration. Konformitätszitate zu Authentifizierung und Transportsicherheit sind unter /connect/security-and-operations/ verankert.

Kommerzieller Kontext

Payload- und Timeout-Obergrenzen pro Stufe (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit und die zugehörigen Timeouts) gelten für den REST-Transport entsprechend der Stufe des authentifizierten API-Keys. Sie greifen nur, wenn Pro- oder Enterprise-Tools installiert sind und der Key dazu berechtigt ist.

Siehe auch

/connect/install/ — Installation und optionale Pakete
/connect/boot-and-discovery/ — Einbindung der Konfiguration in die Boot-Sequenz
/connect/hitl-risk-tiers/ — das Risikomodell und das nur aufwärts gerichtete Override
/connect/security-and-operations/ — API-Key-Konfiguration und Transportsicherheit
/connect/deployment/ — Worker-Anzahl, Redis und Stufen-Obergrenzen in Produktionsumgebungen