Server MCP Python

Server MCP Python

SDK Python NextPDF menyertakan server Model Context Protocol (MCP) yang mengekspos operasi ekstraksi PDF sebagai alat native bagi agen. Agen yang mendukung MCP, seperti Claude Code, mendaftarkan server sekali, lalu memanggil alat NextPDF dengan cara yang sama seperti alat lainnya.

Server ini merupakan adaptor tipis. Setiap alat membaca PDF dari disk lokal, memanggil klien async untuk endpoint NextPDF Connect Anda, dan mengembalikan hasilnya sebagai string JSON. Server tidak menyimpan logika bisnis maupun data antar-pemanggilan.

Pasang SDK dengan ekstra MCP:

pip install nextpdf[mcp]

Ekstra mcp memasang paket upstream mcp (batasan mcp>=1.0,<2.0). Server membutuhkan Python 3.10 atau yang lebih baru.

Jalankan modul server dari konfigurasi klien MCP Anda. Contoh di bawah membaca kedua nilai koneksi dari environment host, bukan menanamkan rahasia di berkas konfigurasi (lihat Keamanan):

{
  "mcpServers": {
    "nextpdf": {
      "command": "python",
      "args": ["-m", "nextpdf.mcp"],
      "env": {
        "NEXTPDF_BASE_URL": "https://connect.example.com",
        "NEXTPDF_API_KEY": "${NEXTPDF_API_KEY}"
      }
    }
  }
}

Entry point python -m nextpdf.mcp menjalankan main(), yang memulai server melalui input/output standar (stdio) dengan asyncio.run(serve()). Jangan tertukar dengan python -m nextpdf, yang menjalankan antarmuka baris perintah (CLI), bukan server MCP.

NEXTPDF_BASE_URL dan NEXTPDF_API_KEY wajib diisi. Server membuat kliennya secara lazy saat alat pertama kali dipanggil. Jika salah satu variabel kosong, server memunculkan RuntimeError dan mengembalikannya ke agen sebagai error alat, alih-alih membuat proses crash.

Katalog alat dan pemetaan SDK

Server mendaftarkan delapan alat. Nama setiap alat menggunakan awalan nextpdf_. Setiap alat dipetakan ke metode pada namespace ast milik klien async (AsyncNextPDF.ast), kecuali dua alat komposit yang dicatat di bawah. Server merakitnya dari pemanggilan tingkat lebih rendah.

Alat MCP	Pemanggilan SDK	Catatan
nextpdf_extract_text	ast.extract_cited_text(pdf_data, page_index=..., headings_only=...)	Mengembalikan daftar CitedTextBlock.
nextpdf_extract_tables	ast.extract_cited_tables(pdf_data, page_range=...)	Mengembalikan ExtractCitedTablesResponse.
nextpdf_get_ast	ast.get_document_ast(pdf_data, page_range_start=0, page_range_end=..., token_budget=...)	Mengembalikan AstDocument.
nextpdf_info	ast.get_document_ast(pdf_data)	Server memproyeksikan ringkasan metadata; tidak ada endpoint khusus.
nextpdf_health	tidak ada	Hanya memeriksa variabel environment; tidak melakukan pemanggilan jaringan.
nextpdf_search	ast.search_ast_nodes(pdf_data, node_type=..., page_index=..., text_query=..., max_results=...)	Mengembalikan SearchAstNodesResponse.
nextpdf_get_outline	ast.search_ast_nodes(pdf_data, node_type="heading", max_results=500)	Server membentuk ulang node heading menjadi sebuah outline.
nextpdf_diff	ast.get_ast_diff(original_pdf_data, modified_pdf_data)	Mengembalikan GetAstDiffResponse.

Perhatikan detail input alat berikut sebelum Anda menghubungkan agen:

