NextPDF Connect sunucusuna genel bakış

Bir bakışta

NextPDF Connect, NextPDF PDF 2.0 motorunu yapay zeka aracılarına ve HTTP istemcilerine sunan, uzun süre çalışan bir hizmet olan nextpdf/server paketidir. Üç taşıyıcı kullanır: stdio üzerinden Model Context Protocol (MCP), bir REST API ve gRPC. Üç taşıyıcının tamamı tek bir araç kayıt defterini ve tek bir insan onaylı (HITL) doğrulama kapısını paylaşır.

Kurulum

composer require nextpdf/server

Composer kısıtı, nextpdf/core: ^3.0 ile birlikte php: >=8.4 <9.0 şeklindedir. Eksiksiz kurulum adımları için /connect/install/ sayfasına bakın. O sayfa iki isteğe bağlı eklentiyi de kapsar: ext-redis uzantısı ve nextpdf/premium paketi.

Kavramsal genel bakış

nextpdf/server, çatıdan bağımsız NextPDF çekirdeğini bir hizmet yüzeyine uyarlar. PDF oluşturmayı yeniden inşa etmez. Bunun yerine motorun her yeteneğini, kendi şemasına sahip adlandırılmış bir araç olarak sarmalar ve ardından bu kataloğu çeşitli ağ protokolleri üzerinden sunar.

Tüm tasarım üç kavram üzerine oturur:

Araç kayıt defteri. NextPDF\Server\ToolRegistry, başlatılırken araçları bulur ve kaydeder. Paket bir çekirdek küme içerir ve bu küme her zaman kullanılabilir durumdadır. Pro ve Enterprise sağlayıcıları ek araçlar kaydeder, ancak bunu yalnızca eşleşen paketler kurulu olduğunda yapar. Sunulan araçların sayısı sabit bir değer değil, dağıtımın çalışma zamanına ait bir özelliğidir. /connect/tool-catalog/ sayfasına bakın.
Taşıyıcılar. Aynı kayıt defteri üç farklı şekilde sunulur. MCP, yerel yapay zeka istemcileri için stdio üzerinden çalışır. REST, ağ üzerinden bağlanan istemciler için bir RoadRunner çalışan havuzunda, PSR-15 ara katman işlem hattı üzerinden çalışır. gRPC ise tipli veya akışlı istemciler için bir Spiral RoadRunner gRPC çalışanı üzerinde çalışır. Her taşıyıcı, kendi giriş noktasına sahip ayrı bir süreçtir. /transports/mcp/, /transports/rest/ ve /transports/grpc/ sayfalarına bakın.
Doğrulama kapısı. Her araç bir risk düzeyi bildirir. En yüksek risk düzeyindeki bir araç, çalışmadan önce açık bir insan onayı gerektirir. Kapı, tek kullanımlık bir onay belirteci verir. Çağıran aracı, bu belirteci bir insana iletmeli ve ardından aynı aracı belirteçle birlikte yeniden çağırmalıdır. /connect/hitl-risk-tiers/ sayfasına bakın.

Aşağıdaki şema, tek bir kayıt defterinin üç taşıyıcıya nasıl ulaştığını gösterir. Ayrıca doğrulama kapısının istek yolunda nerede konumlandığını da gösterir.

NextPDF Connect component architecture

Paket Apache-2.0 lisansıyla sunulur ve bu lisans nextpdf/core ile eşleşir. Uygulanan MCP protokolü sürümü, tarihle sürümlenen 2025-06-18 revizyonudur. REST yüzeyini bir OpenAPI 3.1 belgesi tanımlar. gRPC yüzeyini ise nextpdf.connect.v1 Protocol Buffers paketi tanımlar.

API yüzeyi

Genel giriş noktaları üç sunucu sınıfıdır. Her biri için bir komut satırı arabirimi (CLI) sarmalayıcısı bulunur:

Giriş noktası	Sınıf	Taşıyıcı
`bin/nextpdf-mcp`	`NextPDF\Server\Mcp\McpServer`	stdio üzerinden MCP
`bin/nextpdf-server`	`NextPDF\Server\Http\HttpServer`	RoadRunner HTTP üzerinden REST
`bin/nextpdf-grpc`	`NextPDF\Server\Grpc\GrpcServer`	RoadRunner gRPC üzerinden gRPC
`bin/generate-skills`	`NextPDF\Server\Skills\SkillsDumper`	Araç kataloğu dışa aktarımı

McpServer::create(), HttpServer::create() ve GrpcServer::create() yöntemlerinin her biri, ortam ve yapılandırma girdilerini kullanarak tamamen yapılandırılmış bir sunucu oluşturur. Kayıt defteri, belge deposu, güvenlik ilkesi ve doğrulama kapısı üç sunucunun tamamında paylaşılan kavramlardır.

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

En basit MCP sunucusu için tek komut yeterlidir; herhangi bir PHP bağlama kodu yazmazsınız:

./vendor/bin/nextpdf-mcp

