Filesystem MCP Server

파일 시스템 MCP 서버

포괄적인 권한 제어와 향상된 기능을 갖춘 파일 시스템 작업을 위한 모델 컨텍스트 프로토콜(MCP)을 구현하는 Node.js 서버입니다.

특징

• 세분화된 권한 제어(읽기 전용, 전체 액세스 또는 특정 작업 권한)
• 허용된 디렉토리 내에서 보안 파일 작업
• 파일 작업:
  • 파일 읽기/쓰기/수정
  • 디렉토리 생성/나열/삭제
  • 파일/디렉토리 이동
  • 이름이나 확장자로 파일 검색
  • 파일 메타데이터 가져오기
• 디렉토리 작업:
  • 디렉토리 구조의 트리 뷰
  • 제외 패턴을 사용한 재귀 연산
• 유틸리티 기능:
  • XML에서 JSON으로 변환
  • 한 번의 호출로 여러 파일 작업 수행
  • 패턴 매칭을 통한 고급 파일 편집
• 보안 기능:
  • 심볼릭 링크 제어
  • 경로 검증
  • 샌드박스 운영

참고 : 서버는 args 통해 지정된 디렉토리 내에서만 작업을 허용하고 구성된 권한에 따라 작업을 수행합니다.

API

자원

• file://system : 파일 시스템 작업 인터페이스

도구

• 읽기_파일
  • 파일의 전체 내용 읽기
  • 입력: path (문자열)
  • UTF-8 인코딩으로 전체 파일 내용을 읽습니다.
• 여러 파일 읽기
  • 여러 파일을 동시에 읽기
  • 입력: paths (문자열[])
  • 읽기에 실패해도 전체 작업이 중단되지는 않습니다.
• 파일 생성
  • 콘텐츠가 있는 새 파일을 만듭니다.
  • 입력:
    • path (문자열): 파일 위치
    • content (문자열): 파일 내용
  • 파일이 이미 존재하면 실패합니다.
  • create 권한이 필요합니다
• 수정_파일
  • 기존 파일을 새 콘텐츠로 수정
  • 입력:
    • path (문자열): 파일 위치
    • content (문자열): 새 파일 내용
  • 파일이 존재하지 않으면 실패합니다.
  • edit 권한이 필요합니다
• 편집_파일
  • 패턴 매칭 및 서식을 사용하여 선택적 편집을 수행합니다.
  • 특징:
    • 줄 기반 및 다중 줄 콘텐츠 매칭
    • 들여쓰기 보존을 통한 공백 정규화
    • 올바른 위치 지정을 통한 여러 동시 편집
    • 들여쓰기 스타일 감지 및 보존
    • 컨텍스트가 포함된 Git 스타일 diff 출력
    • 드라이런 모드로 변경 사항 미리 보기
  • 입력:
    • path (문자열): 편집할 파일
    • edits (배열): 편집 작업 목록
      • oldText (문자열): 검색할 텍스트(정확히 일치)
      • newText (문자열): 바꿀 텍스트
    • dryRun (부울): 변경 사항을 적용하지 않고 미리 봅니다(기본값: false)
  • 드라이런에 대한 자세한 diff를 반환하고, 그렇지 않으면 변경 사항을 적용합니다.
  • edit 권한이 필요합니다
  • 모범 사례: 항상 dryRun을 먼저 사용하여 변경 사항을 미리 봅니다.
• 디렉토리 생성
  • 새 디렉토리를 생성하거나 디렉토리가 존재하는지 확인하세요.
  • 입력: path (문자열)
  • 필요한 경우 상위 디렉토리를 생성합니다.
  • 디렉토리가 있으면 자동으로 성공합니다.
  • create 권한이 필요합니다
• 목록_디렉토리
  • [FILE] 또는 [DIR] 접두사를 사용하여 디렉토리 내용을 나열합니다.
  • 입력: path (문자열)
  • 파일 및 디렉토리의 자세한 목록을 반환합니다.
• 디렉토리 트리
  • 디렉토리 구조의 재귀적 트리 뷰 가져오기
  • 입력: path (문자열)
  • 파일 및 디렉토리가 포함된 JSON 구조를 반환합니다.
  • 각 항목에는 이름, 유형 및 자식(디렉토리용)이 포함됩니다.
