Pelayan MCP manakah yang patut saya gunakan?
Kedua-dua pelayan menyediakan operasi PDF123. Bezanya ialah tempat ia berjalan dan cara fail sampai kepadanya.
| Setempat: @pdf123/mcp | Dihoskan: /mcp | |
|---|---|---|
| Berjalan di mana | Pada mesin anda, dimulakan oleh klien MCP melalui stdio | Pada pelayan PDF123 di https://pdf123.xyz/mcp |
| Input | Laluan fail pada cakera. Pelayan memuat naiknya dan menyimpan hasil di sebelah input | Fail yang dihantar melalui alat muat naik |
| Bukti kelayakan | Tiada untuk penggunaan tanpa nama. PDFX_API_KEY ialah pilihan | Pengepala X-API-KEY pada setiap permintaan. Tanpanya jawapannya 401 |
| Pemasangan | npx -y @pdf123/mcp | Tiada. Tambah URL dan pengepala pada klien |
| Alat | Lima alat untuk katalog penuh 97 alat | Tujuh alat: describe, convert, pages, misc, security, upload dan download |
| Gunakannya apabila | Ejen bekerja pada dokumen dalam folder setempat | Ejen atau perkhidmatan yang dihoskan sudah mengendalikan muat naik melalui API |
Gunakan pelayan setempat untuk pembantu pengekodan pada komputer riba. Gunakan titik akhir yang dihoskan apabila ejen berjalan di awan dan tidak boleh membaca cakera anda.
Bagaimana saya memasang pelayan MCP setempat?
Tiada apa-apa yang perlu dipasang, kerana klien MCP memulakan pelayan dengan npx. Dalam Claude Code, tambahkannya dengan satu perintah.
claude mcp add pdf123 -- npx -y @pdf123/mcpClaude Desktop membaca claude_desktop_config.json, dan Cursor membaca .cursor/mcp.json. Klien lain mempunyai halaman atau fail tetapan MCP. Kesemuanya menerima entri mcpServers yang sama.
{
"mcpServers": {
"pdf123": {
"command": "npx",
"args": ["-y", "@pdf123/mcp"]
}
}
}Mulakan semula klien selepas anda menukar konfigurasinya. Untuk menyimpan salinan pada laluan anda, jalankan npm install -g @pdf123/mcp, yang menyediakan perintah pdf123-mcp. Pelayan memerlukan Node 20.3 atau lebih baharu dan asas API yang boleh dicapai. Tiada mod luar talian.
Apakah yang patut saya minta daripada ejen dahulu?
Minta dalam bahasa biasa dan namakan failnya. Contohnya:
Gabungkan ~/Documents/a.pdf dan ~/Documents/b.pdf, kemudian mampatkan hasilnya.
Ejen memanggil pdf123_run_pipeline, atau pdf123_run_tool dua kali, memuat naik fail ke PDF123, dan menjawab dengan laluan fail yang disimpan. Hasil disimpan di sebelah input pertama dan tidak pernah menggantikan fail yang sedia ada. Operasi yang sama wujud sebagai Gabungkan dan Mampatkan di laman web.
Alat manakah yang ditawarkan oleh pelayan setempat?
Pelayan mempunyai lima alat. Id alat seperti merge ialah argumen rentetan biasa, jadi senarai alat kekal kecil.
| Alat | Fungsi | Argumen utama |
|---|---|---|
pdf123_list_tools | Menyenaraikan alat, satu baris bagi setiap alat | group, query, format |
pdf123_describe_tool | Menunjukkan medan alat, nilai lalai, nilai yang dibenarkan dan sama ada ia berjalan sebagai kelompok | tool |
pdf123_run_tool | Menjalankan satu alat pada fail setempat dan memulangkan laluan yang disimpan atau laporan JSON | tool, files, params, output |
pdf123_run_pipeline | Merangkaikan sehingga 8 alat dalam satu permintaan | steps, files, output |
pdf123_call | Menghantar permintaan mentah kepada mana-mana id alat, id operasi atau laluan /api/... | target, files, fields |
Ejen biasanya memanggil pdf123_list_tools untuk mencari alat, pdf123_describe_tool untuk membaca medannya, dan kemudian pdf123_run_tool. Id yang tersalah taip mendapat cadangan "adakah anda maksudkan".
Bagaimana kelompok, kata laluan dan saluran paip berfungsi?
- Kelompok. Beberapa fail yang diberikan kepada alat satu fail dijalankan sebagai kelompok dengan satu hasil bagi setiap fail. Setiap fail disimpan sebaik sahaja siap. Balasannya ialah laporan bagi setiap fail. Jika mana-mana fail gagal, balasannya ialah ralat dengan laporan dilampirkan, supaya ejen boleh mencuba semula fail yang gagal sahaja.
- Kata laluan.
input_passwordmembuka setiap input yang disulitkan.passwordsmenetapkan satu kata laluan bagi setiap fail, dalam susunan yang sama denganfiles, dengan rentetan kosong untuk fail yang terbuka. Ini juga berfungsi untuk alat berbilang fail seperti Gabungkan. - Saluran paip.
pdf123_run_pipelinemenerima sehingga 8 langkah, dan setiap langkah menyalurkan hasilnya kepada yang seterusnya. Ia menerima argumen kata laluan yang sama. - Panggilan mentah.
pdf123_callmencapai operasi yang lebih baharu daripada pelayan. Tiada apa-apa disahkan secara setempat. - Alat penapis. Alat yang id-nya bermula dengan
filter-menjawab{"matched": false}apabila syaratnya tidak dipenuhi. Itu ialah hasil, bukan ralat. - Cuba semula.
idempotencyKeymemainkan semula hasil pertama selama 24 jam.
Bagaimana saya menghadkan folder yang boleh digunakan oleh ejen?
Tetapkan PDFX_MCP_ROOT kepada sebuah direktori. Asingkan beberapa direktori dengan tanda titik bertindih, atau koma bertitik pada Windows. Pelayan kemudian hanya membaca input dan menulis hasil di dalam direktori tersebut. Laluan di luarnya, helah .. dan pautan simbolik yang menuju ke luar ditolak sebelum apa-apa dimuat naik, dengan Code: path_not_allowed. Tanpa pemboleh ubah ini, mana-mana laluan yang boleh dicapai oleh proses pelayan dibenarkan.
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }Tetapkan pemboleh ubah persekitaran dalam blok env klien, atau dengan claude mcp add -e NAME=value. PDFX_API_BASE menghalakan pelayan ke pdfx-server anda sendiri; lihat Self-host.
Bagaimana rupa hasil dan ralat?
Hasil tunggal ialah objek JSON kecil dengan path yang disimpan, contentType dan saiz dalam bytes. Hasil kelompok mempunyai processed, unmatched, failed dan senarai files. Bentuk ini sepadan dengan pdfx --json pada baris perintah. Alat yang memulangkan laporan, seperti Maklumat dokumen, memulangkan laporan itu secara sebaris.
{
"path": "/Users/me/Documents/merged.pdf",
"contentType": "application/pdf",
"bytes": 1096
}Panggilan yang gagal kembali sebagai ralat alat. Teksnya berakhir dengan baris Reason:, Code: dan Hint: apabila pelayan membekalkannya, supaya ejen boleh bercabang mengikut kod.
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.Jika id alat tersalah taip, ralat menyenaraikan id yang hampir sama dan berakhir dengan Code: unknown_tool. Alat yang tiada apa-apa untuk dipulangkan, seperti pdf-to-csv pada PDF tanpa jadual, memulangkan Code: no_content dan bukannya fail kosong. Lihat Kod ralat.
Bagaimana saya menggunakan titik akhir MCP yang dihoskan?
API membenamkan pelayan MCP di POST https://pdf123.xyz/mcp. Sahkan dengan pengepala X-API-KEY yang sama seperti yang digunakan oleh REST API. Tanpa kunci, titik akhir menjawab 401. Cipta kunci di halaman pembangun.
{
"mcpServers": {
"pdf123": {
"url": "https://pdf123.xyz/mcp",
"headers": { "X-API-KEY": "<your-key>" }
}
}
}Pelayan yang dihoskan menyenaraikan tujuh alat: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload dan pdf_toolbox_download. Setiap alat kategori menerima nama operation dan parameternya, serta fail atau fileId yang dipulangkan oleh alat muat naik. Gunakan alat describe untuk mendapatkan skema satu operasi.
Halaman berkaitan
- Skill ejen untuk Claude Code, Codex dan Cursor, satu untuk katalog dan satu bagi setiap alat
- /llms.txt, indeks teks biasa bagi alat, API dan titik akhir MCP
- Baris perintah pdfx dan SDK TypeScript, yang berkongsi katalog
- Gambaran keseluruhan pembangun, dokumen OpenAPI dan Swagger UI
- Halaman alat: Gabungkan, Mampatkan, OCR, Lindungi, Baiki
- Catatan "Built for AI Agents, Not Just Browsers" dan "Same Operation, Four Clients" di blog PDF123
FAQ
Apakah itu MCP?
MCP, Model Context Protocol, ialah standard terbuka untuk menyambungkan klien AI kepada alat luaran. Klien seperti Claude Code memulakan atau menghubungi pelayan MCP, menyenaraikan alatnya, dan memanggilnya bagi pihak pengguna.
Adakah pelayan MCP setempat berfungsi di luar talian?
Tidak. Ia memuat naik fail ke API PDF123, atau ke pelayan yang dinamakan dalam PDFX_API_BASE, dan menyimpan hasilnya secara setempat. Asas API mesti boleh dicapai.
Adakah ia memerlukan kunci API?
Pelayan setempat tidak memerlukan kunci untuk penggunaan tanpa nama. Tetapkan PDFX_API_KEY jika pelayan anda memerlukannya. Titik akhir yang dihoskan di /mcp sentiasa memerlukan pengepala X-API-KEY.
Bolehkah ejen membaca mana-mana fail pada komputer saya?
Secara lalai ia boleh membaca mana-mana laluan yang dapat dicapai oleh proses pelayan. Tetapkan PDFX_MCP_ROOT untuk menghadkan bacaan dan penulisan kepada direktori yang anda pilih.
Apakah yang berlaku kepada fail saya?
Pelayan setempat memuat naik setiap input ke API PDF123, atau ke pelayan anda sendiri, untuk diproses. Huraian alat menyatakan bahawa fail dipadam di sana selepas pemprosesan. Hasil disimpan pada mesin anda. Untuk butiran, baca halaman privasi fail.
Berapa banyak alat yang boleh digunakan oleh ejen?
Pelayan setempat mencapai kesemua 97 alat dalam katalog melalui lima alat MCP. Titik akhir yang dihoskan mengumpulkan operasinya mengikut kategori (convert, pages, misc dan security) di sebalik tujuh alat MCP.