Hangi MCP sunucusunu kullanmalıyım?
İki sunucu da PDF123 işlemlerini sunar. Nerede çalıştıkları ve dosyaların onlara nasıl ulaştığı bakımından ayrılırlar.
| Yerel: @pdf123/mcp | Barındırılan: /mcp | |
|---|---|---|
| Nerede çalışır | Makinenizde; MCP istemcisi onu stdio üzerinden başlatır | https://pdf123.xyz/mcp adresindeki PDF123 sunucularında |
| Girdi | Diskteki dosya yolları. Sunucu dosyaları yükler ve sonucu girdinin yanına kaydeder | Yükleme aracıyla gönderilen dosyalar |
| Kimlik bilgileri | Anonim kullanım için yok. PDFX_API_KEY isteğe bağlıdır | Her istekte X-API-KEY başlığı. Olmazsa yanıt 401 olur |
| Kurulum | npx -y @pdf123/mcp | Gerekmez. URL'yi ve başlığı istemciye ekleyin |
| Araçlar | 97 araçlık kataloğun tamamı için beş araç | Yedi araç: describe, convert, pages, misc, security, upload ve download |
| Ne zaman kullanılır | Bir ajan yerel bir klasördeki belgeler üzerinde çalışırken | Bir ajan ya da barındırılan bir hizmet yüklemeleri zaten API üzerinden yürütüyorsa |
Dizüstü bilgisayardaki kodlama asistanları için yerel sunucuyu kullanın. Ajan bulutta çalışıyor ve diskinizi okuyamıyorsa barındırılan uç noktayı kullanın.
Yerel MCP sunucusunu nasıl kurarım?
Hiçbir şeyin kurulması gerekmez, çünkü MCP istemcisi sunucuyu npx ile başlatır. Claude Code'da tek komutla ekleyin.
claude mcp add pdf123 -- npx -y @pdf123/mcpClaude Desktop claude_desktop_config.json dosyasını, Cursor ise .cursor/mcp.json dosyasını okur. Diğer istemcilerin bir MCP ayar sayfası veya dosyası vardır. Hepsi aynı mcpServers girdisini kabul eder.
{
"mcpServers": {
"pdf123": {
"command": "npx",
"args": ["-y", "@pdf123/mcp"]
}
}
}Yapılandırmayı değiştirdikten sonra istemciyi yeniden başlatın. Bir kopyayı yolunuzda tutmak için pdf123-mcp komutunu sağlayan npm install -g @pdf123/mcp komutunu çalıştırın. Sunucu Node 20.3 veya üstünü ve erişilebilir bir API tabanını gerektirir. Çevrimdışı mod yoktur.
Ajana önce ne söylemeliyim?
Düz bir dille isteyin ve dosyaları adlandırın. Örneğin:
~/Documents/a.pdf ile ~/Documents/b.pdf dosyalarını birleştir, sonra sonucu sıkıştır.
Ajan pdf123_run_pipeline aracını ya da pdf123_run_tool aracını iki kez çağırır, dosyaları PDF123'e yükler ve kaydedilen dosyanın yoluyla yanıt verir. Sonuç ilk girdinin yanına kaydedilir ve var olan bir dosyanın yerine hiçbir zaman yazılmaz. Aynı işlemler web sitesinde PDF birleştir ve PDF sıkıştır olarak da bulunur.
Yerel sunucu hangi araçları sunar?
Sunucuda beş araç vardır. merge gibi araç kimlikleri düz dize bağımsız değişkenleridir; bu yüzden araç listesi küçük kalır.
| Araç | Ne yapar | Temel bağımsız değişkenler |
|---|---|---|
pdf123_list_tools | Araçları satır satır listeler | group, query, format |
pdf123_describe_tool | Bir aracın alanlarını, varsayılanlarını, izin verilen değerlerini ve toplu çalışıp çalışmadığını gösterir | tool |
pdf123_run_tool | Bir aracı yerel dosyalar üzerinde çalıştırır ve kaydedilen yolu ya da JSON raporunu döndürür | tool, files, params, output |
pdf123_run_pipeline | Tek istekte en fazla 8 aracı zincirler | steps, files, output |
pdf123_call | Herhangi bir araç kimliğine, işlem kimliğine veya /api/... yoluna ham istek gönderir | target, files, fields |
Bir ajan genellikle aracı bulmak için pdf123_list_tools, alanlarını okumak için pdf123_describe_tool, ardından pdf123_run_tool çağırır. Yanlış yazılmış bir kimlik "bunu mu demek istediniz" önerileri döndürür.
Toplu işlemler, parolalar ve pipeline'lar nasıl çalışır?
- Toplu işlemler. Tek dosyalı bir araca verilen birkaç dosya, dosya başına bir sonuçla toplu olarak çalışır. Her dosya biter bitmez kaydedilir. Yanıt dosya başına bir rapordur. Herhangi bir dosya başarısız olursa yanıt, raporun eklendiği bir hatadır; böylece ajan yalnızca başarısız dosyaları yeniden deneyebilir.
- Parolalar.
input_passwordşifreli her girdiyi açar.passwords,filesile aynı sırada dosya başına bir parola belirler; açık dosya için boş dize kullanılır. Bu, Birleştir gibi çok dosyalı araçlarda da çalışır. - Pipeline'lar.
pdf123_run_pipelineen fazla 8 adım alır ve her adım sonrakini besler. Aynı parola bağımsız değişkenlerini kabul eder. - Ham çağrılar.
pdf123_call, sunucudan daha yeni işlemlere ulaşır. Yerelde hiçbir şey doğrulanmaz. - Filtre araçları. Kimliği
filter-ile başlayan bir araç, koşulu sağlanmadığında{"matched": false}yanıtı verir. Bu bir hata değil, bir sonuçtur. - Yeniden denemeler.
idempotencyKeyilk sonucu 24 saat boyunca yeniden verir.
Ajanın kullanabileceği klasörleri nasıl sınırlarım?
PDFX_MCP_ROOT değişkenini bir dizine ayarlayın. Birden çok dizini iki nokta üst üste ile, Windows'ta noktalı virgülle ayırın. Sunucu o zaman girdileri yalnızca bu dizinlerden okur ve sonuçları yalnızca bu dizinlere yazar. Bunların dışındaki yollar, .. ile kaçışlar ve dışarı çıkan sembolik bağlantılar, herhangi bir şey yüklenmeden önce Code: path_not_allowed ile reddedilir. Bu değişken olmadan, sunucu sürecinin erişebildiği her yola izin verilir.
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }Ortam değişkenlerini istemcinin env bloğunda ya da claude mcp add -e NAME=value ile ayarlayın. PDFX_API_BASE sunucuyu bunun yerine kendi pdfx-server sunucunuza yöneltir; bkz. Self-host.
Sonuçlar ve hatalar neye benzer?
Tek bir sonuç, kaydedilen path, contentType ve bayt cinsinden boyut olan bytes alanlarından oluşan küçük bir JSON nesnesidir. Toplu işlem sonucu processed, unmatched, failed ve bir files listesi içerir. Bu biçimler komut satırındaki pdfx --json çıktısıyla aynıdır. Belge bilgisi gibi rapor döndüren bir araç, raporu satır içinde döndürür.
{
"path": "/Users/me/Documents/merged.pdf",
"contentType": "application/pdf",
"bytes": 1096
}Başarısız bir çağrı bir araç hatası olarak döner. Sunucu sağladığında metni Reason:, Code: ve Hint: satırlarıyla biter; böylece ajan koda göre dallanabilir.
HTTP 400: This PDF is password-protected. Enter its password.
Reason: password_required
Code: bad_request
Hint: Provide the document password, or unlock the PDF first.Bir araç kimliğinde yazım hatası varsa hata yakın kimlikleri listeler ve Code: unknown_tool ile biter. Döndürecek bir şey bulamayan bir araç, örneğin tablosu olmayan bir PDF üzerinde pdf-to-csv, boş dosya yerine Code: no_content döndürür. Bkz. Hata kodları.
Barındırılan MCP uç noktasını nasıl kullanırım?
API, POST https://pdf123.xyz/mcp adresinde gömülü bir MCP sunucusu barındırır. REST API'nin kullandığı X-API-KEY başlığıyla kimlik doğrulayın. Anahtar olmazsa uç nokta 401 yanıtı verir. Anahtarı Geliştiriciler sayfasında oluşturun.
{
"mcpServers": {
"pdf123": {
"url": "https://pdf123.xyz/mcp",
"headers": { "X-API-KEY": "<your-key>" }
}
}
}Barındırılan sunucu yedi araç listeler: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload ve pdf_toolbox_download. Her kategori aracı bir operation adı ve parametrelerini, ayrıca bir dosya ya da yükleme aracının döndürdüğü bir fileId alır. Tek bir işlemin şemasını almak için describe aracını kullanın.
İlgili sayfalar
- Claude Code, Codex ve Cursor için Ajan becerileri; biri katalog, biri her araç içindir
- Araçların, API'nin ve MCP uç noktasının düz metin dizini olan /llms.txt
- Kataloğu paylaşan pdfx komut satırı ve TypeScript SDK
- Geliştiriciler genel bakış, OpenAPI belgesi ve Swagger UI
- Araç sayfaları: Birleştir, Sıkıştır, OCR, Koru, Onar
- PDF123 blogundaki "Built for AI Agents, Not Just Browsers" ve "Same Operation, Four Clients" yazıları
SSS
MCP nedir?
MCP (Model Context Protocol), yapay zekâ istemcilerini harici araçlara bağlamak için açık bir standarttır. Claude Code gibi bir istemci bir MCP sunucusunu başlatır ya da ona bağlanır, araçlarını listeler ve kullanıcı adına çağırır.
Yerel MCP sunucusu çevrimdışı çalışır mı?
Hayır. Dosyaları PDF123 API'sine ya da PDFX_API_BASE ile belirtilen sunucuya yükler ve sonucu yerel olarak kaydeder. API tabanına erişilebilir olmalıdır.
API anahtarı gerekir mi?
Yerel sunucu anonim kullanım için anahtar gerektirmez. Sunucunuz anahtar istiyorsa PDFX_API_KEY değişkenini ayarlayın. /mcp adresindeki barındırılan uç nokta her zaman X-API-KEY başlığı ister.
Ajan bilgisayarımdaki her dosyayı okuyabilir mi?
Varsayılan olarak sunucu sürecinin erişebildiği her yolu okuyabilir. Okuma ve yazmayı seçtiğiniz dizinlerle sınırlamak için PDFX_MCP_ROOT değişkenini ayarlayın.
Dosyalarıma ne olur?
Yerel sunucu her girdiyi işlenmek üzere PDF123 API'sine ya da kendi sunucunuza yükler. Araç açıklaması, dosyaların işlemden sonra orada silindiğini belirtir. Sonuç makinenize kaydedilir. Ayrıntılar için dosya gizliliği sayfasını okuyun.
Bir ajan kaç araç kullanabilir?
Yerel sunucu, kataloğundaki 97 aracın tümüne beş MCP aracı üzerinden ulaşır. Barındırılan uç nokta işlemlerini kategoriye göre (convert, pages, misc ve security) gruplar ve yedi MCP aracının arkasında sunar.