File Manage MCP Server

# 📂 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 설치 ```bash uv pip install -r requirements.txt ``` ## ⚙️ Claude Desktop 설정 ### Claude Desktop 설정 (`claude_desktop_config.json`) Windows: `%APPDATA%\Claude\claude_desktop_config.json` ```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](LICENSE) file for details.