# 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](https://www.python.org/downloads/)에서 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](https://github.com/UB-Mannheim/tesseract/wiki)로 설치 후,
`.mcp.json`의 `TESSERACT_CMD` 값을 실제 설치 경로로 맞춘다. 설치하지 않아도 서버는 정상 동작하며,
PNG 분석 시 이미지 자체(멀티모달)는 반환되고 OCR 텍스트만 "unavailable" 메시지로 대체된다.

## 설치

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

## 검증

```bash
# 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`와 안내 문구가 포함된다.