Ves al contingut principal
PPDF123

Servidors MCP de PDF123 per a agents d'IA

MCP, el Model Context Protocol, és un estàndard obert que permet als clients d'IA com Claude Code, Claude Desktop i Cursor cridar eines externes. PDF123 ofereix un servidor MCP local, @pdf123/mcp, per als fitxers de la teva màquina i un punt allotjat que fa servir una clau d'API.

@pdf123/mcpNode 20.3 o superior

Instal·lació

npx -y @pdf123/mcp
En aquesta pàgina

Quin servidor MCP he de fer servir?

Tots dos servidors exposen operacions de PDF123. Es diferencien pel lloc on s'executen i per com hi arriben els fitxers.

Local: @pdf123/mcpAllotjat: /mcp
On s'executaA la teva màquina, iniciat pel client MCP per stdioAls servidors de PDF123, a https://pdf123.xyz/mcp
EntradaRutes de fitxers del disc. El servidor els puja i desa el resultat al costat de l'entradaFitxers enviats amb l'eina de pujada
CredencialsCap per a l'ús anònim. PDFX_API_KEY és opcionalCapçalera X-API-KEY a cada petició. Sense ella la resposta és 401
Instal·laciónpx -y @pdf123/mcpCap. Afegeix l'URL i la capçalera al client
EinesCinc eines per a tot el catàleg de 97 einesSet eines: describe, convert, pages, misc, security, upload i download
Fes-lo servir quanUn agent treballa amb documents d'una carpeta localUn agent o servei allotjat ja gestiona les pujades amb l'API

Fes servir el servidor local per als assistents de programació d'un portàtil. Fes servir el punt allotjat quan l'agent s'executa al núvol i no pot llegir el teu disc.

Com instal·lo el servidor MCP local?

No cal instal·lar res, perquè el client MCP inicia el servidor amb npx. A Claude Code, afegeix-lo amb una sola ordre.

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

Claude Desktop llegeix claude_desktop_config.json i Cursor llegeix .cursor/mcp.json. Altres clients tenen una pàgina o un fitxer de configuració de MCP. Tots accepten la mateixa entrada mcpServers.

Configuració del client MCPjson
{
  "mcpServers": {
    "pdf123": {
      "command": "npx",
      "args": ["-y", "@pdf123/mcp"]
    }
  }
}

Reinicia el client després de canviar-ne la configuració. Per tenir-ne una còpia al teu path, executa npm install -g @pdf123/mcp, que proporciona l'ordre pdf123-mcp. El servidor necessita Node 20.3 o superior i una base d'API accessible. No hi ha mode sense connexió.

Què li demano primer a l'agent?

Demana-ho en llenguatge natural i anomena els fitxers. Per exemple:

Uneix ~/Documents/a.pdf i ~/Documents/b.pdf i després comprimeix el resultat.

L'agent crida pdf123_run_pipeline, o pdf123_run_tool dues vegades, puja els fitxers a PDF123 i respon amb la ruta del fitxer desat. El resultat es desa al costat de la primera entrada i mai no substitueix un fitxer existent. Les mateixes operacions existeixen al lloc web com a Uneix i Comprimeix.

Quines eines ofereix el servidor local?

El servidor té cinc eines. Els identificadors d'eina com merge són arguments de cadena simples, de manera que la llista d'eines es manté petita.

EinaQuè faArguments clau
pdf123_list_toolsLlista les eines, una línia per einagroup, query, format
pdf123_describe_toolMostra els camps d'una eina, els valors per defecte, els valors permesos i si s'executa com a lottool
pdf123_run_toolExecuta una eina sobre fitxers locals i retorna la ruta desada o l'informe JSONtool, files, params, output
pdf123_run_pipelineEncadena fins a 8 eines en una sola peticiósteps, files, output
pdf123_callEnvia una petició en brut a qualsevol identificador d'eina, identificador d'operació o ruta /api/...target, files, fields

Un agent sol cridar pdf123_list_tools per trobar una eina, pdf123_describe_tool per llegir-ne els camps i després pdf123_run_tool. Un identificador mal escrit retorna suggeriments del tipus «volies dir».

