file-analysis-mcp
file-analysis-mcp
"이 폴더에 있는 pdf/docx/pptx/svg/png 문서들, 다 읽고 요약해줘." Claude Code에게 이 한 문장을 시키기 위한 개인용 MCP 서버입니다.
폴더를 지정하면 안의 문서를 열어 텍스트만 그대로 뽑아 돌려줍니다. 요약·해석은 이 서버가 아니라 이 서버를 호출한 Claude가 대화 중에 합니다 — 그래서 별도의 LLM API 키 없이, 로컬에서 완전히 개인적으로 동작합니다.
목차
Related MCP server: file-analyzer
실제로 이렇게 동작합니다
Claude Code에서 실제 폴더(사내 PRD 문서가 담긴 폴더)를 지정해 물어본 결과입니다.
나:
docs폴더에 있는 문서들을 요약하고 파일 구조를 분석해줘
Claude가 analyze_folder_structure → analyze_folder를 차례로 호출하고, 돌아온
원문 텍스트를 바탕으로 이렇게 답합니다.
[analyze_folder_structure] pdf 2개, 총 455KB, 최대 파일 prd.pdf(231KB)
[analyze_folder] 2개 파일 모두 추출 성공 (succeeded: 2, failed: 0)
→ Claude의 요약:
두 문서는 같은 프로젝트("ParameterCheck")의 서로 다른 산출물입니다.
- proposal.pdf: RF솔루션 파트의 CAB 파라미터 검증 자동화 기획서
- prd.pdf: 같은 아이디어의 정식 PRD. 목표는 검증 시간 10분→5분 단축,
MVP는 "파라미터 엑셀 입력 시 집계시트 자동 생성 + 오류 빨강 표시"
공통점: 사람 검토·승인은 항상 최종 단계로 남겨둔다는 원칙이 두 문서 모두에 명시됨.서버는 텍스트만 넘겼을 뿐, 위 요약 문장은 전부 Claude가 만들었습니다 — 이게 이 프로젝트가 지향하는 역할 분리입니다.
빠른 시작
# 1) 의존성 설치 (uv 사용)
uv sync --extra dev
# 2) 확인
uv run pytest # 유닛테스트
uv run python scripts/smoke_stdio.py # 실제 MCP 프로토콜로 서버를 띄워보는 스모크 테스트OCR(PNG 분석)이 필요하면 Tesseract-OCR을 따로 설치하세요 — 아래 Claude Code에 등록 앞부분에 안내가 있습니다. 설치 전에도 나머지 4개 도구는 정상 동작합니다.
도구 5개
도구 | 설명 | 가드레일 |
| 폴더 안의 대상 파일 목록(경로/크기/수정일)과 확장자별 개수를 반환 |
|
| 하위 폴더 포함 트리 구조, 확장자별 통계, 용량, 최대 파일 목록 반환 | 트리만 |
| pdf/docx/pptx/svg 문서 하나의 텍스트를 추출 |
|
| png 이미지 하나를 OCR로 읽어 텍스트를 추출 | 동일 + OCR 결과가 비면 이유를 next_actions로 안내 |
| 폴더 안의 모든 대상 파일을 한 번에 추출해 리포트로 반환 (여러 번 호출하지 않아도 됨) |
|
모든 도구는 읽기 전용이며 파일을 수정/삭제하지 않습니다. 상한(max_files)에 걸려도
파일을 조용히 누락하지 않고 몇 개를 못 봤는지 응답에 그대로 남기며, status가
PARTIAL이 되어 그 사실을 바로 알 수 있습니다.
Claude Code에 등록
OCR 엔진 설치 (PNG 분석에만 필요)
pytesseract는 Tesseract-OCR 엔진의 파이썬 바인딩일 뿐이며, 엔진 자체는 별도로
설치해야 합니다.
UB-Mannheim Tesseract 설치본을 다운로드해 Windows에 설치합니다. (한국어 인식이 필요하면 설치 중 "Additional language data"에서 Korean을 체크하세요.)
설치 경로(기본값
C:\Program Files\Tesseract-OCR)를 시스템 PATH에 추가합니다.tesseract --version으로 설치를 확인합니다.
서버 등록
이 저장소에는 이미 .mcp.json이 루트에 준비되어 있습니다. Claude Code를
file-analysis-mcp 폴더(또는 상위 폴더)에서 실행하면 자동으로 인식됩니다. 재시작
후 /mcp 명령이나 도구 목록에서 file-analysis의 5개 도구가 보이는지 확인하세요.
수동으로 등록하려면:
claude mcp add file-analysis -- uv --directory "C:\Users\20223\Desktop\file-analysis-mcp" run python src/file_analysis_mcp/server.py권장 흐름: analyze_folder_structure로 구조를 먼저 파악 → analyze_folder로
전체 문서 텍스트를 일괄 추출 → Claude가 추출된 텍스트를 바탕으로 요약.
프로젝트 구조
file-analysis-mcp/
├── pyproject.toml
├── .mcp.json
├── src/file_analysis_mcp/
│ ├── server.py # FastMCP 서버, 도구 5개
│ ├── harness.py # 응답/오류 계약 (BaseResponse, ToolFailure 등)
│ ├── scanner.py # 폴더 스캔/구조 분석
│ └── extractors/ # pdf/docx/pptx/svg/image 텍스트 추출기
├── scripts/smoke_stdio.py
├── tests/
│ ├── test_scanner.py # 도메인 로직(순수 함수) 유닛테스트
│ ├── test_extractors.py # 포맷별 추출기 유닛테스트
│ └── test_server_contract.py # 하네스 규약(도구 계약) 테스트
└── data/sample_docs/ # 테스트용 샘플 문서설계 원칙: 하네스 엔지니어링
이 서버는 "기능을 늘리는 것"보다 모델이 응답만 보고 다음에 무엇을 해야 할지 알 수 있게 만드는 것을 우선합니다. awesome-harness-engineering에서 소개하는 원칙 중, 로컬·단일 사용자·읽기 전용이라는 이 프로젝트 성격에 실제로 맞는 것만 선택적으로 적용했습니다. (OpenTelemetry 관측, 프롬프트 인젝션 샌드박싱, mcp-guardian류 스코프 승인 게이팅 등은 다중 사용자·장기 실행 에이전트를 위한 것이라 이 규모의 개인용 도구에는 과해서 적용하지 않았습니다.)
적용한 것 | 이 프로젝트에서의 형태 |
명확한 도구 경계 | 도구 docstring에 목적 + Returns + "사용 / 사용하지 않음" 예시를 명시해, 모델이 5개 도구 중 정확한 것을 고르게 함 |
다음 액션 안내 | 모든 응답이 |
액션 가능한 오류 |
|
컨텍스트 절약(개별 응답) |
|
컨텍스트 절약(가드레일) |
|
유용한 실패를 컨텍스트에 유지 |
|
조용한 손실 금지 | 상한을 넘겨도 파일을 몰래 건너뛰지 않고 |
도구 계약 테스트 |
|
의도적으로 적용하지 않은 것
요약/근거검증(grounding) 기능: 이 서버는 "추출만" 하기로 설계했으므로(요약은 호스트 모델 몫) 해당하지 않습니다.
줄 번호 인용 앵커(
L12 | ...): 인용 근거를 검증하는 별도 도구가 없는 한 텍스트만 지저분해지므로 적용하지 않았습니다. 필요해지면harness.number_lines()를 재사용해 추가할 수 있습니다.승인 토큰 기반 저장 워크플로: 이 서버는 파일을 쓰지 않으므로 해당 없음.
Available Tools
5 toolsanalyze_folderARead-onlyIdempotent
폴더 안의 모든 대상 파일(pdf/docx/pptx/svg/png)을 한 번에 추출해 리포트로 반환합니다.
파일마다 read_document/read_image_text를 따로 호출하지 않아도 되는 배치 도구입니다. 한 파일이 실패해도 나머지 파일 처리는 계속되며, 실패 이유는 파일별로 남습니다. 파일 수가 max_files를 넘으면 앞쪽부터 max_files개만 처리하고, 넘겨받지 못한 개수는 skipped_due_to_limit로 투명하게 알려줍니다(조용히 누락되지 않습니다).
Returns:
AnalyzeFolderResponse: reports[]의 각 항목은 status(OK/ERROR)와 함께
text 또는 error를 담습니다. status가 PARTIAL이면 일부 실패했거나(failed>0)
상한 때문에 스킵된 파일(skipped_due_to_limit>0)이 있다는 뜻입니다.
Examples: - 사용: "이 폴더 문서들 다 요약해줘", "폴더 구조 분석하고 내용도 정리해줘" - 사용하지 않음: 파일 목록만 필요할 때 → scan_folder - 사용하지 않음: 특정 파일 하나만 자세히 → read_document / read_image_text
Inputs: folder_path (required), max_files, recursive, extensions, +1 more. Returns: failed, folder, status, reports, +5 more
analyze_folder_structureARead-onlyIdempotent
폴더의 하위 디렉터리 트리와 확장자별 통계, 용량, 최대 파일을 분석합니다.
scan_folder보다 한 단계 더 깊은 "구조" 파악용 도구입니다. 폴더가 어떻게 구성돼 있는지(하위 폴더별 파일 분포, 가장 큰 파일 등)를 먼저 감 잡고 싶을 때 사용하세요.
Returns:
FolderStructureResponse: tree는 {"하위폴더명": {...}, "_files": [...]}
형태의 중첩 딕셔너리입니다. 파일이 max_files보다 많으면 tree에는 앞쪽
max_files개만 반영되고 list_truncated=True가 되지만, total_files/
by_extension/total_size_bytes 등 통계는 항상 전체 파일 기준입니다.
Examples: - 사용: "이 폴더 구조 좀 분석해줘", "가장 큰 파일이 뭐야?" - 사용하지 않음: 파일 목록만 빠르게 보고 싶을 때 → scan_folder
Inputs: folder_path (required), max_files, extensions. Returns: tree, folder, status, max_depth, +6 more
read_documentARead-onlyIdempotent
문서 파일(pdf/docx/pptx/svg) 하나의 텍스트를 추출합니다. 요약은 하지 않습니다.
scan_folder/analyze_folder에서 찾은 파일 중 하나를 더 자세히 보고 싶을 때, 또는 analyze_folder의 일괄 요약이 잘렸을 때(truncated=True) 이어서 읽을 때 씁니다.
Returns:
ReadDocumentResponse: text에 원문(잘렸으면 앞부분)이 담깁니다.
truncated=True면 max_chars를 늘려 다시 호출해 나머지를 볼 수 있습니다.
Examples: - 사용: "이 pdf 파일 내용 좀 자세히 보여줘" - 사용하지 않음: png 이미지 → read_image_text - 사용하지 않음: 폴더 전체를 한 번에 훑고 싶을 때 → analyze_folder
Inputs: file_path (required), max_chars. Returns: path, text, status, metadata, +3 more
read_image_textARead-onlyIdempotent
PNG 이미지 하나를 OCR로 읽어 텍스트를 추출합니다(Tesseract-OCR 필요).
스크린샷, 스캔한 메모, 다이어그램에 박힌 라벨처럼 이미지 안의 문자를 읽어야 할 때 사용하세요. 순수 그림/사진처럼 텍스트가 없는 이미지는 빈 결과가 나올 수 있습니다(비전 해석이 아니라 OCR이므로 그림 자체의 의미는 파악하지 못합니다).
Returns:
ReadImageTextResponse: text에 인식된 문자열이 담깁니다. 결과가 비어
있으면 next_actions에서 그 이유를 안내합니다.
Examples: - 사용: "이 스크린샷에 뭐라고 적혀 있어?" - 사용하지 않음: pdf/docx/pptx/svg 문서 → read_document
Inputs: file_path (required), max_chars. Returns: path, text, status, metadata, +2 more
scan_folderARead-onlyIdempotent
폴더 안의 대상 파일(pdf/docx/pptx/svg/png) 목록과 확장자별 개수를 조회합니다.
문서 내용을 읽지 않고 메타데이터(경로/크기/수정일)만 가볍게 훑어보는 도구입니다. 폴더 안에 어떤 파일이 몇 개 있는지 빠르게 확인하고 싶을 때 사용하세요.
Returns:
ScanFolderResponse: files[]에 경로/이름/확장자/크기/수정일이 담깁니다.
파일이 max_files보다 많으면 list_truncated=True이고, by_extension의
개수는 상한과 무관하게 항상 전체 매칭 파일 기준입니다.
Examples: - 사용: "이 폴더에 어떤 문서들이 있어?", "pdf 몇 개야?" - 사용하지 않음: 파일 내용까지 요약하고 싶을 때 → analyze_folder - 사용하지 않음: 하위 폴더 구조/통계까지 보고 싶을 때 → analyze_folder_structure
Inputs: folder_path (required), max_files, recursive, extensions. Returns: files, folder, status, total_files, +4 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: read_document handles individual text documents, scan_folder lists metadata, analyze_folder_structure provides hierarchical stats, read_image_text does OCR, and analyze_folder batch-processes all files. Descriptions explicitly state what not to use each tool for, reinforcing boundaries.
All tool names follow a consistent snake_case verb_noun pattern (read_document, scan_folder, analyze_folder_structure, read_image_text, analyze_folder). The verbs are distinct and descriptive, and the pattern is uniform across the set.
With 5 tools, the server is well-scoped for file and folder analysis. Each tool covers a distinct aspect (single read, metadata scan, structure analysis, OCR, batch processing) without redundancy or missing essentials, making the count ideal for its purpose.
The tool surface covers the full lifecycle of file analysis: listing, detailed reading (both text and OCR), structural analysis, and batch processing. Error handling and truncation are addressed. No obvious gaps for the stated domain, such as missing file deletion or modification, which are out of scope.
Related MCP Connectors
Read and search folders on your own computer with explicit consent. Files are never uploaded.
Convert PDF, Word, Excel and scanned documents to Markdown, tables and RAG chunks. OCR.
Converts PDF, scans, DOCX, XLSX and PPTX to Markdown with tables and page-aware RAG chunks.
Safe folder access for ChatGPT and Claude: read, write and search files, risky tools opt-in.
Related MCP Servers
- AlicenseAqualityFmaintenanceProvides LLMs with secure, read-only access to local documentation by scanning directories, extracting content from PDF, DOCX, Markdown, and text files, and performing keyword searches.35 npmMIT
- FlicenseAqualityDmaintenanceEnables read-only analysis of local unstructured documents by scanning a folder, extracting text and structural metadata, and passing content with truncation and error-awareness to an LLM for summarization.91-
- FlicenseNot gradedqualityDmaintenanceEnables local, read-only extraction of text and structure from PDF, DOCX, PPTX, SVG, and PNG files, including OCR for images, directory tree and metadata reporting, with strict path isolation and audit logging.-
- FlicenseNot gradedqualityDmaintenanceEnables local folder analysis of unstructured documents (PDF, DOCX, PPTX, TXT, SVG, PNG, CSV, XLSX) by extracting structure, reading content, and generating reports, with a strict approval gate before any save operation.-