file-analysis-mcp

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

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

목차

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

• 빠른 시작

• 도구 5개

• Claude Code에 등록

• 프로젝트 구조

• 설계 원칙: 하네스 엔지니어링

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개

모든 도구는 읽기 전용이며 파일을 수정/삭제하지 않습니다. 상한(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류 스코프 승인 게이팅 등은 다중 사용자·장기 실행 에이전트를 위한 것이라 이 규모의 개인용 도구에는 과해서 적용하지 않았습니다.)

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

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

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

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