파일 시스템 MCP 서버

FastMCP 기반으로 구축된 강력한 파일 시스템 관리 서버로, 파일 및 디렉터리 작업을 위한 포괄적인 도구 세트를 제공합니다. 이 서버를 사용하면 구조화된 API를 통해 다양한 파일 시스템 작업을 수행할 수 있으므로 자동화 및 다른 시스템과의 통합에 이상적입니다.

플랫폼 지원

이 서버는 다양한 운영 체제에서 작동하도록 설계되었지만 기능 수준은 다양합니다.

윈도우

• 모든 기능 지원
• 드라이브 목록
• 특수 폴더 액세스
• Windows 특정 경로 처리
• 자세한 시스템 정보

맥OS/리눅스

• 기본 파일 작업
• 디렉토리 작업
• 파일 검색 및 메타데이터
• 기본 시스템 정보
• 참고: 일부 Windows 특정 기능은 사용할 수 없습니다.

향후 구현

계획된 macOS 지원

• macOS용 기본 경로 처리
• macOS 특정 시스템 정보 검색
• macOS 파일 시스템 기능과의 통합
• macOS 특정 파일 속성 지원
• macOS 전용 유틸리티 구현(windows_utils.py와 유사)

계획된 Linux 지원

• Linux용 기본 경로 처리
• Linux 특정 시스템 정보 검색
• Linux 파일 시스템 기능과의 통합
• Linux 파일 권한 및 속성 지원
• Linux 전용 유틸리티 구현

크로스 플랫폼 개선

• 통합 경로 처리 시스템
• 플랫폼에 구애받지 않는 드라이브 감지
• 일관된 시스템 정보 API
• 플랫폼 간 표준화된 파일 속성
• 크로스 플랫폼 파일 시스템 이벤트 모니터링
• 범용 파일 수집 시스템

타임라인

• 1단계: 기본 크로스 플랫폼 호환성 개선
• 2단계: 플랫폼별 기능 구현
• 3단계: 고급 크로스 플랫폼 기능
• 4단계: 성능 최적화 및 개선

특징

파일 작업

• 백업 지원으로 파일 복사
• 백업 지원을 통한 파일 이동
• 안전 검사가 적용된 파일 삭제
• 파일 내용 읽기
• 파일 내용 쓰기
• 파일 정보(크기, 생성 시간, 수정 시간) 가져오기
• 이름 패턴으로 파일 검색
• 관련 파일을 정리하기 위한 파일 컬렉션을 만듭니다.

디렉토리 작업

• 디렉토리 내용 나열
• 디렉토리 생성
• 디렉토리 삭제
• 디렉토리를 재귀적으로 나열합니다(트리와 같은 구조)
• 이름 패턴으로 디렉토리 검색

시스템 정보

• 시스템 정보(OS, CPU, 메모리, 디스크 사용량)를 가져옵니다.
• 디스크 정보 가져오기(전체 공간, 사용된 공간, 여유 공간)
• 디렉토리 정보 가져오기(파일 수, 총 크기)

프로젝트 구조

지엑스피1

컬렉션 스토리지

컬렉션은 사용자가 지정한 모든 디렉터리에 저장할 수 있습니다. 저장 위치를 지정하지 않으면 프로젝트의 data/collections 디렉터리 내 기본 위치에 저장됩니다.

사용 예:

종속성

필수 종속성

• 패스트MCP
• 피단틱
• pywin32(Windows 전용)
• WMI(Windows 전용)

종속성을 설치하려면:

설정

1. 저장소를 복제합니다.

2. 가상 환경을 만들고 활성화하세요.

3. 종속성 설치:

용법

다양한 개발 환경(Claude, Cursor, Windsurf)에 대한 자세한 MCP 구성 지침은 MCP 구성 가이드를 참조하세요.

Claude와의 통합

Claude와 파일 시스템 MCP 서버를 통합하려면 claude_desktop_config.json 파일에 다음을 추가하세요.

