Langkau ke kandungan utama
PPDF123

Pelayan MCP PDF123 untuk ejen AI

MCP, Model Context Protocol, ialah standard terbuka yang membolehkan klien AI seperti Claude Code, Claude Desktop dan Cursor memanggil alat luaran. PDF123 menawarkan pelayan MCP setempat, @pdf123/mcp, untuk fail pada mesin anda dan titik akhir yang dihoskan yang menggunakan kunci API.

@pdf123/mcpNode 20.3 atau lebih baharu

Pasang

npx -y @pdf123/mcp
Dalam halaman ini

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/mcpDihoskan: /mcp
Berjalan di manaPada mesin anda, dimulakan oleh klien MCP melalui stdioPada pelayan PDF123 di https://pdf123.xyz/mcp
InputLaluan fail pada cakera. Pelayan memuat naiknya dan menyimpan hasil di sebelah inputFail yang dihantar melalui alat muat naik
Bukti kelayakanTiada untuk penggunaan tanpa nama. PDFX_API_KEY ialah pilihanPengepala X-API-KEY pada setiap permintaan. Tanpanya jawapannya 401
Pemasangannpx -y @pdf123/mcpTiada. Tambah URL dan pengepala pada klien
AlatLima alat untuk katalog penuh 97 alatTujuh alat: describe, convert, pages, misc, security, upload dan download
Gunakannya apabilaEjen bekerja pada dokumen dalam folder setempatEjen 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 Codebash
claude mcp add pdf123 -- npx -y @pdf123/mcp

Claude 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.

MCP client configurationjson
{
  "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.

AlatFungsiArgumen utama
pdf123_list_toolsMenyenaraikan alat, satu baris bagi setiap alatgroup, query, format
pdf123_describe_toolMenunjukkan medan alat, nilai lalai, nilai yang dibenarkan dan sama ada ia berjalan sebagai kelompoktool
pdf123_run_toolMenjalankan satu alat pada fail setempat dan memulangkan laluan yang disimpan atau laporan JSONtool, files, params, output
pdf123_run_pipelineMerangkaikan sehingga 8 alat dalam satu permintaansteps, files, output
pdf123_callMenghantar 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_password membuka setiap input yang disulitkan. passwords menetapkan satu kata laluan bagi setiap fail, dalam susunan yang sama dengan files, dengan rentetan kosong untuk fail yang terbuka. Ini juga berfungsi untuk alat berbilang fail seperti Gabungkan.
  • Saluran paip. pdf123_run_pipeline menerima sehingga 8 langkah, dan setiap langkah menyalurkan hasilnya kepada yang seterusnya. Ia menerima argumen kata laluan yang sama.
  • Panggilan mentah. pdf123_call mencapai 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. idempotencyKey memainkan 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.

Restrict file accessjson
"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.

Single resultjson
{
  "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.

Error texttext
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.

Hosted endpoint configurationjson
{
  "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.

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.