Com funcionen els lots, les contrasenyes i els pipelines?

  • Lots. Diversos fitxers donats a una eina d'un sol fitxer s'executen com a lot amb un resultat per fitxer. Cada fitxer es desa quan acaba. La resposta és un informe per fitxer. Si algun fitxer falla, la resposta és un error amb l'informe adjunt, de manera que l'agent pot tornar a provar només els fitxers fallits.
  • Contrasenyes. input_password obre totes les entrades xifrades. passwords defineix una contrasenya per fitxer, en el mateix ordre que files, amb una cadena buida per a un fitxer obert. També funciona amb eines de diversos fitxers com Uneix.
  • Pipelines. pdf123_run_pipeline accepta fins a 8 passos, i cada pas alimenta el següent. Accepta els mateixos arguments de contrasenya.
  • Crides en brut. pdf123_call arriba a operacions més noves que el servidor. No es valida res en local.
  • Eines de filtre. Una eina l'identificador de la qual comença per filter- respon {"matched": false} quan no es compleix la seva condició. És un resultat, no un error.
  • Reintents. idempotencyKey reprodueix el primer resultat durant 24 hores.

Com limito les carpetes que pot fer servir l'agent?

Defineix PDFX_MCP_ROOT amb un directori. Separa diversos directoris amb dos punts, o amb punt i coma a Windows. Aleshores el servidor llegeix les entrades i escriu els resultats només dins d'aquests directoris. Les rutes de fora, els escapaments amb .. i els enllaços simbòlics que surten es rebutgen abans de pujar res, amb Code: path_not_allowed. Sense aquesta variable, es permet qualsevol ruta a la qual pugui arribar el procés del servidor.

Restringir l'accés als fitxersjson
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }

Defineix les variables d'entorn al bloc env del client, o amb claude mcp add -e NAME=value. PDFX_API_BASE apunta el servidor al teu propi pdfx-server; consulta Autoallotjament.

Com són els resultats i els errors?

Un resultat únic és un petit objecte JSON amb el path desat, el contentType i la mida en bytes. El resultat d'un lot té processed, unmatched, failed i una llista files. Aquestes formes coincideixen amb pdfx --json a la línia d'ordres. Una eina que retorna un informe, com Informació del document, el retorna en línia.

Resultat únicjson
{
  "path": "/Users/me/Documents/merged.pdf",
  "contentType": "application/pdf",
  "bytes": 1096
}

Una crida fallida torna com a error d'eina. El seu text acaba amb les línies Reason:, Code: i Hint: quan el servidor les ha proporcionat, de manera que l'agent pot bifurcar segons el codi.

Text de l'errortext
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.

Si un identificador d'eina té una errada, l'error llista identificadors propers i acaba amb Code: unknown_tool. Una eina que no troba res per retornar, com pdf-to-csv en un PDF sense taules, retorna Code: no_content en lloc d'un fitxer buit. Consulta Codis d'error.

Com faig servir el punt MCP allotjat?

L'API incorpora un servidor MCP a POST https://pdf123.xyz/mcp. Autentica't amb la mateixa capçalera X-API-KEY que fa servir l'API REST. Sense clau, el punt respon 401. Crea una clau a la pàgina per a desenvolupadors.

Configuració del punt allotjatjson
{
  "mcpServers": {
    "pdf123": {
      "url": "https://pdf123.xyz/mcp",
      "headers": { "X-API-KEY": "<your-key>" }
    }
  }
}

El servidor allotjat llista set eines: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload i pdf_toolbox_download. Cada eina de categoria accepta un nom d'operation i els seus paràmetres, a més d'un fitxer o d'un fileId retornat per l'eina de pujada. Fes servir l'eina describe per obtenir l'esquema d'una operació.

FAQ

Què és MCP?

MCP, el Model Context Protocol, és un estàndard obert per connectar clients d'IA amb eines externes. Un client com Claude Code inicia o contacta un servidor MCP, en llista les eines i les crida en nom de la persona usuària.

Funciona el servidor MCP local sense connexió?

No. Puja els fitxers a l'API de PDF123, o al servidor indicat a PDFX_API_BASE, i desa el resultat en local. La base de l'API ha de ser accessible.

Necessita una clau d'API?

El servidor local no necessita clau per a l'ús anònim. Defineix PDFX_API_KEY si el teu servidor en requereix una. El punt allotjat a /mcp sempre necessita una capçalera X-API-KEY.

Pot l'agent llegir qualsevol fitxer del meu ordinador?

Per defecte pot llegir qualsevol ruta a la qual pugui arribar el procés del servidor. Defineix PDFX_MCP_ROOT per limitar les lectures i les escriptures als directoris que triïs.

Què passa amb els meus fitxers?

El servidor local puja cada entrada a l'API de PDF123, o al teu propi servidor, per processar-la. La descripció de l'eina indica que els fitxers s'hi eliminen després del processament. El resultat es desa a la teva màquina. Per als detalls, llegeix la pàgina de privadesa dels fitxers.

Quantes eines pot fer servir un agent?

El servidor local arriba a les 97 eines del catàleg amb cinc eines MCP. El punt allotjat agrupa les operacions per categoria (convert, pages, misc i security) darrere de set eines MCP.