파일 시스템 MCP 서버 (@sylphlab/filesystem-mcp)

AI 에이전트(예: Cline/Claude)에게 프로젝트 파일에 대한 안전하고 효율적이며 토큰을 절약하는 접근 권한을 부여하세요. 이 Node.js 서버는 모델 컨텍스트 프로토콜(MCP)을 구현하여 정의된 프로젝트 루트 디렉터리 내에서 안전하게 작동하는 강력한 파일 시스템 도구 세트를 제공합니다.

설치

파일 시스템 MCP 서버를 사용하는 방법에는 여러 가지가 있습니다.

1. 권장: MCP 호스트 구성을 통한 npx (또는 bunx )

가장 간단한 방법은 npx 또는 bunx 통해 MCP 호스트 환경(예: Roo/Cline의 mcp_settings.json )에서 직접 설정하는 것입니다. 이렇게 하면 로컬 설치나 Docker 없이도 항상 npm의 최신 버전을 사용할 수 있습니다.

예시( npx ):

지엑스피1

예( bunx ):

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "bunx",
      "args": ["@sylphlab/filesystem-mcp"],
      "name": "Filesystem (bunx)"
    }
  }
}

중요: 서버는 자체 현재 작업 디렉터리( cwd )를 프로젝트 루트로 사용합니다. MCP 호스트(예: Cline/VSCode)가 활성 프로젝트의 루트 디렉터리로 설정된 cwd 사용하여 명령을 실행하도록 구성되어 있는지 확인하십시오.

2. 도커

컨테이너화된 환경에는 공식 Docker 이미지를 사용하세요.

MCP 호스트 구성 예:

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/project:/app", // Mount your project to /app
        "sylphlab/filesystem-mcp:latest"
      ],
      "name": "Filesystem (Docker)"
    }
  }
}

/path/to/your/project 올바른 절대 경로로 바꾸는 것을 잊지 마세요.

3. 로컬 빌드(개발용)

