NextPDF Connect'i yapılandırma

Bir bakışta

NextPDF Connect iki ayrı yapılandırma yüzeyi sunar. Model Context Protocol (MCP) sunucusu bir YAML dosyasını ve NEXTPDF_MCP_* değişkenlerini okur. REST ve gRPC sunucuları NEXTPDF_* ortam değişkenlerini okur. Sunucu başlatıldıktan sonra yapılandırma değiştirilemez hâle gelir.

Kurulum

composer require nextpdf/server

Kavramsal genel bakış

MCP sunucusu yapılandırmayı sabit bir öncelik sırasına göre çözümler. Önceliği en yüksek kaynak geçerli olur:

Ortam değişkenleri (NEXTPDF_MCP_*).
YAML yapılandırma dosyasının nextpdf_mcp bölümü.
Yerleşik varsayılanlar.

YAML dosyasını --config=PATH ile belirtin. Bu seçeneği atladığınızda sunucu yalnızca varsayılanları ve ortam değişkenlerini kullanır. Sonuçta oluşan McpConfig bir readonly değer nesnesidir. Başlatma sonrasında hiçbir ayar değiştirilemez.

REST ve gRPC sunucuları başlatma sırasında HttpConfig değerini ortamdan okur. Ortam üzerinden geçersiz kılma için NEXTPDF_BIND, NEXTPDF_WORKER_COUNT, NEXTPDF_SESSIONS_ENABLED ve NEXTPDF_CORS_ENABLED değişkenlerini destekler. Kalan üst sınırlar güvenli varsayılanları kullanır.

API yüzeyi

MCP yapılandırması (`nextpdf-mcp`)

YAML dosyası, nextpdf_mcp bölümü:

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)

MCP sunucusu için ortam geçersiz kılmaları:

Değişken	Yapılandırma anahtarı	Varsayılan
`NEXTPDF_MCP_ENABLED_TOOLS`	`enabled_tools`	tüm araçlara izin verilir
`NEXTPDF_MCP_TEMP_DIR`	`temp_directory`	sistem geçici dizini + `/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` saniye
`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`	(`parse_pdf` aracını denetler)	ayarlanmamış (devre dışı)
`NEXTPDF_AST_TOOLS_ENABLED`	(AST araçlarını denetler)	etkin
`NEXTPDF_MUTATION_TOOLS_ENABLED`	(AST mutasyon araçlarını denetler)	ayarlanmamış (devre dışı)

REST ve gRPC yapılandırması

Değişken	Varsayılan	Etki
`NEXTPDF_BIND`	`0.0.0.0:8080`	REST dinleme adresi
`NEXTPDF_WORKER_COUNT`	`4`	RoadRunner PHP işçi sayısı
`NEXTPDF_SESSIONS_ENABLED`	`false`	Durum bilgisi taşıyan oturum uç noktalarını etkinleştir
`NEXTPDF_CORS_ENABLED`	`false`	CORS yanıt başlıklarını etkinleştir
`NEXTPDF_API_KEYS`	ayarlanmamış	Satır içi API anahtarı tanımları
`NEXTPDF_API_KEYS_FILE`	ayarlanmamış	API anahtarları dosyasının yolu
`NEXTPDF_JOB_STORE_PATH`	sistem geçici dizini	SQLite iş deposu yolu
`NEXTPDF_REDIS_HOST`	ayarlanmamış	Ayarlandığında Redis destekli depoları etkinleştirir

REST sunucusu, NEXTPDF_REDIS_HOST ayarlandığında ve ext-redis yüklendiğinde Redis’i kullanır:

Değişken	Varsayılan
`NEXTPDF_REDIS_PORT`	`6379`
`NEXTPDF_REDIS_PASSWORD`	boş
`NEXTPDF_REDIS_DATABASE`	`0`
`NEXTPDF_REDIS_PREFIX`	`nextpdf:`
`NEXTPDF_REDIS_CONNECT_TIMEOUT`	`2.0` saniye
`NEXTPDF_REDIS_READ_TIMEOUT`	`2.0` saniye

Kod örneği — hızlı başlangıç

MCP sunucusunu açıkça belirtilen bir yapılandırma dosyasıyla çalıştırın:

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

Kod örneği — üretim