Sunucu, JSON-RPC isteklerini standart girişten okur ve yanıtları standart çıkışa yazar. Çalıştırılabilir initialize ve tools/list alışverişi ile buna karşılık gelen REST isteği için /connect/quickstart/ sayfasına bakın.

Sınır durumları ve dikkat edilmesi gerekenler

Araç sayısı 33 değildir; başka herhangi bir sabit sayı da değildir. Sunucu, araçları çalışma zamanında, ilke filtrelemesi ve katman algılaması sonrasında count(ToolRegistry::all()) ile sayar. Sabit toplam değer veren belgeler güncelliğini yitirmiştir. Doğru sayıyı almak için çalışan sunucuyu sorgulayın. MCP initialize yanıtını veya REST /api/v1/capabilities uç noktasını kullanın.

Sunulan araçların sayısı, kurulu paketlere ve etkin ilkeye bağlıdır. Bu sayıyı çalışma zamanında, çalışan sunucudan okuyun. Kodunuzdaki veya belgelerinizdeki sabit bir sayı güncelliğini yitirir.
Eksik bir Pro veya Enterprise paketi bir hata değildir. Kayıt defteri, sağlayıcı sınıflarını class_exists() ile denetler, ardından bulunmayan katmanları sessizce atlar. Yalnızca açık kaynak bileşenlerden oluşan bir dağıtım normal şekilde başlatılır ve çekirdek kataloğunu sunar.
Üç taşıyıcı aynı süreci paylaşmaz. MCP sunucusunu çalıştırmak, REST sunucusunu veya gRPC sunucusunu başlatmaz. Tersi de geçerlidir. Birleşik bir dağıtım, RoadRunner gözetmenini her iki çalışan havuzunu da (HTTP havuzunu ve gRPC havuzunu) başlatan bir yapılandırmayla çalıştırır. /connect/deployment/ sayfasına bakın.

Performans

Her taşıyıcı çalışan tabanlıdır. Bir çalışan, her seferinde tek bir isteği işler. REST ve gRPC sunucuları RoadRunner çalışan havuzları üzerinde çalışır ve havuz boyutu yapılandırma tarafından belirlenir. Varsayılan değer, dört HTTP çalışanıdır. RoadRunner gözetmeni, her çalışanın belleğine bir üst sınır koyar. Bu sayfadaki performance_budget alanı, soğuk başlatma ve keşif zarfını tanımlar. Bu, istek başına bir hedef değildir. İstek maliyetinin çoğunu, altta çalışan motor işlemi belirler.

Güvenlik notları

Ağ üzerinden çalışan tüm taşıyıcılar, uygulama programlama arabirimi (API) anahtarını taşıyıcı belirteç olarak kullanarak kimlik doğrulaması yapar. MCP stdio taşıyıcısı, MCP taşıyıcı modelinde başlatan istemcinin güvendiği yerel bir alt süreçtir. Yüksek riskli araçlar her taşıyıcıda insan onayı olmadan kapalı kalır. Tam tehdit modeli, kimlik doğrulama modeli ve taşıyıcı güvenliği yapılandırması için /connect/security-and-operations/ sayfasına bakın.

Uygunluk

Bu sayfa yalnızca mimari iddialarda bulunur. Davranışı belirleyen normatif protokol ve güvenlik kaynakları şu sayfalara sabitlenmiştir: /connect/security-and-operations/, /transports/mcp/, /transports/rest/ ve /transports/grpc/. MCP yaşam döngüsü kaynağı, modelcontextprotocol.io adresindeki resmi belirtimdir (revizyon 2025-06-18). MCP belirtimi, erişimi kısıtlı standartlar derlemesinin bir parçası olmadığından, taşıyıcı sayfaları bu kaynağı URL’siyle birlikte kaydeder.

Ticari bağlam

Çekirdek katalog, belge oluşturma, inceleme ve tanılama için eksiksizdir. İmzalama, karartma, uyumluluk sertifikalandırması ve adli analiz için kullanılan araçlar yalnızca nextpdf/premium sunucuyla birlikte kurulduğunda görünür. Bu, çalışma zamanında bir ek satış istemi değil, bir paketleme sınırıdır. Sunucu hiçbir zaman pazarlama içeriği sunmaz.

Ayrıca bakınız

/connect/install/ — kurulum ve isteğe bağlı paketler
/connect/quickstart/ — ilk çalıştırılabilir MCP ve REST alışverişi
/connect/tool-catalog/ — doğrulanmış çekirdek araç kümesi ve sayının çalışma zamanına nasıl bağlı olduğu
/connect/hitl-risk-tiers/ — doğrulama kapısı ve risk modeli
/transports/mcp/, /transports/rest/, /transports/grpc/ — taşıyıcı başına kurulum
/connect/security-and-operations/ — kimlik doğrulama, taşıyıcı güvenliği, tehdit modeli
/connect/deployment/ — RoadRunner, Docker ve birleşik taşıyıcı dağıtımı