• Semua input path (pdf_path, original_pdf_path, modified_pdf_path) adalah path absolut ke berkas pada mesin yang menjalankan server. Agen meneruskan path, lalu server membaca byte-nya secara lokal. Tidak ada alat unggah.
• nextpdf_extract_text mendeklarasikan field max_pages di skema input-nya, tetapi handler teks tidak meneruskannya ke SDK. Pembatasan halaman untuk teks dilakukan melalui page_index (satu halaman berbasis 0). Gunakan nextpdf_get_ast dengan max_pages bila Anda perlu membatasi penelusuran seluruh dokumen.
• nextpdf_get_ast menerjemahkan max_pages menjadi rentang halaman inklusif [0, max_pages - 1] (nilai default max_pages adalah 50). Teruskan token_budget untuk membatasi ukuran tree yang dikembalikan.
• nextpdf_info mengembalikan schema_version, source_hash, page_count, estimated_tokens, root_node_type, dan root_children_count. Nilai-nilai ini berasal dari model AstDocument; di dalamnya, estimated_tokens adalah properti terhitung (kira-kira empat karakter per token).
• nextpdf_get_outline mengembalikan satu entri per heading dengan id, page_index, text, dan depth (dibaca dari attributes["level"] milik node, dengan nilai default 1), serta heading_count, total_matches, dan truncated.

Alat ekstraksi tersitasi melampirkan satu CitationAnchor ke setiap hasil. Setiap anchor mencakup node_id, page_index, bbox yang dinormalisasi (koordinat dalam rentang 0.0 hingga 1.0), dan skor confidence (0.0 hingga 1.0). Agen yang membutuhkan provenance sebaiknya menampilkan field-field ini, bukan hanya teks mentah.

Penanganan error, timeout, dan kuota

Server tidak pernah membiarkan exception lolos ke transport agen. Dispatcher call_tool menangkap setiap error dan mengembalikannya sebagai JSON TextContent, sehingga pemanggilan alat yang gagal menghasilkan payload terstruktur yang dapat dibaca agen, bukan koneksi yang terputus. Bentuk payload-nya adalah:

Kondisi	JSON yang dikembalikan
Nama alat tidak dikenal	{"error": "Unknown tool: <name>"}
Berkas input tidak ada	{"error": "PDF file not found: <path>"}
Setiap subkelas NextPDFError	{"error": "<message>", "error_type": "<class>", "status_code": <int?>}
Exception lain apa pun	{"error": "Unexpected error: <message>"}

status_code muncul hanya ketika error yang mendasarinya menyediakannya. SDK memetakan respons HTTP ke hierarki exception bertipe, yang semuanya berakar pada NextPDFError:

Exception	Status HTTP	error_code	Kapan
NextPDFLicenseError	402	license/tier-required	Endpoint membutuhkan tingkat lisensi sisi server yang lebih tinggi untuk operasi tersebut.
AstNoStructTreeError	422	ast/no-struct-tree	PDF tidak ditandai (untagged), dan fallback heuristik tidak diaktifkan di server.
QuotaExceededError	429	quota/exceeded	Batas laju atau kuota terlampaui. Membawa retry_after (detik) ketika server mengirim header Retry-After.
AstBuildTimeoutError	504	ast/build-timeout	Pembuatan AST melampaui anggaran waktu server. Persempit rentang halaman.
NextPDFAPIError	4xx/5xx lainnya	disediakan server	Kegagalan tingkat API lainnya.

Gunakan panduan ini untuk integrasi agen:

• Timeout. Klien HTTP menggunakan timeout default tetap: total 60 detik dengan timeout koneksi 10 detik. Dokumen yang lambat atau berukuran besar muncul sebagai AstBuildTimeoutError (server berhenti membangun AST) atau, jika klien sendiri mengalami timeout, payload Unexpected error dari lapisan transport. Ketika Anda melihat ast/build-timeout, minta agen mempersempit cakupan: turunkan max_pages pada nextpdf_get_ast, atau atur page_index / page_start dan page_end pada alat ekstraksi.
• Kuota dan backoff. Pada 429, alat mengembalikan error_type QuotaExceededError dengan status_code 429. Nilai retry_after berada pada objek exception. Karena server hanya menserialisasi error, error_type, dan status_code, agen sebaiknya memperlakukan 429 sebagai sinyal untuk berhenti sejenak dan mencoba lagi nanti, bukan mengurai header retry dari output alat. Terapkan kuota di endpoint Connect, bukan di agen.
• PDF tanpa tag. Status 422 ast/no-struct-tree berarti PDF sumber tidak memiliki structure tree. Aktifkan mode heuristik di server untuk dokumen tersebut, atau arahkan ke langkah penandaan (tagging) sebelum ekstraksi.

