# file-analysis-mcp

지정한 폴더 안의 비정형 문서(pdf, docx, pptx, txt, svg, png, csv, xlsx)를 읽고
구조를 파악하며, **승인 없이는 아무것도 저장하지 않는** 개인용 로컬 MCP입니다.

## 실제 동작 예시

포함된 합성 샘플 폴더(`sample_docs/`)를 대상으로 실행한 실제 결과입니다.

```
list_folder_contents()
→ count: 8, entries: data.csv, diagram.svg, notes.docx, photo.png,
  readme.txt, report.pdf, sheet.xlsx, slides.pptx

describe_file(relative_path="slides.pptx")
→ {"slide_count": 3, "slide_titles": ["팀 소개", "구성원", "다음 스프린트"]}
```

이 파일들을 실제로 읽어 작성한 리포트가
[data/outputs/onboarding-overview-report.md](data/outputs/onboarding-overview-report.md)에
있습니다 — 구조 검증 `VALID`, 파일명 근거 검사 `GROUNDED`(100점)로 통과했습니다.

실제 강의 자료 폴더(PPTX, 9MB, 16슬라이드)를 가리켜서도 검증했고, 그 과정에서
PowerPoint를 열어 둔 채 생기는 잠금 파일(`~$*.pptx`)을 읽으려다 포맷 라이브러리
예외가 그대로 튀어나오는 버그를 발견해 고쳤습니다. 지금은 원인 코드와 복구
방법을 담은 오류로 처리됩니다.

```
[INVALID_REQUEST] '~$파일.pptx' 파일을 열지 못했습니다: Package not found ...
복구 방법: list_folder_contents로 파일 목록과 지원 형식을 다시 확인하세요.
```

## 무엇인가

폴더 하나를 지정하면 안의 문서를 읽고, 페이지/슬라이드/시트 수 같은 구조를
먼저 파악하고, 요약 리포트 작성까지 돕습니다. 8가지 형식을 각각 전용
파서(`pypdf`/`python-docx`/`python-pptx`/`openpyxl`/`Pillow`)로 다룹니다.

## 왜 다른가

- **MCP는 LLM을 호출하지 않습니다.** 실제 요약 문장은 Host(Claude/Codex)가
  씁니다. 서버는 데이터 조회·구조 분석·검증·저장만 담당합니다.
- **저장 전에 승인 토큰과 사용자의 명시적 승인이 모두 필요합니다.** 쓰기
  도구는 `save_approved_report` 하나뿐이고, 나머지 10개는 읽기 전용입니다.
- **PNG는 OCR 없이 진짜 이미지 콘텐츠로 전달됩니다.** Host의 비전 능력이
  직접 보고 해석합니다.
- **오류는 항상 원인 코드 + 복구 방법 + 선택 가능한 값**을 함께 돌려줍니다
  (위 예시 참고).

## 어떻게 동작하는가

```
list_folder_contents → describe_file → read_file_text(또는 read_image_file)
  → build_summary_prompt → validate_report_draft → check_report_grounding
  → preview_save_report → [사용자 승인] → save_approved_report
```

| 단계 | 도구 | 역할 |
|---|---|---|
| DISCOVER | `list_folder_contents` | 폴더 재귀 탐색 |
| STRUCTURE | `describe_file` | 페이지/슬라이드/시트 수 등 구조만 (본문 없음) |
| READ | `read_file_text` / `read_image_file` | 본문 텍스트 또는 이미지 콘텐츠 |
| SUMMARIZE | `build_summary_prompt` | 템플릿 + 파일 목록 조립(LLM 호출 없음) |
| CHECK | `validate_report_draft` | 구조 검증 — **저장 게이트** |
| CHECK | `check_report_grounding` | 언급한 파일명이 실제 존재하는지 대조 — 자문 |
| PREVIEW | `preview_save_report` | diff + 승인 토큰 발급 |
| SAVED | `save_approved_report` | **유일한 쓰기 도구** |
| OBSERVE | `list_saved_reports` / `read_report_audit_log` | 저장 이력 조회 |

## 시작하기

```bash
python -m venv .venv
.venv/Scripts/pip install -e ".[dev]"
.venv/Scripts/python scripts/generate_samples.py
.venv/Scripts/python -m pytest -q
.venv/Scripts/python scripts/smoke_stdio.py
```

## 실제 폴더 분석하기

기본값은 `sample_docs/`입니다. 서버 실행 전 환경변수 하나만 바꾸면 됩니다.

```bash
FILE_ANALYSIS_ROOT="D:\내 문서 폴더" .venv/Scripts/python src/file_analysis_mcp/server.py
```

Codex CLI에 등록하려면:

```bash
codex mcp add file-analysis --env FILE_ANALYSIS_ROOT="D:\내 문서 폴더" -- \
  "<프로젝트경로>\.venv\Scripts\python.exe" "<프로젝트경로>\src\file_analysis_mcp\server.py"
```

## 한계

- 이미지는 OCR을 하지 않습니다. 텍스트를 추출하는 게 아니라 이미지 콘텐츠
  그대로 Host에게 전달합니다.
- 20MB가 넘는 파일은 구조 확인만 가능하고 본문은 읽지 못합니다.
- `check_report_grounding`은 정규식 기반 휴리스틱이라 오탐이 있을 수
  있습니다(자문일 뿐 저장을 막지 않습니다).
- 암호화되었거나 손상되었거나 다른 프로그램이 사용 중인 파일은 원인 코드와
  함께 오류로 보고됩니다 — 서버가 죽지 않습니다.

## 기반 패턴

`personal-meeting-mcp-training`과 같은 설계 원칙(계층 분리, `stage`/
`next_actions`, 승인 경계)을 따릅니다. 자세한 도구 계약은
`src/file_analysis_mcp/`의 각 모듈 docstring을 참고하세요.