Μετάβαση στο κύριο περιεχόμενο
PPDF123

Διακομιστές MCP του PDF123 για πράκτορες AI

Το MCP, το Model Context Protocol, είναι ανοιχτό πρότυπο που επιτρέπει σε πελάτες AI όπως το Claude Code, το Claude Desktop και το Cursor να καλούν εξωτερικά εργαλεία. Το PDF123 προσφέρει έναν τοπικό διακομιστή MCP, το @pdf123/mcp, για αρχεία στον υπολογιστή σας και ένα φιλοξενούμενο endpoint που χρησιμοποιεί κλειδί API.

@pdf123/mcpNode 20.3 ή νεότερο

Εγκατάσταση

npx -y @pdf123/mcp
Σε αυτή τη σελίδα

Ποιον διακομιστή MCP να χρησιμοποιήσω;

Και οι δύο διακομιστές εκθέτουν τις λειτουργίες του PDF123. Διαφέρουν ως προς το πού εκτελούνται και το πώς φτάνουν σε αυτούς τα αρχεία.

Τοπικός: @pdf123/mcpΦιλοξενούμενος: /mcp
Πού εκτελείταιΣτον υπολογιστή σας, ξεκινά από τον πελάτη MCP μέσω stdioΣτους διακομιστές του PDF123, στο https://pdf123.xyz/mcp
ΕίσοδοςΔιαδρομές αρχείων στον δίσκο. Ο διακομιστής τα ανεβάζει και αποθηκεύει το αποτέλεσμα δίπλα στην είσοδοΑρχεία που στέλνονται μέσω του εργαλείου μεταφόρτωσης
ΔιαπιστευτήριαΚανένα για ανώνυμη χρήση. Το PDFX_API_KEY είναι προαιρετικόΚεφαλίδα X-API-KEY σε κάθε αίτημα. Χωρίς αυτήν η απάντηση είναι 401
Εγκατάστασηnpx -y @pdf123/mcpΚαμία. Προσθέστε τη διεύθυνση URL και την κεφαλίδα στον πελάτη
ΕργαλείαΠέντε εργαλεία για ολόκληρο τον κατάλογο των 97Επτά εργαλεία: describe, convert, pages, misc, security, upload και download
Επιλέξτε το ότανΈνας πράκτορας δουλεύει με έγγραφα σε τοπικό φάκελοΈνας πράκτορας ή μια φιλοξενούμενη υπηρεσία χειρίζεται ήδη τις μεταφορτώσεις μέσω του API

Χρησιμοποιήστε τον τοπικό διακομιστή για βοηθούς προγραμματισμού σε φορητό υπολογιστή. Χρησιμοποιήστε το φιλοξενούμενο endpoint όταν ο πράκτορας εκτελείται στο cloud και δεν μπορεί να διαβάσει τον δίσκο σας.

Πώς εγκαθιστώ τον τοπικό διακομιστή MCP;

Δεν χρειάζεται να εγκαταστήσετε τίποτα, γιατί ο πελάτης MCP ξεκινά τον διακομιστή με το npx. Στο Claude Code, προσθέστε τον με μία εντολή.

Claude Codebash
claude mcp add pdf123 -- npx -y @pdf123/mcp

Το Claude Desktop διαβάζει το claude_desktop_config.json και το Cursor διαβάζει το .cursor/mcp.json. Άλλοι πελάτες έχουν σελίδα ή αρχείο ρυθμίσεων MCP. Όλοι δέχονται την ίδια εγγραφή mcpServers.

MCP client configurationjson
{
  "mcpServers": {
    "pdf123": {
      "command": "npx",
      "args": ["-y", "@pdf123/mcp"]
    }
  }
}

Επανεκκινήστε τον πελάτη αφού αλλάξετε τις ρυθμίσεις του. Για να κρατήσετε αντίγραφο στο path σας, εκτελέστε npm install -g @pdf123/mcp, που παρέχει την εντολή pdf123-mcp. Ο διακομιστής χρειάζεται Node 20.3 ή νεότερο και προσβάσιμη βάση API. Δεν υπάρχει λειτουργία εκτός σύνδεσης.

Τι να ζητήσω πρώτα από τον πράκτορα;

Ζητήστε το σε φυσική γλώσσα και κατονομάστε τα αρχεία. Για παράδειγμα:

Συγχώνευσε τα ~/Documents/a.pdf και ~/Documents/b.pdf και μετά συμπίεσε το αποτέλεσμα.

Ο πράκτορας καλεί το pdf123_run_pipeline, ή δύο φορές το pdf123_run_tool, ανεβάζει τα αρχεία στο PDF123 και απαντά με τη διαδρομή του αποθηκευμένου αρχείου. Το αποτέλεσμα αποθηκεύεται δίπλα στην πρώτη είσοδο και δεν αντικαθιστά ποτέ υπάρχον αρχείο. Οι ίδιες λειτουργίες υπάρχουν στον ιστότοπο ως Συγχώνευση και Συμπίεση.

