An AI agent nên hỏi một tài liệu ba điều trước khi nó hiển thị một trang duy nhất: tài liệu có bao nhiêu trang, mỗi trang có kích thước bao nhiêu, và liệu nó có cần mật khẩu hay không. Máy chủ GroupDocs.Viewer.Mcp trả lời hai câu hỏi đầu tiên bằng một lời gọi đơn giản (get_view_info), chạy cục bộ trên máy của bạn, và câu hỏi về mật khẩu được giải quyết trong lời nhắc. Sau đó, tác nhân chỉ hiển thị những trang quan trọng:

contract.docx — bao nhiêu trang, và kích thước trang là gì?

Phiên bản từng bước với cấu hình và khắc phục sự cố có trong tài liệu: Cách kiểm tra số trang của tài liệu trước khi hiển thị chúng.

Tại sao cần kiểm tra trước?

Mỗi trang mà công cụ render_page tạo ra sẽ trả lại cho tác nhân dưới dạng PNG nội tuyến, thường vài trăm kilobyte. Một tác nhân hiển thị một tệp 60 trang chỉ để tìm một bảng sẽ phải trả giá cho 59 hình ảnh không cần thiết, cả về thời gian lẫn cửa sổ ngữ cảnh. Công cụ kiểm tra, get_view_info, không hiển thị gì. Nó trả về một đối tượng JSON nhỏ, vì vậy quyết định về việc hiển thị dựa trên thực tế chứ không phải đoán.

Mẫu này có thể tái sử dụng trong bất kỳ client nào: Claude Desktop, Claude Code, Cursor, VS Code với GitHub Copilot hoặc Windsurf. Đó là một thói quen bạn đưa vào lời nhắc, không phải một tính năng bạn cấu hình.

Câu hỏi 1: Có bao nhiêu trang?

get_view_info trả về pageCount. Đây là biện pháp duy nhất bảo vệ trước một lỗ hổng đã được ghi nhận: render_page không kiểm tra số trang so với tài liệu. Yêu cầu trang 40 của một tệp 12 trang và bạn vẫn sẽ nhận được một hình ảnh, được lưu dưới dạng <name>_page40.png, của một trang không phải là trang 40.

Một lời nhắc xây dựng biện pháp bảo vệ này:

Báo cáo có bao nhiêu trang? Sau đó hiển thị cho tôi trang cuối cùng.

Đối với bảng tính, số lượng còn quan trọng hơn. Engine chia một sheet thành các trang, và số trang có thể lớn hơn nhiều so với vẻ bề ngoài của sheet. Biết trước sẽ ngăn tác nhân hiển thị tất cả chúng.

Câu hỏi 2: Kích thước mỗi trang là bao nhiêu?

Kích thước các trang trong PDF này là gì — Letter hay A4?

Phản hồi liệt kê number, width và height cho mỗi trang, tính bằng điểm. 612 x 792 là US Letter; khoảng 595 x 842 là A4. Một tài liệu có một trang ngang trong số các trang dọc sẽ hiển thị kích thước đó, và trang đó thường là bảng hoặc bản vẽ mà ai đó đang hỏi.

Hai trường khác, name và visible, được điền khi định dạng có chúng, ví dụ tên worksheet và các slide hoặc sheet ẩn. Nếu không, chúng sẽ là null và true.

Câu hỏi 3: Tệp có cần mật khẩu không?

get_view_info không có trường bảo vệ, vì vậy loại tệp và số trang không cho biết liệu có cần mật khẩu hay không. Một tệp được bảo vệ bằng mật khẩu cần mật khẩu ở mỗi lần gọi, cho bất kỳ công cụ nào. Cung cấp mật khẩu ngay trong lời nhắc:

Mật khẩu cho contract.pdf nằm trong tin nhắn của tôi. Kiểm tra xem nó có bao nhiêu trang, sau đó hiển thị cho tôi trang 2.

Nếu không có mật khẩu, lời gọi sẽ thất bại, và tác nhân có thể yêu cầu bạn cung cấp mật khẩu thay vì đoán. Khi lời gọi thất bại, get_view_info trả về văn bản bắt đầu bằng View-info lookup failed for kèm theo loại ngoại lệ và thông báo, vì vậy tác nhân có thể đọc lý do và yêu cầu mật khẩu hoặc tên tệp đúng.

Một lời nhắc kiểm tra-đầu-rồi-hiển thị có thể tái sử dụng

Trước khi hiển thị bất kỳ nội dung nào từ tệp có tên dưới đây, hãy kiểm tra loại tệp, số trang và kích thước trang. Hãy cho tôi biết những gì bạn tìm thấy, sau đó chỉ hiển thị các trang cần thiết để trả lời câu hỏi của tôi. Tệp: contract.docx. Câu hỏi: điều khoản chấm dứt nằm ở đâu?

Tác nhân gọi get_view_info, báo cáo loại tệp và số trang, chọn các trang, và gọi render_page cho mỗi trang. Công cụ get_license_status là công cụ thứ ba trên máy chủ; sử dụng nó khi bạn cần biết các trang đã hiển thị có bị đánh dấu watermark hay không.

Phiên làm việc mẫu

Một minh họa dựa trên cấu trúc phản hồi đã được ghi nhận, không phải ảnh chụp màn hình thực tế.

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?

Tác nhân quyết định gì, và engine thực hiện gì?

Bước Tác nhân Engine
Chọn tệp Lấy tên tệp từ lời nhắc của bạn Xác định nó trong thư mục lưu trữ, liệt kê các tệp có sẵn nếu tên không khớp
Kiểm tra Quyết định câu hỏi nào quan trọng Trả về loại tệp, số trang và kích thước trang
Chọn trang Ánh xạ câu hỏi của bạn tới các số trang Không có gì
Hiển thị Gọi render_page cho mỗi trang đã chọn Tạo PNG

Giới hạn thực tế

  • Chế độ đánh giá. Các trang đã hiển thị có chứa watermark đánh giá và một tiến trình máy chủ mở tối đa 15 tài liệu. Hỏi “Máy chủ Viewer có được cấp phép không?” để tác nhân gọi get_license_status trước khi bạn dựa vào kết quả.
  • Số trang không tự động chọn trang cho bạn. get_view_info cho biết những trang nào tồn tại, không phải trang nào chứa câu trả lời. Để làm điều đó, hãy hiển thị một trang mục lục hoặc một vài trang dự đoán.
  • Chỉ PNG. Không có tùy chọn định dạng trên render_page.

Câu hỏi thường gặp

Làm thế nào một tác nhân AI có thể lấy số trang của PDF? Nếu máy chủ Viewer được kết nối, Claude có thể gọi get_view_info và đọc pageCount mà không cần hiển thị gì. Câu trả lời được lấy từ tài liệu, không phải đoán.

Công cụ MCP thông tin tài liệu có thể cho tác nhân biết trang nào cần hiển thị không? Có. Đầu tiên cung cấp số trang và kích thước, sau đó cho nó biết bạn đang tìm gì. Nó sẽ hiển thị các trang trả lời câu hỏi.

Việc kiểm tra tài liệu có tải lên bất kỳ nơi nào không? Không. Máy chủ đọc tệp từ thư mục bạn cấu hình và trả về một đối tượng JSON nhỏ cho client của bạn.

Tìm hiểu sâu hơn