{"_id":"@beanspapa/mcp-file-server","_rev":"2-f2ef6374f5fb642795baa3bd76ccf6a3","name":"@beanspapa/mcp-file-server","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@beanspapa/mcp-file-server","version":"1.0.0","keywords":["mcp","file-server","typescript","cli"],"author":{"url":"junho.bak@gmail.com","name":"beanspapa"},"license":"ISC","_id":"@beanspapa/mcp-file-server@1.0.0","maintainers":[{"name":"beanspapa","email":"junho.bak@gmail.com"}],"homepage":"https://github.com/beanspapa/mcp-file-server#readme","bugs":{"url":"https://github.com/beanspapa/mcp-file-server/issues"},"dist":{"shasum":"10cb477d7f91494630d870b8fe297663da48725c","tarball":"https://registry.npmjs.org/@beanspapa/mcp-file-server/-/mcp-file-server-1.0.0.tgz","fileCount":61,"integrity":"sha512-Kg70c6CtMZi8LRAGDZxSsj+zgNOHg2KLzxE1hP8PQPizbj9CkSs0BnbvPhxwBdgkgUgizUS/4YEMeBysrbAItg==","signatures":[{"sig":"MEUCIQDu93kaoQmqT7oVfwVUcGq0ep6CmsBtU3/Hl7fG0YwAqgIgGfdvXrjOmWOrlhypb8poIyMuuyh2rUi7EqJyksYZpSE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":216519},"main":"dist/server.js","type":"module","types":"./dist/server.d.ts","gitHead":"2598ce6a9c7b29c5723d22ac0050c60cd262dad6","scripts":{"cli":"node --loader ts-node/esm src/cli-test.ts","dev":"node --loader ts-node/esm src/server.ts","build":"tsc","start":"node dist/server.js"},"_npmUser":{"name":"beanspapa","email":"junho.bak@gmail.com"},"repository":{"url":"git+https://github.com/beanspapa/mcp-file-server.git","type":"git"},"_npmVersion":"9.8.0","description":"File system server implementing the Model Context Protocol","directories":{"doc":"docs"},"_nodeVersion":"22.15.0","dependencies":{"dotenv":"^16.0.3","mcp-file-server":"file:","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.1","typescript":"^5.0.0","@types/node":"^18.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-file-server_1.0.0_1747088728442_0.4531854671323712","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@beanspapa/mcp-file-server","version":"1.0.1","description":"File system server implementing the Model Context Protocol","main":"dist/server.js","type":"module","scripts":{"build":"tsc","start":"node dist/server.js","dev":"node --loader ts-node/esm src/server.ts","cli":"node --loader ts-node/esm src/cli-test.ts"},"keywords":["mcp","file-server","typescript","cli"],"repository":{"type":"git","url":"git+https://github.com/beanspapa/mcp-file-server.git"},"author":{"name":"beanspapa","url":"junho.bak@gmail.com"},"license":"ISC","dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","dotenv":"^16.0.3","mcp-file-server":"file:"},"devDependencies":{"@types/node":"^18.0.0","ts-node":"^10.9.1","typescript":"^5.0.0"},"directories":{"doc":"docs"},"_id":"@beanspapa/mcp-file-server@1.0.1","gitHead":"2598ce6a9c7b29c5723d22ac0050c60cd262dad6","types":"./dist/server.d.ts","bugs":{"url":"https://github.com/beanspapa/mcp-file-server/issues"},"homepage":"https://github.com/beanspapa/mcp-file-server#readme","_nodeVersion":"22.15.0","_npmVersion":"9.8.0","dist":{"integrity":"sha512-MVXfSQnqVzg5oBcJqyTif0qVqCRondj1T5XX9wmfS6BxmOfsWvAIAFSDsiyDBqWWf0RaJBAwDYBdEcqJlXhteQ==","shasum":"97d4a5e1e6d2079b9821b0f8fa8c0e33a8ede718","tarball":"https://registry.npmjs.org/@beanspapa/mcp-file-server/-/mcp-file-server-1.0.1.tgz","fileCount":61,"unpackedSize":219156,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDhf27qI7ZH7xsAaKsX1ZGujowUhJ/9+XdclS4nck52fwIgPZ+8icfEj3zfreMaaEqpq/RoLaiP4o/hLz1J9kOUH/0="}]},"_npmUser":{"name":"beanspapa","email":"junho.bak@gmail.com"},"maintainers":[{"name":"beanspapa","email":"junho.bak@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-file-server_1.0.1_1747090249253_0.518870255667683"},"_hasShrinkwrap":false}},"time":{"created":"2025-05-12T22:25:28.343Z","modified":"2025-05-12T22:50:49.673Z","1.0.0":"2025-05-12T22:25:28.668Z","1.0.1":"2025-05-12T22:50:49.487Z"},"bugs":{"url":"https://github.com/beanspapa/mcp-file-server/issues"},"author":{"name":"beanspapa","url":"junho.bak@gmail.com"},"license":"ISC","homepage":"https://github.com/beanspapa/mcp-file-server#readme","keywords":["mcp","file-server","typescript","cli"],"repository":{"type":"git","url":"git+https://github.com/beanspapa/mcp-file-server.git"},"description":"File system server implementing the Model Context Protocol","maintainers":[{"name":"beanspapa","email":"junho.bak@gmail.com"}],"readme":"# MCP 파일 서버 (MCP File Server)\r\n\r\nMCP 파일 서버는 Model Context Protocol(MCP) 표준을 기반으로, 파일 시스템에 대한 **안전하고 제어된 접근**을 제공하는 TypeScript 기반 서버 구현 예시입니다. LLM(거대 언어 모델)이나 자동화된 에이전트가 서버 환경의 파일 시스템과 상호작용해야 할 때, 보안 위험 없이 필요한 파일 작업(읽기, 쓰기, 목록 조회 등)을 수행할 수 있도록 설계되었습니다.\r\n\r\n주요 목적은 클라이언트(또는 LLM)가 서버에 미리 정의된 규칙(허용된 디렉토리, 허용된 파일 확장자) 내에서만 파일 시스템에 접근하도록 강제하여 보안을 유지하는 것입니다.\r\n\r\n## 주요 기능\r\n\r\n- **안전한 파일 작업**: 지정된 `allowedDirectories` 내의, `allowedExtensions` 확장자를 가진 파일에 대해서만 읽기, 쓰기, 삭제 작업을 허용합니다. **Path Traversal 공격을 방지**하는 로직이 포함되어 있습니다.\r\n- **디렉토리 목록 조회**: 허용된 경로 내의 파일 및 하위 디렉토리 목록을 안전하게 조회합니다.\r\n- **설정 기반 접근 제어**: 서버 시작 시 클라이언트로부터 전달받는 `allowedDirectories`, `allowedExtensions` 설정을 통해 파일 접근 범위를 동적으로 제한합니다.\r\n- **MCP 표준 프로토콜 지원**: MCP (`tools/list`, `resources/list`, `prompts/list` 등) 표준 인터페이스를 통해 도구, 리소스, 프롬프트 기능을 제공하여 클라이언트와의 상호작용을 표준화합니다.\r\n- **CLI 테스트 도구**: 서버의 핵심 파일 접근 로직(`FileService`)을 MCP 프로토콜 없이 직접 테스트해볼 수 있는 간단한 명령줄 인터페이스(CLI)를 제공합니다.\r\n\r\n## 핵심 아키텍처\r\n\r\n이 서버는 다음과 같은 주요 구성 요소로 이루어져 있습니다:\r\n\r\n- **`src/server.ts`**: MCP 서버의 메인 진입점입니다. 클라이언트 요청을 수신하고, 적절한 Manager에게 작업을 위임하며, MCP 요청 핸들러를 등록합니다.\r\n- **Managers (`src/managers/`)**: 각 핵심 기능을 관리합니다.\r\n  - `ToolManager`: 사용 가능한 도구(`file-reader` 등) 목록 관리 및 실행을 담당합니다. (`tools/list` 등 처리)\r\n  - `ResourceManager`: 파일 기반 리소스(예: `file://` URI) 목록 조회 및 접근 유효성 검증을 담당합니다. (`resources/list` 등 처리)\r\n  - `PromptManager`: 프롬프트 템플릿 관리 및 조회를 담당합니다. (`prompts/list`, `prompts/get` 등 처리)\r\n- **`src/fileService.ts`**: **모든 파일 시스템 접근 로직을 담당하는 핵심 보안 구성 요소**입니다. 다른 어떤 컴포넌트(Manager, Tool 등)도 직접 `fs` 모듈을 사용해서는 안 되며, 반드시 `FileService`를 통해야 합니다. `FileService`는 내부적으로 경로 검증(Path Traversal 방지), 허용 디렉토리 및 확장자 검사를 수행합니다.\r\n- **Tools (`src/tools/`)**: 실제 작업을 수행하는 도구 구현체입니다. (예: `FileReaderTool`)\r\n\r\n**중요: 초기화 순서**\r\n\r\n1.  서버는 시작 시 **명령줄 인수**를 통해 `allowedDirectories`, `allowedExtensions` 등의 설정을 전달받습니다. (자세한 형식은 아래 \"설정\" 섹션 참조)\r\n2.  이 설정값을 기반으로 `FileService` 및 각 `Manager` (Tool, Resource, Prompt)가 **초기화**됩니다.\r\n3.  Manager들이 성공적으로 초기화된 **후에** 관련 MCP 요청 핸들러(예: `tools/list`, `resources/list`, 개별 도구 핸들러 등)가 등록됩니다.\r\n\r\n## 설치\r\n\r\n```bash\r\nnpm install\r\n```\r\n\r\n## 실행\r\n\r\n### MCP 서버 실행\r\n\r\n```bash\r\n# 개발 모드로 실행 (변경사항 자동 감지)\r\nnpm run dev -- <허용디렉토리1> <허용디렉토리2> ... --extensions <확장자1>,<확장자2>,...\r\n\r\n# 예시: 현재 디렉토리의 data와 /tmp/shared를 허용하고, .txt와 .json 확장자만 허용\r\nnpm run dev -- ./data /tmp/shared --extensions .txt,.json\r\n\r\n# 빌드 후 실행\r\nnpm run build\r\nnode dist/server.js ./data /tmp/shared --extensions .txt,.json\r\n```\r\n\r\n- 서버는 MCP 프로토콜을 통해 클라이언트와 통신합니다.\r\n- **주의**: 서버가 정상적으로 동작하려면, 서버를 시작할 때 반드시 유효한 `allowedDirectories`와 `allowedExtensions`를 명령줄 인수로 전달해야 합니다. 이 설정 없이는 `FileService`가 초기화되지 않아 대부분의 기능이 작동하지 않습니다.\r\n\r\n### CLI 테스트 도구\r\n\r\nCLI 테스트 도구는 `FileService`의 기능을 MCP 서버 없이 직접 테스트하기 위해 제공됩니다. **이 CLI를 사용하기 전에는, 테스트하려는 경로와 파일이 해당 CLI 코드 내에 하드코딩된 `allowedDirectories` 및 `allowedExtensions` 설정과 일치하는지 확인해야 합니다.** (실제 서버와는 별개의 설정일 수 있습니다.)\r\n\r\n```bash\r\n# CLI 사용법 (Windows 경로 예시)\r\nnpm run cli <명령어> <경로> [\"내용\"]\r\n\r\n# 사용 가능한 명령어:\r\nnpm run cli read <파일경로>              # 파일 읽기\r\nnpm run cli write <파일경로> \"<내용>\"    # 파일 쓰기 (내용은 큰따옴표로 감싸세요)\r\nnpm run cli list <디렉토리경로>          # 디렉토리 목록\r\nnpm run cli delete <파일경로>            # 파일 삭제\r\nnpm run cli createDir <디렉토리경로>     # 디렉토리 생성\r\n\r\n# 예시 (경로는 실제 테스트 환경에 맞게 수정 필요):\r\nnpm run cli read C:\\\\Users\\\\User\\\\Desktop\\\\mcp-test\\\\data.txt\r\nnpm run cli write C:\\\\Users\\\\User\\\\Desktop\\\\mcp-test\\\\new_data.txt \"새로운 파일 내용입니다.\"\r\nnpm run cli list C:\\\\Users\\\\User\\\\Desktop\\\\mcp-test\r\nnpm run cli delete C:\\\\Users\\\\User\\\\Desktop\\\\mcp-test\\\\obsolete.txt\r\nnpm run cli createDir C:\\\\Users\\\\User\\\\Desktop\\\\mcp-test\\\\new_folder\r\n```\r\n\r\n## MCP 클라이언트 상호작용 예시 (개념)\r\n\r\n실제 MCP 클라이언트는 서버를 시작할 때 필요한 설정(`allowedDirectories`, `allowedExtensions`)을 **명령줄 인수로 전달**해야 합니다. 클라이언트 구현에 따라 다르지만, 일반적으로 클라이언트 설정 파일에서 서버 실행 시 전달할 인수를 지정합니다.\r\n\r\n**클라이언트 설정 파일 예시 (가상):**\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"my-file-server\": {\r\n      \"command\": \"node\", // 또는 \"npx @beanspapa/mcp-file-server\" 등\r\n      \"args\": [\r\n        \"dist/server.js\", // 실행할 스크립트 또는 패키지\r\n        // --- 허용할 디렉토리 경로 목록 ---\r\n        \"/path/to/safe-workspace\",\r\n        \"/another/safe/path\",\r\n        // --- 확장자 플래그 및 목록 ---\r\n        \"--extensions\",\r\n        \".txt,.md,.json\"\r\n        // ---------------------------\r\n      ]\r\n      // \"cwd\" 필드 등이 필요할 수 있음\r\n    }\r\n    // ... 다른 서버 설정 ...\r\n  }\r\n}\r\n```\r\n\r\n서버가 위 설정으로 시작된 후, 클라이언트는 다음과 같은 MCP 요청을 보낼 수 있습니다:\r\n\r\n```json\r\n// 도구 목록 요청\r\n{ \"jsonrpc\": \"2.0\", \"method\": \"tools/list\", \"params\": {} }\r\n\r\n// 파일 읽기 도구 실행 요청\r\n{\r\n  \"jsonrpc\": \"2.0\",\r\n  \"method\": \"readFile\", // FileToolManager에 등록된 도구 이름\r\n  \"params\": {\r\n    \"path\": \"documents/report.txt\" // allowedDirectories 중 하나에 속하는 경로\r\n  }\r\n}\r\n```\r\n\r\n## 설정 (명령줄 인수)\r\n\r\n서버를 시작할 때 다음 형식으로 명령줄 인수를 전달하여 `allowedDirectories`와 `allowedExtensions`를 설정합니다.\r\n\r\n**형식:**\r\n\r\n```\r\nnode <스크립트경로> <허용디렉토리1> <허용디렉토리2> ... --extensions <확장자1>,<확장자2>,...\r\n```\r\n\r\n- `<스크립트경로>`: 컴파일된 서버 파일 경로 (예: `dist/server.js`).\r\n- `<허용디렉토리...>`: 서버가 접근할 수 있는 **절대 경로 또는 상대 경로** 목록입니다. 여러 개를 공백으로 구분하여 전달합니다. 경로는 서버 내부에서 절대 경로로 변환되어 처리됩니다.\r\n- `--extensions`: 허용 디렉토리 목록과 확장자 목록을 구분하는 플래그입니다. **반드시 포함되어야 합니다.**\r\n- `<확장자1>,<확장자2>,...`: 접근을 허용할 파일 확장자 목록입니다. **콤마(,)로 구분하고, 반드시 점(.)으로 시작**해야 합니다. (예: `.txt,.json,.md`). 확장자 목록 앞뒤나 콤마 주변에 공백이 있으면 제거됩니다.\r\n\r\n**실행 예시:**\r\n\r\n```bash\r\n# 현재 디렉토리의 data 폴더와 /tmp/shared 폴더를 허용하고, .txt와 .json 확장자만 허용\r\nnode dist/server.js ./data /tmp/shared --extensions .txt,.json\r\n\r\n# Windows 예시: C 드라이브의 work 폴더와 D 드라이브의 projects 폴더를 허용하고 .md 확장자만 허용\r\nnode dist/server.js C:\\\\work D:\\\\projects --extensions .md\r\n```\r\n\r\n- **주의:** `--extensions` 플래그 뒤에 확장자를 지정하지 않거나 유효한 확장자(점으로 시작)가 없으면 경고가 출력되며, `FileService`가 모든 파일 작업을 차단할 수 있습니다. 명시적으로 허용할 확장자를 지정하는 것이 안전합니다.\r\n\r\n## 타입 정의 (주요 타입)\r\n\r\n- **`FileOperationParams` (예: `readFile` 도구 입력)**: `path: string` 등 도구별 파라미터.\r\n- **`FileConfig`**: `{ allowedDirectories: string[]; allowedExtensions: string[]; }` (명령줄 인수로 전달됨)\r\n- **`McpError`**: MCP 표준 오류 객체 (`code`, `message`, `data?`).\r\n\r\n(자세한 MCP 요청/응답 타입은 `@modelcontextprotocol/sdk` 등 관련 SDK 문서를 참조하세요.)\r\n\r\n## 폴더 구조\r\n\r\n- `src/`: 소스 코드 루트\r\n  - `server.ts`: MCP 서버 메인 파일\r\n  - `cli-test.ts`: CLI 테스트 도구 구현\r\n  - `fileService.ts`: 핵심 파일 시스템 접근 및 보안 로직\r\n  - `managers/`: 기능별 관리자 클래스 (`ToolManager`, `ResourceManager`, `PromptManager`)\r\n  - `tools/`: 개별 도구 구현체 (`FileReaderTool` 등)\r\n  - `prompts/`: 프롬프트 템플릿 파일 (예시)\r\n  - `resources/`: 리소스 파일 (예시)\r\n  - `types/`: 프로젝트 내 커스텀 타입 정의\r\n- `dist/`: TypeScript 컴파일 결과 (JavaScript)\r\n- `node_modules/`: 의존성 패키지\r\n- `tsconfig.json`: TypeScript 컴파일 설정\r\n- `package.json`: 프로젝트 정보 및 의존성 관리\r\n- `README.md`: 프로젝트 설명 (이 파일)\r\n\r\n## 라이선스\r\n\r\nISC\r\n","readmeFilename":"README.md"}