{"id":27999181,"url":"https://github.com/bsmi021/mcp-file-operations-server","last_synced_at":"2025-10-30T19:04:08.682Z","repository":{"id":281559006,"uuid":"910361941","full_name":"bsmi021/mcp-file-operations-server","owner":"bsmi021","description":"A Model Context Protocol (MCP) server that provides enhanced file operation capabilities with streaming, patching, and change tracking support.","archived":false,"fork":false,"pushed_at":"2025-07-11T10:12:38.000Z","size":211,"stargazers_count":17,"open_issues_count":2,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-29T20:14:13.656Z","etag":null,"topics":["claude","mcp","mcp-server","modelcontextprotocol"],"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/bsmi021.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}},"created_at":"2024-12-31T04:39:04.000Z","updated_at":"2025-09-26T12:37:09.000Z","dependencies_parsed_at":"2025-03-09T23:18:01.138Z","dependency_job_id":"5c2de470-2dde-4beb-860b-8f8ed453e784","html_url":"https://github.com/bsmi021/mcp-file-operations-server","commit_stats":null,"previous_names":["bsmi021/mcp-file-operations-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bsmi021/mcp-file-operations-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsmi021%2Fmcp-file-operations-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsmi021%2Fmcp-file-operations-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsmi021%2Fmcp-file-operations-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsmi021%2Fmcp-file-operations-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bsmi021","download_url":"https://codeload.github.com/bsmi021/mcp-file-operations-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsmi021%2Fmcp-file-operations-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002963,"owners_count":26083487,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["claude","mcp","mcp-server","modelcontextprotocol"],"created_at":"2025-05-08T22:56:52.181Z","updated_at":"2025-10-10T06:06:58.377Z","avatar_url":"https://github.com/bsmi021.png","language":"TypeScript","funding_links":[],"categories":["File Management","File Systems"],"sub_categories":["How to Submit"],"readme":"# File Operations MCP Server\n\n[![smithery badge](https://smithery.ai/badge/@bsmi021/mcp-file-operations-server)](https://smithery.ai/server/@bsmi021/mcp-file-operations-server)\n\nA Model Context Protocol (MCP) server that provides enhanced file operation capabilities with streaming, patching, and change tracking support.\n\n\u003ca href=\"https://glama.ai/mcp/servers/7b750si00d\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/7b750si00d/badge\" alt=\"File Operations Server MCP server\" /\u003e\n\u003c/a\u003e\n\n## Features\n\n- **Basic File Operations**: Copy, read, write, move, and delete files\n- **Directory Operations**: Create, remove, and copy directories\n- **File Watching**: Monitor files and directories for changes\n- **Change Tracking**: Track and query file operation history\n- **Streaming Support**: Handle large files efficiently with streaming\n- **HTTP Interface**: Streamable HTTP interface with Server-Sent Events (SSE)\n- **Resource Support**: Access files and directories through MCP resources\n- **Progress Reporting**: Real-time progress updates for long operations\n- **Rate Limiting**: Protection against excessive requests\n- **Enhanced Security**: Path validation and input sanitization\n- **Robust Error Handling**: Comprehensive error handling and reporting\n- **Type Safety**: Full TypeScript support with strict type checking\n- **Docker Support**: Containerized deployment with volume mounting\n\n## Installation\n\n### Installing via Smithery\n\nTo install File Operations Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@bsmi021/mcp-file-operations-server):\n\n```bash\nnpx -y @smithery/cli install @bsmi021/mcp-file-operations-server --client claude\n```\n\n### Manual Installation\n```bash\nnpm install\n```\n\n### Docker Installation\n\nSee [DOCKER.md](./DOCKER.md) for comprehensive Docker setup instructions including local drive mounting for Windows and Linux.\n\n**Quick Docker Start:**\n```bash\n# Stdio transport (for MCP clients)\ndocker run -it --rm -v \"$(pwd):/workspace\" ghcr.io/bsmi021/mcp-file-operations-server\n\n# HTTP transport (for web/remote access)\ndocker run -it --rm -p 3001:3001 -v \"$(pwd):/workspace\" -e MCP_TRANSPORT=http ghcr.io/bsmi021/mcp-file-operations-server\n```\n\n## Usage\n\n### Transport Modes\n\nThe server supports two transport modes:\n\n#### 1. Stdio Transport (Default)\nFor direct integration with MCP clients like Claude Desktop:\n\n```bash\nnpm start\n```\n\n#### 2. HTTP Transport with SSE (New in v1.5)\nFor remote connections and web applications:\n\n```bash\nnpm run start:http\n```\n\nThe HTTP server provides:\n- **SSE Endpoint**: `GET http://localhost:3001/sse` - Establishes streaming connection\n- **Messages Endpoint**: `POST http://localhost:3001/messages` - Receives client messages  \n- **Health Check**: `GET http://localhost:3001/health` - Server status\n- **Sessions**: `GET http://localhost:3001/sessions` - Active connection info\n\n### Starting the Server\n\n#### Development Mode\n\n```bash\n# Stdio transport with auto-reload\nnpm run dev\n\n# HTTP transport with auto-reload\nnpm run dev:http\n```\n\n#### Production Mode\n\n```bash\n# Stdio transport\nnpm start\n\n# HTTP transport\nnpm run start:http\n\n# Custom port for HTTP\nnpm run start:http -- --port 8080\n```\n\n### Available Tools\n\n#### Basic File Operations\n\n- `copy_file`: Copy a file to a new location\n- `read_file`: Read content from a file\n- `write_file`: Write content to a file\n- `move_file`: Move/rename a file\n- `delete_file`: Delete a file\n- `append_file`: Append content to a file\n\n#### Directory Operations\n\n- `make_directory`: Create a directory\n- `remove_directory`: Remove a directory\n- `copy_directory`: Copy a directory recursively (with progress reporting)\n\n#### Watch Operations\n\n- `watch_directory`: Start watching a directory for changes\n- `unwatch_directory`: Stop watching a directory\n\n#### Change Tracking\n\n- `get_changes`: Get the list of recorded changes\n- `clear_changes`: Clear all recorded changes\n\n### Available Resources\n\n#### Static Resources\n\n- `file:///recent-changes`: List of recent file system changes\n\n#### Resource Templates\n\n- `file://{path}`: Access file contents\n- `metadata://{path}`: Access file metadata\n- `directory://{path}`: List directory contents\n\n### Example Usage\n\n#### Using Stdio Transport (MCP Clients)\n\n```typescript\n// Copy a file\nawait fileOperations.copyFile({\n    source: 'source.txt',\n    destination: 'destination.txt',\n    overwrite: false\n});\n\n// Watch a directory\nawait fileOperations.watchDirectory({\n    path: './watched-dir',\n    recursive: true\n});\n\n// Access file contents through resource\nconst resource = await mcp.readResource('file:///path/to/file.txt');\nconsole.log(resource.contents[0].text);\n\n// Copy directory with progress tracking\nconst result = await fileOperations.copyDirectory({\n    source: './source-dir',\n    destination: './dest-dir',\n    overwrite: false\n});\n// Progress token in result can be used to track progress\nconsole.log(result.progressToken);\n```\n\n#### Using HTTP Transport (Web/Remote)\n\n**Connecting via JavaScript:**\n\n```javascript\n// Establish SSE connection\nconst eventSource = new EventSource('http://localhost:3001/sse');\nlet sessionId = null;\n\neventSource.onopen = function() {\n    console.log('Connected to MCP server');\n};\n\neventSource.onmessage = function(event) {\n    const message = JSON.parse(event.data);\n    \n    // Extract session ID from first message\n    if (!sessionId \u0026\u0026 message.sessionId) {\n        sessionId = message.sessionId;\n    }\n    \n    console.log('Received:', message);\n};\n\n// Send a message to the server\nasync function sendMessage(method, params) {\n    const message = {\n        jsonrpc: '2.0',\n        id: Date.now(),\n        method: method,\n        params: params\n    };\n    \n    const response = await fetch('http://localhost:3001/messages', {\n        method: 'POST',\n        headers: {\n            'Content-Type': 'application/json',\n            'X-Session-ID': sessionId\n        },\n        body: JSON.stringify(message)\n    });\n    \n    return response.json();\n}\n\n// Example: List tools\nsendMessage('tools/list', {});\n\n// Example: Read a file\nsendMessage('tools/call', {\n    name: 'read_file',\n    arguments: { path: '/workspace/example.txt' }\n});\n```\n\n**Using curl for testing:**\n\n```bash\n# Start SSE connection in background\ncurl -N http://localhost:3001/sse \u0026\n\n# Check server health\ncurl http://localhost:3001/health\n\n# List active sessions\ncurl http://localhost:3001/sessions\n```\n\n**Interactive Web Client:**\n\nA complete interactive example is available at [`examples/http-client.html`](./examples/http-client.html). Open this file in a web browser to test the HTTP interface with a user-friendly GUI.\n\n## What's New in v1.5\n\n### MCP SDK v1.5 Upgrade\n- **Streamable HTTP Interface**: New HTTP transport with Server-Sent Events (SSE)\n- **Enhanced API**: Upgraded to MCP SDK v1.5 with improved zod-based schemas\n- **Multiple Connections**: Support for simultaneous HTTP connections with session management\n- **Better Type Safety**: Improved TypeScript integration and error handling\n\n### Streaming Features\n- **Large File Support**: Efficient streaming for large file operations\n- **Real-time Progress**: Progress updates via SSE for long-running operations\n- **Session Management**: Multiple client connections with isolated sessions\n- **HTTP API**: RESTful endpoints alongside traditional MCP protocol\n\n## Docker Support\n\n### Quick Start with Docker\n\n```bash\n# Build the image\ndocker build -t mcp-file-operations-server .\n\n# Run with stdio (for MCP clients)\ndocker run -it --rm -v \"$(pwd):/workspace\" mcp-file-operations-server\n\n# Run with HTTP interface\ndocker run -it --rm -p 3001:3001 -v \"$(pwd):/workspace\" -e MCP_TRANSPORT=http mcp-file-operations-server\n```\n\n### Volume Mounting\n\n**Windows:**\n```cmd\ndocker run -it --rm -v \"C:\\MyProject:/workspace\" -p 3001:3001 -e MCP_TRANSPORT=http mcp-file-operations-server\n```\n\n**Linux/macOS:**\n```bash\ndocker run -it --rm -v \"/home/user/project:/workspace\" -p 3001:3001 -e MCP_TRANSPORT=http mcp-file-operations-server\n```\n\nFor comprehensive Docker setup instructions including local drive mounting for Windows and Linux, see [DOCKER.md](./DOCKER.md).\n\n## Rate Limits\n\nThe server implements rate limiting to prevent abuse:\n\n- **Tools**: 100 requests per minute\n- **Resources**: 200 requests per minute\n- **Watch Operations**: 20 operations per minute\n\nRate limit errors include a retry-after period in the error message.\n\n## Security Features\n\n### Path Validation\n\nAll file paths are validated to prevent directory traversal attacks:\n\n- No parent directory references (`../`)\n- Proper path normalization\n- Input sanitization\n\n### Resource Protection\n\n- Rate limiting on all operations\n- Proper error handling and logging\n- Input validation on all parameters\n- Safe resource cleanup\n\n## Progress Reporting\n\nLong-running operations like directory copying provide progress updates:\n\n```typescript\ninterface ProgressUpdate {\n    token: string | number;\n    message: string;\n    percentage: number;\n}\n```\n\nProgress can be tracked through the progress token returned in the operation result.\n\n## Development\n\n### Building\n\n```bash\nnpm run build\n```\n\n### Linting\n\n```bash\nnpm run lint\n```\n\n### Formatting\n\n```bash\nnpm run format\n```\n\n### Testing\n\n```bash\nnpm test\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |\n| `MCP_HTTP_PORT` | `3001` | Port for HTTP transport |\n\n### Transport Selection\n\n- **Stdio**: Best for MCP clients like Claude Desktop, direct integration\n- **HTTP**: Best for web applications, remote access, development/testing\n\nThe server can be configured through various settings:\n\n- **Rate Limiting**: Configure request limits and windows\n- **Progress Reporting**: Control update frequency and detail level\n- **Resource Access**: Configure resource permissions and limits\n- **Security Settings**: Configure path validation rules\n- **Change Tracking**: Set retention periods and storage options\n- **Watch Settings**: Configure debounce times and recursive watching\n\n## Error Handling\n\nThe server provides detailed error information through the `FileOperationError` class and MCP error codes:\n\n### Standard MCP Error Codes\n\n- `InvalidRequest`: Invalid parameters or request format\n- `MethodNotFound`: Unknown tool or resource requested\n- `InvalidParams`: Invalid parameters (e.g., path validation failure)\n- `InternalError`: Server-side errors\n\n### Custom Error Types\n\n- File operation failures\n- Rate limit exceeded\n- Path validation errors\n- Resource access errors\n\nEach error includes:\n\n- Specific error code\n- Detailed error message\n- Relevant metadata (file paths, limits, etc.)\n- Stack traces in development mode\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbsmi021%2Fmcp-file-operations-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbsmi021%2Fmcp-file-operations-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbsmi021%2Fmcp-file-operations-server/lists"}