# file-analysis-mcp

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

![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
![MCP](https://img.shields.io/badge/protocol-MCP-6b5b95)
![read--only](https://img.shields.io/badge/tools-read--only-2ea44f)
![tests](https://img.shields.io/badge/tests-27%20passing-2ea44f)

폴더를 지정하면 안의 문서를 열어 **텍스트만 그대로 뽑아 돌려줍니다.** 요약·해석은
이 서버가 아니라 이 서버를 호출한 Claude가 대화 중에 합니다 — 그래서 별도의 LLM
API 키 없이, 로컬에서 완전히 개인적으로 동작합니다.

---

## 목차

- [실제로 이렇게 동작합니다](#실제로-이렇게-동작합니다)
- [빠른 시작](#빠른-시작)
- [도구 5개](#도구-5개)
- [Claude Code에 등록](#claude-code에-등록)
- [프로젝트 구조](#프로젝트-구조)
- [설계 원칙: 하네스 엔지니어링](#설계-원칙-하네스-엔지니어링)

---

## 실제로 이렇게 동작합니다

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가 만들었습니다 — 이게 이
프로젝트가 지향하는 역할 분리입니다.

## 빠른 시작

```bash
# 1) 의존성 설치 (uv 사용)
uv sync --extra dev

# 2) 확인
uv run pytest                        # 유닛테스트
uv run python scripts/smoke_stdio.py # 실제 MCP 프로토콜로 서버를 띄워보는 스모크 테스트
```

OCR(PNG 분석)이 필요하면 [Tesseract-OCR](https://github.com/UB-Mannheim/tesseract/wiki)을
따로 설치하세요 — 아래 [Claude Code에 등록](#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 설치본](https://github.com/UB-Mannheim/tesseract/wiki)을
   다운로드해 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개 도구가 보이는지 확인하세요.

수동으로 등록하려면:

```bash
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](https://github.com/walkinglabs/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()`를
  재사용해 추가할 수 있습니다.
- **승인 토큰 기반 저장 워크플로**: 이 서버는 파일을 쓰지 않으므로 해당 없음.