file-organizer-mcp 3.0.0 → 3.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/ARCHITECTURE.md +0 -1
  2. package/CHANGELOG.md +33 -4
  3. package/CONTRIBUTING.md +4 -3
  4. package/MIGRATION.md +1 -1
  5. package/README.md +218 -51
  6. package/dist/config.d.ts +64 -0
  7. package/dist/config.d.ts.map +1 -1
  8. package/dist/config.js +90 -17
  9. package/dist/config.js.map +1 -1
  10. package/dist/constants.js +1 -1
  11. package/dist/constants.js.map +1 -1
  12. package/dist/index.d.ts +6 -0
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +84 -0
  15. package/dist/index.js.map +1 -1
  16. package/dist/schemas/rename.schemas.d.ts +95 -0
  17. package/dist/schemas/rename.schemas.d.ts.map +1 -0
  18. package/dist/schemas/rename.schemas.js +39 -0
  19. package/dist/schemas/rename.schemas.js.map +1 -0
  20. package/dist/server.d.ts.map +1 -1
  21. package/dist/server.js +87 -28
  22. package/dist/server.js.map +1 -1
  23. package/dist/services/auto-organize.service.d.ts +88 -0
  24. package/dist/services/auto-organize.service.d.ts.map +1 -0
  25. package/dist/services/auto-organize.service.js +269 -0
  26. package/dist/services/auto-organize.service.js.map +1 -0
  27. package/dist/services/categorizer.service.d.ts.map +1 -1
  28. package/dist/services/categorizer.service.js +27 -1
  29. package/dist/services/categorizer.service.js.map +1 -1
  30. package/dist/services/index.d.ts +1 -0
  31. package/dist/services/index.d.ts.map +1 -1
  32. package/dist/services/index.js +1 -0
  33. package/dist/services/index.js.map +1 -1
  34. package/dist/services/metadata.service.d.ts +36 -0
  35. package/dist/services/metadata.service.d.ts.map +1 -0
  36. package/dist/services/metadata.service.js +212 -0
  37. package/dist/services/metadata.service.js.map +1 -0
  38. package/dist/services/organizer.service.d.ts +3 -1
  39. package/dist/services/organizer.service.d.ts.map +1 -1
  40. package/dist/services/organizer.service.js +28 -5
  41. package/dist/services/organizer.service.js.map +1 -1
  42. package/dist/services/path-validator.service.d.ts +1 -0
  43. package/dist/services/path-validator.service.d.ts.map +1 -1
  44. package/dist/services/path-validator.service.js +42 -6
  45. package/dist/services/path-validator.service.js.map +1 -1
  46. package/dist/services/renaming.service.d.ts +39 -0
  47. package/dist/services/renaming.service.d.ts.map +1 -0
  48. package/dist/services/renaming.service.js +296 -0
  49. package/dist/services/renaming.service.js.map +1 -0
  50. package/dist/services/rollback.service.js +2 -2
  51. package/dist/services/rollback.service.js.map +1 -1
  52. package/dist/tools/file-organization.d.ts +5 -0
  53. package/dist/tools/file-organization.d.ts.map +1 -1
  54. package/dist/tools/file-organization.js +23 -2
  55. package/dist/tools/file-organization.js.map +1 -1
  56. package/dist/tools/file-renaming.d.ts +65 -0
  57. package/dist/tools/file-renaming.d.ts.map +1 -0
  58. package/dist/tools/file-renaming.js +148 -0
  59. package/dist/tools/file-renaming.js.map +1 -0
  60. package/dist/tools/index.d.ts +4 -0
  61. package/dist/tools/index.d.ts.map +1 -1
  62. package/dist/tools/index.js +12 -0
  63. package/dist/tools/index.js.map +1 -1
  64. package/dist/tools/metadata-inspection.d.ts +41 -0
  65. package/dist/tools/metadata-inspection.d.ts.map +1 -0
  66. package/dist/tools/metadata-inspection.js +220 -0
  67. package/dist/tools/metadata-inspection.js.map +1 -0
  68. package/dist/tools/organization-preview.d.ts +5 -0
  69. package/dist/tools/organization-preview.d.ts.map +1 -1
  70. package/dist/tools/organization-preview.js +23 -3
  71. package/dist/tools/organization-preview.js.map +1 -1
  72. package/dist/tools/watch.tool.d.ts +48 -0
  73. package/dist/tools/watch.tool.d.ts.map +1 -0
  74. package/dist/tools/watch.tool.js +329 -0
  75. package/dist/tools/watch.tool.js.map +1 -0
  76. package/dist/tui/index.d.ts +9 -0
  77. package/dist/tui/index.d.ts.map +1 -0
  78. package/dist/tui/index.js +17 -0
  79. package/dist/tui/index.js.map +1 -0
  80. package/dist/tui/screens.d.ts +2 -0
  81. package/dist/tui/screens.d.ts.map +1 -0
  82. package/dist/tui/screens.js +3 -0
  83. package/dist/tui/screens.js.map +1 -0
  84. package/dist/tui/setup-wizard.d.ts +5 -0
  85. package/dist/tui/setup-wizard.d.ts.map +1 -0
  86. package/dist/tui/setup-wizard.js +229 -0
  87. package/dist/tui/setup-wizard.js.map +1 -0
  88. package/dist/types.d.ts +1 -1
  89. package/dist/types.d.ts.map +1 -1
  90. package/package.json +16 -4
