📂 File Manage MCP Server

Windows용 로컬 MCP 서버로, LLM이 파일 시스템을 정리할 수 있도록 도구를 제공합니다.

✨ 주요 기능

• 디렉토리 분석: 파일/폴더 목록 조회, 날짜 정보 추출
• 파일 내용 확인: 텍스트/코드 파일 스니펫 읽기 (cp949/euc-kr 인코딩 지원)
• 이미지 메타데이터: EXIF 정보에서 촬영 날짜 추출
• 지능형 파일 분석: 텍스트 분석 및 이미지 분석을 통한 파일명 제안 (LLM 연동)
• 파일 그룹핑: 관련 파일 분석 및 자동 그룹핑 제안
• 파일 작업: 이동, 이름 변경, 폴더 생성, 의미를 알 수 없는 파일명 정리
• 일괄 처리: 날짜 접두사 일괄 추가, 다중 파일 그룹 폴더 이동
• 안전 기능: Dry Run 모드, 샌드박스 제한, 시스템 폴더 보호

📋 파일 정리 규칙

2가지 절대 규칙

1. 5단계 규칙: 디렉토리 깊이는 최대 5단계까지
2. 번호 체계: 폴더는 00~99 접두사 사용 (예: 01_Project), 99는 Archive용

명명 규칙

• 폴더: NN_이름 형식 (예: 01_Business, 02_Project)
• 파일: YYMMDD_파일명 형식 (예: 251202_회의록.docx)
• 버전: _v1.0 형식 (Final, 최최최종 금지!)

🚀 설치 및 실행

요구 사항

• Windows 10/11
• Python 3.13+
• uv

uv dependency 설치

uv pip install -r requirements.txt

⚙️ Claude Desktop 설정

Claude Desktop 설정 (claude_desktop_config.json)

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "file-organization-agent": {
      "command": "uv",
      "args": [
        "--directory",
        "{your_path}/FileManageMCP",
        "run",
        "python",
        "server.py"
      ]
    }
  }
}

🛠️ 사용 가능한 도구

설정 도구

도구	설명
tool_set_dry_run	Dry Run 모드 설정 (기본: 활성화)
tool_get_status	현재 설정 상태 확인
tool_configure_workspace	작업 영역(샌드박스) 설정

분석 도구 (Read-Only)

도구	설명
tool_list_directory	디렉토리 내용 조회 (날짜 정보 포함)
tool_read_file_snippet	파일 내용 미리보기
tool_get_image_metadata	이미지 EXIF 정보 추출
tool_analyze_directory_structure	디렉토리 구조 분석 및 문제점 파악

고급 분석 및 정리 도구

도구	설명
tool_find_files_needing_rename	의미를 알 수 없는 파일명을 가진 파일 찾기 (정리 대상 발굴)
tool_suggest_filename_from_content	파일 내용(텍스트/문서) 분석용 요약 정보 반환
tool_get_image_for_analysis	이미지 파일 분석용 데이터 반환 (LLM Vision 연동)
tool_analyze_file_relationships	파일 관계 분석 및 그룹핑 제안

액션 도구 (Dry Run 지원)

도구	설명
tool_move_file	파일 이동
tool_rename_file	파일/폴더 이름 변경
tool_rename_with_suggestion	LLM 제안 이름으로 변경 (고급)
tool_create_folder	새 폴더 생성
tool_group_files_into_folder	관련 파일들을 새 폴더로 일괄 이동 (고급)
tool_batch_rename_with_date	날짜 접두사 일괄 추가

🔒 안전 기능

Dry Run 모드 (기본 활성화)

• 모든 파일 수정 작업은 기본적으로 시뮬레이션만 수행
• 실제 변경 전 예상 결과 확인 가능
• tool_set_dry_run(false) 호출로 실제 모드 전환

샌드박스 제한

• tool_configure_workspace로 작업 영역 설정
• 설정된 영역 외부 접근 차단

시스템 폴더 보호

접근 차단되는 경로:

• C:\Windows
• C:\Program Files
• C:\Program Files (x86)
• .git, node_modules 등

📖 사용 예시

기본 워크플로우

User: D:\Downloads 폴더를 정리해줘

AI: 
1. 먼저 작업 영역을 설정합니다.
   → tool_configure_workspace("D:\\Downloads")

2. 현재 상태를 확인합니다.
   → tool_get_status()  # Dry Run 활성화 확인

3. 디렉토리 구조를 분석합니다.
   → tool_analyze_directory_structure("D:\\Downloads")

4. 의미를 알 수 없는 파일명 파일들을 찾아 정리합니다.
   → tool_find_files_needing_rename("D:\\Downloads")
   → tool_suggest_filename_from_content(...) 또는 tool_get_image_for_analysis(...)
   → tool_rename_with_suggestion(...)

5. 남은 파일들을 주제별로 그룹핑합니다.
   → tool_analyze_file_relationships("D:\\Downloads")
   → tool_group_files_into_folder("D:\\Downloads", "01_References", ["file1.txt", "file2.pdf"])

6. 결과 확인 후 실제 실행합니다.
   → tool_set_dry_run(false)
   → (위 작업 실제 수행)

📁 프로젝트 구조

FileManageMCP/
├── server.py          # MCP 서버 진입점 (FastMCP)
├── tools.py           # MCP 도구 함수 구현
├── utils.py           # 유틸리티 (경로 검증, 인코딩 처리)
├── requirements.txt   # Python 의존성
└── README.md          # 이 문서

📸 실행 예시

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.