NextPDF Connect'te önyükleme ve keşif

Bir bakışta

Her aktarımın kendi giriş noktası ve önyükleme dizisi vardır. Aktarımlar kayıt defterini, yapılandırmayı ve kapıyı kavram olarak paylaşır. Bağımsız süreçler olarak çalışırlar; bu yüzden birinin başlatılması diğerlerini başlatmaz.

Kurulum

composer require nextpdf/server

Kavramsal genel bakış

MCP önyükleme dizisi

McpServer::create(), Model Context Protocol (MCP) sunucusunu sabit bir sırayla birbirine bağlar. Önce yapılandırmayı yükler, bu yapılandırmadan güvenlik ilkesini oluşturur, araç kayıt defterini kurar ve katman keşfini çalıştırır. Ardından, yapılandırılmış yaşam süresi (TTL) ve kapasiteden bellek içi belge deposunu oluşturur, stdio aktarımını oluşturur ve JSON-RPC protokol işleyicisini onay kapısı ve denetim günlükleyicisiyle birlikte bir araya getirir. Sonra sunucu, oku-işle-yaz döngüsüne girer ve standart giriş dosya sonuna ulaşana kadar çalışır.

REST önyükleme dizisi

HttpServer::create(), ortamdan HttpConfig değerini okur ve komut satırı arabirimi (CLI) geçersiz kılmalarını uygular. Ardından uygulama programlama arabirimi (API) anahtarı deposunu şu tercih sırasıyla çözümler: önce anlık yeniden yükleme yapan dosya deposu, sonra statik dosya, sonra ortam. Ardından hız sınırı ve eşgüçlülük depolarını çözümler. Redis yapılandırılmış ve erişilebilir durumdaysa Redis kullanırlar; aksi takdirde bellek içi depolamaya geri dönerler. Buradan sonra sunucu, paylaşılan SQLite iş deposunu açar, uygulama hizmetlerini oluşturur ve rota tablosunu kurar. Rota tablosu algılanan katmanlardan oluşturulduğu için kurulu paketleri yansıtır. Ardından RoadRunner, çalışan istek döngüsünü yürütür.

gRPC önyükleme dizisi

GrpcServer::create(), aynı anahtar deposunu çözümler, aynı uygulama hizmetlerini oluşturur ve nextpdf.connect.v1 hizmetini Spiral gRPC çalışanıyla kaydeder. Altyapı bağımlılığı kullanılamadığında, gRPC sunucusu yine de başlar ve durum ve yetenek sorgularını yanıtlar. Bu durumda süreç önyüklemeyi reddetmez; bunun yerine, veri taşıyan uzaktan yordam çağrıları (RPC’ler) kontrollü biçimde başarısız olur.

Araç keşfi

Keşif, kayıt defterinin varsayılan kayıt adımıdır. Önce çekirdek katman kaydolur. Pro ve Enterprise sağlayıcıları, sınıfları class_exists() aracılığıyla çözümlenirse daha sonra kaydolur. Birlikte gelen soyut söz dizimi ağacı (AST) ve mutasyon sağlayıcıları, ortam kapılarına bağlı olarak Pro katmanı altında kaydolur. Her kayıt, enabled_tools güvenlik izin listesinden geçirilerek süzülür ve MCP initialize yanıtı, ortaya çıkan katman başına sayıları bildirir. Bkz. /connect/tool-catalog/.

Aktarım keşfi

Tek bir yapılandırma ayarı “aktarımları etkinleştirmez.” Her aktarım ayrı bir giriş noktasıdır. REST ve gRPC’nin her biri ayrı bir RoadRunner profiline sahiptir. Bir dağıtım, aktarımları çalıştırdığı profile göre seçer: REST için .rr.yaml, gRPC için .rr.grpc.yaml veya her ikisi için .rr.full.yaml. Aktarımlar bağımsız süreçler olarak çalışır. Eksik bir MCP istemcisi REST sunucusunu hiçbir zaman engellemez; eksik bir REST istemcisi de MCP’yi hiçbir zaman engellemez. Bkz. /connect/deployment/.