package/ARCHITECTURE.md CHANGED
@@ -580,4 +580,3 @@ type Args = z.infer<typeof ArgsSchema>;
580
580
 
581
581
  **Last Updated:** February 3, 2026
582
582
  **Version:** 3.0.0
583
-
package/CHANGELOG.md CHANGED
@@ -1,5 +1,35 @@
1
1
  # Changelog
2
2
 
3
+ ## [3.1.1] - 2026-02-06
4
+
5
+ ### ✨ New Features
6
+ - **Interactive Setup Wizard**: New TUI-based setup (`npx file-organizer-mcp --setup`) for easy configuration of folders, conflict strategies, and Claude Desktop integration.
7
+ - **Smart Metadata Organization**:
8
+ - Organization by Year/Month for images and videos.
9
+ - Organization by Artist/Album for audio files.
10
+ - New tool `file_organizer_inspect_metadata` for safe metadata extraction.
11
+ - **Smart Scheduling & Watch Mode**:
12
+ - New tools: `file_organizer_watch_directory`, `file_organizer_unwatch_directory`, `file_organizer_list_watches`.
13
+ - Cron-based scheduling for automatic organization (e.g., `"0 10 * * *"` for daily at 10am).
14
+ - Per-directory configuration with independent schedules.
15
+ - `min_file_age_minutes` - Skip files newer than X minutes (prevents organizing in-progress downloads).
16
+ - `max_files_per_run` - Limit files processed per scheduled run.
17
+ - Hot-reload configuration without server restart.
18
+ - **Batch Renaming**: New powerful `file_organizer_batch_rename` tool.
19
+
20
+ ### 🛡️ Improvements
21
+ - **Conflict Strategy**: Configurable default conflict resolution (`rename`/`skip`/`overwrite`) via config.
22
+ - **Security Check**: Enforced stricter validation for symlink security with explicit `lstat` checks.
23
+ - **Config Management**: Deep merge updates preserve existing settings when adding new configuration.
24
+ - **Free Models**: Updated default configuration to prioritize free models.
25
+
26
+ ### 🐛 Fixed
27
+ - Resolved JSON configuration errors.
28
+ - Fixed Cloud Authentication issues.
29
+ - Fixed server disconnection stability issues.
30
+
31
+ ---
32
+
3
33
  ## [3.0.0] - 2026-02-02
4
34
 
5
35
  ### 🚀 Major: Full TypeScript Migration
@@ -8,7 +38,7 @@ Complete rewrite from monolithic JavaScript to modular TypeScript architecture.
8
38
 
9
39
  ### ✨ Added
10
40
 
11
- **Architecture**
41
+ #### Architecture
12
42
  - New `src/` directory structure with layered architecture
13
43
  - TypeScript strict mode with full type safety
14
44
  - ESLint + Prettier configuration for code quality
@@ -43,7 +73,7 @@ Complete rewrite from monolithic JavaScript to modular TypeScript architecture.
43
73
  - Runtime validation with descriptive error messages
44
74
  - Type inference from schemas
45
75
 
46
- **Testing**
76
+ #### Testing
47
77
  - Comprehensive unit tests for all services
48
78
  - Integration tests for complete workflows
49
79
  - Performance benchmarks
@@ -76,7 +106,6 @@ Complete rewrite from monolithic JavaScript to modular TypeScript architecture.
76
106
  - `eslint`, `prettier`, `rimraf`
77
107
  - `jest` for testing
78
108
 
79
-
80
109
  ---
81
110
 
82
111
  ## [3.0.0-beta.1] - 2026-02-02
@@ -117,4 +146,4 @@ If you were using `../` paths (which was a security bug), those now correctly fa
117
146
  ---
118
147
 
119
148
  ## [2.1.0] - 2026-02-01
