Którego serwera MCP użyć?
Oba serwery udostępniają operacje PDF123. Różnią się tym, gdzie działają i w jaki sposób trafiają do nich pliki.
| Lokalny: @pdf123/mcp | Hostowany: /mcp | |
|---|---|---|
| Gdzie działa | Na Twoim komputerze, uruchamiany przez klienta MCP przez stdio | Na serwerach PDF123 pod adresem https://pdf123.xyz/mcp |
| Wejście | Ścieżki plików na dysku. Serwer przesyła je i zapisuje wynik obok pliku wejściowego | Pliki wysyłane przez narzędzie przesyłania |
| Poświadczenia | Brak przy użyciu anonimowym. PDFX_API_KEY jest opcjonalny | Nagłówek X-API-KEY w każdym żądaniu. Bez niego odpowiedź to 401 |
| Instalacja | npx -y @pdf123/mcp | Nic. Dodaj adres URL i nagłówek w kliencie |
| Narzędzia | Pięć narzędzi obejmujących cały katalog 97 narzędzi | Siedem narzędzi: describe, convert, pages, misc, security, upload i download |
| Kiedy użyć | Agent pracuje na dokumentach w lokalnym folderze | Agent lub usługa hostowana już obsługuje przesyłanie plików przez API |
Lokalny serwer wybierz dla asystentów programistycznych na laptopie. Hostowany endpoint wybierz wtedy, gdy agent działa w chmurze i nie może czytać Twojego dysku.
Jak zainstalować lokalny serwer MCP?
Nic nie trzeba instalować, ponieważ klient MCP uruchamia serwer przez npx. W Claude Code dodasz go jednym poleceniem.
claude mcp add pdf123 -- npx -y @pdf123/mcpClaude Desktop czyta claude_desktop_config.json, a Cursor czyta .cursor/mcp.json. Inne klienty mają stronę lub plik ustawień MCP. Wszystkie akceptują ten sam wpis mcpServers.
{
"mcpServers": {
"pdf123": {
"command": "npx",
"args": ["-y", "@pdf123/mcp"]
}
}
}Po zmianie konfiguracji uruchom klienta ponownie. Aby mieć kopię w ścieżce systemowej, uruchom npm install -g @pdf123/mcp, co udostępnia polecenie pdf123-mcp. Serwer wymaga Node 20.3 lub nowszego oraz osiągalnego adresu bazowego API. Nie ma trybu offline.
O co poprosić agenta na początek?
Pisz zwykłym językiem i podaj nazwy plików. Na przykład:
Połącz ~/Documents/a.pdf i ~/Documents/b.pdf, a potem skompresuj wynik.
Agent wywołuje pdf123_run_pipeline albo dwa razy pdf123_run_tool, przesyła pliki do PDF123 i odpowiada ścieżką zapisanego pliku. Wynik jest zapisywany obok pierwszego pliku wejściowego i nigdy nie zastępuje istniejącego pliku. Te same operacje są dostępne w serwisie jako Połącz i Kompresuj.
Jakie narzędzia oferuje lokalny serwer?
Serwer ma pięć narzędzi. Identyfikatory narzędzi, takie jak merge, są zwykłymi argumentami tekstowymi, dzięki czemu lista narzędzi pozostaje krótka.
| Narzędzie | Co robi | Kluczowe argumenty |
|---|---|---|
pdf123_list_tools | Wypisuje narzędzia, po jednej linii na narzędzie | group, query, format |
pdf123_describe_tool | Pokazuje pola narzędzia, wartości domyślne, dozwolone wartości i informację, czy działa jako partia | tool |
pdf123_run_tool | Uruchamia jedno narzędzie na plikach lokalnych i zwraca zapisaną ścieżkę lub raport JSON | tool, files, params, output |
pdf123_run_pipeline | Łączy do 8 narzędzi w jednym żądaniu | steps, files, output |
pdf123_call | Wysyła surowe żądanie do dowolnego identyfikatora narzędzia, identyfikatora operacji lub ścieżki /api/... | target, files, fields |
Agent zwykle wywołuje pdf123_list_tools, aby znaleźć narzędzie, pdf123_describe_tool, aby przeczytać jego pola, a następnie pdf123_run_tool. Literówka w identyfikatorze zwraca podpowiedzi „czy chodziło o”.
Jak działają partie, hasła i potoki?
- Partie. Kilka plików podanych narzędziu jednoplikowemu jest uruchamianych jako partia z jednym wynikiem na plik. Każdy plik jest zapisywany, gdy tylko zostanie przetworzony. Odpowiedź to raport dla każdego pliku. Jeśli którykolwiek plik się nie powiedzie, odpowiedzią jest błąd z dołączonym raportem, dzięki czemu agent może ponowić tylko nieudane pliki.
- Hasła.
input_passwordotwiera każde zaszyfrowane wejście.passwordsustawia jedno hasło na plik, w tej samej kolejności cofiles, z pustym ciągiem dla pliku otwartego. Działa to także dla narzędzi wieloplikowych, takich jak Połącz. - Potoki.
pdf123_run_pipelineprzyjmuje do 8 kroków, a każdy krok zasila następny. Przyjmuje te same argumenty haseł. - Wywołania surowe.
pdf123_callsięga po operacje nowsze niż serwer. Lokalnie nic nie jest walidowane. - Narzędzia filtrujące. Narzędzie, którego identyfikator zaczyna się od
filter-, odpowiada{"matched": false}, gdy jego warunek nie jest spełniony. To wynik, a nie błąd. - Ponawianie.
idempotencyKeyzwraca pierwszy wynik przez 24 godziny.
Jak ograniczyć, z których folderów może korzystać agent?
Ustaw PDFX_MCP_ROOT na katalog. Kilka katalogów rozdziel dwukropkiem, a w systemie Windows średnikiem. Serwer czyta wtedy wejścia i zapisuje wyniki tylko w tych katalogach. Ścieżki spoza nich, wyjścia przez .. i dowiązania symboliczne prowadzące na zewnątrz są odrzucane, zanim cokolwiek zostanie wysłane, z Code: path_not_allowed. Bez tej zmiennej dozwolona jest każda ścieżka, do której ma dostęp proces serwera.
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }Zmienne środowiskowe ustaw w bloku env klienta lub przez claude mcp add -e NAME=value. PDFX_API_BASE kieruje serwer na Twój własny pdfx-server; zobacz Self-host.
Jak wyglądają wyniki i błędy?
Pojedynczy wynik to mały obiekt JSON z zapisaną ścieżką path, typem contentType i rozmiarem w bytes. Wynik partii zawiera processed, unmatched, failed oraz listę files. Te kształty odpowiadają pdfx --json w wierszu poleceń. Narzędzie zwracające raport, takie jak Informacje o dokumencie, zwraca raport bezpośrednio w odpowiedzi.
{
"path": "/Users/me/Documents/merged.pdf",
"contentType": "application/pdf",
"bytes": 1096
}Nieudane wywołanie wraca jako błąd narzędzia. Jego tekst kończy się liniami Reason:, Code: i Hint:, jeśli serwer je podał, więc agent może rozgałęziać logikę według kodu.
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.Jeśli w identyfikatorze narzędzia jest literówka, błąd wymienia zbliżone identyfikatory i kończy się Code: unknown_tool. Narzędzie, które nie ma nic do zwrócenia, na przykład pdf-to-csv dla PDF-a bez tabel, zwraca Code: no_content zamiast pustego pliku. Zobacz Kody błędów.
Jak używać hostowanego endpointu MCP?
API zawiera wbudowany serwer MCP pod adresem POST https://pdf123.xyz/mcp. Uwierzytelnij się tym samym nagłówkiem X-API-KEY, którego używa API REST. Bez klucza endpoint odpowiada 401. Klucz utworzysz na stronie dla deweloperów.
{
"mcpServers": {
"pdf123": {
"url": "https://pdf123.xyz/mcp",
"headers": { "X-API-KEY": "<your-key>" }
}
}
}Hostowany serwer udostępnia siedem narzędzi: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload i pdf_toolbox_download. Każde narzędzie kategorii przyjmuje nazwę operation i jej parametry oraz plik lub fileId zwrócony przez narzędzie przesyłania. Schemat jednej operacji pobierzesz narzędziem describe.
Powiązane strony
- Skille dla agentów dla Claude Code, Codex i Cursor: jeden dla katalogu i po jednym dla każdego narzędzia
- /llms.txt, indeks narzędzi, API i endpointu MCP zwykłym tekstem
- Wiersz poleceń pdfx i SDK TypeScript, które współdzielą katalog
- Przegląd dla deweloperów, dokument OpenAPI i Swagger UI
- Strony narzędzi: Połącz, Kompresuj, OCR, Zabezpiecz, Napraw
- Wpisy „Built for AI Agents, Not Just Browsers” i „Same Operation, Four Clients” na blogu PDF123
FAQ
Czym jest MCP?
MCP, czyli Model Context Protocol, to otwarty standard łączenia klientów AI z zewnętrznymi narzędziami. Klient, taki jak Claude Code, uruchamia serwer MCP lub łączy się z nim, pobiera listę jego narzędzi i wywołuje je w imieniu użytkownika.
Czy lokalny serwer MCP działa offline?
Nie. Przesyła pliki do API PDF123 lub na serwer wskazany w PDFX_API_BASE i zapisuje wynik lokalnie. Adres bazowy API musi być osiągalny.
Czy potrzebuje klucza API?
Lokalny serwer nie wymaga klucza przy użyciu anonimowym. Ustaw PDFX_API_KEY, jeśli Twój serwer tego wymaga. Hostowany endpoint pod /mcp zawsze wymaga nagłówka X-API-KEY.
Czy agent może czytać dowolny plik na moim komputerze?
Domyślnie może czytać każdą ścieżkę, do której ma dostęp proces serwera. Ustaw PDFX_MCP_ROOT, aby ograniczyć odczyt i zapis do wybranych katalogów.
Co się dzieje z moimi plikami?
Lokalny serwer przesyła każde wejście do API PDF123 lub na Twój własny serwer w celu przetworzenia. Opis narzędzia podaje, że pliki są tam usuwane po przetworzeniu. Wynik jest zapisywany na Twoim komputerze. Szczegóły znajdziesz na stronie o prywatności plików.
Ile narzędzi może używać agent?
Lokalny serwer udostępnia wszystkie 97 narzędzi z katalogu przez pięć narzędzi MCP. Hostowany endpoint grupuje swoje operacje według kategorii (convert, pages, misc i security) za siedmioma narzędziami MCP.