로컬 폴더의 PDF·DOCX·PPTX·SVG·PNG에서 텍스트/구조만 추출해 주는 개인용 stdio MCP 서버입니다. 요약·해석은 하지 않습니다 — 추출된 결과를 읽고 요약하는 건 이 도구를 호출하는 호스트 LLM(Claude Code 등)의 몫입니다.
하는 일 | 하지 않는 일 |
지정 루트 폴더 하위 문서의 텍스트/구조 추출 | 요약·해석 (호스트 LLM이 담당) |
폴더 트리 · 확장자별 파일 수/용량 집계 | 파일 쓰기·삭제·이동 (읽기 전용) |
PNG의 OCR 텍스트 추출 | 이미지의 시각적 의미(그림·차트) 파악 |
대용량/손상 파일에 대한 타임아웃 처리 | 서버 실행 중 분석 대상 폴더 변경 |
Related MCP server: file-analysis-mcp
> read_document("quarterly-report.pdf")
{
"type": "pdf",
"num_pages": 12,
"text": "Q3 Revenue Summary\n..."
}
> read_document("../../etc/passwd")
{ "error": "'../../etc/passwd' resolves outside the allowed root folder" }git clone https://github.com/saewookkangboy/fileanalyzer_mcp_testmonial.git
cd fileanalyzer_mcp_testmonial
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
brew install tesseract # PNG OCR용 (한국어는 brew install tesseract-lang 추가)Claude Code에 등록:
claude mcp add file-analyzer --env FILE_ANALYZER_ROOT=/분석할/폴더 -- \
"$(pwd)/.venv/bin/python" "$(pwd)/server.py"
claude mcp list # ✔ Connected 확인등록 후 새 세션에서 "이 폴더 문서들 요약해줘"라고 요청하면 아래 3개 도구를 Claude가 직접 호출합니다.
도구 | 설명 |
| 폴더 트리, 확장자별 파일 수/용량 |
| 텍스트/구조 추출 — |
| 크기, 수정시각, 페이지/슬라이드 수, 이미지 해상도 등 |
server.py # FastMCP 앱 진입점, 툴 등록, 루트 폴더 검증
file_analyzer/
security.py # 경로 격리(resolve_safe_path), 크기 제한
timeout.py # 추출 작업 하드 타임아웃
audit.py # 로컬 감사 로그(logs/audit.jsonl)
tree.py, metadata.py # list_directory / get_file_metadata 로직
extractors/ # pdf · docx · pptx · svg · image(OCR) 추출기
tests/ # pytest 회귀 스위트
AGENTS.md # 호출 에이전트(Claude Code)를 위한 운영 지침항목 | 정책 |
경로 격리 |
|
파일 크기 | 50MB 초과 시 읽지 않고 에러 반환 |
타임아웃 | 추출/메타데이터 파싱이 30초를 넘으면 에러로 중단 반환 |
지원 확장자 |
|
이미지 해석 | OCR 텍스트만 추출, 그림/차트의 시각적 의미는 파악하지 못함 |
분석 대상 폴더 | 서버 시작 시 1회 고정, 실행 중 변경 불가 |
모든 도구 호출은 logs/audit.jsonl에 로컬로만 한 줄씩 기록됩니다(외부 전송 없음).
{"timestamp": "2026-08-26T06:03:35Z", "tool": "read_document", "params": {"relative_path": "report.pdf"}, "status": "ok", "duration_ms": 251.3}로그를 비우려면 logs/audit.jsonl을 삭제하면 됩니다.
pip install -e ".[dev]"
pytest -qtests/는 경로 이탈·절대경로 주입 차단, 5종 추출기, 타임아웃, 감사 로그, 서버 통합을
다룹니다. 이 프로젝트 규모에서는 CI 파이프라인 없이 로컬 pytest 실행만으로 회귀 검증이
충분하다고 보고 그렇게 유지했습니다.
요약 기능이 없음 — 별도 LLM API 키 없이도 동작하도록, 추출은 서버가/요약은 호스트가 나눠 맡는 최소 구조를 택했습니다.
PNG는 OCR, vision 전달 아님 — 호스트에 이미지를 base64로 넘기는 대신 텍스트만 뽑아 반환량과 구현 복잡도를 낮췄습니다 (그림의 시각적 의미는 못 봄).
git/CI 없이 로컬 pytest만 — 1인 로컬 도구 규모에서 CI 인프라는 과하다고 판단했습니다.
타임아웃은 스레드 기반이라, 초과된 호출 자체의 백그라운드 스레드는 반환 이후에도 끝까지 실행될 수 있습니다.
.ppt는 지원하지 않습니다 — .pptx로 변환 후 사용하세요.
별도 라이선스 파일이 없는 개인 프로젝트입니다.
This server cannot be deployed
Convert PDF, Word, Excel and scanned documents to Markdown, tables and RAG chunks. OCR.
Extract text, pages and metadata from PDFs in bulk, with OCR for scanned files.
Deterministic DOCX/PPTX/XLSX/PDF parser: track changes, comments, headers, footers, merged cells.
High-fidelity PDF to structured Markdown conversion and document field extraction.