120
- (Previous version with path traversal vulnerability - UPGRADE IMMEDIATELY)
149
+ (Previous version with path traversal vulnerability - UPGRADE IMMEDIATELY)
package/CONTRIBUTING.md CHANGED
@@ -8,9 +8,9 @@ This project prioritizes security. All contributions must maintain or improve th
8
8
 
9
9
  ### Reporting Security Vulnerabilities
10
10
 
11
- **⚠️ DO NOT open public issues for security vulnerabilities**
11
+ > **⚠️ DO NOT open public issues for security vulnerabilities**
12
12
 
13
- Instead, email security concerns to: **technocratix902@gmail.com**
13
+ Instead, email security concerns to: **<technocratix902@gmail.com>**
14
14
 
15
15
  We will respond within 48 hours and work with you to address the issue.
16
16
 
@@ -179,6 +179,7 @@ throw new Error(`Invalid path: ${internalPath}`);
179
179
  ### 1. Create an Issue
180
180
 
181
181
  Before starting work, create an issue describing:
182
+
182
183
  - The problem or feature request
183
184
  - Proposed solution (if applicable)
184
185
  - Any breaking changes
@@ -299,7 +300,7 @@ Before submitting your PR, ensure:
299
300
 
300
301
  - **Questions**: Open a discussion on GitHub
301
302
  - **Issues**: Check existing issues or create new one
302
- - **Email**: technocratix902@gmail.com
303
+ - **Email**: <technocratix902@gmail.com>
303
304
 
304
305
  ## 🙏 Recognition
305
306
 
package/MIGRATION.md CHANGED
@@ -344,7 +344,7 @@ When reporting issues, include:
344
344
  - **Advanced duplicate detection** - Fuzzy matching, content similarity
345
345
  - **Performance mode** - Skip security checks for trusted paths
346
346
 
347
- ## 🎉 Migration Complete!
347
+ ## 🎉 Migration Complete
348
348
 
349
349
  If you've followed all steps, you're now running File Organizer MCP v3.0 with enhanced security and reliability.
350
350
 
package/README.md CHANGED
@@ -1,26 +1,25 @@
1
- # File Organizer MCP Server 🗂️
1
+ # <a id="file-organizer-mcp-server"></a>File Organizer MCP Server 🗂️
2
2
 
3
- **Version:** 3.0.0 | **MCP Protocol:** 2024-11-05 | **Node:** ≥18.0.0
3
+ **Version:** 3.1.1 | **MCP Protocol:** 2024-11-05 | **Node:** ≥18.0.0
4
4
 