파이썬 경로 찾기

Python 실행 파일 경로를 찾으려면 다음 명령을 사용하세요.

윈도우(PowerShell):

Windows(명령 프롬프트/터미널):

Linux/macOS(터미널):

/absolute/path/to/python 위의 해당 명령의 출력으로 바꾸세요.

구성 예

Windows의 경우 구성은 다음과 같습니다.

macOS/Linux의 경우:

구성을 추가한 후:

1. claude_desktop_config.json 파일을 저장합니다.
2. 클로드를 다시 시작하세요
3. 이제 Claude에게 파일 작업을 수행하도록 요청하여 파일 시스템 도구를 사용할 수 있습니다.

사용 가능한 도구

파일 작업

• copy_file : 선택적 백업을 포함한 파일 복사
• move_file : 선택적 백업으로 파일 이동
• delete_file : 안전 검사를 통해 파일을 삭제합니다.
• read_file : 파일 내용 읽기
• write_file : 파일에 내용을 씁니다.
• get_file_info : 자세한 파일 정보를 가져옵니다
• search_files : 이름 패턴으로 파일 검색
• create_collection : 파일 컬렉션을 생성합니다.

디렉토리 작업

• list_directory : 디렉토리 내용 나열
• create_directory : 새로운 디렉토리를 생성합니다
• delete_directory : 디렉토리 삭제
• list_directory_recursively : 디렉토리 구조를 트리 형식으로 표시합니다.
• search_directories : 이름 패턴으로 디렉토리 검색

시스템 정보

• get_system_info : 시스템 정보 가져오기
• get_disk_info : 디스크 사용 정보 가져오기
• get_directory_info : 디렉토리 통계 가져오기

알려진 문제

다음 기능은 현재 문제가 발생하여 예상대로 작동하지 않을 수 있습니다.

1. 파일 삭제 기능
   • delete_file 함수는 어떤 경우에는 파일을 제대로 삭제하지 못할 수 있습니다.
   • 사용자는 파일 삭제를 수동으로 확인하거나 중요한 경우 대체 방법을 사용하는 것이 좋습니다.
   • 문제는 조사 중이며 향후 업데이트에서 수정될 예정입니다.
2. 드라이브 목록 기능
   • list_drives 함수는 사용 가능한 모든 드라이브를 올바르게 감지하거나 표시하지 못할 수 있습니다.
   • 일부 드라이브가 목록에서 누락되었거나 잘못된 정보가 표시될 수 있습니다.
   • 이는 알려진 제한 사항이며 향후 업데이트에서 해결될 예정입니다.
3. 플랫폼별 제한 사항
   • Windows 전용 기능은 macOS/Linux에서는 사용할 수 없습니다.
   • 일부 경로 처리 방식은 플랫폼마다 다를 수 있습니다.
   • 시스템 정보 검색은 플랫폼마다 다릅니다.

오류 처리

서버에는 다음에 대한 포괄적인 오류 처리 기능이 포함되어 있습니다.

• 잘못된 파일 경로
• 파일/디렉토리를 찾을 수 없습니다
• 권한 문제
• 디스크 공간 제한
• 잘못된 작업
• 플랫폼별 오류

보안

• 모든 파일 작업에는 경로 검증이 포함됩니다.
• 파괴적인 작업 전에 백업 파일이 생성됩니다.
• 시스템 정보 접근은 안전한 운영을 위해 제한됩니다.
• 파일 작업은 적절한 오류 처리를 통해 수행됩니다.

기여하다

1. 저장소를 포크하세요
2. 기능 브랜치 생성
3. 변경 사항을 커밋하세요
4. 지점으로 밀어 넣기
5. 풀 리퀘스트 만들기

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

감사의 말

• FastMCP로 구축됨
• 데이터 검증을 위해 Pydantic을 사용합니다.
• 최신 파일 시스템 관리 도구에서 영감을 받음