| disable-model-invocation | true |
| name | pdf |
| description | Extracts text, tables, and structure from PDF files using opendataloader-pdf. Use when reading PDFs, converting PDF to markdown/JSON/HTML, extracting tables from PDF, processing scanned PDFs with OCR, or analyzing PDF content for RAG pipelines. Do NOT use for creating/editing PDFs, Word/Excel/PPT files (use xlsx2md for Excel), or viewing PDFs (use Read tool for simple PDF viewing). |
| argument-hint | <file.pdf> [--format markdown|json|html] [--pages 1,3,5-7] |
| user-invocable | true |
| allowed-tools | Bash(opendataloader-pdf*), Bash(pip*), Bash(python3*), Bash(java*), Read, Grep, Glob |
pdf — opendataloader-pdf
PDF를 Markdown, JSON (bounding boxes 포함), HTML로 변환합니다.
벤치마크 #1 (0.90 overall accuracy). Java 11+ 필요.
Prerequisites
- Java 11+ (
java -version으로 확인)
- Python 3.10+
pip install -U opendataloader-pdf
pip install -U "opendataloader-pdf[hybrid]"
Phase 1: 입력 분석
사용자 요청에서 파악:
- PDF 경로 —
$ARGUMENTS에서 추출 또는 사용자에게 확인
- 출력 포맷 — markdown (추천), json (좌표 필요 시), html, text (CLI 기본값은 json)
- 복잡도 — 단순 텍스트 PDF vs 복잡한 테이블/스캔/수식
Phase 2: 변환 실행
기본 변환 (Fast mode)
opendataloader-pdf <file.pdf> -o <output-dir> -f markdown
Python API
import opendataloader_pdf
opendataloader_pdf.convert(
input_path=["file.pdf"],
output_dir="output/",
format="markdown,json"
)
주요 옵션
| 옵션 | 설명 | 기본값 |
|---|
-f, --format | 출력 포맷 (json, text, html, markdown, markdown-with-html, markdown-with-images) | json |
-o, --output-dir | 출력 디렉토리 | 입력 파일 디렉토리 |
--pages | 추출 페이지 (예: "1,3,5-7") | 전체 |
-p, --password | 암호화된 PDF 비밀번호 | - |
--use-struct-tree | Tagged PDF 구조 트리 사용 | false |
--table-method | 테이블 감지 (default, cluster) | default |
--image-output | 이미지 처리 (off, embedded, external) | external |
--image-format | 이미지 포맷 (png, jpeg) | png |
--keep-line-breaks | 원본 줄바꿈 보존 | false |
--sanitize | 민감 데이터 마스킹 (이메일, 전화번호, IP 등) | false |
--include-header-footer | 머리글/바닥글 포함 | false |
--markdown-page-separator | 페이지 구분자 (%page-number% 사용 가능) | 없음 |
전체 옵션: resources/options-reference.md
Phase 3: Hybrid Mode (복잡한 PDF)
복잡한 테이블, 스캔 PDF, 수식, 차트가 있을 때 사용.
단순 페이지는 로컬(0.05s), 복잡한 페이지만 AI 백엔드로 라우팅.
opendataloader-pdf-hybrid --port 5002
opendataloader-pdf --hybrid docling-fast <file.pdf>
| 문서 유형 | 서버 옵션 | 클라이언트 옵션 |
|---|
| 복잡한 테이블 | --port 5002 | --hybrid docling-fast |
| 스캔/이미지 PDF | --port 5002 --force-ocr | --hybrid docling-fast |
| 비영어 스캔 | --port 5002 --force-ocr --ocr-lang "ko,en" | --hybrid docling-fast |
| 수식 포함 | --enrich-formula | --hybrid docling-fast --hybrid-mode full |
| 차트 설명 필요 | --enrich-picture-description | --hybrid docling-fast --hybrid-mode full |
--enrich-formula/--enrich-picture-description 사용 시 클라이언트에서 반드시 --hybrid-mode full 지정.
그렇지 않으면 enrichment가 조용히 무시됨.
Phase 4: 결과 처리
변환 결과를 사용자 목적에 맞게 가공:
- RAG 파이프라인 → markdown 포맷, 페이지 구분자 추가 (
--markdown-page-separator "--- page %page-number% ---")
- 데이터 추출 → json 포맷 (bounding boxes로 소스 위치 추적)
- 웹 표시 → html 포맷
- 이미지 포함 문서 → markdown-with-images 포맷
MCP Server
Claude Code에서 MCP 서버로 직접 사용 가능:
claude mcp add opendataloader-pdf -- uvx opendataloader-pdf-mcp
중요 원칙
- 배치 우선:
convert() 호출마다 JVM이 생성되므로, 여러 파일은 한 번에 전달
- Fast mode 먼저: 단순 PDF는 hybrid 없이 시도. 테이블이 깨지면 hybrid로 전환
- 포맷 선택: 텍스트만 필요 → markdown, 좌표 필요 → json, 웹 표시 → html
- Tagged PDF 활용: 이미 태그된 PDF는
--use-struct-tree로 구조 활용
- 민감 데이터 주의: 개인정보 포함 PDF는
--sanitize 옵션 안내