5
- [Quick Start](#-quick-start) • [Features](#-features) • [Tools](#-tools-reference) • [Examples](#-example-workflows) • [API](API.md) • [Security](#-security) • [Architecture](ARCHITECTURE.md)
5
+ [Quick Start](#quick-start) • [Features](#features) • [Tools](#tools-reference) • [Examples](#example-workflows) • [API](API.md) • [Security](#security-configuration) • [Architecture](ARCHITECTURE.md)
6
6
 
7
7
  ---
8
8
 
9
- [![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/servers/io.github.kridaydave/file-organizer)
10
- [![npm version](https://img.shields.io/badge/npm-v3.0.0-blue.svg)](https://www.npmjs.com/package/file-organizer-mcp)
9
+ [![npm version](https://img.shields.io/badge/npm-v3.1.0-blue.svg)](https://www.npmjs.com/package/file-organizer-mcp)
11
10
  [![npm downloads](https://img.shields.io/npm/dm/file-organizer-mcp.svg)](https://www.npmjs.com/package/file-organizer-mcp)
12
11
  [![Security](https://img.shields.io/badge/security-hardened-green.svg)](https://github.com/kridaydave/File-Organizer-MCP)
13
12
  [![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
14
13
  [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
15
- [![Tests](https://img.shields.io/badge/tests-133%20passing-success.svg)](tests/)
14
+ [![Tests](https://img.shields.io/badge/tests-209%20passing-success.svg)](tests/)
16
15
 
17
- **A powerful, security-hardened Model Context Protocol (MCP) server for intelligent file organization with Claude**
16
+ > **A powerful, security-hardened Model Context Protocol (MCP) server for intelligent file organization with Claude**
18
17
 
19
18
  🎯 [Install from MCP Registry](https://registry.modelcontextprotocol.io/servers/io.github.kridaydave/file-organizer) • 📦 [View on NPM](https://www.npmjs.com/package/file-organizer-mcp) • 🐛 [Report Issues](https://github.com/kridaydave/File-Organizer-MCP/issues)
20
19
 
21
20
  ---
22
21
 
23
- ## 🚀 Quick Start
22
+ ## <a id="quick-start"></a>Quick Start 🚀
24
23
 
25
24
  ### Installation
26
25
 
@@ -30,6 +29,9 @@ npm install -g file-organizer-mcp
30
29
 
31
30
  # Option 2: Use npx (no installation)
32
31
  npx file-organizer-mcp
32
+
33
+ # Option 3: Run the interactive setup wizard (Recommended)
34
+ npx file-organizer-mcp --setup
33
35
  ```
34
36
 
35
37
  ### Claude Desktop Configuration
@@ -55,28 +57,44 @@ Add to `claude_desktop_config.json`:
55
57
 
56
58
  ### First Steps
57
59
 
58
- 1. **Restart Claude Desktop**
59
- 2. Try: `"Scan my Downloads folder"`
60
- 3. Then: `"Show me the largest files"`
61
- 4. Finally: `"Organize my files — preview first"`
60
+ 1. **Run the Setup Wizard (Recommended)**
61
+ ```bash
62
+ npx file-organizer-mcp --setup
63
+ ```
64
+ This interactive wizard helps you:
65
+ - Select folders to organize
66
+ - Set your preferred conflict strategy
67
+ - Configure auto-organize schedules
68
+ - Generate Claude Desktop config
69
+
70
+ 2. **Restart Claude Desktop**
71
+ 3. Try: `"Scan my Downloads folder"`
72
+ 4. Then: `"Show me the largest files"`
73
+ 5. Finally: `"Organize my files — preview first"`
62
74
 
63
75
  ---
64
76
 
65
- ## 🎯 Features
77
+ ## <a id="features"></a>Features 🎯
66
78
 
67
79
  ### Core Functionality
68
80
 
69
81
  * **🤖 Auto-categorization** - Intelligently organizes files into 12+ categories
82
+ * **📅 Smart Scheduling** - Cron-based automatic organization with per-directory configuration
70
83
  * **🔍 Duplicate Detection** - Finds duplicate files using SHA-256 content hashing
71
- * **🛡️ Smart Conflict Resolution** - Handles filename conflicts automatically (rename/skip/overwrite)
84
+ * **🏷️ Smart Metadata** - Extracts EXIF/ID3 tags for content-aware organization
85
+ * **✏️ Batch Renaming** - Flexible renaming with patterns, regex, and case conversion
86
+ * **🛡️ Smart Conflict Resolution** - Handles filename conflicts (rename/skip/overwrite)
72
87
  * **👁️ Dry Run Mode** - Preview changes before executing
88
+ * **👀 File Watching** - Watch directories and auto-organize on schedule
89
+ * **⏱️ Age-Based Filtering** - Skip files newer than X minutes (prevents organizing in-progress downloads)
73
90
  * **📊 Comprehensive Scanning** - Detailed directory analysis with statistics
74
91
  * **📈 Space Analysis** - Quickly identify space-consuming files
75
92
  * **⏮️ Rollback Support** - Undo file organization operations
76
93
  * **⚛️ Safe Atomic Moves** - Uses `COPYFILE_EXCL` to prevent race conditions during file moves
77
94
  * **💾 Automatic Backups** - Safely backs up files before overwriting to `.file-organizer-backups`
78
- * **📝 Structured Logging** - JSON-formatted logs with configurable log levels (debug/info/warn/error)
79
- * **💻 Multi-Platform Support** - Native support for Windows, macOS, and Linux (Ubuntu, Debian, etc.)
95
+ * **📝 Structured Logging** - JSON-formatted logs with configurable log levels
96
+ * **📜 Audit Trail** - Complete logging of all operations for transparency
97
+ * **💻 Multi-Platform Support** - Native support for Windows, macOS, and Linux
80
98
 
81
99
  ### Security Features
82
100
 
@@ -105,27 +123,31 @@ This server implements a multi-layered security architecture designed to operate
105
123
  - **Race Condition Mitigation**: Uses atomic copy-then-delete strategy to prevent data loss if a file is modified during a move operation.
106
124
  - **Safe Overwrites**: When `conflict_strategy: 'overwrite'` is used, the existing file is moved to a timestamped backup folder before replacement.
107
125
 
108
- ### What's New in v3
126
+ ### 🚀 Features Overview
127
+
128
+ ### ⚙️ Interactive Setup Wizard
129
+ Run `npx file-organizer-mcp --setup` for guided configuration:
130
+ - **📁 Folder Selection** - Interactively choose folders to manage
131
+ - **⚡ Conflict Handling** - Set default rename/skip/overwrite strategy
132
+ - **📅 Schedule Setup** - Configure automatic organization schedules
133
+ - **🤖 Claude Integration** - Auto-generates `claude_desktop_config.json`
109
134
 
110
- **Architecture:**
111
- * **TypeScript Migration** - Complete rewrite from JavaScript to TypeScript with strict type safety
112
- * **Modular Design** - Layered architecture with Services, Tools, Utils, and Schemas layers
113
- * **Zod Validation** - Runtime input validation with descriptive error messages
135
+ ### What's New in v3.1.0
114
136
 
115
- **Security:**
116
- * **Secure by Default** - Whitelist-based authorization for directory access
117
- * **System Protection** - Critical system folders are strictly blocked
118
- * **Platform Awareness** - Automatically detects safe folders for Windows, Mac, and Linux
119
- * **8-Layer Path Validation** - Comprehensive validation pipeline preventing path traversal attacks
137
+ **New Features:**
138
+ * **🧙 Interactive Setup Wizard** - Run `npx file-organizer-mcp --setup` for guided configuration
139
+ * **📅 Smart Scheduling** - Cron-based watch mode with `file_organizer_watch_directory`
140
+ * **⏱️ Age Filtering** - Skip recently modified files during auto-organization
141
+ * **🎵 Smart Metadata** - Organize images by Year/Month and audio by Artist/Album
142
+ * **🏷️ Batch Renaming** - Bulk renaming with patterns, regex, and numbering
143
+ * **⚙️ Conflict Strategy** - Configurable default conflict resolution
144
+ * **🛡️ Enhanced Security** - Improved symlink detection and path validation
120
145
 
121
- **Breaking changes:**
122
- * Access is now denied for non-whitelisted directories by default.
123
- * You must add custom paths to `config.json` to access them.
124
- * See [MIGRATION.md](MIGRATION.md) for the upgrade guide.
146
+ See [CHANGELOG.md](CHANGELOG.md) for full details.
125
147
 
126
148
  ---
127
149
 
128
- ## 🛠️ Tools Reference
150
+ ## <a id="tools-reference"></a>Tools Reference 🛠️
129
151
 
130
152
  ### Core Tools
131
153
 
@@ -259,7 +281,7 @@ Automatically organize files into categorized folders.
259
281
 
260
282
  **Parameters:**
261
283
  - `directory` (string, required) - Full path to directory
262
- - `dry_run` (boolean, optional) - Preview without moving (default: false)
284
+ - `dry_run` (boolean, optional) - Preview without moving (default: true)
263
285
  - `conflict_strategy` ('rename'|'skip'|'overwrite'|'overwrite_if_newer', optional) - How to handle conflicts
264
286
  - `response_format` ('json'|'markdown', optional) - Output format
265
287
 
@@ -296,6 +318,92 @@ Reverse file moves and renames from a previous organization.
296
318
 
297
319
  ---
298
320
 
321
+ #### `file_organizer_batch_rename`
322
+
323
+ Batch rename files using pattern matching, case conversion, or sequence numbering.
324
+
325
+ **Parameters:**
326
+ - `directory` (string, optional) - Directory to scan (either this or `files` required)
327
+ - `files` (array, optional) - Specific files to rename
328
+ - `rules` (array, required) - Renaming rules:
329
+ - `type`: 'find_replace' | 'case' | 'add_text' | 'numbering'
330
+ - *...plus rule-specific options (replace, with, conversion, text, position, etc.)*
331
+ - `dry_run` (boolean, optional) - Preview only (default: true)
332
+
333
+ **Annotations:** ⚠️ Destructive (if dry_run=false) • 🔍 Dry-run
334
+
335
+ **Example:**
336
+ ```typescript
337
+ file_organizer_batch_rename({
338
+ directory: "/Docs",
339
+ rules: [
340
+ { type: "find_replace", find: "IMG", replace: "Photo" },
341
+ { type: "case", conversion: "lowercase" }
342
+ ],
343
+ dry_run: true
344
+ })
345
+ ```
346
+
347
+ ---
348
+
349
+ ### Watch & Schedule Tools
350
+
351
+ #### `file_organizer_watch_directory`
352
+
353
+ Add a directory to the automatic organization watch list with cron-based scheduling.
354
+ Files will be automatically organized based on the schedule you set.
355
+
356
+ **Parameters:**
357
+ - `directory` (string, required) - Full path to the directory to watch
358
+ - `schedule` (string, required) - Cron expression (e.g., `"0 10 * * *"` for daily at 10am)
359
+ - `auto_organize` (boolean, optional) - Enable auto-organization (default: true)
360
+ - `min_file_age_minutes` (number, optional) - Only organize files older than X minutes
361
+ - `max_files_per_run` (number, optional) - Maximum files to process per run
362
+ - `response_format` ('json'|'markdown', optional) - Output format
363
+
364
+ **Cron Expression Examples:**
365
+ | Expression | Schedule |
366
+ |------------|----------|
367
+ | `0 10 * * *` | Daily at 10:00 AM |
368
+ | `*/30 * * * *` | Every 30 minutes |
369
+ | `0 */6 * * *` | Every 6 hours |
370
+ | `0 9 * * 1` | Every Monday at 9:00 AM |
371
+ | `0 0 * * 0` | Weekly on Sunday at midnight |
372
+
373
+ **Example:**
374
+ ```typescript
375
+ // Watch Downloads folder - organize daily at 9am, files must be 5+ minutes old
376
+ file_organizer_watch_directory({
377
+ directory: "/Users/john/Downloads",
378
+ schedule: "0 9 * * *",
379
+ min_file_age_minutes: 5,
380
+ max_files_per_run: 100
381
+ })
382
+ ```
383
+
384
+ ---
385
+
386
+ #### `file_organizer_unwatch_directory`
387
+
388
+ Remove a directory from the watch list.
389
+
390
+ **Parameters:**
391
+ - `directory` (string, required) - Full path to remove from watch list
392
+ - `response_format` ('json'|'markdown', optional) - Output format
393
+
394
+ ---
395
+
396
+ #### `file_organizer_list_watches`
397
+
398
+ List all directories currently being watched with their schedules.
399
+
400
+ **Parameters:**
401
+ - `response_format` ('json'|'markdown', optional) - Output format
402
+
403
+ **Returns:** List of watched directories with schedules and rules
404
+
405
+ ---
406
+
299
407
  ### Utility Tools
300
408
 
301
409
  #### `file_organizer_get_categories`
@@ -345,7 +453,7 @@ Permanently delete specified duplicate files. **This operation is destructive an
345
453
 
346
454
  ---
347
455
 
348
- ## 📁 File Categories
456
+ ## File Categories
349
457
 
350
458
  Files are automatically sorted into these categories:
351
459
 
@@ -353,13 +461,16 @@ Files are automatically sorted into these categories:
353
461
  | --- | --- |
354
462
  | **Executables** | `.exe`, `.msi`, `.bat`, `.cmd`, `.sh` |
355
463
  | **Videos** | `.mp4`, `.avi`, `.mkv`, `.mov`, `.wmv`, `.flv`, `.webm`, `.m4v` |
356
- | **Documents** | `.pdf`, `.doc`, `.docx`, `.txt`, `.rtf`, `.odt` |
464
+ | **Documents** | `.pdf`, `.doc`, `.docx`, `.txt`, `.rtf`, `.odt`, `.md`, `.tex` |
357
465
  | **Presentations** | `.ppt`, `.pptx`, `.odp`, `.key` |
358
466
  | **Spreadsheets** | `.xls`, `.xlsx`, `.csv`, `.ods` |
359
467
  | **Images** | `.jpg`, `.jpeg`, `.png`, `.gif`, `.bmp`, `.svg`, `.ico`, `.webp` |
360
468
  | **Audio** | `.mp3`, `.wav`, `.flac`, `.aac`, `.ogg`, `.wma`, `.m4a` |
361
469
  | **Archives** | `.zip`, `.rar`, `.7z`, `.tar`, `.gz`, `.bz2`, `.xz` |
362
470
  | **Code** | `.py`, `.js`, `.ts`, `.java`, `.cpp`, `.c`, `.html`, `.css`, `.php`, `.rb`, `.go`, `.json` |
471
+ | **Tests** | `*test*`, `*spec*`, `.test.ts`, `.spec.ts` |
472
+ | **Logs** | `*debug*`, `*.log` |
473
+ | **Scripts** | `*script*`, `.sh`, `.bat` |
363
474
  | **Installers** | `.dmg`, `.pkg`, `.deb`, `.rpm`, `.apk` |
364
475
  | **Ebooks** | `.epub`, `.mobi`, `.azw`, `.azw3` |
365
476
  | **Fonts** | `.ttf`, `.otf`, `.woff`, `.woff2` |
@@ -367,7 +478,7 @@ Files are automatically sorted into these categories:
367
478
 
368
479
  ---
369
480
 
370
- ## 💡 Example Workflows
481
+ ## <a id="example-workflows"></a>Example Workflows 💡
371
482
 
372
483
  ### Workflow 1: Intelligent Downloads Cleanup
373
484
 
@@ -396,7 +507,7 @@ User: "Claude, organize my project folder at ~/myproject"
396
507
  Claude:
397
508
  1. Scans the project → 423 files across multiple subdirectories
398
509
  2. Identifies file types → Code (289), Assets (87), Docs (47)
399
- 3. Suggests organization → Preserves src/ structure, organizes root files
510
+ 3. Suggestions organization → Preserves src/ structure, organizes root files
400
511
  4. Previews changes → Shows (47) items to organize
401
512
  5. Executes → Moves config files, readmes, screenshots to proper folders
402
513
 
@@ -441,9 +552,39 @@ Result: Clear visibility into space usage with actionable insights
441
552
 
442
553
  ---
443
554
 
444
- ## 🔐 Security Configuration
555
+ ### Workflow 5: Set Up Automatic Organization
445
556
 
446
- **Security Score: 10/10 🌟**
557
+ ```
558
+ User: "Claude, automatically organize my Downloads folder every day at 9am"
559
+
560
+ Claude:
561
+ 1. Sets up watch directory →
562
+ file_organizer_watch_directory({
563
+ directory: "/Users/john/Downloads",
564
+ schedule: "0 9 * * *",
565
+ min_file_age_minutes: 5
566
+ })
567
+ 2. Confirms setup → "Downloads folder will be organized daily at 9:00 AM"
568
+ 3. Shows current watches → Lists all watched directories
569
+
570
+ User: "Also watch my Desktop folder every hour"
571
+
572
+ Claude:
573
+ 4. Adds second watch →
574
+ file_organizer_watch_directory({
575
+ directory: "/Users/john/Desktop",
576
+ schedule: "0 * * * *",
577
+ max_files_per_run: 50
578
+ })
579
+
580
+ Result: Automatic background organization with smart scheduling
581
+ ```
582
+
583
+ ---
584
+
585
+ ## <a id="security-configuration"></a>Security Configuration 🔐
586
+
587
+ ### Security Score: 10/10 🌟
447
588
 
448
589
  The server uses a **Secure by Default** approach. Access is restricted to a specific whitelist of user directories. All system directories are blacklisted.
449
590
 
@@ -470,7 +611,7 @@ To prevent accidents, the following are **always blocked**, even if added to con
470
611
 
471
612
  ### ⚙️ Custom Configuration
472
613
 
473
- You can allow access to additional folders by editing the user configuration file.
614
+ You can customize behavior by editing the user configuration file.
474
615
 
475
616
  **Config Location:**
476
617
  * **Windows:** `%APPDATA%\file-organizer-mcp\config.json`
@@ -481,21 +622,47 @@ You can allow access to additional folders by editing the user configuration fil
481
622
  1. Open `config.json`
482
623
  2. Add paths to `customAllowedDirectories`:
483
624
 
625
+ ```json
626
+ {
627
+ "customAllowedDirectories": [
628
+ "C:\\Users\\Name\\My Special Folder",
629
+ "D:\\Backups"
630
+ ]
631
+ }
632
+ ```
633
+ > 💡 **Tip:** You can copy a folder path directly from your file explorer's address bar and paste it into `customAllowedDirectories`.
634
+
635
+ 3. Restart Claude Desktop.
636
+
637
+ ### Conflict Strategy
638
+
639
+ Set your preferred default conflict resolution strategy:
640
+
484
641
  ```json
485
642
  {
486
- "customAllowedDirectories": [
487
- "C:\\Users\\Name\\My Special Folder",
488
- "D:\\Backups"
489
- ],
490
- "settings": {
491
- "maxScanDepth": 10,
492
- "logAccess": true
643
+ "conflictStrategy": "rename"
644
+ }
645
+ ```
646
+
647
+ Available strategies:
648
+ - `"rename"` (default) - Renames new file (e.g., `file (1).txt`)
649
+ - `"skip"` - Keeps existing file, skips new one
650
+ - `"overwrite"` - Replaces existing file (creates backup first)
651
+
652
+ ### Auto-Organize Schedule (Legacy)
653
+
654
+ Simple schedule configuration (for basic hourly/daily/weekly):
655
+
656
+ ```json
657
+ {
658
+ "autoOrganize": {
659
+ "enabled": true,
660
+ "schedule": "daily"
493
661
  }
494
662
  }
495
663
  ```
496
- > 💡 **Tip:** You can copy a folder path directly from your file explorer's address bar and paste it into `customAllowedDirectories`.
497
664
 
498
- 3. Restart Claude Desktop.
665
+ For advanced cron-based scheduling, use the `file_organizer_watch_directory` tool.
499
666
 
500
667
  ### Security Defenses
501
668
 
@@ -599,8 +766,8 @@ MIT License - see [LICENSE](LICENSE) file for details
599
766
 
600
767
  ---
601
768
 
602
- **Happy Organizing! 🎯**
769
+ ### Happy Organizing! 🎯
603
770
 
604
- *Built with ❤️ for the MCP community*
771
+ > *Built with ❤️ for the MCP community*
605
772
 
606
- [⬆ Back to Top](#file-organizer-mcp-server-)
773
+ [⬆ Back to Top](#file-organizer-mcp-server)
package/dist/config.d.ts CHANGED
@@ -17,6 +17,70 @@ export declare const CONFIG: {
17
17
  alwaysBlocked: RegExp[];
18
18
  };
19
19
  };
20
+ /**
21
+ * User configuration structure
22
+ */
23
+ export interface UserConfig {
24
+ /** Custom directories allowed for file operations */
25
+ customAllowedDirectories?: string[];
26
+ /** Conflict resolution strategy */
27
+ conflictStrategy?: 'rename' | 'skip' | 'overwrite';
28
+ /** Auto-organize schedule settings */
29
+ autoOrganize?: {
30
+ enabled: boolean;
31
+ schedule?: 'hourly' | 'daily' | 'weekly';
32
+ };
33
+ /** Security settings */
34
+ settings?: {
35
+ maxScanDepth?: number;
36
+ logAccess?: boolean;
37
+ enablePathValidation?: boolean;
38
+ allowCustomDirectories?: boolean;
39
+ };
40
+ /** Organization rules */
41
+ rules?: Array<{
42
+ pattern: string;
43
+ destination: string;
44
+ overwrite?: boolean;
45
+ }>;
46
+ /** Watch list for smart scheduling */
47
+ watchList?: WatchConfig[];
48
+ }
49
+ /**
50
+ * Watch configuration for per-directory scheduling
51
+ */
52
+ export interface WatchConfig {
53
+ /** Directory path to watch */
54
+ directory: string;
55
+ /** Cron expression for scheduling (e.g., "0 9 * * *" for 9am daily) */
56
+ schedule: string;
57
+ /** Organization rules for this watch */
58
+ rules: {
59
+ /** Enable auto-organization */
60
+ auto_organize: boolean;
61
+ /** Minimum file age in minutes before organizing (prevents organizing files being written) */
62
+ min_file_age_minutes?: number;
63
+ /** Maximum files to process per run (0 or undefined = unlimited) */
64
+ max_files_per_run?: number;
65
+ };
66
+ }
67
+ /**
68
+ * Load custom allowed directories from user config file
69
+ */
70
+ export declare function loadUserConfig(): UserConfig;
71
+ /**
72
+ * Update user config with deep merge (preserves existing settings)
73
+ * @deprecated Use updateUserConfig instead
74
+ */
75
+ export declare function saveConfig(config: Partial<UserConfig>): void;
76
+ /**
77
+ * Update user config with deep merge (preserves existing settings)
78
+ */
79
+ export declare function updateUserConfig(updates: Partial<UserConfig>): void;
80
+ /**
81
+ * Get path to user config file
82
+ */
83
+ export declare function getUserConfigPath(): string;
20
84
  /**
21
85
  * Create default user config file if it doesn't exist
22
86
  */
@@ -1 +1 @@
1
- {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;CAkBlB,CAAC;AAyKF;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CA4B3C;AAMD,eAAO,MAAM,aAAa,QAAoB,CAAC;AAC/C,eAAO,MAAM,SAAS,QAAuC,CAAC;AAC9D,eAAO,MAAM,SAAS,QAA+B,CAAC;AAEtD,eAAO,MAAM,gBAAgB,2DAA4D,CAAC;AAE1F,eAAO,MAAM,aAAa;;CAEhB,CAAC"}
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;CAkBlB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,qDAAqD;IACrD,wBAAwB,CAAC,EAAE,MAAM,EAAE,CAAC;IACpC,mCAAmC;IACnC,gBAAgB,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACnD,sCAAsC;IACtC,YAAY,CAAC,EAAE;QACb,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;KAC1C,CAAC;IACF,wBAAwB;IACxB,QAAQ,CAAC,EAAE;QACT,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,sBAAsB,CAAC,EAAE,OAAO,CAAC;KAClC,CAAC;IACF,yBAAyB;IACzB,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC,CAAC;IACH,sCAAsC;IACtC,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,KAAK,EAAE;QACL,+BAA+B;QAC/B,aAAa,EAAE,OAAO,CAAC;QACvB,8FAA8F;QAC9F,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,oEAAoE;QACpE,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH;AAgGD;;GAEG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAa3C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAE5D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAqBnE;AAwBD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAe1C;AA4DD;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CA8B3C;AAMD,eAAO,MAAM,aAAa,QAAoB,CAAC;AAC/C,eAAO,MAAM,SAAS,QAAuC,CAAC;AAC9D,eAAO,MAAM,SAAS,QAA+B,CAAC;AAEtD,eAAO,MAAM,gBAAgB,2DAA4D,CAAC;AAE1F,eAAO,MAAM,aAAa;;CAEhB,CAAC"}