ellmos-filecommander-mcp 1.7.4 → 1.7.6
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/README.md +297 -284
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,284 +1,297 @@
|
|
|
1
|
-
<p align="center">
|
|
2
|
-
<img src="filecommander_banner.jpg" alt="FileCommander banner" width="700">
|
|
3
|
-
</p>
|
|
4
|
-
|
|
5
|
-
#
|
|
6
|
-
|
|
7
|
-
*Part of the [ellmos-ai](https://github.com/ellmos-ai) family.*
|
|
8
|
-
|
|
9
|
-
[](https://opensource.org/licenses/MIT)
|
|
10
|
-
[](https://nodejs.org/)
|
|
12
|
-
|
|
13
|
-
A comprehensive **Model Context Protocol (MCP) server** that gives AI assistants full filesystem access, process management, interactive shell sessions, and async file search capabilities.
|
|
14
|
-
|
|
15
|
-
**43 tools** in a single server - everything an AI agent needs to interact with the local system.
|
|
16
|
-
|
|
17
|
-
---
|
|
18
|
-
|
|
19
|
-
## Why FileCommander?
|
|
20
|
-
|
|
21
|
-
Most filesystem MCP servers only cover basic read/write operations. FileCommander goes further:
|
|
22
|
-
|
|
23
|
-
- **Safe Delete** - Moves files to Recycle Bin (Windows) or Trash (macOS/Linux) instead of permanent deletion
|
|
24
|
-
- **Interactive Sessions** - Start and interact with REPLs (Python, Node.js, shells) through the MCP protocol
|
|
25
|
-
- **Async Search** - Search large directory trees in the background while the AI continues working
|
|
26
|
-
- **Process Management** - List, start, and terminate system processes
|
|
27
|
-
- **String Replace** - Edit files by matching unique strings with context validation
|
|
28
|
-
- **Format Conversion** - Convert between JSON, CSV, INI, YAML, TOML, XML, and TOON
|
|
29
|
-
- **ZIP Archives** - Create, extract, and list ZIP archives
|
|
30
|
-
- **File Checksums** - SHA-256, MD5, SHA-1, SHA-512 hashing with compare
|
|
31
|
-
- **OCR** - Extract text from images (optional tesseract.js dependency)
|
|
32
|
-
- **Safety Mode** - Toggle to route all deletes through Recycle Bin / Trash
|
|
33
|
-
- **Markdown Export** - Convert Markdown to professional HTML/PDF with code blocks, tables, nested lists, blockquotes
|
|
34
|
-
- **Cross-platform** - Works on Windows, macOS, and Linux with platform-specific optimizations
|
|
35
|
-
|
|
36
|
-
---
|
|
37
|
-
|
|
38
|
-
## Installation
|
|
39
|
-
|
|
40
|
-
### Prerequisites
|
|
41
|
-
|
|
42
|
-
- [Node.js](https://nodejs.org/) 18 or higher
|
|
43
|
-
- npm
|
|
44
|
-
|
|
45
|
-
### Option 1: Install from NPM
|
|
46
|
-
|
|
47
|
-
```bash
|
|
48
|
-
npm install -g
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
### Option 2: Install from Source
|
|
52
|
-
|
|
53
|
-
```bash
|
|
54
|
-
git clone https://github.com/
|
|
55
|
-
cd
|
|
56
|
-
npm install
|
|
57
|
-
npm run build
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
---
|
|
61
|
-
|
|
62
|
-
## Configuration
|
|
63
|
-
|
|
64
|
-
### Claude Desktop
|
|
65
|
-
|
|
66
|
-
Add to your `claude_desktop_config.json`:
|
|
67
|
-
|
|
68
|
-
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
|
|
69
|
-
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
70
|
-
|
|
71
|
-
#### If installed globally via NPM:
|
|
72
|
-
|
|
73
|
-
```json
|
|
74
|
-
{
|
|
75
|
-
"mcpServers": {
|
|
76
|
-
"filecommander": {
|
|
77
|
-
"command": "
|
|
78
|
-
}
|
|
79
|
-
}
|
|
80
|
-
}
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
#### If installed from source:
|
|
84
|
-
|
|
85
|
-
```json
|
|
86
|
-
{
|
|
87
|
-
"mcpServers": {
|
|
88
|
-
"filecommander": {
|
|
89
|
-
"command": "node",
|
|
90
|
-
"args": ["/absolute/path/to/filecommander-mcp/dist/index.js"]
|
|
91
|
-
}
|
|
92
|
-
}
|
|
93
|
-
}
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
Restart Claude Desktop after saving.
|
|
97
|
-
|
|
98
|
-
### Other MCP Clients
|
|
99
|
-
|
|
100
|
-
The server communicates via **stdio transport**. Point your MCP client to the `dist/index.js` entry point or the `
|
|
101
|
-
|
|
102
|
-
---
|
|
103
|
-
|
|
104
|
-
## Tools Overview
|
|
105
|
-
|
|
106
|
-
### Filesystem Operations (14 tools)
|
|
107
|
-
|
|
108
|
-
| Tool | Description |
|
|
109
|
-
|------|-------------|
|
|
110
|
-
| `fc_read_file` | Read file contents with optional line limit |
|
|
111
|
-
| `fc_read_multiple_files` | Read up to 20 files in a single call |
|
|
112
|
-
| `fc_write_file` | Write/create/append to files |
|
|
113
|
-
| `fc_edit_file` | Line-based editing (replace, insert, delete lines) |
|
|
114
|
-
| `fc_str_replace` | Replace a unique string in a file with context validation |
|
|
115
|
-
| `fc_list_directory` | List directory contents (recursive, configurable depth) |
|
|
116
|
-
| `fc_create_directory` | Create directories (including parents) |
|
|
117
|
-
| `fc_delete_file` | Delete a file (permanent) |
|
|
118
|
-
| `fc_delete_directory` | Delete a directory (with optional recursive flag) |
|
|
119
|
-
| `fc_safe_delete` | Move to Recycle Bin / Trash (recoverable!) |
|
|
120
|
-
| `fc_move` | Move or rename files and directories |
|
|
121
|
-
| `fc_copy` | Copy files and directories |
|
|
122
|
-
| `fc_file_info` | Get detailed file metadata (size, dates, type) |
|
|
123
|
-
| `fc_search_files` | Synchronous file search with wildcard patterns |
|
|
124
|
-
|
|
125
|
-
### Async Search (5 tools)
|
|
126
|
-
|
|
127
|
-
| Tool | Description |
|
|
128
|
-
|------|-------------|
|
|
129
|
-
| `fc_start_search` | Start a background search (returns immediately) |
|
|
130
|
-
| `fc_get_search_results` | Retrieve results with pagination |
|
|
131
|
-
| `fc_stop_search` | Cancel a running search |
|
|
132
|
-
| `fc_list_searches` | List all active/completed searches |
|
|
133
|
-
| `fc_clear_search` | Remove completed searches from memory |
|
|
134
|
-
|
|
135
|
-
### Process Management (4 tools)
|
|
136
|
-
|
|
137
|
-
| Tool | Description |
|
|
138
|
-
|------|-------------|
|
|
139
|
-
| `fc_execute_command` | Execute a shell command (blocking, with timeout) |
|
|
140
|
-
| `fc_start_process` | Start a background process (non-blocking) |
|
|
141
|
-
| `fc_list_processes` | List running system processes |
|
|
142
|
-
| `fc_kill_process` | Terminate a process by PID or name |
|
|
143
|
-
|
|
144
|
-
### Interactive Sessions (5 tools)
|
|
145
|
-
|
|
146
|
-
| Tool | Description |
|
|
147
|
-
|------|-------------|
|
|
148
|
-
| `fc_start_session` | Start an interactive process (Python, Node, shell...) |
|
|
149
|
-
| `fc_read_output` | Read session output |
|
|
150
|
-
| `fc_send_input` | Send input to a running session |
|
|
151
|
-
| `fc_list_sessions` | List all sessions |
|
|
152
|
-
| `fc_close_session` | Terminate a session |
|
|
153
|
-
|
|
154
|
-
### File Maintenance & Repair (8 tools)
|
|
155
|
-
|
|
156
|
-
| Tool | Description |
|
|
157
|
-
|------|-------------|
|
|
158
|
-
| `fc_fix_json` | Repair broken JSON (BOM, trailing commas, comments, single quotes) |
|
|
159
|
-
| `fc_validate_json` | Validate JSON with detailed error position and context |
|
|
160
|
-
| `fc_cleanup_file` | Remove BOM, NUL bytes, trailing whitespace, normalize line endings |
|
|
161
|
-
| `fc_fix_encoding` | Fix Mojibake / double-encoded UTF-8 (27+ character patterns) |
|
|
162
|
-
| `fc_folder_diff` | Track directory changes with snapshots (new/modified/deleted) |
|
|
163
|
-
| `fc_batch_rename` | Pattern-based batch renaming (prefix/suffix, replace, auto-detect) |
|
|
164
|
-
| `fc_convert_format` | Convert between JSON, CSV, INI, YAML, TOML, XML, and TOON formats |
|
|
165
|
-
| `fc_detect_duplicates` | Find duplicate files using SHA-256 hashing |
|
|
166
|
-
| `fc_checksum` | File hashing (MD5, SHA-1, SHA-256, SHA-512) with optional compare |
|
|
167
|
-
|
|
168
|
-
### Archive (1 tool)
|
|
169
|
-
|
|
170
|
-
| Tool | Description |
|
|
171
|
-
|------|-------------|
|
|
172
|
-
| `fc_archive` | Create, extract, and list ZIP archives |
|
|
173
|
-
|
|
174
|
-
### OCR (1 tool)
|
|
175
|
-
|
|
176
|
-
| Tool | Description |
|
|
177
|
-
|------|-------------|
|
|
178
|
-
| `fc_ocr` | Extract text from images via tesseract.js (optional dependency) |
|
|
179
|
-
|
|
180
|
-
### System (2 tools)
|
|
181
|
-
|
|
182
|
-
| Tool | Description |
|
|
183
|
-
|------|-------------|
|
|
184
|
-
| `fc_get_time` | Get current system time with timezone info |
|
|
185
|
-
| `fc_set_safe_mode` | Toggle safe mode: all deletes go through Recycle Bin / Trash |
|
|
186
|
-
|
|
187
|
-
### Export (2 tools)
|
|
188
|
-
|
|
189
|
-
| Tool | Description |
|
|
190
|
-
|------|-------------|
|
|
191
|
-
| `fc_md_to_html` | Markdown to standalone HTML with CSS styling (headers, code blocks, tables, nested lists, blockquotes, images, checkboxes) |
|
|
192
|
-
| `fc_md_to_pdf` | Markdown to PDF via headless browser (Edge/Chrome). Falls back to HTML if no browser is available |
|
|
193
|
-
|
|
194
|
-
**Total: 43 tools**
|
|
195
|
-
|
|
196
|
-
---
|
|
197
|
-
|
|
198
|
-
## Comparison with Alternatives
|
|
199
|
-
|
|
200
|
-
| Feature | FileCommander | [Desktop Commander](https://github.com/wonderwhy-er/DesktopCommanderMCP) | [Official Filesystem](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) |
|
|
201
|
-
|---------|:---:|:---:|:---:|
|
|
202
|
-
| File read/write/copy/move | 14 tools | Yes | Yes |
|
|
203
|
-
| Safe delete (Recycle Bin) | Yes | No | No |
|
|
204
|
-
| Async background search | 5 tools | No | No |
|
|
205
|
-
| Interactive sessions (REPL) | 5 tools | Yes | No |
|
|
206
|
-
| Process management | 4 tools | Yes | No |
|
|
207
|
-
| Shell command execution | Yes | Yes | No |
|
|
208
|
-
| String replace with validation | Yes | Yes | No |
|
|
209
|
-
| Line-based file editing | Yes | No | No |
|
|
210
|
-
| JSON repair & validation | 2 tools | No | No |
|
|
211
|
-
| Encoding fix (Mojibake) | Yes | No | No |
|
|
212
|
-
| Duplicate detection (SHA-256) | Yes | No | No |
|
|
213
|
-
| Folder diff / change tracking | Yes | No | No |
|
|
214
|
-
| Batch rename (pattern-based) | Yes | No | No |
|
|
215
|
-
| Format conversion (JSON/CSV/INI/YAML/TOML/XML/TOON) | Yes | No | No |
|
|
216
|
-
| ZIP archive (create/extract/list) | Yes | No | No |
|
|
217
|
-
| File checksums (SHA-256/MD5) | Yes | No | No |
|
|
218
|
-
| OCR (image to text) | Optional | No | No |
|
|
219
|
-
| Safety mode (delete → Recycle Bin) | Yes | No | No |
|
|
220
|
-
| Path allowlist / sandboxing | No | No | Yes |
|
|
221
|
-
| Excel / PDF support | PDF (via browser) | Yes | No |
|
|
222
|
-
| HTTP transport | No | No | No |
|
|
223
|
-
| Markdown to HTML/PDF export | Yes | No | No |
|
|
224
|
-
| **Total tools** | **43** | ~15 | ~11 |
|
|
225
|
-
| **Servers needed** | **1** | 1 | + extra for processes |
|
|
226
|
-
|
|
227
|
-
**Key differentiators:**
|
|
228
|
-
- Only MCP server with **recoverable delete** (Recycle Bin / Trash)
|
|
229
|
-
- Only MCP server with **async background search** with pagination
|
|
230
|
-
- Built-in **JSON repair**, **encoding fix**, and **duplicate detection**
|
|
231
|
-
- Most comprehensive single-server solution (43 tools)
|
|
232
|
-
- Built-in **safety mode** to prevent accidental permanent deletion
|
|
233
|
-
|
|
234
|
-
---
|
|
235
|
-
|
|
236
|
-
## Tool Prefix
|
|
237
|
-
|
|
238
|
-
All tools use the `fc_` prefix (FileCommander) to avoid conflicts with other MCP servers.
|
|
239
|
-
|
|
240
|
-
---
|
|
241
|
-
|
|
242
|
-
## Security
|
|
243
|
-
|
|
244
|
-
**This server has full filesystem access with the running user's permissions.**
|
|
245
|
-
|
|
246
|
-
See [SECURITY.md](SECURITY.md) for detailed security information and recommendations.
|
|
247
|
-
|
|
248
|
-
Key points:
|
|
249
|
-
- `fc_execute_command` runs arbitrary shell commands
|
|
250
|
-
- `fc_delete_*` tools perform permanent deletion by default (use `fc_safe_delete` or enable **safe mode** via `fc_set_safe_mode` to route all deletes through Recycle Bin / Trash)
|
|
251
|
-
- No built-in sandboxing - security is delegated to the MCP client layer
|
|
252
|
-
- Designed for local use via stdio transport only
|
|
253
|
-
|
|
254
|
-
---
|
|
255
|
-
|
|
256
|
-
## Development
|
|
257
|
-
|
|
258
|
-
```bash
|
|
259
|
-
# Install dependencies
|
|
260
|
-
npm install
|
|
261
|
-
|
|
262
|
-
# Watch mode (auto-rebuild on changes)
|
|
263
|
-
npm run dev
|
|
264
|
-
|
|
265
|
-
# One-time build
|
|
266
|
-
npm run build
|
|
267
|
-
|
|
268
|
-
# Start the server
|
|
269
|
-
npm start
|
|
270
|
-
```
|
|
271
|
-
|
|
272
|
-
See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
|
|
273
|
-
|
|
274
|
-
---
|
|
275
|
-
|
|
276
|
-
## Changelog
|
|
277
|
-
|
|
278
|
-
See [CHANGELOG.md](CHANGELOG.md) for the full version history.
|
|
279
|
-
|
|
280
|
-
---
|
|
281
|
-
|
|
282
|
-
## License
|
|
283
|
-
|
|
284
|
-
[MIT](LICENSE) - Lukas (
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="filecommander_banner.jpg" alt="FileCommander banner" width="700">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
# ellmos FileCommander MCP Server
|
|
6
|
+
|
|
7
|
+
*Part of the [ellmos-ai](https://github.com/ellmos-ai) family.*
|
|
8
|
+
|
|
9
|
+
[](https://opensource.org/licenses/MIT)
|
|
10
|
+
[](https://www.npmjs.com/package/ellmos-filecommander-mcp)
|
|
11
|
+
[](https://nodejs.org/)
|
|
12
|
+
|
|
13
|
+
A comprehensive **Model Context Protocol (MCP) server** that gives AI assistants full filesystem access, process management, interactive shell sessions, and async file search capabilities.
|
|
14
|
+
|
|
15
|
+
**43 tools** in a single server - everything an AI agent needs to interact with the local system.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Why FileCommander?
|
|
20
|
+
|
|
21
|
+
Most filesystem MCP servers only cover basic read/write operations. FileCommander goes further:
|
|
22
|
+
|
|
23
|
+
- **Safe Delete** - Moves files to Recycle Bin (Windows) or Trash (macOS/Linux) instead of permanent deletion
|
|
24
|
+
- **Interactive Sessions** - Start and interact with REPLs (Python, Node.js, shells) through the MCP protocol
|
|
25
|
+
- **Async Search** - Search large directory trees in the background while the AI continues working
|
|
26
|
+
- **Process Management** - List, start, and terminate system processes
|
|
27
|
+
- **String Replace** - Edit files by matching unique strings with context validation
|
|
28
|
+
- **Format Conversion** - Convert between JSON, CSV, INI, YAML, TOML, XML, and TOON
|
|
29
|
+
- **ZIP Archives** - Create, extract, and list ZIP archives
|
|
30
|
+
- **File Checksums** - SHA-256, MD5, SHA-1, SHA-512 hashing with compare
|
|
31
|
+
- **OCR** - Extract text from images (optional tesseract.js dependency)
|
|
32
|
+
- **Safety Mode** - Toggle to route all deletes through Recycle Bin / Trash
|
|
33
|
+
- **Markdown Export** - Convert Markdown to professional HTML/PDF with code blocks, tables, nested lists, blockquotes
|
|
34
|
+
- **Cross-platform** - Works on Windows, macOS, and Linux with platform-specific optimizations
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## Installation
|
|
39
|
+
|
|
40
|
+
### Prerequisites
|
|
41
|
+
|
|
42
|
+
- [Node.js](https://nodejs.org/) 18 or higher
|
|
43
|
+
- npm
|
|
44
|
+
|
|
45
|
+
### Option 1: Install from NPM
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
npm install -g ellmos-filecommander-mcp
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### Option 2: Install from Source
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
git clone https://github.com/ellmos-ai/ellmos-filecommander-mcp.git
|
|
55
|
+
cd ellmos-filecommander-mcp
|
|
56
|
+
npm install
|
|
57
|
+
npm run build
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Configuration
|
|
63
|
+
|
|
64
|
+
### Claude Desktop
|
|
65
|
+
|
|
66
|
+
Add to your `claude_desktop_config.json`:
|
|
67
|
+
|
|
68
|
+
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
|
|
69
|
+
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
70
|
+
|
|
71
|
+
#### If installed globally via NPM:
|
|
72
|
+
|
|
73
|
+
```json
|
|
74
|
+
{
|
|
75
|
+
"mcpServers": {
|
|
76
|
+
"filecommander": {
|
|
77
|
+
"command": "ellmos-filecommander"
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
#### If installed from source:
|
|
84
|
+
|
|
85
|
+
```json
|
|
86
|
+
{
|
|
87
|
+
"mcpServers": {
|
|
88
|
+
"filecommander": {
|
|
89
|
+
"command": "node",
|
|
90
|
+
"args": ["/absolute/path/to/filecommander-mcp/dist/index.js"]
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Restart Claude Desktop after saving.
|
|
97
|
+
|
|
98
|
+
### Other MCP Clients
|
|
99
|
+
|
|
100
|
+
The server communicates via **stdio transport**. Point your MCP client to the `dist/index.js` entry point or the `ellmos-filecommander` binary.
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## Tools Overview
|
|
105
|
+
|
|
106
|
+
### Filesystem Operations (14 tools)
|
|
107
|
+
|
|
108
|
+
| Tool | Description |
|
|
109
|
+
|------|-------------|
|
|
110
|
+
| `fc_read_file` | Read file contents with optional line limit |
|
|
111
|
+
| `fc_read_multiple_files` | Read up to 20 files in a single call |
|
|
112
|
+
| `fc_write_file` | Write/create/append to files |
|
|
113
|
+
| `fc_edit_file` | Line-based editing (replace, insert, delete lines) |
|
|
114
|
+
| `fc_str_replace` | Replace a unique string in a file with context validation |
|
|
115
|
+
| `fc_list_directory` | List directory contents (recursive, configurable depth) |
|
|
116
|
+
| `fc_create_directory` | Create directories (including parents) |
|
|
117
|
+
| `fc_delete_file` | Delete a file (permanent) |
|
|
118
|
+
| `fc_delete_directory` | Delete a directory (with optional recursive flag) |
|
|
119
|
+
| `fc_safe_delete` | Move to Recycle Bin / Trash (recoverable!) |
|
|
120
|
+
| `fc_move` | Move or rename files and directories |
|
|
121
|
+
| `fc_copy` | Copy files and directories |
|
|
122
|
+
| `fc_file_info` | Get detailed file metadata (size, dates, type) |
|
|
123
|
+
| `fc_search_files` | Synchronous file search with wildcard patterns |
|
|
124
|
+
|
|
125
|
+
### Async Search (5 tools)
|
|
126
|
+
|
|
127
|
+
| Tool | Description |
|
|
128
|
+
|------|-------------|
|
|
129
|
+
| `fc_start_search` | Start a background search (returns immediately) |
|
|
130
|
+
| `fc_get_search_results` | Retrieve results with pagination |
|
|
131
|
+
| `fc_stop_search` | Cancel a running search |
|
|
132
|
+
| `fc_list_searches` | List all active/completed searches |
|
|
133
|
+
| `fc_clear_search` | Remove completed searches from memory |
|
|
134
|
+
|
|
135
|
+
### Process Management (4 tools)
|
|
136
|
+
|
|
137
|
+
| Tool | Description |
|
|
138
|
+
|------|-------------|
|
|
139
|
+
| `fc_execute_command` | Execute a shell command (blocking, with timeout) |
|
|
140
|
+
| `fc_start_process` | Start a background process (non-blocking) |
|
|
141
|
+
| `fc_list_processes` | List running system processes |
|
|
142
|
+
| `fc_kill_process` | Terminate a process by PID or name |
|
|
143
|
+
|
|
144
|
+
### Interactive Sessions (5 tools)
|
|
145
|
+
|
|
146
|
+
| Tool | Description |
|
|
147
|
+
|------|-------------|
|
|
148
|
+
| `fc_start_session` | Start an interactive process (Python, Node, shell...) |
|
|
149
|
+
| `fc_read_output` | Read session output |
|
|
150
|
+
| `fc_send_input` | Send input to a running session |
|
|
151
|
+
| `fc_list_sessions` | List all sessions |
|
|
152
|
+
| `fc_close_session` | Terminate a session |
|
|
153
|
+
|
|
154
|
+
### File Maintenance & Repair (8 tools)
|
|
155
|
+
|
|
156
|
+
| Tool | Description |
|
|
157
|
+
|------|-------------|
|
|
158
|
+
| `fc_fix_json` | Repair broken JSON (BOM, trailing commas, comments, single quotes) |
|
|
159
|
+
| `fc_validate_json` | Validate JSON with detailed error position and context |
|
|
160
|
+
| `fc_cleanup_file` | Remove BOM, NUL bytes, trailing whitespace, normalize line endings |
|
|
161
|
+
| `fc_fix_encoding` | Fix Mojibake / double-encoded UTF-8 (27+ character patterns) |
|
|
162
|
+
| `fc_folder_diff` | Track directory changes with snapshots (new/modified/deleted) |
|
|
163
|
+
| `fc_batch_rename` | Pattern-based batch renaming (prefix/suffix, replace, auto-detect) |
|
|
164
|
+
| `fc_convert_format` | Convert between JSON, CSV, INI, YAML, TOML, XML, and TOON formats |
|
|
165
|
+
| `fc_detect_duplicates` | Find duplicate files using SHA-256 hashing |
|
|
166
|
+
| `fc_checksum` | File hashing (MD5, SHA-1, SHA-256, SHA-512) with optional compare |
|
|
167
|
+
|
|
168
|
+
### Archive (1 tool)
|
|
169
|
+
|
|
170
|
+
| Tool | Description |
|
|
171
|
+
|------|-------------|
|
|
172
|
+
| `fc_archive` | Create, extract, and list ZIP archives |
|
|
173
|
+
|
|
174
|
+
### OCR (1 tool)
|
|
175
|
+
|
|
176
|
+
| Tool | Description |
|
|
177
|
+
|------|-------------|
|
|
178
|
+
| `fc_ocr` | Extract text from images via tesseract.js (optional dependency) |
|
|
179
|
+
|
|
180
|
+
### System (2 tools)
|
|
181
|
+
|
|
182
|
+
| Tool | Description |
|
|
183
|
+
|------|-------------|
|
|
184
|
+
| `fc_get_time` | Get current system time with timezone info |
|
|
185
|
+
| `fc_set_safe_mode` | Toggle safe mode: all deletes go through Recycle Bin / Trash |
|
|
186
|
+
|
|
187
|
+
### Export (2 tools)
|
|
188
|
+
|
|
189
|
+
| Tool | Description |
|
|
190
|
+
|------|-------------|
|
|
191
|
+
| `fc_md_to_html` | Markdown to standalone HTML with CSS styling (headers, code blocks, tables, nested lists, blockquotes, images, checkboxes) |
|
|
192
|
+
| `fc_md_to_pdf` | Markdown to PDF via headless browser (Edge/Chrome). Falls back to HTML if no browser is available |
|
|
193
|
+
|
|
194
|
+
**Total: 43 tools**
|
|
195
|
+
|
|
196
|
+
---
|
|
197
|
+
|
|
198
|
+
## Comparison with Alternatives
|
|
199
|
+
|
|
200
|
+
| Feature | FileCommander | [Desktop Commander](https://github.com/wonderwhy-er/DesktopCommanderMCP) | [Official Filesystem](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) |
|
|
201
|
+
|---------|:---:|:---:|:---:|
|
|
202
|
+
| File read/write/copy/move | 14 tools | Yes | Yes |
|
|
203
|
+
| Safe delete (Recycle Bin) | Yes | No | No |
|
|
204
|
+
| Async background search | 5 tools | No | No |
|
|
205
|
+
| Interactive sessions (REPL) | 5 tools | Yes | No |
|
|
206
|
+
| Process management | 4 tools | Yes | No |
|
|
207
|
+
| Shell command execution | Yes | Yes | No |
|
|
208
|
+
| String replace with validation | Yes | Yes | No |
|
|
209
|
+
| Line-based file editing | Yes | No | No |
|
|
210
|
+
| JSON repair & validation | 2 tools | No | No |
|
|
211
|
+
| Encoding fix (Mojibake) | Yes | No | No |
|
|
212
|
+
| Duplicate detection (SHA-256) | Yes | No | No |
|
|
213
|
+
| Folder diff / change tracking | Yes | No | No |
|
|
214
|
+
| Batch rename (pattern-based) | Yes | No | No |
|
|
215
|
+
| Format conversion (JSON/CSV/INI/YAML/TOML/XML/TOON) | Yes | No | No |
|
|
216
|
+
| ZIP archive (create/extract/list) | Yes | No | No |
|
|
217
|
+
| File checksums (SHA-256/MD5) | Yes | No | No |
|
|
218
|
+
| OCR (image to text) | Optional | No | No |
|
|
219
|
+
| Safety mode (delete → Recycle Bin) | Yes | No | No |
|
|
220
|
+
| Path allowlist / sandboxing | No | No | Yes |
|
|
221
|
+
| Excel / PDF support | PDF (via browser) | Yes | No |
|
|
222
|
+
| HTTP transport | No | No | No |
|
|
223
|
+
| Markdown to HTML/PDF export | Yes | No | No |
|
|
224
|
+
| **Total tools** | **43** | ~15 | ~11 |
|
|
225
|
+
| **Servers needed** | **1** | 1 | + extra for processes |
|
|
226
|
+
|
|
227
|
+
**Key differentiators:**
|
|
228
|
+
- Only MCP server with **recoverable delete** (Recycle Bin / Trash)
|
|
229
|
+
- Only MCP server with **async background search** with pagination
|
|
230
|
+
- Built-in **JSON repair**, **encoding fix**, and **duplicate detection**
|
|
231
|
+
- Most comprehensive single-server solution (43 tools)
|
|
232
|
+
- Built-in **safety mode** to prevent accidental permanent deletion
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## Tool Prefix
|
|
237
|
+
|
|
238
|
+
All tools use the `fc_` prefix (FileCommander) to avoid conflicts with other MCP servers.
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## Security
|
|
243
|
+
|
|
244
|
+
**This server has full filesystem access with the running user's permissions.**
|
|
245
|
+
|
|
246
|
+
See [SECURITY.md](SECURITY.md) for detailed security information and recommendations.
|
|
247
|
+
|
|
248
|
+
Key points:
|
|
249
|
+
- `fc_execute_command` runs arbitrary shell commands
|
|
250
|
+
- `fc_delete_*` tools perform permanent deletion by default (use `fc_safe_delete` or enable **safe mode** via `fc_set_safe_mode` to route all deletes through Recycle Bin / Trash)
|
|
251
|
+
- No built-in sandboxing - security is delegated to the MCP client layer
|
|
252
|
+
- Designed for local use via stdio transport only
|
|
253
|
+
|
|
254
|
+
---
|
|
255
|
+
|
|
256
|
+
## Development
|
|
257
|
+
|
|
258
|
+
```bash
|
|
259
|
+
# Install dependencies
|
|
260
|
+
npm install
|
|
261
|
+
|
|
262
|
+
# Watch mode (auto-rebuild on changes)
|
|
263
|
+
npm run dev
|
|
264
|
+
|
|
265
|
+
# One-time build
|
|
266
|
+
npm run build
|
|
267
|
+
|
|
268
|
+
# Start the server
|
|
269
|
+
npm start
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
276
|
+
## Changelog
|
|
277
|
+
|
|
278
|
+
See [CHANGELOG.md](CHANGELOG.md) for the full version history.
|
|
279
|
+
|
|
280
|
+
---
|
|
281
|
+
|
|
282
|
+
## License
|
|
283
|
+
|
|
284
|
+
[MIT](LICENSE) - Lukas Geiger ([ellmos-ai](https://github.com/ellmos-ai))
|
|
285
|
+
|
|
286
|
+
---
|
|
287
|
+
|
|
288
|
+
## History
|
|
289
|
+
|
|
290
|
+
This project was originally developed as **BACH FileCommander** (`bach-filecommander-mcp`). It has been renamed to **ellmos FileCommander** (`ellmos-filecommander-mcp`) as part of the [ellmos-ai](https://github.com/ellmos-ai) organization.
|
|
291
|
+
|
|
292
|
+
The old npm package [`bach-filecommander-mcp`](https://www.npmjs.com/package/bach-filecommander-mcp) is deprecated. Please use [`ellmos-filecommander-mcp`](https://www.npmjs.com/package/ellmos-filecommander-mcp) instead:
|
|
293
|
+
|
|
294
|
+
```bash
|
|
295
|
+
npm uninstall -g bach-filecommander-mcp
|
|
296
|
+
npm install -g ellmos-filecommander-mcp
|
|
297
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ellmos-filecommander-mcp",
|
|
3
|
-
"version": "1.7.
|
|
3
|
+
"version": "1.7.6",
|
|
4
4
|
"mcpName": "io.github.ellmos-ai/ellmos-filecommander-mcp",
|
|
5
5
|
"description": "A comprehensive MCP server providing 43 tools for filesystem operations, process management, interactive sessions, async file search, JSON repair, encoding fix, duplicate detection, OCR, ZIP archives, and Markdown export",
|
|
6
6
|
"type": "module",
|