{
  "markdown": "# pdf4vllm\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![PyPI](https://img.shields.io/pypi/v/pdf4vllm-mcp.svg)](https://pypi.org/project/pdf4vllm-mcp/)\n[![Open in Gitpod](https://img.shields.io/badge/Gitpod-Open-orange?logo=gitpod)](https://gitpod.io/#https://github.com/PyJudge/pdf4vllm-mcp)\n\nPDF reading MCP server optimized for vision LLMs.\n\n<!-- mcp-name: io.github.PyJudge/pdf4vllm -->\n\n<details>\n<summary><b>한국어</b></summary>\n\n## 문제\n\n| 방식 | 문제점 |\n|------|--------|\n| 텍스트 추출 | 인코딩 깨짐 → 쓰레기 출력, 이미지-텍스트 순서 뒤섞임 |\n| 이미지 변환 | 토큰 폭발 (특히 페이지 많을 때) |\n\n## 해결\n\npdf4vllm은 **PDF가 지저분하다고 가정**합니다.\n\n- 텍스트 손상 자동 감지 → 이미지로 자동 전환\n- 읽기 순서 보존 (텍스트 → 표 → 이미지 블록 순서대로)\n- 페이지 제한으로 컨텍스트 오버플로우 방지\n- 불필요한 이미지 자동 필터링 (로고, 선, 헤더/푸터)\n\n## 설치\n\n```bash\npip install pdf4vllm-mcp\n# 또는\nuvx pdf4vllm-mcp\n```\n\n## Claude Desktop 설정\n\n```bash\ngit clone https://github.com/PyJudge/pdf4vllm-mcp.git\ncd pdf4vllm-mcp\npython scripts/install_mcp.py\n```\n\n또는 직접 설정 (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"pdf4vllm\": {\n      \"command\": \"/python/경로\",\n      \"args\": [\"/pdf4vllm-mcp/경로/src/server.py\"]\n    }\n  }\n}\n```\n\n## 도구\n\n| 도구 | 설명 |\n|------|------|\n| `list_pdfs` | PDF 파일 찾기 (glob 패턴 `name_pattern` 지원) |\n| `read_pdf` | PDF 내용 블록으로 추출 |\n| `grep_pdf` | PDF 내 텍스트 검색 (`pdfgrep` 설치 필요) |\n\n## 추출 모드\n\n| 모드 | 설명 |\n|------|------|\n| `auto` (기본) | 텍스트 추출 시도 → 손상 감지 시 이미지로 전환 |\n| `text_only` | 텍스트/표만 추출, 이미지 없음 |\n| `image_only` | 페이지를 이미지로만 렌더링 |\n\n</details>\n\n---\n\n## Problem\n\n| Approach | Issue |\n|----------|-------|\n| Text extraction | Encoding corruption → garbage output, mixed text-image ordering |\n| Image conversion | Token explosion (especially with many pages) |\n\n## Solution\n\npdf4vllm **assumes PDFs are messy**.\n\n- Auto-detects text corruption → switches to image automatically\n- Preserves reading order (text → table → image blocks in sequence)\n- Page limits prevent context overflow\n- Filters unnecessary images (logos, lines, headers/footers)\n\n```\nPDF Input\n    ↓\nCorruption Detection (pdfminer.six + pattern analysis)\n    ↓\n┌─────────────┬─────────────┐\n│  Corrupted  │    Clean    │\n│  → Image    │  → Text +   │\n│    only     │    Tables + │\n│             │    Images   │\n└─────────────┴─────────────┘\n    ↓\nOrdered Blocks (JSON)\n```\n\n## Install\n\n```bash\npip install pdf4vllm-mcp\n# or run without installing\nuvx pdf4vllm-mcp\n```\n\n## Claude Desktop Setup\n\n```bash\ngit clone https://github.com/PyJudge/pdf4vllm-mcp.git\ncd pdf4vllm-mcp\npython scripts/install_mcp.py\n```\n\nOr manually edit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"pdf4vllm\": {\n      \"command\": \"/path/to/python\",\n      \"args\": [\"/path/to/pdf4vllm-mcp/src/server.py\"]\n    }\n  }\n}\n```\n\n## Claude Code Setup\n\nCreate `.mcp.json` in your project:\n\n```json\n{\n  \"mcpServers\": {\n    \"pdf4vllm\": {\n      \"command\": \"uvx\",\n      \"args\": [\"pdf4vllm-mcp\"]\n    }\n  }\n}\n```\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_pdfs` | Find PDF files with glob filtering (`name_pattern`) |\n| `read_pdf` | Extract PDF content as ordered blocks |\n| `grep_pdf` | Search text in PDFs using pdfgrep (requires `pdfgrep` installed) |\n\n## Extraction Modes\n\n| Mode | Description |\n|------|-------------|\n| `auto` (default) | Try text extraction → switch to image if corrupted |\n| `text_only` | Text/tables only, no images |\n| `image_only` | Render pages as images only |\n\n## Output Format\n\n```json\n{\n  \"pages\": [\n    {\n      \"page_number\": 1,\n      \"content_blocks\": [\n        {\"type\": \"text\", \"content\": \"...\"},\n        {\"type\": \"table\", \"content\": \"| A | B |\"},\n        {\"type\": \"image\", \"content\": \"[IMAGE_0]\"}\n      ]\n    }\n  ]\n}\n```\n\nWhen text is corrupted:\n```json\n{\n  \"page_number\": 2,\n  \"content_blocks\": [],\n  \"text_corrupted\": true,\n  \"page_image\": \"[IMAGE_1]\"\n}\n```\n\n## Configuration\n\n`config.json` or environment variables:\n\n```json\n{\n  \"max_pages_per_request\": 10,\n  \"max_image_dimension\": 842,\n  \"page_image_dpi\": 100\n}\n```\n\n```bash\nexport PDF_MAX_PAGES=20\nexport PDF_PAGE_IMAGE_DPI=150\n```\n\n## Test Server\n\n```bash\npip install pdf4vllm-mcp[test]\npython test_server.py\n# → http://localhost:8000\n```\n\n## License\n\nMIT\n\n---\n\n[GitHub](https://github.com/PyJudge/pdf4vllm-mcp) · [PyPI](https://pypi.org/project/pdf4vllm-mcp/)\n",
  "bytes": 4450,
  "sha": "c2538f08c98828407e92fab8aae9fd19f8c9830f4eef9c6ab9fb055ab2c29139",
  "repo_slug": "pyjudge/pdf4vllm-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pyjudge_pdf4vllm_1a501376/readme"
}