Puoi far sì che un agente IA guardi una pagina di un documento invece di leggere un dump di testo. Il server GroupDocs.Viewer.Mcp rende qualsiasi pagina di un file PDF, Word, Excel o PowerPoint come PNG e la restituisce all’agente, e lo fa localmente sulla tua macchina:

Quante pagine ha report.pdf? Poi mostrami l’ultima.

La versione passo‑passo con configurazione e risoluzione dei problemi è nella documentazione: Come far vedere a un agente IA le pagine di un documento.

Perché l’estrazione del testo fallisce sui documenti reali?

Un estrattore di testo restituisce i caratteri nell’ordine di lettura. Non restituisce il grafico a barre tra due paragrafi, il timbro “APPROVED” nell’angolo, il layout a colonne di una tabella dei prezzi, o una pagina che è una scansione e non contiene alcun carattere. Un agente che lavora su quell’output risponde con sicurezza su un documento che ha visto solo a metà, e la metà mancante è solitamente la parte di cui hai chiesto.

La soluzione non è un prompt migliore. È un input diverso: la pagina come immagine, fornita a un modello che accetta input immagine.

Approccio sbagliato: passare tutto attraverso un estrattore di testo

Il valore predefinito comune è convertire il documento in testo, incollare il testo nella finestra di contesto e porre domande. Funziona per la prosa. Si rompe in quattro modi che puoi verificare su qualsiasi documento possiedi:

  • Il layout scompare, quindi “il totale è nella colonna di destra?” non può essere risposto.
  • Le figure all’interno di grafici e diagrammi scompaiono, perché sono disegnate, non digitata.
  • Timbri, firme e scritte a mano scompaiono.
  • Un PDF scansionato non produce testo.

Un modello non può ricostruire informazioni che sono state eliminate prima che vedesse il documento.

Approccio corretto: renderizzare una pagina PDF in un’immagine per il LLM

render_page rende una pagina come PNG, restituisce l’immagine inline all’agente e salva una copia nella tua cartella di output come <name>_page<N>.png. Il server supporta più di 170 formati, inclusi PDF, DOCX, XLSX, PPTX, ODT, RTF, HTML, EML e MSG. Un modello con capacità visiva vede quindi la pagina come faresti tu.

L’agente non dovrebbe indovinare i numeri di pagina, quindi associa render_page a get_view_info, che restituisce il tipo di file, il conteggio delle pagine e le dimensioni di ogni pagina senza renderizzare nulla. Un terzo strumento, get_license_status, segnala la modalità di licenza attiva.

Come eseguire il server per Claude, Cursor o Copilot?

L’immagine Docker è autonoma:

docker run --rm -i -v $(pwd)/documents:/data \
  ghcr.io/groupdocs-viewer/viewer-net-mcp:latest

Con il .NET 10 SDK installato, dnx GroupDocs.Viewer.Mcp --yes esegue lo stesso server senza Docker. Registralo in Claude Desktop, Claude Code, Cursor, VS Code con GitHub Copilot, Windsurf e altri client; la pagina hub elenca la configurazione esatta per ciascuno. Il client avvia il server come processo figlio e comunica con esso tramite input e output standard, quindi non c’è alcuna porta in ingresso né endpoint da proteggere.

Sessione di esempio

Questa è un’illustrazione costruita dal comportamento documentato dei due strumenti, non uno screenshot catturato.

You:   How many pages does report.pdf have? Then show me the last one.

Agent: [calls get_view_info on report.pdf]
       report.pdf is a PDF with 2 pages, both 612 x 792 points (US Letter).
       [calls render_page with page = 2]
       Page 2 of 'report.pdf' Saved to: <output folder>/report_page2.png
       Here is what page 2 shows: ...

L’immagine appare inline nei client che la visualizzano. La risposta testuale è la descrizione dell’agente di ciò che vede sulla pagina.

Cosa decide l’agente e cosa fa il motore?

L’agente decide quale pagina risponde alla domanda e cosa chiedere al modello a riguardo. Il motore esegue la parte che deve essere esatta: aprire il file, impaginarlo come fa il documento e produrre il PNG. Il modello non deve mai indovinare il layout della pagina, perché riceve la pagina renderizzata.

Limiti onesti

  • Evaluation mode. Senza licenza, le pagine renderizzate hanno una filigrana di valutazione e il processo server apre al massimo 15 documenti. La filigrana può coprire il dettaglio che chiedi. Chiedi all’agente “Il server viewer è licenziato?” così chiama get_license_status prima di fare affidamento su ciò che legge.
  • PNG only. L’output è un’immagine PNG; non c’è alcuna opzione di formato.
  • No page-number check. render_page non rifiuta un numero di pagina oltre l’ultima pagina. Controlla il conteggio con get_view_info prima.
  • The model must accept images. Con un modello solo testo l’agente riceve comunque il percorso del file salvato, ma non può dirti cosa c’è nella pagina.
  • Images are large. Ogni pagina è un PNG inline, spesso qualche centinaio di kilobyte. Renderizza solo le pagine necessarie al compito, non l’intero file.
  • One thing leaves the machine. L’immagine renderizzata va all’agente e da lì al modello che utilizza. Un modello ospitato localmente mantiene tutto sulla macchina.

FAQ

Can Claude see my PDF page and its layout? Sì, se la pagina PDF è renderizzata in un’immagine e il modello Claude in uso accetta input immagine. render_page produce quell’immagine localmente e la restituisce al client.

Do I have to upload the document anywhere to render it? Il server legge il file dalla cartella che monti e scrive l’immagine accanto; il documento non viene caricato dal server. L’immagine della pagina va comunque al modello del tuo agente.

Does it work for Excel and PowerPoint, not only PDF? Sì. PowerPoint renderizza un’immagine per diapositiva, e i fogli Excel sono suddivisi in pagine, con il conteggio visibile tramite get_view_info.

Approfondisci