Panduan pengembang NextPDF Connect

Sekilas pandang

NextPDF Connect (nextpdf/server) membungkus mesin PDF 2.0 NextPDF yang tidak terikat framework sebagai layanan. Layanan ini tidak mengimplementasikan ulang pembuatan PDF. Ia memaparkan setiap kapabilitas mesin sebagai tool bernama dengan skema, lalu menyajikan katalog tersebut melalui tiga transport: Model Context Protocol (MCP) di atas standard input dan output, Representational State Transfer (REST) Application Programming Interface (API), dan gRPC. Gunakan panduan ini saat Anda membangun integrasi terhadap server, memperluas kumpulan tool-nya, atau menjalankannya di produksi.

Tiga konsep mendefinisikan desain ini: tool registry, ketiga transport yang independen, dan gerbang konfirmasi human-in-the-loop (HITL). Halaman ini menjelaskan bagaimana ketiganya saling terkait dan cara bekerja dengannya tanpa melemahkan model keamanan. Untuk simbol tool, remote procedure call (RPC), dan message yang persis, lihat referensi API.

Prasyarat: PHP 8.4, Composer 2, dan — untuk transport berjaringan — biner RoadRunner serta setidaknya satu API key. Pasang dengan composer require nextpdf/server.

Batas arsitektur

Jaga setiap tanggung jawab tetap berada di sisi batas yang tepat. Sebuah tool adalah pembungkus tipis di sekitar panggilan mesin; ia tidak boleh memuat interpretasi tata letak, semantik dokumen, atau logika transformasi.

Lapisan	Dimiliki oleh	Tanggung jawab	Jangan tempatkan di sini
Client atau agen	Integrasi Anda	Pilih tool yang akan dipanggil; teruskan tantangan konfirmasi kepada manusia.	Logika mesin atau deteksi tier.
Transport	`nextpdf/server`	Format permintaan sebagai JSON-RPC, HTTP, atau Protocol Buffers; lakukan autentikasi; dan rutekan ke eksekutor tool.	Semantik dokumen.
Tool registry	`nextpdf/server`	Temukan tier, daftarkan tool yang tunduk pada allowlist keamanan, dan cari tool berdasarkan nama.	Pembuatan PDF.
Tool	`nextpdf/server`	Validasi argumen terhadap skema input dan panggil mesin.	Interpretasi tata letak atau orkestrasi multi-langkah.
Gerbang konfirmasi	`nextpdf/server`	Tahan operasi `ApprovalRequired` hingga manusia menyetujuinya.	Autentikasi pemanggil.
Mesin	`nextpdf/core` (dan `nextpdf/premium`)	Buat, periksa, dan transformasikan konten PDF.	Urusan transport atau autentikasi.

Siklus hidup runtime

Setiap transport memiliki entry point dan boot factory masing-masing. Masing-masing membangun graf objeknya secara eksplisit. Tidak ada dependency-injection container yang perlu didaftarkan.

Muat konfigurasi. Server MCP menyelesaikan konfigurasi secara berurutan dari variabel lingkungan (NEXTPDF_MCP_*), bagian nextpdf_mcp pada berkas YAML, lalu nilai standar bawaan, dan menghasilkan sebuah readonlyMcpConfig. Server REST dan gRPC membaca HttpConfig dari variabel lingkungan NEXTPDF_*. Lihat Konfigurasi.
Bangun kebijakan keamanan. Allowlist enabled_tools dibangun sebelum registry, sehingga ia membatasi penemuan sejak pendaftaran pertama.
Bangun registry dan temukan tool. ToolRegistry::registerDefaults() mendaftarkan tier core, lalu provider Pro dan Enterprise ketika kelas-kelasnya teresolusi, kemudian provider AST dan mutation bawaan yang tunduk pada gerbang lingkungannya.
Bangun store bersama dan gerbang. Store dokumen dalam memori dibangun dari TTL dan kapasitas yang dikonfigurasi; ConfirmationGate dirakit dengan store token sekali pakainya.
Ikat transport. MCP memasuki loop baca-tangani-tulis di atas stdio hingga akhir berkas. REST dan gRPC membangun tabel rute atau service dari tier yang terdeteksi, lalu menyerahkan loop permintaan ke RoadRunner.

