Filesystem MCP Server

파일 시스템 MCP 서버

견고하고 플랫폼에 독립적인 파일 시스템 기능으로 AI 에이전트의 역량을 강화하세요.

이 모델 컨텍스트 프로토콜(MCP) 서버는 AI 에이전트가 로컬 파일 시스템과 상호 작용할 수 있는 안전하고 안정적인 인터페이스를 제공합니다. 포괄적인 로깅, 오류 처리 및 보안 기능을 갖춘 프로덕션용 TypeScript 기반을 기반으로 파일 및 디렉터리를 읽고, 쓰고, 업데이트하고, 관리할 수 있습니다.

목차

• 개요
• 특징
• 설치
• 구성
• MCP 클라이언트와 함께 사용
• 사용 가능한 도구
• 프로젝트 구조
• 개발
• 특허

개요

모델 컨텍스트 프로토콜(MCP)은 AI 모델이 외부 도구 및 데이터 소스(리소스)와 안전하게 상호 작용할 수 있도록 하는 표준 프레임워크입니다. 이 서버는 MCP 표준을 구현하여 필수 파일 시스템 작업을 도구로 제공하여 AI 에이전트가 다음과 같은 작업을 수행할 수 있도록 합니다.

• 파일 내용을 읽고 분석합니다.
• 파일을 생성, 수정 또는 덮어씁니다.
• 디렉토리와 파일 경로를 관리합니다.
• 파일 내에서 타겟형 업데이트를 수행합니다.

TypeScript로 구축된 이 서버는 유형 안전성, 모듈성, 견고한 오류 처리를 강조하므로 AI 워크플로에 안정적으로 통합하는 데 적합합니다.

건축학

서버는 명확성과 유지관리성을 위해 계층화된 아키텍처를 채택했습니다.

지엑스피1

• API 계층 : MCP 통신을 처리하고 Zod를 사용하여 입력을 검증하고 경로를 정리합니다.
• 핵심 서비스 : 구성, 로깅, 오류 보고, 세션 상태(기본 작업 디렉토리와 같음) 및 기본 MCP 서버 인스턴스를 관리합니다.
• 도구 구현 : 공유 유틸리티를 활용하여 각 파일 시스템 도구에 대한 특정 논리를 포함합니다.

특징

• 포괄적인 파일 작업 : 파일 및 디렉토리를 읽고, 쓰고, 나열하고, 삭제하고, 이동하고, 복사하기 위한 도구입니다.
• 타겟 업데이트 : update_file 도구는 일반 텍스트와 정규식을 지원하여 파일 내에서 정확한 검색 및 교체 작업을 수행할 수 있습니다.
• 세션 인식 경로 관리 : set_filesystem_default 도구는 세션 동안 상대 경로를 확인하기 위한 기본 작업 디렉터리를 설정합니다.
• 보안 우선 : 내장된 경로 정리 기능으로 디렉터리 트래버설 공격을 방지합니다. 선택적인 기본 디렉터리 제한 기능으로 보안을 강화합니다.
• 견고한 기초 : 다음을 위한 생산 등급 유틸리티가 포함되어 있습니다.
  • 구조화된 상황 인식 로깅.
  • 특정 오류 코드를 사용한 표준화된 오류 처리.
  • 요청 추적을 위한 고유 ID 생성.
  • 입력 정리.
  • 선택적 속도 제한(util 파일이 생성되었지만 아직 통합되지 않음).
• 타입 안전성 : TypeScript로 완벽하게 구현되어 안정성과 유지 관리성이 향상되었습니다.

설치

단계

1. 저장소를 복제합니다.
   git clone https://github.com/cyanheads/filesystem-mcp-server.git cd filesystem-mcp-server
2. 종속성 설치:
   npm install
3. 프로젝트를 빌드하세요:
   npm run build
   이렇게 하면 TypeScript 코드가 dist/ 디렉터리의 JavaScript로 컴파일되고, 메인 스크립트가 실행 가능하게 됩니다. 실행 파일은 dist/index.js 에 저장됩니다.

구성

환경 변수를 사용하여 서버를 구성합니다.

• FS_BASE_DIRECTORY (선택 사항, 보안을 위해 권장 ):
  • 절대 경로로 설정하면 서버에서 수행하는 모든 파일 작업이 해당 디렉터리와 그 하위 디렉터리로 엄격하게 제한됩니다. 이를 통해 AI 에이전트가 의도한 범위를 벗어난 파일에 액세스하는 것을 방지할 수 있습니다.
  • 예: FS_BASE_DIRECTORY=/Users/casey/safe-agent-files
• LOG_LEVEL (선택 사항):
  • 로그의 자세한 정도를 제어합니다. 옵션: error , warn , info , http , verbose , debug , silly .
  • 기본값은 info 입니다.
• LOG_DIR (선택 사항):
  • 로그 파일( combined.log , error.log )이 저장될 디렉토리를 지정합니다.
  • 서버의 실행 디렉토리를 기준으로 ./logs 가 기본값입니다.

MCP 클라이언트와 함께 사용

MCP 클라이언트(AI 어시스턴트 등)가 이 서버를 사용하도록 허용하려면 다음을 수행합니다.

1. 서버 실행: 터미널에서 서버를 시작합니다.
   node dist/index.js # Or if you are in the project root: # npm start
2. 클라이언트 구성: MCP 클라이언트 구성에 서버를 추가합니다. 정확한 방법은 클라이언트에 따라 다르지만 일반적으로 다음을 지정합니다.
   • 명령어: node
   • 인수: 빌드된 서버 실행 파일의 절대 경로(예: /path/to/filesystem-mcp-server/dist/index.js ).
   • 환경 변수(선택 사항): 필요에 따라 FS_BASE_DIRECTORY , LOG_LEVEL 또는 LOG_DIR 설정합니다.

   MCP 설정 예시(개념적):

   { "mcpServers": { "filesystem": { "command": "node", "args": ["/path/to/filesystem-mcp-server/dist/index.js"], "env": { "FS_BASE_DIRECTORY": "/path/to/base/directory", "LOG_LEVEL": "debug" }, "disabled": false, "autoApprove": [] } // ... other servers } }

구성하고 실행하면 클라이언트가 서버와 사용 가능한 도구를 감지합니다.

사용 가능한 도구

서버는 파일 시스템과의 상호작용을 위해 다음과 같은 도구를 제공합니다.

자세한 입력/출력 스키마(Zod/JSON 스키마)는 도구 등록 파일( src/mcp-server/tools/*/registration.ts )을 참조하세요.

프로젝트 구조

코드베이스는 명확성과 유지 관리를 위해 구성되어 있습니다.

현재 구조의 라이브 상세 보기를 보려면 npm run tree 실행하세요.

개발자 참고: 이 저장소에는 .clinerules 파일이 포함되어 있습니다. 이 치트 시트는 LLM 코딩 어시스턴트에게 코드베이스 패턴, 파일 위치 및 사용 예에 대한 필수 정보를 제공합니다. 서버가 업데이트될 때마다 업데이트해 주세요!

특허

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