file-analyzer-mcp
file-analyzer-mcp
로컬 폴더의 PDF·DOCX·PPTX·SVG·PNG에서 텍스트/구조만 추출해 주는 개인용 stdio MCP 서버입니다. 요약·해석은 하지 않습니다 — 추출된 결과를 읽고 요약하는 건 이 도구를 호출하는 호스트 LLM(Claude Code 등)의 몫입니다.
하는 일 / 하지 않는 일
하는 일 | 하지 않는 일 |
지정 루트 폴더 하위 문서의 텍스트/구조 추출 | 요약·해석 (호스트 LLM이 담당) |
폴더 트리 · 확장자별 파일 수/용량 집계 | 파일 쓰기·삭제·이동 (읽기 전용) |
PNG의 OCR 텍스트 추출 | 이미지의 시각적 의미(그림·차트) 파악 |
대용량/손상 파일에 대한 타임아웃 처리 | 서버 실행 중 분석 대상 폴더 변경 |
Related MCP server: Docalyze
실행 예시
> 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/asuramama-hue/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가 직접 호출합니다.
도구 (Tools)
도구 | 설명 |
| 폴더 트리, 확장자별 파일 수/용량 |
| 텍스트/구조 추출 — |
| 크기, 수정시각, 페이지/슬라이드 수, 이미지 해상도 등 |
프로젝트 구조
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로 변환 후 사용하세요.
라이선스
별도 라이선스 파일이 없는 개인 프로젝트입니다.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Document conversion MCP server: PDF to Markdown, image OCR, spreadsheet parsing.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMCP server that reads PDFs and exposes them as structured Markdown, metadata, outlines, images, and tables to LLM consumers via tools like pdf_read_markdown and pdf_info.Apache 2.0
- AlicenseBqualityDmaintenanceAn MCP server that lets AI assistants read and visually analyze local documents — PDFs, Excel spreadsheets, CSV files, Word documents, PowerPoint presentations, and images.449 npm100 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceLocal MCP server that indexes folders of documents into a hybrid vector + keyword search index for Claude Desktop, with support for PDFs, Office files, and images via OCR.MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for indexing, semantic search, and generation of multi-format documents. Exposes 13 tools over JSON-RPC 2.0 so an LLM can search your local PDF, Excel, and Word files, and create or edit Excel and Word documents.AGPL 3.0