Sebuah permintaan kemudian mengikuti jalur ini: autentikasi (REST dan gRPC), resolusi tool atau operasi, menjalankan gerbang konfirmasi untuk pekerjaan ApprovalRequired, eksekusi terhadap mesin, dan mengembalikan hasilnya. Lihat Boot dan penemuan.

Model transport

Ketiga transport berbagi konsep registry, konfigurasi, dan gerbang, tetapi berjalan sebagai proses independen. Menjalankan salah satunya tidak menjalankan yang lain.

Transport	Entry point	Kapan memilihnya
MCP	`bin/nextpdf-mcp`	Client artificial intelligence (AI) lokal yang menjalankan server sebagai subproses tepercaya.
REST	`bin/nextpdf-server`	Client HTTP berjaringan; dideskripsikan oleh dokumen OpenAPI 3.1.
gRPC	`bin/nextpdf-grpc`	Client bertipe kuat dan streaming; service `nextpdf.connect.v1.NextPDFConnect`.

Pilih transport berdasarkan profil RoadRunner yang Anda jalankan: .rr.yaml (hanya REST), .rr.grpc.yaml (hanya gRPC), atau .rr.full.yaml (keduanya). Transport MCP adalah subproses biasa dan tidak memerlukan supervisor. Untuk detail wire, lihat transport MCP, transport REST, dan transport gRPC.

Struktur deployment yang direkomendasikan

Jalankan transport berjaringan di bawah RoadRunner dengan store bersama dan kunci yang dipasang melalui secret. Profil gabungan memungkinkan REST dan gRPC berbagi satu supervisor.

Path atau setelan	Tujuan
`.rr.full.yaml`	Profil gabungan REST dan gRPC di bawah satu supervisor.
`NEXTPDF_API_KEYS_FILE`	Path ke berkas API key yang dipasang melalui secret dan dimuat ulang secara langsung.
`NEXTPDF_REDIS_HOST`	Mengaktifkan store rate-limit, idempotensi, dan dokumen yang didukung Redis untuk pool multi-worker.
`NEXTPDF_WORKER_COUNT` / `NEXTPDF_GRPC_WORKER_COUNT`	Ukuran pool worker untuk pool HTTP dan gRPC.
Direktori basis output	Volume khusus dengan izin sistem berkas hak akses paling rendah untuk tool keluaran berkas.

Contoh shell berikut mem-boot profil gabungan dengan kunci yang dipasang melalui secret dan store Redis bersama. Contoh ini tidak memuat secret apa pun; kunci dipasang di /run/secrets/api-keys.

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
export NEXTPDF_WORKER_COUNT=8
export NEXTPDF_GRPC_WORKER_COUNT=4
export NEXTPDF_REDIS_HOST=redis
./vendor/bin/rr serve -c .rr.full.yaml

Untuk pool multi-worker, konfigurasikan Redis dan pastikan ext-redis tersedia pada image yang berjalan. Tanpanya, store rate-limit, idempotensi, dan dokumen bersifat per-worker. Lihat Deployment.

Tool registry dan resolusi tier

NextPDF\Server\ToolRegistry (src/ToolRegistry.php) membangun katalog saat boot. Tier adalah invarian yang dideklarasikan: setiap tool mengembalikan tier() dan riskLevel()-nya sendiri. Registry tidak pernah menyimpulkan tier dari namespace atau pengemasan.