Ποια εργαλεία προσφέρει ο τοπικός διακομιστής;

Ο διακομιστής έχει πέντε εργαλεία. Τα αναγνωριστικά εργαλείων όπως το merge είναι απλά ορίσματα κειμένου, ώστε η λίστα εργαλείων να παραμένει μικρή.

ΕργαλείοΤι κάνειΒασικά ορίσματα
pdf123_list_toolsΠαραθέτει τα εργαλεία, μία γραμμή για καθέναgroup, query, format
pdf123_describe_toolΔείχνει τα πεδία ενός εργαλείου, τις προεπιλογές, τις επιτρεπόμενες τιμές και αν εκτελείται ως παρτίδαtool
pdf123_run_toolΕκτελεί ένα εργαλείο σε τοπικά αρχεία και επιστρέφει τη διαδρομή που αποθηκεύτηκε ή την αναφορά JSONtool, files, params, output
pdf123_run_pipelineΑλυσοδένει έως 8 εργαλεία σε ένα αίτημαsteps, files, output
pdf123_callΣτέλνει ανεπεξέργαστο αίτημα σε οποιοδήποτε αναγνωριστικό εργαλείου, αναγνωριστικό λειτουργίας ή διαδρομή /api/...target, files, fields

Ένας πράκτορας συνήθως καλεί το pdf123_list_tools για να βρει ένα εργαλείο, το pdf123_describe_tool για να διαβάσει τα πεδία του και έπειτα το pdf123_run_tool. Ένα αναγνωριστικό με τυπογραφικό λάθος επιστρέφει προτάσεις τύπου «εννοούσατε».

Πώς λειτουργούν οι παρτίδες, οι κωδικοί και τα pipelines;

  • Παρτίδες. Πολλά αρχεία που δίνονται σε εργαλείο ενός αρχείου εκτελούνται ως παρτίδα με ένα αποτέλεσμα ανά αρχείο. Κάθε αρχείο αποθηκεύεται μόλις ολοκληρωθεί. Η απάντηση είναι αναφορά ανά αρχείο. Αν αποτύχει κάποιο αρχείο, η απάντηση είναι σφάλμα με συνημμένη την αναφορά, ώστε ο πράκτορας να επαναλάβει μόνο τα αρχεία που απέτυχαν.
  • Κωδικοί. Το input_password ανοίγει κάθε κρυπτογραφημένη είσοδο. Το passwords ορίζει έναν κωδικό ανά αρχείο, με την ίδια σειρά με το files, και κενή συμβολοσειρά για ανοιχτό αρχείο. Λειτουργεί και για εργαλεία πολλών αρχείων, όπως η Συγχώνευση.
  • Pipelines. Το pdf123_run_pipeline δέχεται έως 8 βήματα και κάθε βήμα τροφοδοτεί το επόμενο. Δέχεται τα ίδια ορίσματα κωδικού.
  • Ανεπεξέργαστες κλήσεις. Το pdf123_call φτάνει λειτουργίες νεότερες από τον διακομιστή. Τίποτα δεν επικυρώνεται τοπικά.
  • Εργαλεία φίλτρου. Ένα εργαλείο με αναγνωριστικό που αρχίζει με filter- απαντά {"matched": false} όταν δεν ισχύει η συνθήκη του. Αυτό είναι αποτέλεσμα, όχι σφάλμα.
  • Επαναλήψεις. Το idempotencyKey επαναλαμβάνει το πρώτο αποτέλεσμα για 24 ώρες.

Πώς περιορίζω τους φακέλους που μπορεί να χρησιμοποιεί ο πράκτορας;

Ορίστε το PDFX_MCP_ROOT σε έναν κατάλογο. Διαχωρίστε περισσότερους καταλόγους με άνω και κάτω τελεία ή, στα Windows, με ερωτηματικό. Ο διακομιστής τότε διαβάζει εισόδους και γράφει αποτελέσματα μόνο μέσα σε αυτούς τους καταλόγους. Διαδρομές εκτός αυτών, αποδράσεις με .. και συμβολικοί σύνδεσμοι που οδηγούν έξω απορρίπτονται πριν ανέβει οτιδήποτε, με Code: path_not_allowed. Χωρίς αυτή τη μεταβλητή επιτρέπεται κάθε διαδρομή που μπορεί να φτάσει η διεργασία του διακομιστή.

Restrict file accessjson
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }

Ορίστε μεταβλητές περιβάλλοντος στο μπλοκ env του πελάτη ή με claude mcp add -e NAME=value. Το PDFX_API_BASE κατευθύνει τον διακομιστή στο δικό σας pdfx-server· δείτε την Αυτοφιλοξενία.

Πώς μοιάζουν τα αποτελέσματα και τα σφάλματα;