Yapılandırma çözümleme sırası

MCP sunucusu yapılandırmayı şu öncelik sırasıyla çözümler: ortam (NEXTPDF_MCP_*), YAML dosyasının nextpdf_mcp bölümünden önceliklidir; bu bölüm de yerleşik varsayılanlardan önceliklidir. REST ve gRPC sunucuları, HttpConfig değerini güvenli varsayılanlarla birlikte NEXTPDF_* ortam değişkenlerinden okur. MCP YAML dosyasını okumazlar. Bkz. /connect/configuration/.

Kapsayıcı bağlamaları

Kaydedilecek bir bağımlılık enjeksiyonu kapsayıcısı veya hizmet sağlayıcı yoktur. Her create() fabrikası, kendi nesne grafiğini açık ve belirlenimci biçimde kurar. Enjekte edilebilen iki ek noktası vardır — aktarım ve çalışan fabrikası — ve ikisi de uygulama bağlantısı için değil, test için kullanılır.

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

Trafiğe hizmet vermeden keşfin ne ürettiğini inceleyin:

./vendor/bin/generate-skills --dry-run --list-tools

Kod örneği — üretim

Birleştirilmiş aktarımları tek bir denetçi altında önyükleyin:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

Sınır durumları ve dikkat edilmesi gerekenler

• Eksik bir katman önyüklemeyi başarısız kılmaz. Katman keşfi, bulunmayan bir Pro veya Enterprise paketini sessizce atlar. Sunucu, çekirdek katalogla önyüklenir.

• Bir düşürme geçersiz kılması önyüklemeyi başarısız kılar. risk_level_overrides içinde, approval_required olan bir aracı zayıflatan bir girdi, yapılandırma yüklemesi sırasında özel durum fırlatır; sunucu başlamayı reddeder. Bu, bilinçli bir tasarım tercihidir.

• Redis arızası işlevselliği düşürür, çökmeye yol açmaz. Redis yapılandırılmış ancak önyükleme sırasında erişilemez durumdaysa, REST sunucusu bellek içi depolara geri döner. Redis’in kullanımda olduğunu varsaymak yerine Redis durumunu doğrulayın.

Performans

Önyükleme maliyeti; yapılandırmanın ayrıştırılmasından, kayıt defterinin taranmasından ve katmanların algılanmasından kaynaklanır. Sayfanın performance_budget değeri bu maliyeti sınırlar. Maliyet, istek başına değil, süreç başlatma başına bir kez ödenir.

Güvenlik notları

Güvenlik ilkesi kayıt defterinden önce oluşturulur; bu nedenle enabled_tools izin listesi, keşfi ilk kayıttan itibaren kısıtlar. API anahtarları hiçbir zaman MCP YAML dosyasından okunmaz; ağ üzerinden çalışan aktarımlar anahtarları bir gizli dosyadan veya ortamdan çözümler. Bkz. /connect/security-and-operations/.

Uygunluk

Bu sayfa, önyükleme mekaniğini açıklar. Protokol ve güvenlik kaynakları şu sayfalara sabitlenmiştir: /transports/mcp/, /transports/rest/, /transports/grpc/ ve /connect/security-and-operations/.

Ticari bağlam

Önyükleme sırasındaki katman algılama, nextpdf/premium öğesinin, nextpdf/premium sunucuyla birlikte kurulu olduğunda Pro ve Enterprise araçlarını kataloğa kattığı tek noktadır.

Ayrıca bkz.

• /connect/tool-catalog/ — keşfin neleri kaydettiği ve sayının neden değiştiği
• /connect/configuration/ — çözümleme sırası ayrıntılı olarak
• /connect/deployment/ — RoadRunner profilleri aracılığıyla aktarımların seçilmesi
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — aktarım başına ayrıntı