Tier core mendaftar tanpa syarat: tool dokumen dan diagnostik, ditambah generate_barcode ketika registry encoder barcode core tersedia, ditambah parse_pdf hanya ketika NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED bernilai true atau 1.
Provider Pro dan Enterprise mendaftar ketika kelas providernya teresolusi, diuji dengan class_exists(). Tier yang tidak ada dilewati secara diam-diam.
Provider AST dan mutation bawaan mendaftar di bawah tier Pro, dibatasi oleh NEXTPDF_AST_TOOLS_ENABLED dan NEXTPDF_MUTATION_TOOLS_ENABLED (keduanya aktif secara default).
Filter kebijakan keamanan menerapkan irisan antara setiap pendaftaran dan allowlist enabled_tools. Allowlist mengurangi; ia tidak pernah menambah. Penghitung per-tier hanya menghitung tool yang diizinkan oleh kebijakan.

Respons initialize MCP dan endpoint GET /api/v1/capabilities REST melaporkan jumlah per-tier dan total yang dihasilkan. Anggap total tetap apa pun yang tertulis dalam prosa sebagai usang; kueri server yang sedang berjalan. Lihat Katalog tool.

Tier risiko dan gerbang konfirmasi

Setiap tool mendeklarasikan salah satu dari empat tingkat risiko dari enum RiskLevel (src/Config/RiskLevel.php): Safe (0), Caution (1), Review (2), dan ApprovalRequired (3). Pencatatan audit berlaku pada Caution dan di atasnya. Override konfigurasi dapat menaikkan risiko sebuah tool; ia tidak pernah boleh menurunkan tool yang ApprovalRequired berdasarkan desain. Pemuat konfigurasi melempar galat saat pemuatan, dan server menolak untuk boot daripada berjalan dengan gerbang yang dilemahkan.

Ketika tool ApprovalRequired dipanggil tanpa token yang valid, ConfirmationGate (src/Mcp/ConfirmationGate.php) mengembalikan token tantangan sekali pakai. Token tersebut mengikat nama tool, sebuah nonce acak, dan time-to-live (TTL) 300 detik, tetapi bukan argumennya, karena client dapat menserialisasi ulang argumen dengan urutan kunci yang berbeda saat mencoba lagi. Agen meneruskan tantangan kepada manusia dan memanggil ulang tool yang sama dengan token pada argumen _confirmation_token. Token tersebut dikonsumsi saat digunakan, sehingga membuka tepat satu panggilan yang melewati gerbang.

Contoh PHP berikut adalah helper yang tidak terikat transport. Helper ini menjalankan satu panggilan tool MCP dan, saat menerima tantangan konfirmasi, menampilkan tantangan tersebut kepada penyetuju manusia sebelum mencoba lagi dengan token yang diterbitkan. Ia mendeklarasikan strict types, sepenuhnya bertipe, dan menangkap exception yang paling spesifik alih-alih menelan setiap galat.

<?php

declare(strict_types=1);

namespace App\Connect;

use JsonException;

/**
 * Drives one tool call and resolves an ApprovalRequired confirmation
 * challenge through a human approver before retrying.
 */
final readonly class ConfirmingToolCaller
{
    public function __construct(
        private McpClientInterface $client,
        private HumanApproverInterface $approver,
    ) {}

    /**
     * @param non-empty-string     $toolName
     * @param array<string, mixed> $arguments
     *
     * @return array<string, mixed> The tool result content
     *
     * @throws JsonException         When a response cannot be decoded
     * @throws ApprovalDeniedException When the human declines the challenge
     */
    public function call(string $toolName, array $arguments): array
    {
        $response = $this->client->callTool($toolName, $arguments);

        if (!isset($response['challenge'], $response['token'])) {
            return $response;
        }

        $challenge = (string) $response['challenge'];
        $token = (string) $response['token'];

        if (!$this->approver->approve($toolName, $challenge)) {
            throw new ApprovalDeniedException($toolName);
        }

        $arguments['_confirmation_token'] = $token;

        return $this->client->callTool($toolName, $arguments);
    }
}

