shutil-mcp

aioshutil을 사용하여 비동기 셸 유틸리티를 제공하는 MCP 서버입니다.

이 프로젝트는 AI 에이전트를 위해 설계된 파일 시스템 도구 세트를 제공하며, 원시 텍스트 대신 구조화된 JSON 출력을 반환합니다. 이를 통해 AI 모델이 파일 시스템 데이터를 보다 정확하고 직접적으로 소비할 수 있습니다.

기능

• 비동기 작업: aioshutil과 스레드 실행기를 활용하여 파일 시스템 작업을 비차단으로 수행합니다.

• JSON 출력: 모든 도구는 AI 에이전트에 최적화된 축소된 JSON을 반환합니다.

• Jail 지원: 보안을 위해 파일 시스템 접근을 특정 디렉터리 트리로 제한합니다.

• 검증 및 무결성: mv와 cp는 연결 해제 또는 완료 전에 대상 데이터를 검증하여 부분 실패 시 데이터 손실을 방지합니다.

• 되돌릴 수 있는 변경 및 실행 취소: chmod와 chown은 즉각적인 실행 취소/재실행을 위해 이전 모드와 소유권을 반환하며, 실패 시 자동으로 롤백됩니다.

• 소프트 삭제 및 복구: rm은 trash=True 소프트 삭제를 지원하며, 이에 대응하는 restore 도구를 제공합니다.

• Zip-Slip 보호: unpack_archive는 모든 아카이브 멤버 경로를 디렉터리 트래버설 / zip-slip 공격에 대해 검증합니다.

• 상세 메타데이터: ls 및 stat과 같은 도구는 포괄적인 정보(크기, mtime, 모드, 소유자 등)를 제공합니다.

• HTTP 전송 지원: SSE 및 Streamable HTTP 전송에 대한 기본 지원을 포함합니다.

Related MCP server: File Manager MCP Server

사용 가능한 도구

• ls: 상세 메타데이터와 함께 디렉터리 내용을 나열합니다.

• cp: 검증과 함께 파일 또는 디렉터리를 재귀적으로 복사합니다.

• mv: 안전한 사전 제거 검증과 함께 파일 또는 디렉터리를 이동/이름 변경합니다.

• rm: 파일 또는 디렉터리를 제거합니다(trash=True 소프트 삭제 지원).

• restore: 휴지통에서 파일 또는 디렉터리를 복원합니다.

• chmod: 롤백 및 이전 모드와 함께 파일/디렉터리 권한을 변경합니다.

• chown: 롤백 및 이전 소유자와 함께 파일/디렉터리 소유권을 변경합니다.

• disk_usage: 경로에 대한 디스크 사용량 통계를 가져옵니다.

• which: 실행 파일의 경로를 찾습니다.

• cat: 파일 내용을 읽으며, 선택적으로 특정 줄 범위로 제한할 수 있습니다.

• glob: glob 패턴과 일치하는 파일을 찾습니다.

• grep: 정규식 패턴을 사용하여 파일 내용을 검색합니다.

• tree: 중첩된 JSON으로 재귀적 디렉터리 트리를 가져옵니다.

• make_archive: 덮어쓰기 방지와 함께 아카이브 파일(zip, tar 등)을 생성합니다.

• unpack_archive: zip-slip 보호와 함께 아카이브 파일을 안전하게 압축 해제합니다.

• get_archive_formats: 지원되는 아카이브 형식을 나열합니다.

설치

pip install shutil-mcp

사용법

stdio 전송으로 실행

shutil-mcp --transport stdio

jail 제한으로 실행

shutil-mcp --transport stdio --jail /path/to/projects

SSE 서버로 실행

shutil-mcp --transport sse --jail /path/to/projects --port 8000

개발

자세한 개발 지침은 DEVELOPMENT.md를 참조하세요.

라이선스

MIT