Python MCP sunucusu

NextPDF Python SDK, PDF çıkarma işlemlerini aracılar için yerel araçlar olarak sunan bir Model Context Protocol (MCP) sunucusu içerir. Claude Code gibi MCP uyumlu bir aracı, sunucuyu bir kez kaydeder ve ardından NextPDF araçlarını diğer araçları çağırdığı şekilde çağırır.

Sunucu hafif bir adaptör görevi görür. Her araç, yerel diskten bir PDF okur, NextPDF Connect uç noktanız için eşzamansız istemciyi çağırır ve sonucu bir JSON dizesi olarak döndürür. Sunucu hiçbir iş mantığı barındırmaz ve çağrılar arasında veri saklamaz.

SDK’yi MCP eklentisiyle yükleyin:

pip install nextpdf[mcp]

Bu mcp eklentisi, upstream mcp paketini yükler (kısıtlama mcp>=1.0,<2.0). Sunucu, Python 3.10 veya daha yenisini gerektirir.

Sunucu modülünü MCP istemci yapılandırmanızdan çalıştırın. Aşağıdaki örnek, gizli bir değeri yapılandırma dosyasına gömmek yerine her iki bağlantı değerini de ana makine ortamından okur (Güvenlik bölümüne bakın):

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

Bu python -m nextpdf.mcp giriş noktası main() işlevini çalıştırır; bu işlev de sunucuyu standart giriş/çıkış (stdio) üzerinden asyncio.run(serve()) ile başlatır. Bunu, MCP sunucusunu değil komut satırı arabirimini (CLI) çalıştıran python -m nextpdf ile karıştırmayın.

NEXTPDF_BASE_URL ve NEXTPDF_API_KEY zorunludur. Sunucu, istemcisini ilk araç çağrısında geç olarak oluşturur. Değişkenlerden biri boşsa, sürecin çökmesine yol açmak yerine bir RuntimeError fırlatır ve bunu aracıya araç hatası olarak döndürür.

Araç kataloğu ve SDK eşlemesi

Sunucu sekiz araç kaydeder. Her araç adı nextpdf_ ön ekini kullanır. Aşağıda belirtilen iki bileşik araç dışında, her araç eşzamansız istemcinin ast ad alanındaki (AsyncNextPDF.ast) bir yönteme eşlenir. Sunucu, bu bileşik araçları daha alt düzey çağrılardan oluşturur.

MCP aracı	SDK çağrısı	Notlar
`nextpdf_extract_text`	`ast.extract_cited_text(pdf_data, page_index=..., headings_only=...)`	Bir `CitedTextBlock` listesi döndürür.
`nextpdf_extract_tables`	`ast.extract_cited_tables(pdf_data, page_range=...)`	Şunu döndürür: `ExtractCitedTablesResponse`.
`nextpdf_get_ast`	`ast.get_document_ast(pdf_data, page_range_start=0, page_range_end=..., token_budget=...)`	Şunu döndürür: `AstDocument`.
`nextpdf_info`	`ast.get_document_ast(pdf_data)`	Sunucu bir meta veri özeti yansıtır; ayrılmış bir uç nokta yoktur.
`nextpdf_health`	yok	Yalnızca ortam değişkenlerini inceler; ağ çağrısı yapmaz.
`nextpdf_search`	`ast.search_ast_nodes(pdf_data, node_type=..., page_index=..., text_query=..., max_results=...)`	Şunu döndürür: `SearchAstNodesResponse`.
`nextpdf_get_outline`	`ast.search_ast_nodes(pdf_data, node_type="heading", max_results=500)`	Sunucu, başlık düğümlerini yeniden biçimlendirerek bir ana hat oluşturur.
`nextpdf_diff`	`ast.get_ast_diff(original_pdf_data, modified_pdf_data)`	Şunu döndürür: `GetAstDiffResponse`.

Bir aracıyı bağlamadan önce şu araç girişi ayrıntılarını aklınızda bulundurun:

Tüm yol girişleri (pdf_path, original_pdf_path, modified_pdf_path), sunucuyu çalıştıran makinedeki dosyalara giden mutlak yollardır. Aracı bir yol geçirir, sunucu da baytları yerel olarak okur. Yükleme aracı yoktur.
nextpdf_extract_text, giriş şemasında bir max_pages alanı bildirir, ancak metin işleyici bunu SDK’ya geçirmez. Metin için sayfa kapsamı page_index (0 tabanlı tek bir sayfa) aracılığıyla belirlenir. Belgenin tamamında yapılan gezinmeyi sınırlandırmanız gerektiğinde nextpdf_get_ast aracını max_pages ile kullanın.
nextpdf_get_ast, max_pages değerini [0, max_pages - 1] şeklinde, sonu dahil bir sayfa aralığına çevirir (varsayılan max_pages değeri 50’dir). Döndürülen ağacın boyutunu sınırlamak için token_budget geçirin.
nextpdf_info; schema_version, source_hash, page_count, estimated_tokens, root_node_type ve root_children_count döndürür. Bu değerler AstDocument modelinden gelir; burada estimated_tokens hesaplanan bir özelliktir (yaklaşık olarak token başına dört karakter).
nextpdf_get_outline; her başlık için id, page_index, text ve depth (düğümün attributes["level"] değerinden okunur, varsayılan olarak 1) içeren bir girişin yanı sıra heading_count, total_matches ve truncated döndürür.