복제: git clone https://github.com/sylphlab/filesystem-mcp.git
설치: cd filesystem-mcp && pnpm install (지금 pnpm 사용)
빌드: pnpm run build
MCP 호스트 구성:
{ "mcpServers": { "filesystem-mcp": { "command": "node", "args": ["/path/to/cloned/repo/filesystem-mcp/dist/index.js"], // Updated build dir "name": "Filesystem (Local Build)" } } }
참고: 프로젝트 루트로 사용할 디렉토리에서 node 명령을 실행하세요.

빠른 시작

MCP 호스트에서 서버를 구성하면(설치 참조) AI 에이전트가 즉시 파일 시스템 도구를 사용할 수 있습니다.

예시 에이전트 상호작용(개념적):

Agent: <use_mcp_tool>
         <server_name>filesystem-mcp</server_name>
         <tool_name>read_content</tool_name>
         <arguments>{"paths": ["src/index.ts"]}</arguments>
       </use_mcp_tool>

Server Response: (Content of src/index.ts)

왜 이 프로젝트를 선택해야 하나요?

🛡️ 안전하고 편리한 프로젝트 루트 중심: 작업은 프로젝트 루트(출시 시 cwd )로 제한됩니다.
⚡ 최적화 및 통합 도구: 일괄 작업으로 AI 서버 왕복 시간을 줄여 토큰과 지연 시간을 절약합니다. 일괄 작업의 각 항목에 대해 신뢰할 수 있는 결과를 제공합니다.
🚀 간편한 통합: npx / bunx 통한 빠른 설정.
🐳 컨테이너화된 옵션: Docker 이미지로 사용 가능합니다.
🔧 포괄적인 기능: 광범위한 파일 시스템 작업을 처리합니다.
✅ 강력한 검증: 인수 검증을 위해 Zod 스키마를 사용합니다.

성능 이점

(자리 표시자: 벤치마크 결과와 비교를 여기에 추가하여 개별 셸 명령과 같은 대체 방법보다 더 나은 점을 보여줍니다.)

일괄 작업: 단일 작업에 비해 오버헤드가 크게 줄어듭니다.
API 직접 사용: 각 명령에 대해 셸 프로세스를 생성하는 것보다 효율적입니다.
(가능한 경우 구체적인 벤치마크 데이터 추가)

특징

이 서버는 AI 에이전트에 강력하고 효율적인 파일 시스템 툴킷을 제공합니다.

📁 탐색 및 검사( list_files , stat_items ): 파일/디렉토리를 나열하고(재귀적, 통계), 여러 항목의 자세한 상태를 가져옵니다.
📄 콘텐츠 읽기 및 쓰기( read_content , write_content ): 여러 파일을 읽고/쓰고/추가하고, 부모 디렉터리를 만듭니다.
✏️ 정밀 편집 및 검색( edit_file , search_files , replace_content ): 들여쓰기를 보존하고 diff 출력을 사용하여 여러 파일에 걸쳐 정밀한 편집(삽입, 바꾸기, 삭제); 컨텍스트를 활용한 정규식 검색; 다중 파일 검색/바꾸기.
🏗️ 디렉토리 관리( create_directories ): 중간 부모를 포함하여 여러 디렉토리를 만듭니다.
🗑️ 안전하게 삭제( delete_items ): 여러 파일/디렉토리를 재귀적으로 제거합니다.
↔️ 이동 및 복사( move_items , copy_items ): 여러 파일/디렉토리를 이동/이름 바꾸기/복사합니다.
🔒 권한 제어( chmod_items , chown_items ): 여러 항목에 대한 POSIX 권한과 소유권을 변경합니다.

주요 이점: 여러 경로/작업을 허용하는 모든 도구는 각 항목을 개별적으로 처리하고 자세한 상태 보고서를 반환합니다.

디자인 철학

(자리 표시자: 핵심적인 디자인 원칙을 설명합니다.)

보안 우선: 프로젝트 루트 외부에서의 접근을 차단하는 것을 우선시합니다.
효율성: AI 상호작용을 위한 커뮤니케이션 오버헤드와 토큰 사용을 최소화합니다.
견고성: 일괄 작업에 대한 자세한 결과와 오류 보고를 제공합니다.
단순성: MCP를 통해 명확하고 일관된 API를 제공합니다.
표준 준수: 모델 컨텍스트 프로토콜을 엄격히 준수합니다.

다른 솔루션과의 비교

(자리 표시자: 대안과 객관적으로 비교하세요.)

특징/측면	파일 시스템 MCP 서버	개별 셸 명령(에이전트를 통해)	기타 사용자 정의 스크립트
보안	높음 (뿌리 제한)	낮음(에이전트에 셸 액세스가 필요함)	변하기 쉬운
효율성(토큰)	높음(배칭)	낮음(op당 하나의 명령)	변하기 쉬운
숨어 있음	낮음(직접 API)	높음(껍질 생성 위치 위)	변하기 쉬운
배치 작업	네 (대부분의 도구)	아니요	아마도
오류 보고	상세(품목별)	기본(stdout/stderr 구문 분석)	변하기 쉬운
설정	쉬움(npx/Docker)	보안 셸 설정이 필요합니다.	관습

미래 계획

(자리 표시자: 출시 예정인 기능이나 개선 사항을 나열하세요.)

파일 감시 기능을 살펴보세요.
매우 큰 파일에 대한 스트리밍 지원을 조사합니다.
특정 작업의 성능을 향상시킵니다.
list_files 에 대해 더욱 고급 필터링 옵션을 추가합니다.

선적 서류 비치

(자리 표시자: 전체 문서 웹사이트가 공개되면 링크를 추가합니다.)

자세한 API 참조 및 예제를 포함한 전체 문서는 [Docs 사이트 링크]에서 제공됩니다.

기여하다

기여를 환영합니다! GitHub 저장소 에 이슈를 등록하거나 풀 리퀘스트를 제출해 주세요.

특허

이 프로젝트는 MIT 라이선스 에 따라 배포됩니다.

개발

복제: git clone https://github.com/sylphlab/filesystem-mcp.git
설치: cd filesystem-mcp && pnpm install
빌드: pnpm run build (TypeScript를 dist/ 로 컴파일)
시청: pnpm run dev (선택 사항, 저장 시 재컴파일)

게시(GitHub Actions를 통해)

이 저장소는 GitHub Actions( .github/workflows/publish.yml )를 사용하여 패키지를 npm 에 자동으로 게시하고, 버전 태그( v*.*.* )를 main 브랜치에 푸시할 때 Docker 이미지를 Docker Hub 에 빌드/푸시합니다. GitHub 저장소 설정에서 구성된 NPM_TOKEN , DOCKERHUB_USERNAME , DOCKERHUB_TOKEN 비밀이 필요합니다.