Per convertire in batch una cartella con un agente IA, indirizza il server GroupDocs.Conversion.Mcp alla cartella e descrivi il lavoro in una frase. L’agente elabora i file, chiama il motore di conversione una volta per documento e riporta ciò che ha prodotto, tutto localmente in Claude, Cursor o GitHub Copilot. È un’elaborazione batch guidata da una frase:

Converti tutti i DOCX nella mia cartella documenti in PDF, mantieni gli originali

La versione passo‑passo con configurazione e risoluzione dei problemi è nella documentazione: How to batch-convert a folder of documents with an AI agent. Questo post illustra lo stesso lavoro in una breve sessione, dal primo prompt alla gestione dei fallimenti.

Da dove inizi: la cartella di archiviazione o il prompt?

Inizia con la cartella di archiviazione. Un lavoro batch ha successo o fallisce in base alla mappatura della cartella, e la mappatura viene impostata una sola volta nella voce del server, non in ogni prompt. Due variabili d’ambiente la controllano:

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

GROUPDOCS_MCP_STORAGE_PATH è la cartella che l’agente può leggere. GROUPDOCS_MCP_OUTPUT_PATH è dove atterrano i file convertiti. Con entrambe impostate, la cartella di origine rimane intatta e ogni risultato va nella cartella converted. Questo è il layout più pulito per un batch. Il comando dnx richiede il .NET 10 SDK; l’immagine Docker ghcr.io/groupdocs-conversion/conversion-net-mcp:latest monta la cartella come /data. Riavvia Claude Desktop, Claude Code, VS Code o Cursor dopo aver registrato il server.

Cosa fa il primo prompt?

Fornisci all’agente il caso più semplice prima:

Converti tutto in questa cartella da DOCX a PDF.

L’agente elenca la cartella e chiama lo strumento convert per ogni file con format: "pdf". Ogni chiamata prende un nome file dallo storage e restituisce il nome del file salvato. Eseguilo due volte e la seconda esecuzione crea nuovi file, con nomi distinti, accanto ai primi.

Come aggiungere un filtro o una regola?

Il prompt è lo strato di orchestrazione. Filtrare, sequenziare e definire una politica di errore avviene in linguaggio naturale:

Trasforma tutti i PDF in Markdown; salta i file già convertiti.

Converti le fatture in PDF/A per l’archiviazione e elenca qualsiasi file che abbia fallito.

Crea anteprime PNG di ogni presentazione.

Per la sequenza, l’agente può chiamare prima get_document_info, che restituisce tipo di file, numero di pagine e proprietà di base senza convertire:

Controlla il numero di pagine di ogni PDF prima e converti solo quelli con più di 10 pagine.

La decisione “più di 10 pagine” è dell’agente. La conversione rimane compito del motore.

Cosa succede quando un file fallisce?

Quando il motore non riesce a convertire un file, ad esempio perché il formato di origine non è supportato o la password è errata, il testo di risposta per quel file inizia con l’operazione e il motivo. Un nome file inesistente restituisce l’elenco dei file che il server può vedere, così l’agente può correggersi. Per i file protetti, convert accetta un parametro opzionale password.

Ecco perché una politica di fallimento appartiene al prompt: “elenca qualsiasi file che abbia fallito” chiede all’agente un report alla fine dell’esecuzione, così un errore non passa inosservato. Leggi il report e riesegui solo i file falliti.

Sessione di esempio

Questa è una sessione abbreviata e illustrativa. I nomi dei file sono inventati e la risposta è costruita dal comportamento documentato, non da uno screenshot.

You:    Convert the invoices to PDF/A for archiving, and list any file that failed.
Agent:  [enumerates the invoice files]
Agent:  [calls convert for each file, one at a time]
Agent:  Converted 11 files to the output folder.
        Failed: invoice-0412.docx (password-protected, no password given).

Come monitorare l’avanzamento su una cartella grande?

L’agente di solito elabora i file uno dopo l’altro, quindi il tempo di esecuzione cresce con il numero di file e le loro dimensioni. Per ottenere un report di avanzamento, chiedilo nel prompt: “informami dopo ogni dieci file” o “riassumi alla fine”. Alcune centinaia di documenti funzionano senza problemi, e il report finale ti dice cosa è successo. Inizia con una copia di un piccolo sottoinsieme, verifica due o tre output a occhio, poi esegui la cartella completa.

Cosa fare se il batch deve essere eseguito senza supervisione?

Una sessione con l’agente richiede una persona per avviarla. Per pipeline programmate, la guida n8n mostra uno strumento di workflow che guida lo stesso server, e il motore è anche scriptabile tramite la libreria .NET GroupDocs.Conversion. Usa la chat per batch ad‑hoc quando vuoi leggere il report.

Quali sono i limiti?

  • La modalità di valutazione limita un batch a 15 documenti. Senza licenza, un processo server può aprire al massimo 15 documenti e l’output contiene una filigrana di valutazione. Dopo di che, le chiamate successive falliscono fino al riavvio del server. Controlla la modalità con get_license_status prima di avviare un batch reale, o chiedi “qual è lo stato della licenza del server di conversione?”.
  • Le licenze a consumo richiedono accesso in uscita. Con chiavi a consumo, l’utilizzo viene segnalato ai server GroupDocs, quindi una macchina dietro firewall dovrebbe usare un file di licenza. Il contenuto del documento non viene mai inviato.
  • Le scansioni rimangono immagini. L’OCR non fa parte del server, quindi un batch di PDF solo immagine non otterrà uno strato di testo.

FAQ

Come converto tutti i file DOCX in una cartella in PDF con l’IA?
Imposta la cartella di archiviazione, poi chiedi al tuo agente esattamente questo in una frase. Converte i file uno per uno tramite il server locale e nulla viene caricato.

Un agente IA può elaborare un’intera cartella localmente?
Sì. L’agente e il server di conversione girano entrambi sulla tua macchina, e i file vengono letti e scritti nelle tue cartelle.

Qual è il modo migliore per automatizzare una pipeline di conversione documenti?
Usa la chat per batch ad‑hoc che vuoi revisionare. Per una pipeline che gira su programmazione, guida lo stesso server da uno strumento di workflow come n8n, o script la libreria .NET.

Approfondisci