File Analysis MCP

특정 폴더의 비정형 문서(PDF, DOCX, PPTX, SVG, PNG, JPG)를 읽어 구조/내용을 추출하는 개인용 MCP 서버. 요약은 이 서버가 아니라 이 서버를 호출하는 Claude Code/Codex의 LLM이 수행한다. 이 서버는 텍스트/이미지 추출과 폴더 구조 파악만 담당한다.

사전 준비

1. Python

python, pip가 정상적으로 동작해야 한다. Windows에서 python이 Microsoft Store 설치 안내를 띄운다면 다음을 확인:

1. python.org에서 Python 3.11 이상(64-bit) 설치, 설치 중 "Add python.exe to PATH" 체크.

2. 그래도 python이 Store stub을 가리키면: 설정 → 앱 → 고급 앱 설정 → 앱 실행 별칭에서 App Installer의 python.exe/python3.exe 항목을 끈다.

2. Tesseract-OCR (PNG의 OCR 기능에 필요, 선택)

UB-Mannheim Tesseract installer로 설치 후, .mcp.json의 TESSERACT_CMD 값을 실제 설치 경로로 맞춘다. 설치하지 않아도 서버는 정상 동작하며, PNG 분석 시 이미지 자체(멀티모달)는 반환되고 OCR 텍스트만 "unavailable" 메시지로 대체된다.

Related MCP server: ReadPDFx - OCR PDF MCP Server

설치

cd C:\Users\20229\Desktop\MCP
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt

검증

# 1. 샘플 파일 생성 (pdf/docx/pptx/svg/png/txt 각 1개)
.venv\Scripts\python scripts\generate_fixtures.py

# 2. MCP 없이 extractor만 직접 테스트
.venv\Scripts\python scripts\smoke_test.py

Claude Code 등록

이 폴더의 .mcp.json이 이미 프로젝트 스코프로 서버를 등록해 놓았다. command 경로가 실제 .venv\Scripts\python.exe 위치와 일치하는지 확인한 뒤, Claude Code를 재시작하거나 /mcp 명령으로 file-analysis 서버가 connected 상태인지 확인한다.

제공 툴

• scan_folder(folder_path, max_depth=3, max_files=200): 폴더 트리와 확장자별 파일 개수만 반환 (내용은 읽지 않음).

• analyze_file(file_path, max_chars=None): 파일 하나를 확장자에 맞게 추출.

  • pdf/docx/pptx/svg → 텍스트/구조 정보

  • png/jpg/jpeg → 이미지(멀티모달) + OCR 텍스트

제약사항

• SVG는 XML 구조만 파싱한다 (텍스트 노드, 도형 개수, viewBox). 텍스트가 없는 순수 벡터 그림은 시각적으로 무엇을 그리는지 알 수 없다 — 필요하면 PNG로 변환해서 다시 분석할 것.

• PDF 50페이지/5만자, PPTX 100슬라이드/5만자, PNG OCR 2만자 등으로 추출량에 상한이 있다. 초과 시 결과에 truncated: true와 안내 문구가 포함된다.