Skip to main content
Glama
file-analysis-mcp

file-analysis-mcp

file-analysis-mcp

"이 폴더에 있는 pdf/docx/pptx/svg/png 문서들, 다 읽고 요약해줘." Claude Code에게 이 한 문장을 시키기 위한 개인용 MCP 서버입니다.

Python 3.11+ MCP read--only tests

폴더를 지정하면 안의 문서를 열어 텍스트만 그대로 뽑아 돌려줍니다. 요약·해석은 이 서버가 아니라 이 서버를 호출한 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개

도구

설명

가드레일

scan_folder

폴더 안의 대상 파일 목록(경로/크기/수정일)과 확장자별 개수를 반환

max_files(기본 300) 초과 시 list_truncated=True

analyze_folder_structure

하위 폴더 포함 트리 구조, 확장자별 통계, 용량, 최대 파일 목록 반환

트리만 max_files로 상한(통계는 항상 전체 기준)

read_document

pdf/docx/pptx/svg 문서 하나의 텍스트를 추출

max_chars로 절단, truncated=True로 명시

read_image_text

png 이미지 하나를 OCR로 읽어 텍스트를 추출

동일 + OCR 결과가 비면 이유를 next_actions로 안내

analyze_folder

폴더 안의 모든 대상 파일을 한 번에 추출해 리포트로 반환 (여러 번 호출하지 않아도 됨)

max_files(기본 50) 초과 시 skipped_due_to_limit로 개수 명시

모든 도구는 읽기 전용이며 파일을 수정/삭제하지 않습니다. 상한(max_files)에 걸려도 파일을 조용히 누락하지 않고 몇 개를 못 봤는지 응답에 그대로 남기며, status가 PARTIAL이 되어 그 사실을 바로 알 수 있습니다.

Claude Code에 등록

OCR 엔진 설치 (PNG 분석에만 필요)

pytesseract는 Tesseract-OCR 엔진의 파이썬 바인딩일 뿐이며, 엔진 자체는 별도로 설치해야 합니다.

  1. UB-Mannheim Tesseract 설치본을 다운로드해 Windows에 설치합니다. (한국어 인식이 필요하면 설치 중 "Additional language data"에서 Korean을 체크하세요.)

  2. 설치 경로(기본값 C:\Program Files\Tesseract-OCR)를 시스템 PATH에 추가합니다.

  3. 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개 도구 중 정확한 것을 고르게 함

다음 액션 안내

모든 응답이 status + next_actions를 포함. 성공/부분성공/빈 결과 등 상황별로 다음에 부를 도구와 이유를 구체적으로 제시

액션 가능한 오류

ToolFailure가 원인 코드 + 복구 방법 + 선택 가능한 값을 강제. 예: 지원하지 않는 확장자 → 사용 가능한 확장자 목록

컨텍스트 절약(개별 응답)

read_document/read_image_text/analyze_folder는 max_chars(파일당)로 절단하고 truncated로 명시

컨텍스트 절약(가드레일)

scan_folder/analyze_folder_structure/analyze_folder는 파일 개수 상한(max_files)을 두어, 폴더에 파일이 아주 많아도 한 번의 호출이 무한정 커지지 않게 함

유용한 실패를 컨텍스트에 유지

analyze_folder는 파일 하나가 실패해도 배치를 중단하지 않고, 성공/실패를 파일별로 남겨 다음 단계 판단에 활용하게 함

조용한 손실 금지

상한을 넘겨도 파일을 몰래 건너뛰지 않고 list_truncated/skipped_due_to_limit로 정확히 몇 개를 못 봤는지 응답에 남김

도구 계약 테스트

tests/test_server_contract.py가 "모든 도구에 설명/annotations가 있는가", "인자 스키마가 평평한가", "모든 도구가 read-only인가", "가드레일이 실제로 작동하는가"를 코드로 검증

의도적으로 적용하지 않은 것

  • 요약/근거검증(grounding) 기능: 이 서버는 "추출만" 하기로 설계했으므로(요약은 호스트 모델 몫) 해당하지 않습니다.

  • 줄 번호 인용 앵커(L12 | ...): 인용 근거를 검증하는 별도 도구가 없는 한 텍스트만 지저분해지므로 적용하지 않았습니다. 필요해지면 harness.number_lines()를 재사용해 추가할 수 있습니다.

  • 승인 토큰 기반 저장 워크플로: 이 서버는 파일을 쓰지 않으므로 해당 없음.

Available Tools

5 tools
analyze_folderA
Read-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_structureA
Read-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_documentA
Read-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_textA
Read-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_folderA
Read-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

    A4.5/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      Provides 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.
      3
      5 npm
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables 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.
      9
      1
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      -