local-only server

The server can only run on the client’s local machine because it depends on local resources.

파일 작업 MCP 서버

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

특징

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

설치

Smithery를 통해 설치

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

지엑스피1

수동 설치

npm install

용법

서버 시작

npm start

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

npm run dev

사용 가능한 도구

기본 파일 작업

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} : 디렉토리 내용 나열

사용 예

// Copy a file
await fileOperations.copyFile({
    source: 'source.txt',
    destination: 'destination.txt',
    overwrite: false
});

// Watch a directory
await fileOperations.watchDirectory({
    path: './watched-dir',
    recursive: true
});

// Access file contents through resource
const resource = await mcp.readResource('file:///path/to/file.txt');
console.log(resource.contents[0].text);

// Copy directory with progress tracking
const result = await fileOperations.copyDirectory({
    source: './source-dir',
    destination: './dest-dir',
    overwrite: false
});
// Progress token in result can be used to track progress
console.log(result.progressToken);

요금 제한

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

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

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

보안 기능

경로 검증

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

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

자원 보호

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

진행 상황 보고

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

interface ProgressUpdate {
    token: string | number;
    message: string;
    percentage: number;
}

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

개발

건물

npm run build

린팅

npm run lint

서식

npm run format

테스트

npm test

구성

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

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

오류 처리

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

표준 MCP 오류 코드

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

사용자 정의 오류 유형

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

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

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

기여하다

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

특허

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

You must be authenticated.

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

Tools

View all tools

읽기, 쓰기, 복사, 스트리밍 기능을 통한 파일 이동, 디렉토리 관리, 파일 감시, 변경 사항 추적 등 향상된 파일 시스템 작업을 가능하게 하는 모델 컨텍스트 프로토콜 서버입니다.

Related Resources

Reddit Discussion about this server

File Operations MCP Server