Към основното съдържание
PPDF123

MCP сървъри на PDF123 за AI агенти

MCP, Model Context Protocol, е отворен стандарт, който позволява на AI клиенти като Claude Code, Claude Desktop и Cursor да извикват външни инструменти. PDF123 предлага локален MCP сървър, @pdf123/mcp, за файлове на вашия компютър и хостван адрес, който работи с 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Не е нужно. Добавете адреса и заглавката в клиента
ИнструментиПет инструмента за целия каталог от 97 инструментаСедем инструмента: описание, преобразуване, страници, разни, сигурност, качване и изтегляне
Кога да го ползватеАгент работи с документи в локална папкаАгент или хостван сервиз вече управлява качването през API

Използвайте локалния сървър за помощници за програмиране на лаптоп. Използвайте хостваната крайна точка, когато агентът работи в облака и не може да чете диска ви.

Как да инсталирам локалния 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"]
    }
  }
}

Рестартирайте клиента, след като промените конфигурацията му. За да го инсталирате глобално, изпълнете 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. Идентификатор с правописна грешка връща предложения "нямахте ли предвид".

Как работят пакетите, паролите и последователностите?

  • Пакети. Няколко файла, подадени на инструмент за един файл, се изпълняват като пакет с по един резултат за файл. Всеки файл се записва, щом приключи. Отговорът е отчет за всеки файл. Ако някой файл е неуспешен, отговорът е грешка с приложен отчет, така че агентът може да повтори само неуспешните файлове.
  • Пароли. input_password отваря всеки криптиран вход. passwords задава по една парола за файл, в същия ред като files, с празен низ за отворен файл. Това работи и за инструменти с няколко файла, като Обединяване.
  • Последователности. 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; вижте Self-host.

Как изглеждат резултатите и грешките?

Единичният резултат е малък 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 вместо празен файл. Вижте Кодове за грешки.

Как да използвам хостваната MCP крайна точка?

API включва MCP сървър на POST https://pdf123.xyz/mcp. Удостоверявайте се със същата заглавка X-API-KEY, която използва REST API. Без ключ крайната точка отговаря с 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, върнат от инструмента за качване. Използвайте инструмента за описание, за да получите схемата на една операция.

Често задавани въпроси

Какво е MCP?

MCP, Model Context Protocol, е отворен стандарт за свързване на AI клиенти с външни инструменти. Клиент като Claude Code стартира MCP сървър или се свързва с него, изброява инструментите му и ги извиква от името на потребителя.

Работи ли локалният MCP сървър офлайн?

Не. Той качва файловете в PDF123 API или в сървъра, посочен в PDFX_API_BASE, и записва резултата локално. Базовият адрес на API трябва да е достъпен.

Нужен ли му е API ключ?

Локалният сървър не изисква ключ при анонимна употреба. Задайте PDFX_API_KEY, ако сървърът ви изисква ключ. Хостваната крайна точка на /mcp винаги изисква заглавка X-API-KEY.

Може ли агентът да чете всеки файл на компютъра ми?

По подразбиране може да чете всеки път, до който процесът на сървъра има достъп. Задайте PDFX_MCP_ROOT, за да ограничите четенето и записа до директориите, които изберете.

Какво се случва с файловете ми?

Локалният сървър качва всеки вход в PDF123 API или във ваш собствен сървър за обработка. Описанието на инструмента гласи, че файловете се изтриват там след обработката. Резултатът се запазва на вашия компютър. За подробности прочетете страницата за поверителност на файловете.

Колко инструмента може да използва един агент?

Локалният сървър достига всичките 97 инструмента от каталога чрез пет MCP инструмента. Хостваната крайна точка групира операциите си по категории (преобразуване, страници, разни и сигурност) зад седем MCP инструмента.