AI 에이전트가 텍스트 덤프를 읽는 대신 문서 페이지를 보게 할 수 있습니다. GroupDocs.Viewer.Mcp 서버는 PDF, Word, Excel 또는 PowerPoint 파일의 모든 페이지를 PNG로 렌더링하고 에이전트에 반환하며, 이를 로컬 머신에서 수행합니다:

report.pdf 파일은 몇 페이지입니까? 마지막 페이지를 보여 주세요.

문서에 포함된 구성 및 문제 해결 단계는 문서에서 확인할 수 있습니다: AI 에이전트가 문서 페이지를 볼 수 있게 하는 방법.

실제 문서에서 텍스트 추출이 실패하는 이유는?

텍스트 추출기는 읽는 순서대로 문자만 반환합니다. 두 단락 사이에 있는 막대 차트, 모서리에 있는 “APPROVED” 스탬프, 가격표의 열 레이아웃, 혹은 스캔본이라서 문자 자체가 전혀 없는 페이지는 반환하지 않습니다. 이러한 출력만을 기반으로 작업하는 에이전트는 문서를 절반만 본 상태에서 자신 있게 답변을 내놓으며, 누락된 절반이 보통 사용자가 질문한 부분입니다.

해결책은 더 나은 프롬프트가 아니라 다른 입력입니다: 이미지 입력을 받는 모델에 제공되는 페이지 이미지입니다.

잘못된 접근법: 모든 것을 텍스트 추출기로 파이프하기

일반적인 기본 방법은 문서를 텍스트로 변환하고, 그 텍스트를 컨텍스트 창에 붙여넣은 뒤 질문하는 것입니다. 이는 일반 텍스트에는 잘 작동합니다. 하지만 다음 네 가지 방식으로 문제가 발생하며, 이는 자신이 가진 어떤 문서에서도 확인할 수 있습니다:

  • 레이아웃이 사라져서 “총액이 오른쪽 열에 있나요?“와 같은 질문에 답할 수 없습니다.
  • 차트와 다이어그램 내부의 수치는 그려진 것이므로 텍스트가 아니어서 사라집니다.
  • 스탬프, 서명 및 손글씨가 사라집니다.
  • 스캔된 PDF는 텍스트를 제공하지 않습니다.

모델은 문서를 보기 전에 누락된 정보를 복구할 수 없습니다.

올바른 접근법: PDF 페이지를 이미지로 렌더링하여 LLM에 제공하기

render_page는 한 페이지를 PNG로 렌더링하고, 이미지를 에이전트에 인라인으로 반환하며 <name>_page<N>.png 형태로 출력 폴더에 복사본을 저장합니다. 서버는 PDF, DOCX, XLSX, PPTX, ODT, RTF, HTML, EML, MSG 등을 포함한 170개 이상의 형식을 지원합니다. 그런 다음 비전 기능이 있는 모델이 사용자가 보는 방식대로 페이지를 확인합니다.

에이전트가 페이지 번호를 추측하지 않도록 render_page와 get_view_info를 함께 사용합니다. get_view_info는 파일 유형, 페이지 수 및 각 페이지의 크기를 렌더링 없이 반환합니다. 세 번째 도구인 get_license_status는 현재 라이선스 모드를 보고합니다.

Claude, Cursor 또는 Copilot용 서버를 어떻게 실행하나요?

Docker 이미지가 독립형입니다:

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

.NET 10 SDK가 설치된 경우, dnx GroupDocs.Viewer.Mcp --yes 명령으로 Docker 없이 동일한 서버를 실행할 수 있습니다. Claude Desktop, Claude Code, Cursor, GitHub Copilot이 포함된 VS Code, Windsurf 및 기타 클라이언트에 등록하세요; 허브 페이지에 각 클라이언트에 대한 정확한 설정이 나와 있습니다. 클라이언트는 서버를 자식 프로세스로 시작하고 표준 입력·출력을 통해 통신하므로 인바운드 포트나 보안해야 할 엔드포인트가 없습니다.

예시 세션

이는 두 도구의 문서화된 동작을 기반으로 만든 예시이며, 실제 캡처된 스크린샷은 아닙니다.

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: ...

이미지는 이를 표시할 수 있는 클라이언트에서 인라인으로 나타납니다. 텍스트 응답은 에이전트가 페이지에서 본 내용을 설명한 것입니다.

에이전트는 무엇을 결정하고 엔진은 무엇을 수행하나요?

에이전트는 어떤 페이지가 질문에 답하는지와 해당 페이지에 대해 모델에 무엇을 물어볼지를 결정합니다. 엔진은 정확해야 하는 부분을 담당합니다: 파일을 열고, 문서가 페이지를 나누는 방식대로 페이지를 구분하며, PNG를 생성합니다. 모델은 렌더링된 페이지를 받기 때문에 페이지 레이아웃을 추측할 필요가 없습니다.

솔직한 제한 사항

  • Evaluation mode. 라이선스가 없으면 렌더링된 페이지에 평가용 워터마크가 삽입되고 서버 프로세스는 최대 15개의 문서만 열 수 있습니다. 워터마크가 질문한 세부 정보를 가릴 수 있습니다. 에이전트에게 “Viewer 서버에 라이선스가 있나요?“라고 물어 get_license_status를 호출하도록 하세요.
  • PNG only. 출력은 PNG 이미지이며, 다른 형식 옵션은 없습니다.
  • No page-number check. render_page는 마지막 페이지를 초과하는 페이지 번호를 거부하지 않습니다. 먼저 get_view_info로 페이지 수를 확인하세요.
  • The model must accept images. 텍스트 전용 모델의 경우 에이전트는 저장된 파일 경로를 받지만 페이지 내용은 알려줄 수 없습니다.
  • Images are large. 각 페이지는 인라인 PNG이며 보통 수백 킬로바이트 정도입니다. 전체 파일이 아니라 작업에 필요한 페이지만 렌더링하세요.
  • One thing leaves the machine. 렌더링된 이미지는 에이전트로 전달되고, 그곳에서 사용되는 모델로 전송됩니다. 로컬에 호스팅된 모델을 사용하면 모든 것이 머신 안에 머무릅니다.

FAQ

Claude가 내 PDF 페이지와 레이아웃을 볼 수 있나요? 예, PDF 페이지가 이미지로 렌더링되고 사용 중인 Claude 모델이 이미지 입력을 지원한다면 가능합니다. render_page는 해당 이미지를 로컬에서 생성하고 클라이언트에 반환합니다.

문서를 렌더링하기 위해 어디든 업로드해야 하나요? 서버는 마운트한 폴더에서 파일을 읽고 이미지 파일을 그 옆에 저장합니다; 문서는 서버에 업로드되지 않습니다. 페이지 이미지는 에이전트의 모델로 전송됩니다.

PDF뿐만 아니라 Excel 및 PowerPoint에서도 작동하나요? 예. PowerPoint는 슬라이드당 하나의 이미지를 렌더링하고, Excel 시트는 페이지로 분할되며 get_view_info를 통해 페이지 수를 확인할 수 있습니다.

더 깊이 파고들기