Keamanan: pembatasan cakupan API key dan hak akses minimal

Perlakukan API key sebagai rahasia, dengan kehati-hatian yang sama seperti Anda menjaga kata sandi basis data.

• Jangan pernah menanamkan key di berkas konfigurasi MCP. Contoh JSON di atas merujuk ${NEXTPDF_API_KEY} sehingga nilainya diselesaikan dari environment host atau secret manager saat peluncuran. Berkas konfigurasi boleh dikomit ke kontrol versi; rahasia tidak boleh.
• Batasi cakupan key hanya untuk ekstraksi baca-saja. Server MCP hanya memanggil permukaan ekstraksi AST (extract_cited_text, extract_cited_tables, get_document_ast, search_ast_nodes, get_ast_diff). Server tidak merender, menandatangani, meredaksi, atau mengubah dokumen. Berikan agen key yang cakupan sisi server-nya dibatasi pada jalur baca tersebut, sehingga agen yang disusupi tidak dapat menjangkau operasi tulis atau operasi dengan tingkat hak lebih tinggi.
• Gunakan key khusus per agen. Key per agen memungkinkan Anda mencabut atau merotasi satu integrasi tanpa memengaruhi yang lain, serta membuat log endpoint dapat diatribusikan ke agen tertentu.
• Batasi sistem berkas. Karena setiap alat membaca path absolut dari disk lokal, server dapat membaca berkas apa pun yang dapat dibaca oleh proses host. Jalankan sebagai pengguna tanpa hak istimewa, batasi direktori kerjanya ke folder dokumen, dan jangan pernah menjalankannya sebagai akun berhak istimewa.
• Utamakan Transport Layer Security (TLS). Arahkan NEXTPDF_BASE_URL ke endpoint https:// untuk setiap penerapan non-lokal. SDK mengirim key sebagai token Bearer di header Authorization, sehingga transport teks biasa akan mengeksposnya di jaringan.

Lihat Keamanan dan operasi Connect untuk kontrol sisi endpoint yang mendukung praktik sisi klien ini.

Menguji server secara lokal sebelum menyambungkan agen

Validasi server secara terisolasi sebelum Anda menghubungkan agen. Pemeriksaan tercepat tidak memerlukan PDF maupun jaringan:

python -c "from nextpdf.mcp import _tool_definitions; print(len(_tool_definitions()))"

Instalasi yang benar mencetak 8. Jika Anda melihat ImportError yang menyebutkan ekstra mcp, berarti dependensi opsional belum ada. Pasang ulang dengan pip install nextpdf[mcp].

Selanjutnya, jalankan alur SDK yang sama dengan yang digunakan alat melalui CLI. CLI berkomunikasi dengan endpoint Anda menggunakan dua variabel environment yang sama. Tetapkan keduanya sekali:

export NEXTPDF_BASE_URL="https://connect.example.com"
export NEXTPDF_API_KEY="$(cat /run/secrets/nextpdf_api_key)"

Kemudian konfirmasi versi, konektivitas, dan ekstraksi nyata:

nextpdf version
nextpdf info /path/to/sample.pdf
nextpdf extract text /path/to/sample.pdf --headings-only

nextpdf version berjalan tanpa kredensial dan mengonfirmasi bahwa paket dapat diimpor. nextpdf info menjalankan get_document_ast, pemanggilan yang sama yang digunakan oleh nextpdf_get_ast dan nextpdf_info. Jika keduanya berhasil, kredensial dan endpoint sudah benar, dan alat MCP yang sesuai akan berfungsi.

Untuk menjalankan protokol MCP secara langsung, gunakan MCP Inspector dari upstream (disertakan bersama paket mcp). Arahkan ke perintah dan environment yang sama dengan yang akan digunakan agen Anda, lalu daftarkan dan panggil alat secara manual. Pastikan nextpdf_health melaporkan status: "ok". Server mengembalikan misconfigured setiap kali NEXTPDF_BASE_URL atau NEXTPDF_API_KEY tidak diatur, yang merupakan cara tercepat mendeteksi nilai environment yang hilang sebelum agen memanggil alat nyata.

Memantau dan men-debug pemanggilan alat