Atıflı çıkarma araçları her sonuca bir CitationAnchor ekler. Her bağlantı noktası node_id, page_index, normalleştirilmiş bir bbox (0.0 ile 1.0 aralığındaki koordinatlar) ve bir confidence puanı (0.0 ile 1.0) içerir. Kaynak gösterimine ihtiyaç duyan aracılar yalnızca ham metni değil, bu alanları da göstermelidir.

Hata işleme, zaman aşımları ve kota

Sunucu, bir istisnanın aracı aktarımına sızmasına asla izin vermez. call_tool dağıtıcısı her hatayı yakalar ve JSON TextContent biçiminde döndürür; böylece başarısız bir araç çağrısı, kesilen bir bağlantı yerine aracının okuyabileceği yapılandırılmış bir yük üretir. Yük biçimleri şunlardır:

Koşul	Döndürülen JSON
Bilinmeyen araç adı	`{"error": "Unknown tool: <name>"}`
Eksik giriş dosyası	`{"error": "PDF file not found: <path>"}`
Herhangi bir `NextPDFError` alt sınıfı	`{"error": "<message>", "error_type": "<class>", "status_code": <int?>}`
Diğer herhangi bir istisna	`{"error": "Unexpected error: <message>"}`

status_code yalnızca alt katmandaki hata bu değeri taşıdığında görünür. SDK, HTTP yanıtlarını, kökü NextPDFError olan tipli bir istisna hiyerarşisine eşler:

İstisna	HTTP durumu	`error_code`	Ne zaman
`NextPDFLicenseError`	402	`license/tier-required`	Uç nokta, işlem için daha yüksek bir sunucu tarafı lisans katmanı gerektirir.
`AstNoStructTreeError`	422	`ast/no-struct-tree`	PDF etiketsizdir ve sunucuda sezgisel geri dönüş etkin değildir.
`QuotaExceededError`	429	`quota/exceeded`	Bir hız sınırı veya kotaya ulaşıldı. `retry_after` (saniye) taşır; bu değer, sunucu bir `Retry-After` başlığı gönderdiğinde geçerlidir.
`AstBuildTimeoutError`	504	`ast/build-timeout`	AST oluşturma, sunucunun zaman bütçesini aştı. Sayfa aralığını azaltın.
`NextPDFAPIError`	diğer 4xx/5xx	sunucu tarafından sağlanan	Diğer herhangi bir API düzeyinde hata.

Aracı entegrasyonları için şu yönergeleri kullanın:

Zaman aşımları. HTTP istemcisi sabit bir varsayılan zaman aşımı kullanır: toplam 60 saniye, 10 saniyelik bağlantı zaman aşımıyla birlikte. Yavaş veya büyük bir belge ya bir AstBuildTimeoutError (sunucu AST oluşturmaktan vazgeçti) ya da istemcinin kendisi zaman aşımına uğrarsa aktarım katmanından gelen bir Unexpected error yükü olarak ortaya çıkar. ast/build-timeout gördüğünüzde aracıya kapsamı daraltmasını söyleyin: max_pages değerini nextpdf_get_ast üzerinde düşürün ya da çıkarma araçlarında page_index / page_start ve page_end ayarlayın.
Kota ve geri çekilme. 429 durumunda araç, error_type değeri olarak QuotaExceededError ile status_code 429 döndürür. retry_after değeri istisna nesnesinde bulunur. Sunucu yalnızca error, error_type ve status_code alanlarını serileştirdiği için aracı, 429 durumunu araç çıktısından bir yeniden deneme başlığını ayrıştırmak yerine durup daha sonra yeniden denemek için bir sinyal olarak ele almalıdır. Kotaları aracıda değil, Connect uç noktasında uygulayın.
Etiketsiz PDF’ler. Bir 422 ast/no-struct-tree, kaynak PDF’nin yapı ağacına sahip olmadığı anlamına gelir. Bu belgeler için sunucuda sezgisel modu etkinleştirin ya da çıkarma öncesinde onları bir etiketleme adımına yönlendirin.

