An AI 에이전트는 단일 페이지를 렌더링하기 전에 문서에 세 가지를 물어야 합니다: 페이지 수, 각 페이지의 크기, 그리고 비밀번호가 필요한지 여부. GroupDocs.Viewer.Mcp 서버는 첫 두 질문에 대해 저렴한 호출 하나(get_view_info)로 답합니다. 이 호출은 로컬 머신에서 실행되며, 비밀번호 질문은 프롬프트에서 해결됩니다. 에이전트는 이후 중요한 페이지만 렌더링합니다:

contract.docx는 몇 페이지이며, 페이지 크기는 어떻게 되나요?

구성 및 문제 해결이 포함된 단계별 버전은 문서에 있습니다: 렌더링하기 전에 문서 페이지를 확인하는 방법.

먼저 검토해야 하는 이유

render_page 도구가 생성하는 모든 페이지는 인라인 PNG 형태로 에이전트에게 반환되며, 보통 수백 킬로바이트에 달합니다. 60페이지 파일에서 하나의 표만 찾기 위해 전체를 렌더링하면 필요 없는 59개의 이미지에 시간과 컨텍스트 윈도우를 소비하게 됩니다. 검사 도구인 get_view_info는 아무것도 렌더링하지 않습니다. 작은 JSON 객체를 반환하므로, 무엇을 렌더링할지에 대한 결정이 추측이 아닌 사실에 기반하게 됩니다.

이 패턴은 Claude Desktop, Claude Code, Cursor, GitHub Copilot이 포함된 VS Code 또는 Windsurf와 같은 모든 클라이언트에서 재사용할 수 있습니다. 이는 프롬프트에 넣는 습관일 뿐, 설정하는 기능이 아닙니다.

질문 1: 페이지 수는 얼마나 됩니까?

get_view_info는 pageCount를 반환합니다. 이는 문서에서 알려진 날카로운 경계에 대한 유일한 방어책입니다: render_page는 페이지 번호가 문서와 일치하는지 확인하지 않습니다. 12페이지 파일에서 40페이지를 요청하면 여전히 <name>_page40.png라는 이름의 이미지가 반환되며, 이는 실제 40페이지가 아닙니다.

방어 로직을 포함한 프롬프트 예시:

보고서에 몇 페이지가 있나요? 그런 다음 마지막 페이지를 보여 주세요.

스프레드시트의 경우 페이지 수가 더욱 중요합니다. 엔진은 시트를 페이지로 나누며, 실제 페이지 수는 시트가 보이는 것보다 훨씬 많을 수 있습니다. 먼저 이를 알면 에이전트가 모든 페이지를 렌더링하는 일을 방지할 수 있습니다.

질문 2: 각 페이지의 크기는 어떻게 됩니까?

이 PDF의 페이지 크기는 무엇입니까 — Letter 또는 A4?

응답은 각 페이지마다 number, width, height를 포인트 단위로 나열합니다. 612 × 792는 US Letter이며, 약 595 × 842는 A4입니다. 세로 페이지 사이에 가로 페이지가 하나 포함된 문서는 해당 페이지 크기로 표시되며, 그 페이지가 종종 질문 대상인 표나 도면입니다.

또 다른 두 필드인 name과 visible은 해당 포맷에 이름이나 숨김 슬라이드/시트가 있을 경우 채워집니다. 그렇지 않으면 각각 null과 true가 됩니다.

질문 3: 파일에 비밀번호가 필요합니까?

get_view_info에는 보호 필드가 없으므로 파일 유형과 페이지 수만으로 비밀번호 필요 여부를 알 수 없습니다. 비밀번호가 설정된 파일은 모든 호출에 비밀번호를 제공해야 합니다. 프롬프트에 미리 제공하세요:

contract.pdf의 비밀번호는 내 메시지에 있습니다. 페이지 수를 확인한 뒤 2페이지를 보여 주세요.

비밀번호 없이 호출하면 실패하고, 에이전트는 추측 대신 비밀번호를 요청할 수 있습니다. 호출이 실패하면 get_view_info는 View-info lookup failed for로 시작하는 텍스트와 예외 유형 및 메시지를 반환하므로, 에이전트는 이유를 읽고 비밀번호나 올바른 파일명을 물어볼 수 있습니다.

재사용 가능한 검사‑후‑렌더링 프롬프트

아래 파일을 렌더링하기 전에 파일 유형, 페이지 수 및 페이지 크기를 확인하세요. 찾은 내용을 알려준 뒤, 질문에 답하기 위해 필요한 페이지만 렌더링하십시오. 파일: contract.docx. 질문: 해지 조항은 어디에 있나요?

에이전트는 get_view_info를 호출해 파일 유형과 페이지 수를 보고하고, 페이지를 선택한 뒤 각각 render_page를 호출합니다. get_license_status 도구는 서버의 세 번째 도구이며, 렌더링된 페이지에 워터마크가 적용되는지 확인할 때 사용합니다.

예시 세션

문서화된 응답 형태를 기반으로 한 예시이며, 실제 캡처 화면은 아닙니다.

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?

에이전트가 결정하는 내용과 엔진이 수행하는 작업

단계 에이전트 엔진
파일 선택 프롬프트에서 파일 이름을 가져옵니다 스토리지 폴더에서 파일을 찾고, 이름이 일치하지 않으면 사용 가능한 파일을 나열합니다
검토 어떤 질문이 중요한지 결정합니다 파일 유형, 페이지 수 및 페이지 크기를 반환합니다
페이지 선택 질문을 페이지 번호에 매핑합니다 없음
렌더링 선택된 각 페이지에 대해 render_page를 호출합니다 PNG를 생성합니다

솔직한 제한 사항

  • Evaluation mode. 렌더링된 페이지에는 평가 워터마크가 포함되며, 서버 프로세스는 최대 15개의 문서만 열 수 있습니다. 출력에 의존하기 전에 에이전트가 get_license_status를 호출하도록 “Viewer 서버에 라이선스가 있나요?”라고 물어보세요.
  • 페이지 수가 페이지를 선택해 주지는 않습니다. get_view_info는 존재하는 페이지를 알려줄 뿐, 답이 들어 있는 페이지는 알려주지 않습니다. 이를 위해 목차 페이지나 몇 개의 후보 페이지를 렌더링해야 합니다.
  • PNG만 지원합니다. render_page에는 형식 옵션이 없습니다.

FAQ

AI 에이전트가 PDF의 페이지 수를 어떻게 얻을 수 있나요? Viewer 서버가 연결되어 있으면 Claude가 get_view_info를 호출해 pageCount를 읽을 수 있으며, 렌더링 없이 바로 확인합니다. 답은 문서에서 직접 가져온 것이며 추측이 아닙니다.

문서 정보 MCP 도구가 에이전트에게 어떤 페이지를 렌더링해야 할지 알려줄 수 있나요? 예. 먼저 페이지 수와 크기를 제공한 뒤, 찾고 있는 내용을 알려주면 해당 질문에 답하는 페이지만 렌더링합니다.

문서를 검사하면 어디든 업로드되나요? 아니요. 서버는 구성한 폴더에서 파일을 읽고, 작은 JSON 객체를 클라이언트에 반환합니다.

더 깊이 파보기