Un agente IA dovrebbe scegliere quale file convertire e in quale formato convertirlo, mentre un motore di conversione dovrebbe occuparsi della conversione. Con il server GroupDocs.Conversion.Mcp, Claude, Cursor o GitHub Copilot chiamano quel motore localmente, sulla tua macchina, con una sola frase:

Convert contract.docx to PDF

La versione passo‑passo con configurazione e risoluzione dei problemi è nella documentazione: How to convert documents with AI agents using MCP. Questo post spiega perché la divisione è importante e dove l’agente dovrebbe stare fuori dalla strada.

Cosa va storto quando un agente converte un file da solo?

Un modello linguistico che “converte” un PDF in Word non converte nulla. Legge il contenuto che gli è stato fornito e scrive nuovo contenuto nel formato di destinazione. Qualunque cosa il modello non abbia visto, non può riprodurre: il font esatto, la geometria delle colonne, l’interruzione di pagina prima di una tabella, i nomi degli stili da cui dipende un modello Word. Quello che ritorna sembra una conversione ed è una riscrittura.

Questo è il caso di errore di cui parla questo post. È silenzioso: l’output si apre senza errori, quindi nessuno lo controlla finché una tabella non si è spostata o un’intestazione non ha perso lo stile. La fedeltà di rendering è lavoro deterministico del motore, non lavoro di generazione.

Cosa dovrebbe decidere l’agente e cosa dovrebbe fare il motore?

Dividi il lavoro lungo la linea tra giudizio ed esecuzione.

Domanda L’agente decide Il motore fa
Quali file sono in ambito? Legge il tuo prompt e la cartella di archiviazione Niente
Quale formato di destinazione? Mappa “rendi modificabile” a DOCX, “archivia” a PDF Niente
Il file è convertibile? Chiama get_supported_formats e legge la risposta Riporta i formati di destinazione validi
Quanto è grande il file? Chiama get_document_info e legge il conteggio delle pagine Legge tipo, conteggio pagine, proprietà
La conversione stessa Chiama convert Renderizza l’output con il motore GroupDocs.Conversion
Cosa fare in caso di errore Riprova, ti chiede, o salta il file Restituisce il motivo come testo

L’agente non tocca mai i byte del tuo documento. Passa un nome file e un formato, e il motore restituisce un file.

Come collegare un agente al motore localmente?

Registra il server una sola volta nel tuo client. Claude Desktop usa claude_desktop_config.json, Claude Code usa claude mcp add, VS Code con GitHub Copilot usa mcp.json, e Cursor usa ~/.cursor/mcp.json. Il server supporta anche Visual Studio 2022, Windsurf, Cline, Codex CLI e JetBrains Rider. Un esempio di voce per Claude Desktop è il seguente:

{
  "mcpServers": {
    "groupdocs-conversion": {
      "type": "stdio",
      "command": "dnx",
      "args": ["GroupDocs.Conversion.Mcp", "--yes"],
      "env": { "GROUPDOCS_MCP_STORAGE_PATH": "/path/to/documents" }
    }
  }
}

dnx richiede il .NET 10 SDK. Se preferisci Docker, l’immagine autonoma è ghcr.io/groupdocs-conversion/conversion-net-mcp:latest, avviala con docker run --rm -i -v $(pwd)/documents:/data davanti. Il client comunica con il server tramite stdio: il percorso è agente, server locale, filesystem locale. Riavvia il client dopo la registrazione.

Quale strumento attiva ogni richiesta?

Il server espone quattro strumenti. I loro nomi sono letterali; gli agenti li cercano quando qualcosa si rompe.

  • convert converte un documento in un altro formato e salva il risultato nella tua cartella di archiviazione o di output. Accetta file, format (ad esempio pdf, docx, xlsx, pptx, html, png, jpg, csv, txt, rtf, md) e un password opzionale.
  • get_supported_formats elenca i formati di destinazione in cui un dato file sorgente può essere trasformato.
  • get_document_info restituisce tipo di file, numero di pagine e proprietà di base senza effettuare la conversione.
  • get_license_status segnala se il server gira in modalità valutazione, con file di licenza o a consumo.

I prompt aperti funzionano perché l’agente li concatena:

Quali formati posso trasformare questo file Visio? Poi convertilo in PDF.

Controlla prima il conteggio delle pagine di whitepaper.pdf, poi convertilo in DOCX.

I file esistenti non vengono mai sovrascritti. Una seconda conversione dello stesso file ottiene un nome distinto, ad esempio report (1).pdf.

Sessione di esempio

Questa è una sessione illustrativa, abbreviata, costruita dalle descrizioni degli strumenti nella documentazione, non uno screenshot.

You:    Convert contract-draft.pdf to DOCX so I can edit it.
Agent:  [calls convert with file.filePath = "contract-draft.pdf", format = "docx"]
Agent:  Done. The converted file is saved as contract-draft.docx in your output folder.

Per il ciclo completo, the n8n walkthrough mostra lo stesso motore guidato da un workflow invece che da una chat, e l’announcement copre il server in generale.

Quali sono i limiti?

  • Modalità valutazione. Senza licenza il server aggiunge una filigrana di valutazione all’output convertito e limita ogni processo server a 15 documenti aperti; riavviare il server azzera il conteggio. Chiedi al tuo agente “qual è lo stato della licenza del server di conversione?” prima; get_license_status risponde senza elaborare un documento.
  • Nessun OCR. Il server converte documenti che hanno uno strato di testo. Una scansione salvata come PDF solo immagine non verrà restituita come testo modificabile.
  • Conversione, non estrazione. Questo server trasforma documenti interi. Per l’estrazione di dati a livello di campo, il server complementare GroupDocs.Parser.Mcp (distribuito solo come immagine Docker) è più adatto, e molte pipeline lo usano entrambi.

FAQ

Claude può convertire un docx in pdf?
Sì, con un server di conversione collegato. Claude chiama convert con format: "pdf", e il motore GroupDocs produce il file sulla tua macchina.

I miei file vengono caricati quando un agente li converte?
No con questo server. Funziona localmente via stdio, e i documenti rimangono nella tua cartella di archiviazione. Anche il tuo file di licenza viene letto dal disco locale.

Quali formati può convertire il server?
Oltre 100 formati di documenti, fogli di calcolo, presentazioni, immagini, email, CAD e web, lo stesso set della libreria .NET GroupDocs.Conversion. Chiedi get_supported_formats per l’elenco esatto per un dato file.

Approfondisci