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에 있습니다 — 구조 검증 VALID, 파일명 근거 검사 GROUNDED(100점)로 통과했습니다.

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

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

Related MCP server: local-docs-mcp

무엇인가

폴더 하나를 지정하면 안의 문서를 읽고, 페이지/슬라이드/시트 수 같은 구조를 먼저 파악하고, 요약 리포트 작성까지 돕습니다. 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

시작하기

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/입니다. 서버 실행 전 환경변수 하나만 바꾸면 됩니다.

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

Codex CLI에 등록하려면:

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을 참고하세요.