• 이동_파일
  • 파일 및 디렉토리 이동 또는 이름 변경
  • 입력:
    • source (문자열): 소스 경로
    • destination (문자열): 목적지 경로
  • 대상이 존재하면 실패합니다.
  • 파일과 디렉토리 모두에 적용 가능
  • move 허가가 필요합니다
• 파일 삭제
  • 파일 삭제
  • 입력: path (문자열)
  • 파일이 존재하지 않으면 실패합니다.
  • delete 권한이 필요합니다
• 디렉토리 삭제
  • 디렉토리 삭제
  • 입력:
    • path (문자열): 삭제할 디렉토리
    • recursive (boolean): 내용을 삭제할지 여부(기본값: false)
  • 디렉토리가 비어 있지 않고 recursive가 false이면 실패합니다.
  • delete 권한이 필요합니다
• 검색_파일
  • 재귀적으로 파일/디렉토리 검색
  • 입력:
    • path (문자열): 시작 디렉토리
    • pattern (문자열): 패턴 검색
    • excludePatterns (string[]): 패턴 제외(glob 형식 지원)
  • 대소문자 구분 없이 일치
  • 일치 항목의 전체 경로를 반환합니다.
• 확장자로 파일 찾기
  • 특정 확장자를 가진 모든 파일 찾기
  • 입력:
    • path (문자열): 시작 디렉토리
    • extension (문자열): 찾을 파일 확장자
    • excludePatterns (문자열[]): 선택적 제외 패턴
  • 대소문자 구분 없이 확장자 매칭
  • 일치하는 파일의 전체 경로를 반환합니다.
• 파일_정보_받기
  • 자세한 파일/디렉토리 메타데이터 가져오기
  • 입력: path (문자열)
  • 보고:
    • 크기
    • 창조 시간
    • 수정된 시간
    • 접속 시간
    • 유형(파일/디렉토리)
    • 권한
• 권한 얻기
  • 현재 서버 권한 가져오기
  • 입력이 필요하지 않습니다
  • 보고:
    • 권한 플래그(읽기 전용, 전체 액세스, 생성, 편집, 이동, 삭제)
    • 심볼릭 링크 팔로우 상태
    • 허용된 디렉토리 수
• 허용된 디렉토리 목록
  • 서버가 액세스할 수 있는 모든 디렉토리를 나열합니다.
  • 입력이 필요하지 않습니다
  • 허용된 디렉토리 경로 배열을 반환합니다.
• xml_to_json
  • XML 파일을 JSON 형식으로 변환
  • 입력:
    • xmlPath (문자열): 소스 XML 파일
    • jsonPath (문자열): 대상 JSON 파일
    • options (객체): 선택 설정
      • ignoreAttributes (부울): XML 속성 건너뛰기(기본값: false)
      • preserveOrder (부울): 속성 순서 유지(기본값: true)
      • format (boolean): JSON을 예쁘게 인쇄합니다(기본값: true)
      • indentSize (숫자): JSON 들여쓰기(기본값: 2)
  • XML 파일에 대한 read 권한이 필요합니다.
  • JSON 파일에 대한 create 또는 edit 권한이 필요합니다.
• xml_to_json_string
  • XML 파일을 JSON 문자열로 변환
  • 입력:
    • xmlPath (문자열): 소스 XML 파일
    • options (객체): 선택 설정
      • ignoreAttributes (부울): XML 속성 건너뛰기(기본값: false)
      • preserveOrder (부울): 속성 순서 유지(기본값: true)
  • XML 파일에 대한 read 권한이 필요합니다.
  • JSON 문자열 표현을 반환합니다.
• xml_쿼리
  • XPath 표현식을 사용하여 XML 파일 쿼리
  • 입력:
    • path (문자열): XML 파일 경로
    • query (문자열, 선택 사항): 실행할 XPath 쿼리
    • structureOnly (boolean, 선택 사항): 태그 구조만 반환합니다.
    • maxBytes (숫자, 선택 사항): 읽을 최대 바이트(기본값: 1MB)
    • includeAttributes (부울, 선택 사항): 속성 정보 포함(기본값: true)
  • XPath 예:
    • 모든 요소 가져오기: //tagname
    • 특정 속성을 가진 요소를 가져옵니다: //tagname[@attr="value"]
    • 텍스트 콘텐츠 가져오기: //tagname/text()
  • 대용량 XML 파일에 대한 메모리 효율성
  • 쿼리 결과 또는 구조의 JSON 표현을 반환합니다.