Hubungkan McpClientInterface, HumanApproverInterface, dan ApprovalDeniedException ke transport dan saluran persetujuan Anda sendiri. Percobaan ulang menggunakan kembali argumen asli ditambah token yang diterbitkan; jangan pernah menyetujui tantangan secara otomatis tanpa keputusan manusia. Lihat Tier risiko HITL.

Titik perluasan

Perluas server dengan menambahkan tool dan menyediakan provider, bukan dengan menyunting registry.

Titik perluasan	Gunakan untuk	Batasan
Sebuah kelas yang mengimplementasikan `ToolInterface`	Kapabilitas mesin baru yang dipaparkan sebagai sebuah tool.	Deklarasikan `tier()`, `riskLevel()`, `category()`, dan sebuah `inputSchema()` JSON Schema; jaga kelas tetap sebagai pembungkus mesin yang tipis.
Provider `ToolProviderInterface`	Mendaftarkan sekumpulan tool untuk sebuah tier.	Provider Pro dan Enterprise ditemukan oleh `class_exists()`; jangan mewajibkan paket proprietary dari server.
`enabled_tools` allowlist	Pembatasan hak akses paling rendah atas katalog yang dipaparkan.	Allowlist hanya mengurangi; ia tidak dapat mendaftarkan tool yang tidak ada.
`risk_level_overrides`	Memperkeras deployment dengan menaikkan risiko sebuah tool.	Hanya naik tingkat; penurunan tingkat sebuah tool `ApprovalRequired` menggagalkan boot.
Seam transport dan worker yang dapat diinjeksi	Menguji server secara terisolasi.	Batas-batas ini ada untuk pengujian, bukan untuk wiring aplikasi.

Alur kerja operasi

Pilih sebuah profil. Jalankan .rr.yaml, .rr.grpc.yaml, atau .rr.full.yaml untuk transport yang Anda paparkan.
Pasang kunci dari sebuah secret. Arahkan NEXTPDF_API_KEYS_FILE ke sebuah berkas secret; utamakan store kunci berbasis berkas yang dimuat ulang secara langsung agar rotasi tidak memerlukan restart.
Konfigurasikan store bersama. Setel NEXTPDF_REDIS_HOST dan pastikan ext-redis tersedia untuk pool apa pun yang lebih besar dari satu worker; tempatkan store job SQLite pada volume yang dapat ditulis semua worker.
Terminasi TLS. Jalankan REST di belakang terminator Transport Layer Security (TLS); jalankan gRPC dengan mutual TLS pada jaringan tidak tepercaya mana pun, dengan kunci server, sertifikat server, dan otoritas sertifikat client disediakan sebagai secret deployment.
Periksa kesehatan. Gunakan endpoint anonim /healthz dan /readyz (REST) atau RPC HealthCheck dan ReadinessCheck (gRPC) untuk pemeriksaan oleh orchestrator.
Lingkupi katalog. Batasi enabled_tools ke kumpulan minimum yang dibutuhkan sebuah integrasi.

Verifikasi kesehatan Redis alih-alih mengasumsikannya. Server REST beralih kembali ke store dalam memori ketika koneksi Redis yang dikonfigurasi gagal. Lihat Deployment dan Keamanan dan operasi.

Penanganan kegagalan

Kegagalan	Tempat ia muncul	Respons yang direkomendasikan
`document_id` tidak dikenal	Eksekusi tool	Kembalikan galat terdefinisi kepada pemanggil; instruksikan ia untuk memanggil `create_pdf` terlebih dahulu.
ETag usang pada mutation	Tool mutation AST	Baca ulang dokumen dengan `get_document_ast` dan coba lagi dengan ETag yang baru.
API key hilang atau tidak valid (REST)	Middleware autentikasi	Kembalikan `401` dengan tantangan `WWW-Authenticate: Bearer`; jangan membocorkan bagian mana yang salah.
Tier tidak berwenang (REST)	Otorisasi	Kembalikan `403`; tier kunci tersebut berada di bawah tier operasi.
Rute tier tidak ada (REST)	Router	Kembalikan `404`; paket tidak terpasang. Ini adalah operasi yang diharapkan, bukan kesalahan.
Token buruk (gRPC)	Autentikator gRPC	Gagalkan panggilan dengan `UNAUTHENTICATED`.
Redis tidak dapat dijangkau	Boot atau runtime	Turunkan ke store dalam memori; beri tahu operator dan verifikasi kesehatan Redis.
Path output di luar direktori basis	Tool keluaran berkas	Gagal secara tertutup; path dikanonisasi dan traversal ditolak.