Ένα μεμονωμένο αποτέλεσμα είναι ένα μικρό αντικείμενο JSON με το path που αποθηκεύτηκε, το contentType και το μέγεθος σε bytes. Το αποτέλεσμα μιας παρτίδας έχει processed, unmatched, failed και μια λίστα files. Αυτές οι μορφές ταιριάζουν με το pdfx --json στη γραμμή εντολών. Ένα εργαλείο που επιστρέφει αναφορά, όπως οι Πληροφορίες εγγράφου, την επιστρέφει ενσωματωμένη.

Single resultjson
{
  "path": "/Users/me/Documents/merged.pdf",
  "contentType": "application/pdf",
  "bytes": 1096
}

Μια αποτυχημένη κλήση επιστρέφει ως σφάλμα εργαλείου. Το κείμενό της τελειώνει με γραμμές Reason:, Code: και Hint: όταν τις παρείχε ο διακομιστής, ώστε ο πράκτορας να διακλαδωθεί με βάση τον κωδικό.

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.

Αν ένα αναγνωριστικό εργαλείου έχει τυπογραφικό λάθος, το σφάλμα παραθέτει παρόμοια αναγνωριστικά και τελειώνει με Code: unknown_tool. Ένα εργαλείο που δεν βρίσκει τίποτα να επιστρέψει, όπως το pdf-to-csv σε PDF χωρίς πίνακες, επιστρέφει Code: no_content αντί για κενό αρχείο. Δείτε τους Κωδικούς σφαλμάτων.

Πώς χρησιμοποιώ το φιλοξενούμενο endpoint MCP;

Το API ενσωματώνει έναν διακομιστή MCP στο POST https://pdf123.xyz/mcp. Ταυτοποιηθείτε με την ίδια κεφαλίδα X-API-KEY που χρησιμοποιεί το REST API. Χωρίς κλειδί, το endpoint απαντά 401. Δημιουργήστε κλειδί στη σελίδα για προγραμματιστές.

Hosted endpoint configurationjson
{
  "mcpServers": {
    "pdf123": {
      "url": "https://pdf123.xyz/mcp",
      "headers": { "X-API-KEY": "<your-key>" }
    }
  }
}

Ο φιλοξενούμενος διακομιστής παραθέτει επτά εργαλεία: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload και pdf_toolbox_download. Κάθε εργαλείο κατηγορίας δέχεται ένα όνομα operation και τις παραμέτρους του, μαζί με ένα αρχείο ή ένα fileId που επιστρέφει το εργαλείο μεταφόρτωσης. Χρησιμοποιήστε το εργαλείο describe για να πάρετε το σχήμα μιας λειτουργίας.

Συχνές ερωτήσεις

Τι είναι το MCP;

Το MCP, το Model Context Protocol, είναι ανοιχτό πρότυπο για τη σύνδεση πελατών AI με εξωτερικά εργαλεία. Ένας πελάτης όπως το Claude Code ξεκινά ή επικοινωνεί με έναν διακομιστή MCP, παραθέτει τα εργαλεία του και τα καλεί για λογαριασμό του χρήστη.

Λειτουργεί ο τοπικός διακομιστής MCP εκτός σύνδεσης;

Όχι. Ανεβάζει αρχεία στο API του PDF123, ή στον διακομιστή που ορίζει το PDFX_API_BASE, και αποθηκεύει το αποτέλεσμα τοπικά. Η βάση του API πρέπει να είναι προσβάσιμη.

Χρειάζεται κλειδί API;

Ο τοπικός διακομιστής δεν χρειάζεται κλειδί για ανώνυμη χρήση. Ορίστε το PDFX_API_KEY αν ο διακομιστής σας απαιτεί κλειδί. Το φιλοξενούμενο endpoint στο /mcp χρειάζεται πάντα κεφαλίδα X-API-KEY.

Μπορεί ο πράκτορας να διαβάσει οποιοδήποτε αρχείο στον υπολογιστή μου;

Από προεπιλογή μπορεί να διαβάσει κάθε διαδρομή που φτάνει η διεργασία του διακομιστή. Ορίστε το PDFX_MCP_ROOT για να περιορίσετε τις αναγνώσεις και τις εγγραφές στους καταλόγους που επιλέγετε.

Τι γίνεται με τα αρχεία μου;

Ο τοπικός διακομιστής ανεβάζει κάθε είσοδο στο API του PDF123, ή στον δικό σας διακομιστή, για επεξεργασία. Η περιγραφή του εργαλείου αναφέρει ότι τα αρχεία διαγράφονται εκεί μετά την επεξεργασία. Το αποτέλεσμα αποθηκεύεται στον υπολογιστή σας. Για λεπτομέρειες, διαβάστε τη σελίδα απορρήτου αρχείων.

Πόσα εργαλεία μπορεί να χρησιμοποιήσει ένας πράκτορας;

Ο τοπικός διακομιστής φτάνει και τα 97 εργαλεία του καταλόγου μέσω πέντε εργαλείων MCP. Το φιλοξενούμενο endpoint ομαδοποιεί τις λειτουργίες του ανά κατηγορία (convert, pages, misc και security) πίσω από επτά εργαλεία MCP.