• xml_구조
  • 전체 파일을 읽지 않고 XML 구조 분석
  • 입력:
    • path (문자열): XML 파일 경로
    • depth (숫자, 선택 사항): 분석 깊이(기본값: 2)
    • includeAttributes (부울, 선택 사항): 속성 분석 포함
    • maxBytes (숫자, 선택 사항): 읽을 최대 바이트(기본값: 1MB)
  • 요소, 속성 및 구조에 대한 통계 정보를 반환합니다.
  • 자세한 분석 전에 대용량 XML 파일을 이해하는 데 유용합니다.

권한 및 보안

서버는 세부적인 권한 제어를 통해 포괄적인 보안 모델을 구현합니다.

디렉토리 액세스 제어

• 작업은 args 통해 시작 중에 지정된 디렉토리로 엄격하게 제한됩니다.
• 모든 작업(심볼릭 링크 대상 포함)은 허용된 디렉토리 내에 있어야 합니다.
• 경로 검증은 허용된 경로 외부에서 디렉토리 탐색이나 액세스가 발생하지 않도록 보장합니다.

권한 플래그

• --readonly : 다른 모든 권한 플래그를 무시하고 읽기 전용 모드를 적용합니다.
• --full-access : 모든 작업(생성, 편집, 이동, 삭제)을 활성화합니다.
• 개별 권한 플래그(--full-access가 설정되지 않은 경우 명시적으로 활성화해야 함):
  • --allow-create : 새로운 파일 및 디렉토리 생성을 허용합니다.
  • --allow-edit : 기존 파일 수정을 허용합니다.
  • --allow-move : 파일 및 디렉토리 이동/이름 변경 허용
  • --allow-delete : 파일 및 디렉토리 삭제 허용

기본 동작 : 권한 플래그를 지정하지 않으면 서버는 읽기 전용 모드로 실행됩니다. 쓰기 작업을 허용하려면 --full-access 또는 특정 --allow-* 플래그를 사용해야 합니다.

심볼릭 링크 처리

• 기본적으로 심볼릭 링크가 따라갑니다(링크와 대상 모두 허용된 디렉토리에 있어야 함)
• --no-follow-symlinks : 심볼릭 링크 팔로우를 비활성화합니다(작업은 링크 자체에서 실행됩니다).

Claude Desktop 및 커서 사용

Claude Desktop의 경우 claude_desktop_config.json 또는 Cursor의 경우 .cursor/mcp.json 에 적절한 구성을 추가합니다.

커서 구성

.cursor/mcp.json 에서:

지엑스피1

Docker 구성

Docker를 사용한 Claude Desktop의 경우:

NPX 구성

NPX를 사용하는 Claude Desktop 또는 Cursor의 경우:

권한 플래그 예

다양한 권한 조합으로 서버를 구성할 수 있습니다.

참고: --readonly 다른 모든 권한 플래그보다 우선하며, --full-access --readonly 지정되지 않은 경우 모든 작업을 활성화합니다.

여러 디렉터리 및 권한

여러 디렉토리를 지정하는 경우 권한 플래그는 모든 디렉토리에 전역적으로 적용됩니다.

다양한 디렉토리에 대해 서로 다른 권한 수준이 필요한 경우 여러 서버 구성을 만드세요.

명령줄 예제

1. 읽기 전용 액세스:

2. 전체 접근:

3. 특정 권한:

4. 다음에 심볼릭 링크가 없습니다.

짓다

Docker 빌드:

특허

이 MCP 서버는 MIT 라이선스에 따라 라이선스가 부여됩니다. 즉, MIT 라이선스의 조건에 따라 소프트웨어를 자유롭게 사용, 수정 및 배포할 수 있습니다. 자세한 내용은 프로젝트 저장소의 LICENSE 파일을 참조하세요.