PDF Reader MCP Server

1. 개요

이 문서는 PDF Reader MCP Server를 설치하고 실행하며, 실제 사용하는 방법을 안내합니다. 이 서버는 PDF 문서를 읽고, 텍스트(Markdown), 이미지, 표를 추출하여 AI에게 제공하는 기능을 수행합니다.

2. 설치 및 실행 (Installation & Execution)

이 프로젝트는 uv 패키지 매니저를 사용하여 의존성을 관리합니다.

2.1. 필수 요구사항

uv (Python Package Manager)
Tesseract-OCR (OCR 기능 사용 시 필요)
- macOS: brew install tesseract tesseract-lang
- Linux (Ubuntu): sudo apt-get install tesseract-ocr tesseract-ocr-kor
- Windows: UB-Mannheim/tesseract 설치 관리자 다운로드 후 설치 시 'Korean' 언어 팩 선택

2.2. 환경 설정 (uv)

프로젝트 루트에서 다음 명령어로 가상환경을 생성하고 의존성을 설치합니다.

uv sync

2.3. 환경 점검

설치된 환경(uv 가상환경)이 올바른지 확인합니다.

uv run src/utils/env_check.py

2.4. 서버 실행 테스트

터미널에서 직접 실행하여 에러가 없는지 확인합니다.

uv run src/server/main.py

3. MCP 서버 등록 (Claude Desktop / Antigravity)

클라이언트 설정 파일(claude_desktop_config.json 등)의 mcpServers 섹션에 아래와 같이 추가하십시오.

{
  "mcpServers": {
    "pdf-reader": {
      "command": "uv",
      "args": [
        "--directory",
        "/YOUR/ABSOLUTE/PATH/TO/pdf_reader_mcp_server",
        "run",
        "src/server/main.py"
      ]
    }
  }
}

참고: args의 /YOUR/ABSOLUTE/PATH/TO/... 부분을 실제 프로젝트가 위치한 절대 경로로 변경해야 합니다.

4. 기능 사용 가이드 (Usage)

4.1. MCP Tools

AI 에이전트는 다음 도구들을 사용하여 PDF와 상호작용합니다.

도구 이름	설명	인자 예시
`read_pdf`	PDF 내용을 읽어 Markdown으로 반환	`source="/path/to/doc.pdf"`, `page_range="1-3"`
`get_pdf_metadata`	제목, 페이지 수 등 메타데이터 확인	`source="https://example.com/paper.pdf"`

4.2. MCP Resources

URI를 통해 직접 접근할 수도 있습니다.

URI Pattern: pdf://{absolute_path_to_file}
사용법: AI에게 "이 파일 읽어줘: pdf:///Users/me/docs/manual.pdf" 라고 요청하면, 내부적으로 read_resource를 호출하여 처리합니다.

4.3. Prompts

사전 정의된 프롬프트를 사용할 수 있습니다.

summarize_pdf: 지정된 PDF를 읽고 요약해줍니다.

5. 테스트 결과 (Verification)

자동화된 단위 테스트를 통해 핵심 모듈(Loader, Extractor, Parser)의 동작을 검증했습니다.

로컬 파일 및 URL 로딩 테스트 완료
텍스트 및 이미지 추출 테스트 완료
통합 파싱 로직 테스트 완료

uv run python -m unittest discover tests
# Result: OK