Server MCP berkomunikasi melalui input/output standar (stdio), sehingga output standarnya membawa aliran protokol dan harus tetap bersih. Server tidak mengonfigurasi logging aplikasinya sendiri. Saluran observabilitas utama Anda adalah payload error alat yang terstruktur, CLI, dan log endpoint Anda sendiri.

• Payload error alat adalah sinyal utama. Setiap pemanggilan yang gagal mengembalikan objek JSON dengan error dan, untuk error SDK, error_type dan status_code (lihat Penanganan error). Minta host agen mencatat payload-payload ini. Payload tersebut mengidentifikasi alat yang gagal dan penyebab pastinya tanpa instrumentasi server tambahan.
• Reproduksi melalui CLI dengan logging debug. Server MCP sendiri tidak memancarkan log, tetapi CLI menjalankan pemanggilan SDK yang sama dan menghasilkan log. Reproduksi alat yang gagal melalui perintah CLI yang sesuai dengan --log-level debug. CLI mencatat ke stderr dengan stempel waktu dan merekam traceback lengkap untuk error yang tidak terduga, yang merupakan cara paling langsung untuk melihat apa yang dilakukan handler tanpa memasang debugger.
• Health sebagai probe. Panggil nextpdf_health untuk mengonfirmasi bahwa server melihat base URL dan API key. Hasilnya melaporkan sdk_version, server_url, api_key_configured (sebuah boolean, tidak pernah key itu sendiri), dan status.
• Observabilitas sisi endpoint. Karena setiap alat dipetakan ke satu permintaan Connect, korelasikan aktivitas alat dengan log akses endpoint berdasarkan API key dan stempel waktu. Jalankan endpoint di balik kontrol autentikasi, kuota, dan observabilitas yang sama dengan yang Anda gunakan untuk klien layanan lainnya.

Mengatasi masalah umum integrasi agen

Gejala	Kemungkinan penyebab	Penyelesaian
Server gagal dijalankan dengan ImportError tentang ekstra mcp	Dependensi opsional mcp tidak terpasang	Pasang dengan pip install nextpdf[mcp].
Pemanggilan alat pertama mengembalikan {"error": "NEXTPDF_BASE_URL environment variable is required..."}	Blok env MCP tidak meneruskan base URL, atau shell tidak memperluas ${NEXTPDF_BASE_URL}	Atur variabel di environment host agen dan pastikan peluncur memperluasnya.
nextpdf_health melaporkan "status": "misconfigured"	Salah satu dari dua variabel wajib kosong	Sediakan keduanya, NEXTPDF_BASE_URL dan NEXTPDF_API_KEY.
Setiap alat berbasis path mengembalikan {"error": "PDF file not found: <path>"}	Agen meneruskan path relatif atau path sisi-host yang tidak dapat dilihat proses server	Teruskan path absolut yang dapat dibaca oleh pengguna server; konfirmasi dengan nextpdf info <path>.
Alat mengembalikan error_typeNextPDFLicenseError (status 402)	Operasi membutuhkan tingkat lisensi sisi server yang lebih tinggi	Gunakan endpoint dan key yang berhak untuk operasi tersebut.
Alat mengembalikan error_typeAstNoStructTreeError (status 422)	PDF tidak ditandai (untagged) dan fallback heuristik mati	Aktifkan mode heuristik di endpoint, atau tandai PDF terlebih dahulu.
Alat mengembalikan error_typeQuotaExceededError (status 429)	Batas laju atau kuota tercapai	Berhenti sejenak lalu coba lagi; naikkan kuota endpoint jika batasnya terlalu rendah.
Alat mengembalikan error_typeAstBuildTimeoutError (status 504), atau timeout transport	Dokumen terlalu besar untuk anggaran waktu	Persempit cakupan dengan max_pages, page_index, atau page_start/page_end.
Agen tidak mendaftarkan alat NextPDF apa pun	Agen memanggil python -m nextpdf (CLI) alih-alih python -m nextpdf.mcp	Gunakan python -m nextpdf.mcp sebagai command/args.

Untuk kegagalan tingkat endpoint dan pemeriksaan penerapan, lihat Mengatasi masalah Connect. Untuk operasi SDK yang dibungkus alat-alat ini, lihat referensi CLI dan ikhtisar SDK.