MCP kataloğunu açıkça tanımlanmış bir izin listesiyle kısıtlayın ve bir aracın riskini yükseltin:

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

Boş olmayan bir enabled_tools listesiyle güvenlik politikası yalnızca listelenen araç adlarını kabul eder. Kayıt defteri diğer tüm araçları sessizce atar. Boş bırakılan veya bulunmayan bir liste, mevcut tüm araçları kabul eder.

Sınır durumları ve dikkat edilmesi gerekenler

İki kritik aracın risk seviyesi düşürülemez. output_pdf ve sign_pdf tasarım gereği onaya tabidir: bir risk_level_overrides girdisi bu araçlardan herhangi birini ApprovalRequired seviyesinin altına düşürürse, yükleme sırasında bir InvalidArgumentException fırlatır ve sunucu başlatılmayı reddeder. Diğer her aracın risk seviyesini yükseltebilir veya düşürebilirsiniz; bu nedenle her seviye düşürmeyi kendi tehdit modelinize göre gözden geçirin. Bkz. /connect/hitl-risk-tiers/.
enabled_tools filtre uygular, ekleme yapmaz. nextpdf/premium mevcut değilken bir Pro araç adını listelemek, bu aracın görünmesini sağlamaz. İzin listesi, kayıt defterinin gerçekten keşfettiği araçlarla kesiştirilir.
MCP sunucusunda ortam değişkenleri YAML’ye göre önceliklidir. Bir NEXTPDF_MCP_* değişkeni, YAML dosyasındaki aynı anahtarı geçersiz kılar. REST ve gRPC sunucuları MCP YAML dosyasını hiç okumaz.
parse_pdf isteğe bağlıdır. Sunucu, parse_pdf aracını yalnızca NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED değeri true veya 1 olduğunda kaydeder. Çekirdek katalogda bile varsayılan olarak bulunmaz.

Performans

Yapılandırma, başlatma sırasında bir kez ayrıştırılır. max_documents ve document_ttl ayarları, bellek içi belge deposunu sınırlandırır. Bunları düşürmek en yüksek bellek kullanımını azaltır, ancak belgelerin ömrünü kısaltır. İşçi sayısı ve katman başına yük üst sınırları, dağıtımda ince ayar denetimleridir ve /connect/deployment/ sayfasında ele alınır.

Güvenlik notları

En az ayrıcalıklı dağıtımlar için enabled_tools ayarını varsayılan olarak reddeden bir denetim olarak değerlendirin: yalnızca belirli bir entegrasyonun ihtiyaç duyduğu araçları listeleyin.
API anahtarlarını asla YAML dosyasında saklamayın. NEXTPDF_API_KEYS_FILE ayarını, Docker veya Kubernetes gizli bilgisi olarak bağlanan bir dosyayla kullanın. Sunucu, anlık yeniden yükleme yapan dosya tabanlı depoyu tercih eder; böylece anahtarlar yeniden başlatma gerekmeden döndürülebilir. Bkz. /connect/security-and-operations/.
Dosya çıktısı için zorunlu kılınan temel dizin temp_directory ayarıdır. Sunucu çıktı yollarını normalleştirir ve bu dizinin dışında çözümlenen her şeyi reddeder.

Uygunluk

Bu sayfa, yapılandırma mekaniğini açıklar. Kimlik doğrulama ve aktarım güvenliğiyle ilgili uygunluk atıfları /connect/security-and-operations/ sayfasında sabitlenmiştir.

Ticari bağlam

Katman başına yük ve zaman aşımı üst sınırları (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit ve bunlara karşılık gelen zaman aşımları), kimliği doğrulanmış API anahtarının katmanına göre REST aktarımına uygulanır. Bunlar yalnızca Pro veya Enterprise araçları kurulduğunda ve anahtar bu araçlara yetkili olduğunda etkili olur.

Ayrıca bkz.

/connect/install/ — kurulum ve isteğe bağlı paketler
/connect/boot-and-discovery/ — yapılandırmanın başlatma sırasını nasıl beslediği
/connect/hitl-risk-tiers/ — risk modeli ve yalnızca yükseltme amaçlı geçersiz kılma
/connect/security-and-operations/ — API anahtarı yapılandırması ve aktarım güvenliği
/connect/deployment/ — üretimde işçi sayısı, Redis ve katman üst sınırları