Ποιον διακομιστή 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 mcp add pdf123 -- npx -y @pdf123/mcpΤο Claude Desktop διαβάζει το claude_desktop_config.json και το Cursor διαβάζει το .cursor/mcp.json. Άλλοι πελάτες έχουν σελίδα ή αρχείο ρυθμίσεων MCP. Όλοι δέχονται την ίδια εγγραφή mcpServers.
{
"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 | Εκτελεί ένα εργαλείο σε τοπικά αρχεία και επιστρέφει τη διαδρομή που αποθηκεύτηκε ή την αναφορά JSON | tool, 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. Χωρίς αυτή τη μεταβλητή επιτρέπεται κάθε διαδρομή που μπορεί να φτάσει η διεργασία του διακομιστή.
"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 στη γραμμή εντολών. Ένα εργαλείο που επιστρέφει αναφορά, όπως οι Πληροφορίες εγγράφου, την επιστρέφει ενσωματωμένη.
{
"path": "/Users/me/Documents/merged.pdf",
"contentType": "application/pdf",
"bytes": 1096
}Μια αποτυχημένη κλήση επιστρέφει ως σφάλμα εργαλείου. Το κείμενό της τελειώνει με γραμμές Reason:, Code: και Hint: όταν τις παρείχε ο διακομιστής, ώστε ο πράκτορας να διακλαδωθεί με βάση τον κωδικό.
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. Δημιουργήστε κλειδί στη σελίδα για προγραμματιστές.
{
"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 για να πάρετε το σχήμα μιας λειτουργίας.
Σχετικές σελίδες
- Skills για πράκτορες για Claude Code, Codex και Cursor, ένα για τον κατάλογο και ένα ανά εργαλείο
- /llms.txt, ευρετήριο σε απλό κείμενο των εργαλείων, του API και του endpoint MCP
- Γραμμή εντολών pdfx και SDK TypeScript, που μοιράζονται τον κατάλογο
- Επισκόπηση για προγραμματιστές, το έγγραφο OpenAPI και το Swagger UI
- Σελίδες εργαλείων: Συγχώνευση, Συμπίεση, OCR, Προσθήκη κωδικού, Επισκευή
- Τα άρθρα «Built for AI Agents, Not Just Browsers» και «Same Operation, Four Clients» στο ιστολόγιο του PDF123
Συχνές ερωτήσεις
Τι είναι το 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.