Tampilkan kegagalan mesin sebagai objek galat terdefinisi, jangan pernah sebagai keberhasilan diam-diam. Referensi API merinci model galat untuk setiap transport.

Nilai standar yang aman

Hal yang diperhatikan	Standar	Kapan harus menggantinya
`parse_pdf`	Dinonaktifkan (opt-in melalui `NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`).	Aktifkan hanya ketika sebuah integrasi memerlukan inspeksi struktural.
`enabled_tools`	Kosong (semua tool yang ditemukan diizinkan).	Setel allowlist eksplisit untuk deployment hak-paling-rendah.
Override risiko	Tidak ada.	Naikkan risiko untuk deployment yang diperkeras; jangan pernah mencoba penurunan tingkat.
`document_ttl` / `max_documents`	1800 detik / 50 dokumen.	Turunkan untuk deployment yang sensitif terhadap residensi atau terbatas memori.
`allow_file_output`	Diaktifkan.	Setel ke `false` untuk deployment stateless dan sensitif terhadap residensi.
Jumlah worker	Empat (HTTP), dua (gRPC).	Tentukan ukuran terhadap latensi yang teramati dan core yang tersedia.
Listener REST	HTTP teks polos di belakang terminator TLS.	Selalu terminasi TLS di hulu; jangan pernah memaparkan teks polos pada jaringan tidak tepercaya.
gRPC pada jaringan tidak tepercaya	Mutual TLS.	Wajib; jangan pernah menjalankan listener gRPC teks polos pada jaringan tidak tepercaya.

Daftar periksa pengujian

Uji registry memastikan bahwa tier Pro atau Enterprise yang tidak ada dilewati secara diam-diam dan katalog core tetap terdaftar.
Uji allowlist memastikan bahwa enabled_tools mengurangi dan tidak pernah menambah tool yang tidak ditemukan oleh registry.
Uji gerbang konfirmasi memastikan bahwa tool ApprovalRequired mengembalikan tantangan pada panggilan pertama, berjalan sekali pada token sekali pakai yang valid, dan menggugurkan token setelah TTL-nya.
Uji penurunan tingkat memastikan bahwa entri risk_level_overrides yang melemahkan tool ApprovalRequired menggagalkan boot.
Uji autentikasi mencakup kunci yang hilang, salah bentuk, dinonaktifkan, dan kedaluwarsa pada REST (401 dengan WWW-Authenticate) dan gRPC (UNAUTHENTICATED), serta penolakan hak tier (403).
Uji konkurensi memastikan bahwa ETag usang menggagalkan mutation dan bahwa idempotency_key yang berulang memutar ulang hasil yang sudah di-cache.
Uji pembatasan path memastikan bahwa path keluaran berkas yang teresolusi di luar direktori basis ditolak.
Jaga fixture tetap kecil dan tidak sensitif; jangan pernah meng-commit API key asli atau konten dokumen.

Lihat juga

Referensi API — simbol tool, RPC, dan message persis
Katalog tool — kumpulan core terverifikasi dan jumlah runtime
Tier risiko HITL — model risiko dan confirmation envelope
Konfigurasi — urutan resolusi dan override yang hanya menaikkan tingkat
Deployment — profil RoadRunner, Redis, dan mutual TLS
Keamanan dan operasi — autentikasi, keamanan transport, dan model ancaman