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.
- package/ARCHITECTURE.md +0 -1
- package/CHANGELOG.md +33 -4
- package/CONTRIBUTING.md +4 -3
- package/MIGRATION.md +1 -1
- package/README.md +218 -51
- package/dist/config.d.ts +64 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +90 -17
- package/dist/config.js.map +1 -1
- package/dist/constants.js +1 -1
- package/dist/constants.js.map +1 -1
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +84 -0
- package/dist/index.js.map +1 -1
- package/dist/schemas/rename.schemas.d.ts +95 -0
- package/dist/schemas/rename.schemas.d.ts.map +1 -0
- package/dist/schemas/rename.schemas.js +39 -0
- package/dist/schemas/rename.schemas.js.map +1 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +87 -28
- package/dist/server.js.map +1 -1
- package/dist/services/auto-organize.service.d.ts +88 -0
- package/dist/services/auto-organize.service.d.ts.map +1 -0
- package/dist/services/auto-organize.service.js +269 -0
- package/dist/services/auto-organize.service.js.map +1 -0
- package/dist/services/categorizer.service.d.ts.map +1 -1
- package/dist/services/categorizer.service.js +27 -1
- package/dist/services/categorizer.service.js.map +1 -1
- package/dist/services/index.d.ts +1 -0
- package/dist/services/index.d.ts.map +1 -1
- package/dist/services/index.js +1 -0
- package/dist/services/index.js.map +1 -1
- package/dist/services/metadata.service.d.ts +36 -0
- package/dist/services/metadata.service.d.ts.map +1 -0
- package/dist/services/metadata.service.js +212 -0
- package/dist/services/metadata.service.js.map +1 -0
- package/dist/services/organizer.service.d.ts +3 -1
- package/dist/services/organizer.service.d.ts.map +1 -1
- package/dist/services/organizer.service.js +28 -5
- package/dist/services/organizer.service.js.map +1 -1
- package/dist/services/path-validator.service.d.ts +1 -0
- package/dist/services/path-validator.service.d.ts.map +1 -1
- package/dist/services/path-validator.service.js +42 -6
- package/dist/services/path-validator.service.js.map +1 -1
- package/dist/services/renaming.service.d.ts +39 -0
- package/dist/services/renaming.service.d.ts.map +1 -0
- package/dist/services/renaming.service.js +296 -0
- package/dist/services/renaming.service.js.map +1 -0
- package/dist/services/rollback.service.js +2 -2
- package/dist/services/rollback.service.js.map +1 -1
- package/dist/tools/file-organization.d.ts +5 -0
- package/dist/tools/file-organization.d.ts.map +1 -1
- package/dist/tools/file-organization.js +23 -2
- package/dist/tools/file-organization.js.map +1 -1
- package/dist/tools/file-renaming.d.ts +65 -0
- package/dist/tools/file-renaming.d.ts.map +1 -0
- package/dist/tools/file-renaming.js +148 -0
- package/dist/tools/file-renaming.js.map +1 -0
- package/dist/tools/index.d.ts +4 -0
- package/dist/tools/index.d.ts.map +1 -1
- package/dist/tools/index.js +12 -0
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/metadata-inspection.d.ts +41 -0
- package/dist/tools/metadata-inspection.d.ts.map +1 -0
- package/dist/tools/metadata-inspection.js +220 -0
- package/dist/tools/metadata-inspection.js.map +1 -0
- package/dist/tools/organization-preview.d.ts +5 -0
- package/dist/tools/organization-preview.d.ts.map +1 -1
- package/dist/tools/organization-preview.js +23 -3
- package/dist/tools/organization-preview.js.map +1 -1
- package/dist/tools/watch.tool.d.ts +48 -0
- package/dist/tools/watch.tool.d.ts.map +1 -0
- package/dist/tools/watch.tool.js +329 -0
- package/dist/tools/watch.tool.js.map +1 -0
- package/dist/tui/index.d.ts +9 -0
- package/dist/tui/index.d.ts.map +1 -0
- package/dist/tui/index.js +17 -0
- package/dist/tui/index.js.map +1 -0
- package/dist/tui/screens.d.ts +2 -0
- package/dist/tui/screens.d.ts.map +1 -0
- package/dist/tui/screens.js +3 -0
- package/dist/tui/screens.js.map +1 -0
- package/dist/tui/setup-wizard.d.ts +5 -0
- package/dist/tui/setup-wizard.d.ts.map +1 -0
- package/dist/tui/setup-wizard.js +229 -0
- package/dist/tui/setup-wizard.js.map +1 -0
- package/dist/types.d.ts +1 -1
- package/dist/types.d.ts.map +1 -1
- package/package.json +16 -4
package/ARCHITECTURE.md
CHANGED
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
|
-
|
|
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
|
-
|
|
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:
|
|
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.
|
|
3
|
+
**Version:** 3.1.1 | **MCP Protocol:** 2024-11-05 | **Node:** ≥18.0.0
|
|
4
4
|
|
|
5
|
-
[Quick Start](
|
|
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
|
-
[](https://www.npmjs.com/package/file-organizer-mcp)
|
|
9
|
+
[](https://www.npmjs.com/package/file-organizer-mcp)
|
|
11
10
|
[](https://www.npmjs.com/package/file-organizer-mcp)
|
|
12
11
|
[](https://github.com/kridaydave/File-Organizer-MCP)
|
|
13
12
|
[](https://nodejs.org)
|
|
14
13
|
[](LICENSE)
|
|
15
|
-
[](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
|
-
##
|
|
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. **
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
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
|
-
##
|
|
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
|
-
*
|
|
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
|
|
79
|
-
*
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
-
**
|
|
116
|
-
*
|
|
117
|
-
*
|
|
118
|
-
*
|
|
119
|
-
*
|
|
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
|
-
|
|
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
|
-
##
|
|
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:
|
|
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
|
-
##
|
|
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
|
-
##
|
|
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.
|
|
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
|
-
|
|
555
|
+
### Workflow 5: Set Up Automatic Organization
|
|
445
556
|
|
|
446
|
-
|
|
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
|
|
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
|
-
"
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
*/
|
package/dist/config.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;CAkBlB,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"}
|