Un agente IA dovrebbe chiedere a un documento tre cose prima di renderizzare una singola pagina: quante pagine ha, quanto è grande ogni pagina e se necessita di una password. Il server GroupDocs.Viewer.Mcp risponde alle prime due con una chiamata economica (get_view_info), eseguita localmente sulla tua macchina, e la questione della password viene risolta nel prompt. L’agente quindi renderizza solo le pagine che contano:

Qual è contract.docx — quante pagine ha e qual è la dimensione della pagina?

La versione passo‑passo con configurazione e risoluzione dei problemi è nella documentazione: Come controllare le pagine di un documento prima di renderizzarle.

Perché ispezionare prima?

Ogni pagina che lo strumento render_page produce ritorna all’agente come un PNG inline, spesso di qualche centinaio di kilobyte. Un agente che renderizza un file di 60 pagine per trovare una tabella paga per 59 immagini non necessarie, in termini di tempo e di finestra di contesto. Lo strumento di ispezione, get_view_info, non renderizza nulla. Restituisce un piccolo oggetto JSON, così la decisione su cosa renderizzare è basata su fatti piuttosto che su supposizioni.

Il modello è riutilizzabile in qualsiasi client: Claude Desktop, Claude Code, Cursor, VS Code con GitHub Copilot o Windsurf. È un’abitudine che inserisci in un prompt, non una funzionalità da configurare.

Domanda 1: Quante pagine ci sono?

get_view_info restituisce pageCount. Questo è l’unico meccanismo di protezione contro un limite documentato: render_page non verifica il numero di pagina rispetto al documento. Richiedi la pagina 40 di un file di 12 pagine e riceverai comunque un’immagine, salvata come <name>_page40.png, di una pagina che non è la pagina 40.

Un prompt che costruisce la protezione:

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

Per i fogli di calcolo il conteggio è ancora più importante. Il motore suddivide un foglio in pagine, e il numero può essere molto più grande di quanto il foglio sembri. Conoscerlo in anticipo impedisce all’agente di renderizzare tutte.

Domanda 2: Qual è la dimensione di ogni pagina?

Qual è la dimensione delle pagine in questo PDF — Letter o A4?

La risposta elenca number, width e height per ogni pagina, in punti. 612 per 792 corrisponde a US Letter; circa 595 per 842 è A4. Un documento con una pagina in orizzontale tra pagine in verticale lo mostra nelle dimensioni, e quella pagina è spesso la tabella o il disegno di cui qualcuno sta chiedendo.

Altri due campi, name e visible, sono compilati dove il formato li prevede, ad esempio i nomi dei fogli di lavoro e le diapositive o i fogli nascosti. Altrimenti sono null e true.

Domanda 3: Il file richiede una password?

get_view_info non ha un campo di protezione, quindi il tipo di file e il conteggio delle pagine non indicano se è necessaria una password. Un file protetto da password richiede la password ad ogni chiamata, a entrambi gli strumenti. Forniscila subito nel prompt:

La password per contract.pdf è nel mio messaggio. Controlla quante pagine ha, poi mostrami la pagina 2.

Senza la password la chiamata fallisce, e l’agente può chiedertela invece di indovinare. Se la chiamata fallisce, get_view_info restituisce un testo che inizia con View-info lookup failed for seguito dal tipo di eccezione e dal messaggio, così l’agente può leggere il motivo e chiedere la password o il nome corretto del file.

Un prompt riutilizzabile di ispezione‑then‑render

Prima di renderizzare qualsiasi cosa dal file indicato di seguito, controlla il suo tipo di file, il conteggio delle pagine e le dimensioni delle pagine. Dimmi cosa hai trovato, poi renderizza solo le pagine necessarie per rispondere alla mia domanda. File: contract.docx. Domanda: dove si trova la clausola di risoluzione?

L’agente chiama get_view_info, riporta il tipo di file e il conteggio delle pagine, seleziona le pagine e chiama render_page per ciascuna. Lo strumento get_license_status è il terzo strumento sul server; usalo quando devi sapere se le pagine renderizzate saranno contrassegnate da watermark.

Sessione di esempio

Un’illustrazione basata sulla forma della risposta documentata, non uno screenshot catturato.

You:   Inspect report.pdf before rendering anything.

Agent: [calls get_view_info on report.pdf]
       report.pdf: Portable Document Format File (.pdf), 2 pages.
       Page 1: 612 x 792 points (US Letter). Page 2: 612 x 792 points.
       Which page would you like me to render?

Cosa decide l’agente e cosa fa il motore?

Step Agent Engine
Scegli il file Prende il nome del file dal tuo prompt Lo risolve nella cartella di archiviazione, elenca i file disponibili se il nome non corrisponde
Ispeziona Decide quali domande sono rilevanti Restituisce tipo di file, conteggio delle pagine e dimensioni delle pagine
Seleziona pagine Mappa la tua domanda ai numeri di pagina Niente
Renderizza Chiama render_page per ogni pagina scelta Produce il PNG

Limiti onesti

  • Modalità di valutazione. Le pagine renderizzate hanno un watermark di valutazione e un processo server apre al massimo 15 documenti. Chiedi “Il server Viewer è licenziato?” così l’agente chiama get_license_status prima di fare affidamento sull’output.
  • Il conteggio delle pagine non sceglie le pagine per te. get_view_info indica quali pagine esistono, non quale contiene la risposta. Per questo, renderizza una pagina di indice o qualche candidato.
  • Solo PNG. Non c’è un’opzione di formato su render_page.

FAQ

Come può un agente IA ottenere il conteggio delle pagine di un PDF? Se il server Viewer è connesso, Claude può chiamare get_view_info e leggere pageCount senza renderizzare nulla. La risposta proviene dal documento, non da un’ipotesi.

Può uno strumento MCP di informazioni sul documento dire all’agente quali pagine renderizzare? Sì. Fornisci prima il conteggio delle pagine e le dimensioni, poi indica cosa stai cercando. Renderizza le pagine che rispondono alla domanda.

L’ispezione di un documento lo carica da qualche parte? No. Il server legge il file dalla cartella che configuri e restituisce un piccolo oggetto JSON al tuo client.

Approfondisci