File Operations MCP Server

파일 작업 MCP 서버

스트리밍, 패치, 변경 사항 추적 지원으로 향상된 파일 작업 기능을 제공하는 MCP(Model Context Protocol) 서버입니다.

특징

• 기본 파일 작업 : 파일 복사, 읽기, 쓰기, 이동 및 삭제
• 디렉토리 작업 : 디렉토리 생성, 제거 및 복사
• 파일 감시 : 파일 및 디렉토리의 변경 사항을 모니터링합니다.
• 변경 추적 : 파일 작업 내역 추적 및 쿼리
• 스트리밍 지원 : 스트리밍을 통해 대용량 파일을 효율적으로 처리
• 리소스 지원 : MCP 리소스를 통해 파일 및 디렉토리에 액세스
• 진행 상황 보고 : 장기 작업에 대한 실시간 진행 상황 업데이트
• 속도 제한 : 과도한 요청으로부터 보호
• 강화된 보안 : 경로 검증 및 입력 정리
• 강력한 오류 처리 : 포괄적인 오류 처리 및 보고
• 유형 안전성 : 엄격한 유형 검사를 통한 전체 TypeScript 지원

설치

Smithery를 통해 설치

Smithery를 통해 Claude Desktop용 File Operations Server를 자동으로 설치하려면:

지엑스피1

수동 설치

용법

서버 시작

자동 재로딩을 이용한 개발의 경우:

사용 가능한 도구

기본 파일 작업

• copy_file : 파일을 새 위치로 복사합니다.
• read_file : 파일에서 내용을 읽습니다.
• write_file : 파일에 내용을 씁니다.
• move_file : 파일 이동/이름 변경
• delete_file : 파일 삭제
• append_file : 파일에 내용을 추가합니다.

디렉토리 작업

• make_directory : 디렉토리를 생성합니다
• remove_directory : 디렉토리 제거
• copy_directory : 디렉토리를 재귀적으로 복사합니다(진행률 보고 포함)

시계 작업

• watch_directory : 디렉토리의 변경 사항을 감시하기 시작합니다.
• unwatch_directory : 디렉토리 감시 중지

변경 사항 추적

• get_changes : 기록된 변경 사항 목록을 가져옵니다.
• clear_changes : 기록된 모든 변경 사항을 지웁니다.

사용 가능한 리소스

정적 리소스

• file:///recent-changes : 최근 파일 시스템 변경 사항 목록

리소스 템플릿

• file://{path} : 파일 내용에 접근
• metadata://{path} : 파일 메타데이터에 접근
• directory://{path} : 디렉토리 내용 나열

사용 예

요금 제한

서버는 남용을 방지하기 위해 속도 제한을 구현합니다.

• 도구 : 분당 100개 요청
• 리소스 : 분당 200개 요청
• 시계 작동 : 분당 20회 작동

속도 제한 오류에는 오류 메시지에 재시도 기간이 포함됩니다.

보안 기능

경로 검증

모든 파일 경로는 디렉토리 탐색 공격을 방지하기 위해 검증됩니다.

• 상위 디렉토리 참조 없음( ../ )
• 적절한 경로 정규화
• 입력 살균

자원 보호

• 모든 작업에 대한 속도 제한
• 적절한 오류 처리 및 로깅
• 모든 매개변수에 대한 입력 검증
• 안전한 자원 정리

진행 상황 보고

디렉토리 복사와 같은 장기 실행 작업은 진행 상황 업데이트를 제공합니다.

진행 상황은 작업 결과에서 반환된 진행 토큰을 통해 추적할 수 있습니다.

개발

건물

린팅

서식

테스트

구성

서버는 다양한 설정을 통해 구성될 수 있습니다.

• 속도 제한 : 요청 제한 및 창 구성
• 진행 상황 보고 : 업데이트 빈도 및 세부 수준 제어
• 리소스 액세스 : 리소스 권한 및 제한 구성
• 보안 설정 : 경로 유효성 검사 규칙 구성
• 변경 추적 : 보존 기간 및 저장 옵션 설정
• 감시 설정 : 디바운스 시간 및 재귀 감시 구성

오류 처리

서버는 FileOperationError 클래스와 MCP 오류 코드를 통해 자세한 오류 정보를 제공합니다.

표준 MCP 오류 코드

• InvalidRequest : 잘못된 매개변수 또는 요청 형식
• MethodNotFound : 알 수 없는 도구 또는 리소스가 요청되었습니다.
• InvalidParams : 잘못된 매개변수(예: 경로 유효성 검사 실패)
• InternalError : 서버 측 오류

사용자 정의 오류 유형

• 파일 작업 실패
• 요금 제한을 초과했습니다
• 경로 검증 오류
• 리소스 액세스 오류

각 오류에는 다음이 포함됩니다.

• 특정 오류 코드
• 자세한 오류 메시지
• 관련 메타데이터(파일 경로, 제한 등)
• 개발 모드에서의 스택 추적

기여하다

1. 저장소를 포크하세요
2. 기능 브랜치를 생성합니다( git checkout -b feature/amazing-feature )
3. 변경 사항을 커밋하세요( git commit -m 'Add amazing feature' )
4. 브랜치에 푸시( git push origin feature/amazing-feature )
5. 풀 리퀘스트 열기

특허

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