Güvenlik: API anahtarı kapsamlandırması ve en az ayrıcalık

API anahtarını, bir veritabanı parolasına gösterdiğiniz özenin aynısıyla, bir gizli değer olarak ele alın.

Anahtarı MCP yapılandırma dosyasına asla gömmeyin. Yukarıdaki JSON örneği ${NEXTPDF_API_KEY} değerine başvurur; böylece değer, başlatma anında ana makine ortamından veya bir gizli değer yöneticisinden çözülür. Bir yapılandırma dosyası sürüm denetimine girebilir; ancak gizli değer giremez.
Anahtarı salt okunur çıkarmayla kapsamlandırın. MCP sunucusu yalnızca AST çıkarma yüzeyini (extract_cited_text, extract_cited_tables, get_document_ast, search_ast_nodes, get_ast_diff) çağırır. Belgeleri işlemez, imzalamaz, redakte etmez veya değiştirmez. Aracıya, sunucu tarafı kapsamı bu okuma yollarıyla sınırlı bir anahtar verin; böylece ele geçirilmiş bir aracı yazma işlemlerine veya daha yüksek katmanlı işlemlere erişemez.
Her aracı için ayrı bir anahtar kullanın. Aracı başına bir anahtar, diğerlerini etkilemeden bir entegrasyonu iptal etmenizi veya değiştirmenizi sağlar ve uç nokta günlüklerini belirli bir aracıyla ilişkilendirilebilir kılar.
Dosya sistemini kısıtlayın. Her araç yerel diskten mutlak bir yol okuduğu için sunucu, ana makine sürecinin okuyabileceği her dosyayı okuyabilir. Sunucuyu ayrıcalıksız bir kullanıcı olarak çalıştırın, çalışma dizinini bir belgeler klasörüyle sınırlayın ve onu asla ayrıcalıklı bir hesapla çalıştırmayın.
Aktarım katmanı güvenliğini (TLS) tercih edin. Yerel olmayan herhangi bir dağıtım için NEXTPDF_BASE_URL değerini bir https:// uç noktasına yöneltin. SDK, anahtarı bir Bearer belirteci olarak Authorization başlığında gönderir; bu nedenle düz metin aktarımı onu ağ üzerinde açığa çıkarır.

Bu istemci tarafı uygulamaları destekleyen uç nokta tarafı denetimleri için Connect güvenliği ve operasyonları bölümüne bakın.

Bir aracıyı bağlamadan önce sunucuyu yerel olarak test etme

Bir aracı bağlamadan önce sunucuyu yalıtılmış şekilde doğrulayın. En hızlı denetim için PDF ve ağ gerekmez:

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

Doğru bir kurulum 8 yazdırır. ImportError hatası mcp eklentisinden bahsediyorsa isteğe bağlı bağımlılık eksiktir. pip install nextpdf[mcp] ile yeniden yükleyin.

Ardından, araçların kullandığı aynı SDK yollarını CLI üzerinden çalıştırın. CLI, uç noktanızla aynı iki ortam değişkenini kullanarak iletişim kurar. Bu değişkenleri bir kez ayarlayın:

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

Ardından sürümü, bağlantıyı ve gerçek bir çıkarma işlemini doğrulayın:

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

nextpdf version kimlik bilgileri olmadan çalışır ve paketin içe aktarıldığını doğrular. nextpdf info, get_document_ast çağrısını çalıştırır; bu, nextpdf_get_ast ve nextpdf_info araçlarının kullandığı aynı çağrıdır. Her ikisi de başarılı olursa kimlik bilgileri ve uç nokta doğrudur; eşleşen MCP araçları da çalışacaktır.

MCP protokolünü doğrudan çalıştırmak için upstream MCP Inspector aracını kullanın (mcp paketiyle birlikte gelir). Aracı, aracınızın kullanacağı aynı komuta ve ortama yöneltin, ardından araçları el ile listeleyin ve çağırın. nextpdf_health aracının status: "ok" bildirdiğini doğrulayın. misconfigured değerini, NEXTPDF_BASE_URL veya NEXTPDF_API_KEY ayarlanmadığında döndürür; bu da bir yapay zekâ aracısı gerçek bir araç çağırmadan önce eksik bir ortam değerini yakalamanın en hızlı yoludur.

Araç çağrılarını izleme ve hata ayıklama

MCP sunucusu standart giriş/çıkış (stdio) üzerinden iletişim kurar; bu nedenle standart çıktısı protokol akışını taşır ve temiz kalmalıdır. Sunucu kendi uygulama günlüklemesini yapılandırmaz. Birincil gözlemlenebilirlik kanallarınız yapılandırılmış araç hatası yükleri, CLI ve uç noktanızın kendi günlükleridir.

