{"id":48832318,"url":"https://github.com/1999azzar/filesystem-mcp-server","last_synced_at":"2026-04-14T21:02:03.116Z","repository":{"id":322588615,"uuid":"1061870394","full_name":"1999AZZAR/filesystem-mcp-server","owner":"1999AZZAR","description":"A comprehensive Model Context Protocol (MCP) server for advanced file system operations. This server provides structured file management capabilities including file operations, directory management, file watching, search functionality, and archiving operations.","archived":false,"fork":false,"pushed_at":"2025-12-18T15:51:07.000Z","size":333,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-20T21:16:02.072Z","etag":null,"topics":["mcp","mcp-server","mcp-tools"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/1999AZZAR.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-22T13:50:57.000Z","updated_at":"2025-12-18T15:33:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/1999AZZAR/filesystem-mcp-server","commit_stats":null,"previous_names":["1999azzar/filesystem-mcp-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/1999AZZAR/filesystem-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1999AZZAR%2Ffilesystem-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1999AZZAR%2Ffilesystem-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1999AZZAR%2Ffilesystem-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1999AZZAR%2Ffilesystem-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/1999AZZAR","download_url":"https://codeload.github.com/1999AZZAR/filesystem-mcp-server/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1999AZZAR%2Ffilesystem-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31815080,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-server","mcp-tools"],"created_at":"2026-04-14T21:02:00.207Z","updated_at":"2026-04-14T21:02:03.096Z","avatar_url":"https://github.com/1999AZZAR.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FileSystem MCP Server\n\nA comprehensive Model Context Protocol (MCP) server for advanced file system operations. This server provides structured file management capabilities including file operations, directory management, file watching, search functionality, and archiving operations.\n\n## Table of Contents\n\n- [Features](#features)\n  - [Core File Operations](#core-file-operations)\n  - [Directory Operations](#directory-operations)\n  - [Advanced Operations](#advanced-operations)\n  - [Enterprise Features](#enterprise-features)\n- [Available Resources](#available-resources)\n- [Installation](#installation)\n- [Configuration](#configuration)\n  - [For Cursor IDE](#for-cursor-ide)\n  - [For Claude Desktop](#for-claude-desktop)\n- [Available Tools](#available-tools)\n  - [1. File Operations](#1-file-operations)\n  - [2. Directory Operations](#2-directory-operations)\n  - [3. Advanced Operations](#3-advanced-operations)\n- [Usage Examples](#usage-examples)\n  - [Basic File Operations](#basic-file-operations)\n  - [Directory Management](#directory-management)\n  - [Advanced Operations](#advanced-operations)\n- [Development](#development)\n  - [Project Structure](#project-structure)\n  - [Development Commands](#development-commands)\n  - [Testing](#testing)\n  - [Error Handling](#error-handling)\n  - [Performance Considerations](#performance-considerations)\n- [Security Considerations](#security-considerations)\n- [License](#license)\n- [Contributing](#contributing)\n- [Support](#support)\n\n## Features\n\n### Core File Operations\n- **File Reading**: Read files with optional encoding and range support\n- **File Writing**: Write content with encoding options and directory creation\n- **File Copying**: Copy files with timestamp preservation and overwrite control\n- **File Moving**: Move/rename files with conflict resolution\n- **File Deletion**: Delete files and directories with recursive options\n- **File Information**: Get detailed file metadata including permissions and timestamps\n\n### Directory Operations\n- **Directory Creation**: Create directories with recursive parent creation\n- **Directory Listing**: List contents with filtering, recursion, and depth control\n- **File Finding**: Find files using glob patterns with advanced filtering\n- **Directory Size**: Calculate directory sizes recursively with human-readable formatting\n\n### Advanced Operations\n- **Text Search**: Search for patterns in files with context and filtering\n- **File Watching**: Watch files and directories for changes with event handling\n- **File Comparison**: Compare files with whitespace and case sensitivity options\n- **Archiving**: Create and extract archives in multiple formats (ZIP, TAR, GZIP)\n- **Batch Operations**: Perform operations on multiple files efficiently\n\n### Enterprise Features\n- **TypeScript**: Fully typed with comprehensive error handling\n- **Input Validation**: Zod schema validation for all parameters\n- **Error Recovery**: Graceful error handling with detailed error messages\n- **Resource Management**: Automatic cleanup of watchers and resources\n- **Performance**: Optimized for large file operations and batch processing\n- **Intelligent Caching**: TTL-based caching system for file metadata and search results\n- **MCP Resources**: 7 specialized resources providing cached filesystem data and metadata\n\n## Available Resources\n\nFileSystem MCP Server provides **7 specialized resources** that offer cached file system data and intelligent metadata access with configurable TTL-based caching for optimal performance:\n\n### `file://metadata/{path}`\nReturns cached metadata for files and directories including permissions, size, modification dates, and ownership.\n\n**Resource Details:**\n- **Purpose**: Access file/directory metadata without repeated stat calls\n- **Benefits**: Faster file information queries, reduced I/O operations, metadata caching\n- **Cache TTL**: 5 minutes - balances metadata freshness with performance\n- **Use Cases**: File explorers, permission checking, size calculations, file monitoring\n\n**Response Format:**\n```json\n{\n  \"path\": \"/home/user/document.txt\",\n  \"metadata\": {\n    \"size\": 1024,\n    \"permissions\": \"rw-r--r--\",\n    \"owner\": \"user\",\n    \"group\": \"users\",\n    \"modified\": \"2025-11-02T10:30:00.000Z\",\n    \"accessed\": \"2025-11-02T10:30:00.000Z\",\n    \"created\": \"2025-11-01T15:20:00.000Z\"\n  },\n  \"cached\": false,\n  \"timestamp\": \"2025-11-02T17:09:14.866Z\"\n}\n```\n\n### `file://directory/{path}`\nProvides cached directory listing with file details, sizes, and metadata for faster browsing.\n\n**Resource Details:**\n- **Purpose**: Access directory contents without repeated directory reads\n- **Benefits**: Instant directory browsing, cached file listings, reduced I/O for navigation\n- **Cache TTL**: 5 minutes - keeps directory structure reasonably current\n- **Use Cases**: File managers, directory exploration, project navigation\n\n**Response Format:**\n```json\n{\n  \"path\": \"/home/user/projects\",\n  \"contents\": {\n    \"success\": true,\n    \"data\": {\n      \"items\": [\n        {\n          \"name\": \"app.js\",\n          \"path\": \"/home/user/projects/app.js\",\n          \"type\": \"file\",\n          \"size\": 2048,\n          \"permissions\": \"rw-r--r--\",\n          \"modified\": \"2025-11-02T10:30:00.000Z\"\n        }\n      ]\n    }\n  },\n  \"cached\": false,\n  \"timestamp\": \"2025-11-02T17:09:14.866Z\"\n}\n```\n\n### `file://search/cache/{query}`\nCaches results from file content and pattern searches across the filesystem.\n\n**Resource Details:**\n- **Purpose**: Cache expensive search operations across large codebases\n- **Benefits**: Fast repeated searches, reduced filesystem traversal, search result persistence\n- **Cache TTL**: 5 minutes - allows for reasonable search result freshness\n- **Use Cases**: Code search, content finding, pattern matching, file discovery\n\n**Response Format:**\n```json\n{\n  \"query\": \"function.*handleError\",\n  \"results\": {\n    \"success\": true,\n    \"data\": {\n      \"matches\": [\n        {\n          \"file\": \"/src/error-handler.js\",\n          \"line\": 15,\n          \"content\": \"function handleError(error) {\",\n          \"context\": [\"// Error handling function\", \"function handleError(error) {\", \"  console.error(error);\"]\n        }\n      ]\n    }\n  },\n  \"cached\": false,\n  \"timestamp\": \"2025-11-02T17:09:14.866Z\"\n}\n```\n\n### `file://watch/status/{path}`\nShows current status and recent events for file system watchers.\n\n**Resource Details:**\n- **Purpose**: Monitor file watching status and recent change events\n- **Benefits**: Track active watchers, view recent file changes, debug watch operations\n- **Cache TTL**: 30 seconds - provides near real-time watch status\n- **Use Cases**: Development monitoring, file change tracking, watch debugging\n\n**Response Format:**\n```json\n{\n  \"path\": \"/home/user/projects\",\n  \"isWatching\": true,\n  \"lastEvents\": [\n    {\n      \"event\": \"change\",\n      \"filename\": \"app.js\",\n      \"timestamp\": \"2025-11-02T17:08:45.123Z\"\n    }\n  ],\n  \"cached\": false,\n  \"timestamp\": \"2025-11-02T17:09:14.866Z\"\n}\n```\n\n### `file://recent/{type}`\nLists recently accessed files of specified type (read/write/modified).\n\n**Resource Details:**\n- **Purpose**: Track recently accessed files for quick access and auditing\n- **Benefits**: Quick access to recently worked files, usage tracking, productivity insights\n- **Cache TTL**: 5 minutes - keeps recent file list reasonably current\n- **Use Cases**: File history, recent documents, usage analytics\n\n**Response Format:**\n```json\n{\n  \"type\": \"modified\",\n  \"files\": [\n    {\n      \"path\": \"/home/user/document.txt\",\n      \"accessed\": \"2025-11-02T17:05:00.000Z\",\n      \"size\": 1024\n    }\n  ],\n  \"count\": 1,\n  \"cached\": false,\n  \"timestamp\": \"2025-11-02T17:09:14.866Z\"\n}\n```\n\n### `file://structure/{path}`\nProvides hierarchical directory structure with file counts and size summaries.\n\n**Resource Details:**\n- **Purpose**: Get complete directory tree structure with statistics\n- **Benefits**: Project overview, size analysis, structure visualization, disk usage tracking\n- **Cache TTL**: 5 minutes - balances structure accuracy with performance\n- **Use Cases**: Project analysis, disk cleanup, directory visualization\n\n**Response Format:**\n```json\n{\n  \"path\": \"/home/user/projects\",\n  \"structure\": {\n    \"name\": \"projects\",\n    \"type\": \"directory\",\n    \"path\": \"/home/user/projects\",\n    \"children\": [\n      {\n        \"name\": \"src\",\n        \"type\": \"directory\",\n        \"path\": \"/home/user/projects/src\",\n        \"size\": 0\n      },\n      {\n        \"name\": \"README.md\",\n        \"type\": \"file\",\n        \"path\": \"/home/user/projects/README.md\",\n        \"size\": 2048\n      }\n    ],\n    \"stats\": {\n      \"totalFiles\": 5,\n      \"totalDirs\": 3,\n      \"totalSize\": 15360\n    }\n  },\n  \"cached\": false,\n  \"timestamp\": \"2025-11-02T17:09:14.866Z\"\n}\n```\n\n### `file://content/preview/{path}`\nGenerates cached preview of file content (first lines/chars) for quick inspection.\n\n**Resource Details:**\n- **Purpose**: Preview file content without loading entire files\n- **Benefits**: Quick file inspection, content type detection, safe file preview\n- **Cache TTL**: 5 minutes - keeps previews reasonably fresh\n- **Use Cases**: File exploration, content verification, type detection, safe browsing\n\n**Response Format:**\n```json\n{\n  \"path\": \"/home/user/document.txt\",\n  \"preview\": {\n    \"path\": \"/home/user/document.txt\",\n    \"type\": \"file\",\n    \"preview\": \"This is the beginning of the document...\\nIt contains important information...\",\n    \"canPreview\": true,\n    \"size\": 1024,\n    \"mimeType\": \"text/plain\",\n    \"encoding\": \"utf8\"\n  },\n  \"cached\": false,\n  \"timestamp\": \"2025-11-02T17:09:14.866Z\"\n}\n```\n\n## Installation\n\n1. **Clone the repository:**\n```bash\ngit clone https://github.com/1999AZZAR/filesystem-mcp-server.git\ncd filesystem-mcp-server\n```\n\n2. **Install dependencies:**\n```bash\nnpm install\n```\n\n3. **Build the project:**\n```bash\nnpm run build\n```\n\n4. **Test the server:**\n```bash\nnpm start\n```\n\n## Configuration\n\n### For Cursor IDE\n\nAdd this server to your Cursor MCP configuration (`~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/filesystem-mcp-server/dist/index.js\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n### For Claude Desktop\n\nAdd this server to your Claude Desktop configuration (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/filesystem-mcp-server/dist/index.js\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n## Available Tools\n\nThis MCP server provides **18 powerful tools** for comprehensive file system management:\n\n### 1. File Operations\n\n#### `read_file` - Read File Content\nRead file content with optional encoding and range support.\n\n**Parameters:**\n- `path` (required): Path to the file to read\n- `encoding` (optional): File encoding - \"utf8\", \"utf16le\", \"latin1\", \"base64\", \"hex\", \"ascii\", \"binary\" (default: \"utf8\")\n- `offset` (optional): Byte offset to start reading from\n- `limit` (optional): Maximum number of bytes to read\n\n**Example:**\n```json\n{\n  \"name\": \"read_file\",\n  \"arguments\": {\n    \"path\": \"/path/to/file.txt\",\n    \"encoding\": \"utf8\",\n    \"offset\": 0,\n    \"limit\": 1024\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"message\": \"File read successfully\",\n  \"path\": \"/path/to/file.txt\",\n  \"data\": {\n    \"content\": \"File content here...\",\n    \"encoding\": \"utf8\",\n    \"size\": 1024\n  }\n}\n```\n\n#### `write_file` - Write File Content\nWrite content to file with optional encoding and directory creation.\n\n**Parameters:**\n- `path` (required): Path to the file to write\n- `content` (required): Content to write to the file\n- `encoding` (optional): File encoding (default: \"utf8\")\n- `createDirs` (optional): Create parent directories if they don't exist (default: false)\n- `append` (optional): Append to file instead of overwriting (default: false)\n\n**Example:**\n```json\n{\n  \"name\": \"write_file\",\n  \"arguments\": {\n    \"path\": \"/path/to/file.txt\",\n    \"content\": \"Hello, World!\",\n    \"encoding\": \"utf8\",\n    \"createDirs\": true\n  }\n}\n```\n\n#### `copy_file` - Copy File\nCopy file from source to destination with options.\n\n**Parameters:**\n- `source` (required): Source file path\n- `destination` (required): Destination file path\n- `overwrite` (optional): Overwrite destination if it exists (default: false)\n- `preserveTimestamps` (optional): Preserve file timestamps (default: true)\n\n**Example:**\n```json\n{\n  \"name\": \"copy_file\",\n  \"arguments\": {\n    \"source\": \"/path/to/source.txt\",\n    \"destination\": \"/path/to/destination.txt\",\n    \"overwrite\": true,\n    \"preserveTimestamps\": true\n  }\n}\n```\n\n#### `move_file` - Move File\nMove file from source to destination.\n\n**Parameters:**\n- `source` (required): Source file path\n- `destination` (required): Destination file path\n- `overwrite` (optional): Overwrite destination if it exists (default: false)\n\n**Example:**\n```json\n{\n  \"name\": \"move_file\",\n  \"arguments\": {\n    \"source\": \"/path/to/source.txt\",\n    \"destination\": \"/path/to/destination.txt\",\n    \"overwrite\": false\n  }\n}\n```\n\n#### `delete_file` - Delete File or Directory\nDelete file or directory with options.\n\n**Parameters:**\n- `path` (required): Path to delete\n- `recursive` (optional): Recursively delete directories (default: false)\n- `force` (optional): Force deletion even if path doesn't exist (default: false)\n\n**Example:**\n```json\n{\n  \"name\": \"delete_file\",\n  \"arguments\": {\n    \"path\": \"/path/to/file.txt\",\n    \"recursive\": false,\n    \"force\": false\n  }\n}\n```\n\n#### `get_file_info` - Get File Information\nGet detailed file information including metadata.\n\n**Parameters:**\n- `path` (required): Path to get information for\n- `followSymlinks` (optional): Follow symbolic links (default: true)\n\n**Example:**\n```json\n{\n  \"name\": \"get_file_info\",\n  \"arguments\": {\n    \"path\": \"/path/to/file.txt\",\n    \"followSymlinks\": true\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"message\": \"File information retrieved successfully\",\n  \"path\": \"/path/to/file.txt\",\n  \"data\": {\n    \"name\": \"file.txt\",\n    \"path\": \"/path/to/file.txt\",\n    \"type\": \"file\",\n    \"size\": 1024,\n    \"isDirectory\": false,\n    \"isFile\": true,\n    \"isSymlink\": false,\n    \"permissions\": \"644\",\n    \"createdAt\": \"2024-01-15T10:30:00.000Z\",\n    \"modifiedAt\": \"2024-01-15T10:30:00.000Z\",\n    \"accessedAt\": \"2024-01-15T10:30:00.000Z\",\n    \"extension\": \".txt\",\n    \"mimeType\": \"text/plain\"\n  }\n}\n```\n\n### 2. Directory Operations\n\n#### `create_directory` - Create Directory\nCreate directory with optional recursive creation.\n\n**Parameters:**\n- `path` (required): Directory path to create\n- `recursive` (optional): Create parent directories recursively (default: false)\n- `mode` (optional): Directory permissions in octal format\n\n**Example:**\n```json\n{\n  \"name\": \"create_directory\",\n  \"arguments\": {\n    \"path\": \"/path/to/new/directory\",\n    \"recursive\": true,\n    \"mode\": \"755\"\n  }\n}\n```\n\n#### `list_directory` - List Directory Contents\nList directory contents with optional filtering and recursion.\n\n**Parameters:**\n- `path` (required): Directory path to list\n- `recursive` (optional): List contents recursively (default: false)\n- `includeHidden` (optional): Include hidden files and directories (default: false)\n- `maxDepth` (optional): Maximum depth for recursive listing\n- `fileTypes` (optional): Filter by file types - [\"file\", \"directory\", \"symlink\"]\n\n**Example:**\n```json\n{\n  \"name\": \"list_directory\",\n  \"arguments\": {\n    \"path\": \"/path/to/directory\",\n    \"recursive\": true,\n    \"includeHidden\": false,\n    \"maxDepth\": 3,\n    \"fileTypes\": [\"file\", \"directory\"]\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"message\": \"Directory listed successfully (15 items)\",\n  \"path\": \"/path/to/directory\",\n  \"data\": {\n    \"items\": [\n      {\n        \"name\": \"file1.txt\",\n        \"path\": \"/path/to/directory/file1.txt\",\n        \"type\": \"file\",\n        \"size\": 1024,\n        \"isDirectory\": false,\n        \"isFile\": true,\n        \"isSymlink\": false,\n        \"permissions\": \"644\",\n        \"createdAt\": \"2024-01-15T10:30:00.000Z\",\n        \"modifiedAt\": \"2024-01-15T10:30:00.000Z\",\n        \"accessedAt\": \"2024-01-15T10:30:00.000Z\",\n        \"extension\": \".txt\",\n        \"mimeType\": \"text/plain\"\n      }\n    ],\n    \"count\": 15,\n    \"recursive\": true,\n    \"includeHidden\": false\n  }\n}\n```\n\n#### `find_files` - Find Files\nFind files matching a pattern.\n\n**Parameters:**\n- `pattern` (required): Glob pattern to match files\n- `directory` (optional): Directory to search in (default: \".\")\n- `maxDepth` (optional): Maximum search depth\n- `includeHidden` (optional): Include hidden files (default: false)\n- `fileTypes` (optional): Filter by file types\n- `caseSensitive` (optional): Case-sensitive pattern matching (default: false)\n\n**Example:**\n```json\n{\n  \"name\": \"find_files\",\n  \"arguments\": {\n    \"pattern\": \"*.txt\",\n    \"directory\": \"/path/to/search\",\n    \"maxDepth\": 3,\n    \"includeHidden\": false,\n    \"fileTypes\": [\"file\"],\n    \"caseSensitive\": false\n  }\n}\n```\n\n#### `get_directory_size` - Get Directory Size\nGet directory size recursively.\n\n**Parameters:**\n- `path` (required): Directory path\n\n**Example:**\n```json\n{\n  \"name\": \"get_directory_size\",\n  \"arguments\": {\n    \"path\": \"/path/to/directory\"\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"message\": \"Directory size calculated successfully\",\n  \"path\": \"/path/to/directory\",\n  \"data\": {\n    \"totalSize\": 1048576,\n    \"fileCount\": 25,\n    \"dirCount\": 5,\n    \"humanReadable\": \"1.00 MB\"\n  }\n}\n```\n\n### 3. Advanced Operations\n\n#### `search_in_files` - Search in Files\nSearch for text patterns in files.\n\n**Parameters:**\n- `pattern` (required): Text pattern to search for\n- `directory` (optional): Directory to search in (default: \".\")\n- `filePattern` (optional): Glob pattern for files to search\n- `maxDepth` (optional): Maximum search depth\n- `includeHidden` (optional): Include hidden files (default: false)\n- `caseSensitive` (optional): Case-sensitive search (default: false)\n- `wholeWord` (optional): Match whole words only (default: false)\n- `contextLines` (optional): Number of context lines around matches (default: 2)\n\n**Example:**\n```json\n{\n  \"name\": \"search_in_files\",\n  \"arguments\": {\n    \"pattern\": \"function\",\n    \"directory\": \"/path/to/code\",\n    \"filePattern\": \"*.js\",\n    \"maxDepth\": 2,\n    \"includeHidden\": false,\n    \"caseSensitive\": false,\n    \"wholeWord\": true,\n    \"contextLines\": 3\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"message\": \"Search completed: 5 files with matches\",\n  \"path\": \"/path/to/code\",\n  \"data\": {\n    \"results\": [\n      {\n        \"path\": \"/path/to/code/file.js\",\n        \"matches\": [\n          {\n            \"line\": 10,\n            \"column\": 1,\n            \"text\": \"function\",\n            \"context\": \"// This is a function\\nexport function myFunction() {\\n  return 'hello';\\n}\"\n          }\n        ],\n        \"fileInfo\": {\n          \"name\": \"file.js\",\n          \"path\": \"/path/to/code/file.js\",\n          \"type\": \"file\",\n          \"size\": 2048,\n          \"isDirectory\": false,\n          \"isFile\": true,\n          \"isSymlink\": false,\n          \"permissions\": \"644\",\n          \"createdAt\": \"2024-01-15T10:30:00.000Z\",\n          \"modifiedAt\": \"2024-01-15T10:30:00.000Z\",\n          \"accessedAt\": \"2024-01-15T10:30:00.000Z\",\n          \"extension\": \".js\",\n          \"mimeType\": \"application/javascript\"\n        }\n      }\n    ],\n    \"totalMatches\": 8,\n    \"pattern\": \"function\",\n    \"directory\": \"/path/to/code\"\n  }\n}\n```\n\n#### `watch_file` - Watch File or Directory\nWatch file or directory for changes.\n\n**Parameters:**\n- `path` (required): Path to watch\n- `recursive` (optional): Watch recursively (default: false)\n- `ignoreInitial` (optional): Ignore initial events (default: true)\n- `ignored` (optional): Patterns to ignore\n\n**Example:**\n```json\n{\n  \"name\": \"watch_file\",\n  \"arguments\": {\n    \"path\": \"/path/to/watch\",\n    \"recursive\": true,\n    \"ignoreInitial\": true,\n    \"ignored\": [\"*.tmp\", \"node_modules/**\"]\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"message\": \"File watching started successfully\",\n  \"path\": \"/path/to/watch\",\n  \"data\": {\n    \"watching\": true,\n    \"recursive\": true,\n    \"ignoreInitial\": true,\n    \"events\": [\n      {\n        \"type\": \"add\",\n        \"path\": \"/path/to/watch/newfile.txt\",\n        \"stats\": {\n          \"name\": \"newfile.txt\",\n          \"path\": \"/path/to/watch/newfile.txt\",\n          \"type\": \"file\",\n          \"size\": 0,\n          \"isDirectory\": false,\n          \"isFile\": true,\n          \"isSymlink\": false,\n          \"permissions\": \"644\",\n          \"createdAt\": \"2024-01-15T10:30:00.000Z\",\n          \"modifiedAt\": \"2024-01-15T10:30:00.000Z\",\n          \"accessedAt\": \"2024-01-15T10:30:00.000Z\"\n        }\n      }\n    ]\n  }\n}\n```\n\n#### `stop_watching` - Stop Watching\nStop watching a file or directory.\n\n**Parameters:**\n- `path` (required): Path to stop watching\n\n**Example:**\n```json\n{\n  \"name\": \"stop_watching\",\n  \"arguments\": {\n    \"path\": \"/path/to/watch\"\n  }\n}\n```\n\n#### `compare_files` - Compare Files\nCompare two files and show differences.\n\n**Parameters:**\n- `file1` (required): First file path\n- `file2` (required): Second file path\n- `ignoreWhitespace` (optional): Ignore whitespace differences (default: false)\n- `ignoreCase` (optional): Ignore case differences (default: false)\n\n**Example:**\n```json\n{\n  \"name\": \"compare_files\",\n  \"arguments\": {\n    \"file1\": \"/path/to/file1.txt\",\n    \"file2\": \"/path/to/file2.txt\",\n    \"ignoreWhitespace\": true,\n    \"ignoreCase\": false\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"message\": \"Files differ: 3 differences found\",\n  \"path\": \"/path/to/file1.txt\",\n  \"data\": {\n    \"identical\": false,\n    \"differences\": [\n      {\n        \"line\": 5,\n        \"type\": \"modified\",\n        \"content\": \"- old content\\n+ new content\"\n      }\n    ],\n    \"totalDifferences\": 3,\n    \"file1\": {\n      \"path\": \"/path/to/file1.txt\",\n      \"lines\": 10,\n      \"size\": 1024\n    },\n    \"file2\": {\n      \"path\": \"/path/to/file2.txt\",\n      \"lines\": 12,\n      \"size\": 1156\n    },\n    \"options\": {\n      \"ignoreWhitespace\": true,\n      \"ignoreCase\": false\n    }\n  }\n}\n```\n\n#### `archive_files` - Create Archive\nCreate archive from files.\n\n**Parameters:**\n- `files` (required): Files to archive\n- `archivePath` (required): Archive file path\n- `format` (optional): Archive format - \"zip\", \"tar\", \"gzip\" (default: \"zip\")\n- `compressionLevel` (optional): Compression level (0-9, default: 6)\n- `includeHidden` (optional): Include hidden files (default: false)\n- `excludePatterns` (optional): Patterns to exclude\n\n**Example:**\n```json\n{\n  \"name\": \"archive_files\",\n  \"arguments\": {\n    \"files\": [\"/path/to/file1.txt\", \"/path/to/file2.txt\"],\n    \"archivePath\": \"/path/to/archive.zip\",\n    \"format\": \"zip\",\n    \"compressionLevel\": 6,\n    \"includeHidden\": false,\n    \"excludePatterns\": [\"*.tmp\"]\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"message\": \"Archive created successfully\",\n  \"path\": \"/path/to/archive.zip\",\n  \"data\": {\n    \"archivePath\": \"/path/to/archive.zip\",\n    \"format\": \"zip\",\n    \"compressionLevel\": 6,\n    \"size\": 2048,\n    \"filesCount\": 2,\n    \"humanReadable\": \"2.00 KB\"\n  }\n}\n```\n\n#### `extract_archive` - Extract Archive\nExtract archive to destination.\n\n**Parameters:**\n- `archivePath` (required): Archive file path\n- `destination` (required): Extraction destination\n\n**Example:**\n```json\n{\n  \"name\": \"extract_archive\",\n  \"arguments\": {\n    \"archivePath\": \"/path/to/archive.zip\",\n    \"destination\": \"/path/to/extract\"\n  }\n}\n```\n\n## Usage Examples\n\n### Basic File Operations\n\n```typescript\n// Read a file\nconst readResult = await mcpClient.callTool('read_file', {\n  path: '/path/to/file.txt',\n  encoding: 'utf8'\n});\n\n// Write a file\nconst writeResult = await mcpClient.callTool('write_file', {\n  path: '/path/to/newfile.txt',\n  content: 'Hello, World!',\n  createDirs: true\n});\n\n// Copy a file\nconst copyResult = await mcpClient.callTool('copy_file', {\n  source: '/path/to/source.txt',\n  destination: '/path/to/destination.txt',\n  overwrite: true\n});\n```\n\n### Directory Management\n\n```typescript\n// Create directory\nconst createDirResult = await mcpClient.callTool('create_directory', {\n  path: '/path/to/new/directory',\n  recursive: true\n});\n\n// List directory contents\nconst listResult = await mcpClient.callTool('list_directory', {\n  path: '/path/to/directory',\n  recursive: true,\n  includeHidden: false,\n  maxDepth: 3\n});\n\n// Find files\nconst findResult = await mcpClient.callTool('find_files', {\n  pattern: '*.js',\n  directory: '/path/to/code',\n  maxDepth: 2,\n  fileTypes: ['file']\n});\n```\n\n### Advanced Operations\n\n```typescript\n// Search in files\nconst searchResult = await mcpClient.callTool('search_in_files', {\n  pattern: 'function',\n  directory: '/path/to/code',\n  filePattern: '*.js',\n  caseSensitive: false,\n  wholeWord: true,\n  contextLines: 3\n});\n\n// Watch for changes\nconst watchResult = await mcpClient.callTool('watch_file', {\n  path: '/path/to/watch',\n  recursive: true,\n  ignoreInitial: true\n});\n\n// Compare files\nconst compareResult = await mcpClient.callTool('compare_files', {\n  file1: '/path/to/file1.txt',\n  file2: '/path/to/file2.txt',\n  ignoreWhitespace: true\n});\n\n// Create archive\nconst archiveResult = await mcpClient.callTool('archive_files', {\n  files: ['/path/to/file1.txt', '/path/to/file2.txt'],\n  archivePath: '/path/to/archive.zip',\n  format: 'zip',\n  compressionLevel: 6\n});\n```\n\n## Development\n\n### Project Structure\n\n```\nfilesystem-mcp-server/\n├── src/\n│   ├── index.ts              # Main entry point\n│   ├── server.ts             # MCP server implementation\n│   ├── file-operations.ts    # Core file operations\n│   ├── directory-operations.ts # Directory management\n│   ├── advanced-operations.ts # Advanced features\n│   └── types.ts              # Type definitions and schemas\n├── dist/                     # Compiled JavaScript output\n├── __tests__/               # Test files\n├── package.json             # Dependencies and scripts\n├── tsconfig.json            # TypeScript configuration\n├── jest.config.js           # Jest testing configuration\n└── README.md                # This documentation\n```\n\n### Development Commands\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run in development mode with hot reload\nnpm run dev\n\n# Run tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Run linting\nnpm run lint\n\n# Fix linting issues\nnpm run lint:fix\n\n# Clean build directory\nnpm run clean\n\n# Start production server\nnpm start\n```\n\n### Testing\n\nThe server includes comprehensive Jest tests:\n\n```bash\nnpm test\n```\n\n**Test Coverage:**\n- File operations (read, write, copy, move, delete)\n- Directory operations (create, list, find)\n- Advanced operations (search, watch, compare, archive)\n- Error handling and edge cases\n- Input validation and schema validation\n\n### Error Handling\n\nThe server includes comprehensive error handling:\n\n- **Input Validation**: All parameters validated with Zod schemas\n- **File System Errors**: Graceful handling of permission, not found, and access errors\n- **Resource Cleanup**: Automatic cleanup of watchers and resources\n- **Process Management**: Proper signal handling for graceful shutdown\n\n### Performance Considerations\n\n- **Streaming**: Large file operations use streaming for memory efficiency\n- **Batch Operations**: Multiple file operations optimized for performance\n- **Caching**: File information cached for repeated operations\n- **Resource Management**: Automatic cleanup prevents memory leaks\n\n## Security Considerations\n\n- **Path Validation**: All paths validated to prevent directory traversal attacks\n- **Permission Checks**: File operations respect system permissions\n- **Input Sanitization**: All inputs validated and sanitized\n- **Error Information**: Error messages don't expose sensitive information\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes and add tests\n4. Run the test suite: `npm test`\n5. Commit your changes: `git commit -m 'Add amazing feature'`\n6. Push to the branch: `git push origin feature/amazing-feature`\n7. Open a Pull Request\n\n## Support\n\nFor issues and questions:\n- **GitHub Issues**: [Open an issue](https://github.com/1999AZZAR/filesystem-mcp-server/issues)\n- **Documentation**: Check this README for comprehensive usage examples\n- **Examples**: See the examples section above for common use cases\n\n---\n\n**FileSystem MCP Server** - Comprehensive file system operations for the Model Context Protocol ecosystem.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1999azzar%2Ffilesystem-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F1999azzar%2Ffilesystem-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1999azzar%2Ffilesystem-mcp-server/lists"}