NextPDF Connect — MCP taşıma katmanı

Bir bakışta

Model Context Protocol (MCP) taşıma katmanı, bin/nextpdf-mcp dosyasını yerel bir alt süreç olarak çalıştırır. Standart girdi ve çıktı üzerinden JSON-RPC 2.0 ile iletişim kurar. Sunucu, tarih tabanlı sürümlendirilmiş MCP revizyonu 2025-06-18’i uygular.

Kurulum

composer require nextpdf/server

Kavramsal genel bakış

MCP stdio modelinde istemci, sunucuyu alt süreç olarak başlatır. İstemci, satır sonlarıyla ayrılmış JSON-RPC iletileri alıp verir: satır başına bir ileti, gömülü satır sonu olmadan ve UTF-8 kodlamasıyla. Sunucu, standart çıktıya yalnızca geçerli MCP iletileri yazar ve günlükleri standart hataya gönderir. Uygulama, denetim günlükleyicisini standart hataya yönlendirir; böylece günlük satırları protokol akışını asla bozmaz. Bu çerçevelemeyi, resmi MCP belirtiminin 2025-06-18 revizyonu tanımlar. Bu belirtim, kapılı standartlar derlemesinin bir parçası değildir; bu nedenle URL ile gösterilir: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports.

NextPDF Connect, stdio taşıma katmanını uygular. MCP belirtimi ayrıca bir Streamable HTTP taşıma katmanı da tanımlar. Belirtim, istemcilerin mümkün olduğunda stdio’yu desteklemesi gerektiğini ve bir sunucunun yalnızca stdio’yu uygulayabileceğini belirtir. Aynı araçlara ağ üzerinden erişmek için bunun yerine REST veya gRPC taşıma katmanlarından birini kullanın; bkz. /transports/rest/ ve /transports/grpc/.

API yüzeyi

Yöntemler

Yöntem	Davranış
`initialize`	Protokol sürümünü, yetenekleri ve sunucu bilgilerini döndürür
`notifications/initialized`	Bir bildirim (`id` yok); yanıt verilmeden kabul edilir
`tools/list`	Kayıtlı araçları, isteğe bağlı bir `params.category` filtresiyle listeler
`tools/call`	Aracı `params.name` ile çalıştırır; bağımsız değişkenler: `params.arguments`

Başka herhangi bir yöntem için yöntem-bulunamadı (-32601) döndürülür. Geçerli JSON-RPC 2.0 biçiminde olmayan bir ileti için geçersiz-istek (-32600) döndürülür; ayrıştırılamayan girdi için ayrıştırma-hatası (-32700) döndürülür. Yinelenen bir istek id değeri alındığında, istek yeniden çalıştırılmadan 64 girişli bir arabellekten önbelleğe alınmış önceki yanıt döndürülür.

initialize yanıtı

Sunucu, initialize sonucunda protocolVersion 2025-06-18, serverInfo.name: NextPDF Connect ve bir capabilities nesnesi döndürür. Standart tools yeteneğine ek olarak sunucu, capabilities.nextpdf bloğu ekler:

tiers — katman bazında çalışma zamanındaki kayıtlı araç sayıları (core / pro / enterprise).
tool_count — çalışma zamanında hesaplanan, kayıtlı araçların toplam sayısı.
risk_model_version — sunucunun uyguladığı risk modeli sürümü.
hitl_enabled — true; onay kapısı etkindir.

tool_count, bu dağıtım için referans alınacak sayıdır. Bu, belgelenmiş bir sabit değil, çalışma zamanında yapılan sayımdır; bkz. /connect/tool-catalog/.

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

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

Kod örneği — üretim

Kategori filtresi, kataloğu tek bir alanla sınırlar:

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"category":"diagnostic"}}
EOF

Kategori değerleri, her aracın bildirdiği kategoriden gelir (örneğin document, diagnostic).

Sınır durumları ve dikkat edilmesi gerekenler

API anahtarı yok. stdio taşıma katmanının ağ dinleyicisi de taşıyıcı belirteci de yoktur. MCP stdio modeline göre işletim sistemi süreç sınırını güven sınırı olarak kabul edin. Bu taşıma katmanını bir ağa köprülemeyin.
Onay zorlukları bant içidir. Bir ApprovalRequired aracı, başarılı bir JSON-RPC yanıtı döndürür. Yanıt içeriği bir hata değil; zorluk metni ve tek kullanımlık bir belirteçtir. Bkz. /connect/hitl-risk-tiers/.
Bildirimler sessizdir. id içermeyen bir ileti hiçbir yanıt üretmez. El sıkışma sırası şudur: initialize (id ile), ardından initialized bildirimi, sonra da id taşıyan çağrılar.

Performans

MCP sunucusu tek bir süreç olarak çalışır ve borular üzerinden aynı anda bir istek işler. Ağ gidiş-dönüşü yoktur; gecikmeyi esas olarak alttaki motor işlemi belirler.

Güvenlik notları

Taşıma katmanı, onu başlatan istemcinin güven bağlamını devralır. Alt süreci yerel tutun. API anahtarı bulunmasa bile yüksek riskli araçlar insan onayı gerektirmeye devam eder. Bkz. /connect/security-and-operations/.

Uygunluk

stdio çerçevelemesi ve initialize/lifecycle davranışı, resmi Model Context Protocol belirtiminin 2025-06-18 revizyonuna uygundur:

Taşıma katmanları: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
Yaşam döngüsü: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

MCP belirtimi, kapılı standartlar derlemesinde yer almaz; bu nedenle bir reference_id değeri yoktur; yukarıdaki resmi URL’ler kayıt referansıdır.

Ticari bağlam

tools/list, Pro ve Enterprise araçlarını yalnızca sunucuyla birlikte nextpdf/premium kurulu olduğunda döndürür. Hangi katmanların kurulu olduğundan bağımsız olarak taşıma katmanının kendisi aynıdır.

Ayrıca bkz.

/connect/quickstart/ — çalıştırılabilir el sıkışma örneği
/connect/tool-catalog/ — tools/list ne döndürür ve sayılar neden değişir
/connect/hitl-risk-tiers/ — onay zorluğu biçimi
/transports/rest/ · /transports/grpc/ — ağ üzerinden çalışan alternatifler
/connect/migrating-to-multi-transport/ — yalnızca MCP kullanan bir tümleştirmeyi REST/gRPC’ye taşıma