Araç hatası yükleri sinyaldir. Her başarısız çağrı, error içeren ve SDK hataları için error_type ile status_code içeren bir JSON nesnesi döndürür (Hata işleme bölümüne bakın). Aracı ana makinesinin bu yükleri kaydetmesini sağlayın. Bunlar, ek sunucu ölçümlemesi olmadan başarısız olan aracı ve kesin nedeni belirler.
CLI üzerinden hata ayıklama günlüklemesiyle yeniden üretin. MCP sunucusunun kendisi günlük yaymaz, ancak CLI aynı SDK çağrılarını çalıştırır ve günlük tutar. Başarısız olan bir araç çağrısını, eşleşen CLI komutuyla --log-level debug kullanarak yeniden üretin. CLI, zaman damgalarıyla stderr’e günlük yazar ve beklenmeyen hatalar için tam yığın izlerini kaydeder; bu da bir hata ayıklayıcı eklemeden bir işleyicinin ne yaptığını görmenin en doğrudan yoludur.
Sağlık denetimini yoklama olarak kullanın. Sunucunun bir temel URL ve bir API anahtarı gördüğünü doğrulamak için nextpdf_health aracını çağırın. Sonuç sdk_version, server_url, api_key_configured (bir boole değeri, asla anahtarın kendisi değil) ve status bildirir.
Uç nokta tarafı gözlemlenebilirlik. Her araç bir Connect isteğine eşlendiği için araç etkinliğini API anahtarı ve zaman damgasına göre uç nokta erişim günlükleriyle ilişkilendirin. Uç noktayı, diğer hizmet istemcileri için kullandığınız aynı kimlik doğrulama, kota ve gözlemlenebilirlik denetimlerinin arkasında çalıştırın.

Sık görülen aracı entegrasyonu sorunlarını giderme

Belirti	Olası neden	Çözüm
Sunucu, `ImportError` hatasıyla başlatılamıyor; hata `mcp` eklentisiyle ilgili	İsteğe bağlı `mcp` bağımlılığı yüklü değil	Şununla yükleyin: `pip install nextpdf[mcp]`.
İlk araç çağrısının döndürdüğü değer: `{"error": "NEXTPDF_BASE_URL environment variable is required..."}`	MCP `env` bloğu temel URL’yi geçirmedi ya da kabuk şu değeri genişletmedi: `${NEXTPDF_BASE_URL}`	Değişkeni aracı ana makinesinin ortamında ayarlayın ve başlatıcının onu genişlettiğini doğrulayın.
`nextpdf_health`, `"status": "misconfigured"` bildiriyor	İki zorunlu değişkenden biri boş	`NEXTPDF_BASE_URL` ve `NEXTPDF_API_KEY` değişkenlerinin her ikisini de sağlayın.
Yol kullanan her aracın döndürdüğü değer: `{"error": "PDF file not found: <path>"}`	Aracı, sunucu sürecinin göremediği göreli veya ana makine tarafı bir yol geçirdi	Sunucu kullanıcısının okuyabileceği mutlak bir yol geçirin; `nextpdf info <path>` ile doğrulayın.
Araç `error_typeNextPDFLicenseError` döndürür (durum 402)	İşlem, daha yüksek bir sunucu tarafı lisans katmanı gerektirir	İşleme yetkili bir uç nokta ve anahtar kullanın.
Araç `error_typeAstNoStructTreeError` döndürür (durum 422)	PDF etiketsizdir ve sezgisel geri dönüş kapalıdır	Uç noktada sezgisel modu etkinleştirin ya da önce PDF’yi etiketleyin.
Araç `error_typeQuotaExceededError` döndürür (durum 429)	Bir hız sınırı veya kotaya ulaşıldı	Bekleyin ve yeniden deneyin; sınır çok düşükse uç nokta kotasını yükseltin.
Araç `error_typeAstBuildTimeoutError` döndürür (durum 504) ya da bir aktarım zaman aşımı	Belge, zaman bütçesi için çok büyük	Kapsamı `max_pages`, `page_index` ya da `page_start`/`page_end` ile daraltın.
Aracı hiçbir NextPDF aracı kaydetmiyor	Aracı, `python -m nextpdf` (CLI) komutunu `python -m nextpdf.mcp` yerine çağırdı	`python -m nextpdf.mcp` komutunu `command`/`args` olarak kullanın.

Uç nokta düzeyindeki hatalar ve dağıtım denetimleri için Connect sorun giderme bölümüne bakın. Bu araçların sardığı SDK işlemleri için CLI referansı ve SDK genel bakışı bölümüne bakın.