ellmos-filecommander-mcp 1.7.4

package/CHANGELOG.md

@@ -0,0 +1,116 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.7.2] - 2026-02-20
+
+### Fixed
+- Update CHANGELOG with 5 missing version entries (v1.5.0-v1.7.1)
+- Fix server.json version mismatch
+- Update SECURITY.md supported versions (1.3.x -> 1.7.x)
+- Add missing runtime dependencies to THIRD_PARTY_NOTICES.md
+- Remove stale "NEW in v1.4.0" label from README
+
+## [1.7.1] - 2026-02-17
+
+### Changed
+- Replace custom TOON parser/serializer with official `@toon-format/toon` package
+- Proper TOON format: `key: value` syntax instead of custom `key = value`
+
+## [1.7.0] - 2026-02-17
+
+### Added
+- `fc_ocr` - Extract text from images via optional tesseract.js dependency
+- `fc_archive` - Create, extract, and list ZIP archives (via adm-zip)
+- `fc_checksum` - File hashing (MD5, SHA-1, SHA-256, SHA-512) with optional compare
+- `fc_set_safe_mode` - Toggle safety mode: route all deletes through Recycle Bin / Trash
+- Expand `fc_convert_format`: add YAML, TOML, XML, and TOON support (was JSON/CSV/INI only)
+- Full i18n (DE/EN) for all new tools
+- Total tools: 43
+
+## [1.6.1] - 2026-02-17
+
+### Added
+- `mcpName` field in package.json for MCP Registry verification
+- `server.json` for official MCP Registry publishing
+
+## [1.6.0] - 2026-02-17
+
+### Added
+- `fc_md_to_pdf` - Real PDF generation via headless Edge/Chrome browser
+- Cross-platform browser detection (Windows, macOS, Linux)
+- Fallback to HTML output if no browser is available
+- Total tools: 39
+
+## [1.5.0] - 2026-02-15
+
+### Added
+- Complete internationalization (i18n) infrastructure with German (default) and English support
+- New `fc_set_language` tool for runtime language switching
+- `FC_LANGUAGE` environment variable for startup configuration
+- ~270 translated strings (tool titles, descriptions, error messages, weekdays)
+- i18n test suite (66 tests)
+- Language priority: `fc_set_language` > `FC_LANGUAGE` env > `"de"` default
+
+## [1.4.1] - 2026-02-14
+
+### Fixed
+- `fc_md_to_html` completely rewritten: line-by-line parser instead of regex chain
+- Added: nested lists, ordered lists, blockquotes, checkboxes, badge images, standalone images
+- Added: bold+italic combo (`***text***`), proper `<thead>/<tbody>` tables
+- Professional CSS: dark code blocks, colored headers, print-ready layout
+
+## [1.4.0] - 2026-02-14
+
+### Added
+- `fc_fix_json` - Repair common JSON errors (BOM, trailing commas, single quotes, comments, NUL bytes)
+- `fc_validate_json` - Validate JSON with detailed error position and context
+- `fc_cleanup_file` - Clean files: remove BOM, NUL bytes, trailing whitespace, normalize line endings
+- `fc_fix_encoding` - Fix Mojibake and double-encoded UTF-8 (27+ patterns for German, French, Spanish)
+- `fc_folder_diff` - Track directory changes (new/modified/deleted files) with snapshots
+- `fc_batch_rename` - Pattern-based batch renaming (prefix/suffix removal, replace, auto-detect)
+- `fc_convert_format` - Convert between JSON, CSV, and INI formats
+- `fc_detect_duplicates` - Find duplicate files using SHA-256 hashing with size pre-filter
+- `fc_md_to_html` - Convert Markdown to styled HTML (printable as PDF via browser)
+- Total tools: 38
+
+## [1.3.0] - 2026-02-14
+
+### Changed
+- Project prepared for public open-source release
+- README rewritten in English for international audience
+- Added LICENSE (MIT), SECURITY.md, CONTRIBUTING.md
+- Package metadata updated for NPM publishing
+
+## [1.2.1] - 2025-01-05
+
+### Added
+- `fc_str_replace` - String replacement tool with unique-match validation
+- Total tools: 29
+
+### Fixed
+- `fc_safe_delete` PowerShell escaping for paths with special characters
+- `&` character handling in Windows paths (PowerShell fallback)
+
+## [1.2.0] - 2025-01-05
+
+### Added
+- Async Search system (5 tools): `fc_start_search`, `fc_get_search_results`, `fc_stop_search`, `fc_list_searches`, `fc_clear_search`
+- `fc_safe_delete` - Moves files to Recycle Bin (Windows) or Trash (macOS/Linux) instead of permanent deletion
+
+## [1.1.0] - 2025-01-05
+
+### Added
+- `fc_read_multiple_files` - Read multiple files in one call
+- `fc_edit_file` - Line-based file editing (replace/insert/delete)
+- `fc_list_processes` - List running system processes
+- `fc_kill_process` - Terminate processes by PID or name
+- Interactive Sessions (4 tools): `fc_start_session`, `fc_read_output`, `fc_send_input`, `fc_close_session`
+
+## [1.0.0] - 2025-01-05
+
+### Added
+- Initial release with 13 filesystem tools
+- File operations: read, write, list, create directory, delete, move, copy, file info, search
+- Process execution: `fc_execute_command`, `fc_start_process`
+- System: `fc_get_time`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Lukas (BACH)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,284 @@
+<p align="center">
+  <img src="filecommander_banner.jpg" alt="FileCommander banner" width="700">
+</p>
+
+# BACH FileCommander MCP Server
+
+*Part of the [ellmos-ai](https://github.com/ellmos-ai) family.*
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/bach-filecommander-mcp.svg)](https://www.npmjs.com/package/bach-filecommander-mcp)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+
+A comprehensive **Model Context Protocol (MCP) server** that gives AI assistants full filesystem access, process management, interactive shell sessions, and async file search capabilities.
+
+**43 tools** in a single server - everything an AI agent needs to interact with the local system.
+
+---
+
+## Why FileCommander?
+
+Most filesystem MCP servers only cover basic read/write operations. FileCommander goes further:
+
+- **Safe Delete** - Moves files to Recycle Bin (Windows) or Trash (macOS/Linux) instead of permanent deletion
+- **Interactive Sessions** - Start and interact with REPLs (Python, Node.js, shells) through the MCP protocol
+- **Async Search** - Search large directory trees in the background while the AI continues working
+- **Process Management** - List, start, and terminate system processes
+- **String Replace** - Edit files by matching unique strings with context validation
+- **Format Conversion** - Convert between JSON, CSV, INI, YAML, TOML, XML, and TOON
+- **ZIP Archives** - Create, extract, and list ZIP archives
+- **File Checksums** - SHA-256, MD5, SHA-1, SHA-512 hashing with compare
+- **OCR** - Extract text from images (optional tesseract.js dependency)
+- **Safety Mode** - Toggle to route all deletes through Recycle Bin / Trash
+- **Markdown Export** - Convert Markdown to professional HTML/PDF with code blocks, tables, nested lists, blockquotes
+- **Cross-platform** - Works on Windows, macOS, and Linux with platform-specific optimizations
+
+---
+
+## Installation
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) 18 or higher
+- npm
+
+### Option 1: Install from NPM
+
+```bash
+npm install -g bach-filecommander-mcp
+```
+
+### Option 2: Install from Source
+
+```bash
+git clone https://github.com/lukisch/bach-filecommander-mcp.git
+cd bach-filecommander-mcp
+npm install
+npm run build
+```
+
+---
+
+## Configuration
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+#### If installed globally via NPM:
+
+```json
+{
+  "mcpServers": {
+    "filecommander": {
+      "command": "bach-filecommander"
+    }
+  }
+}
+```
+
+#### If installed from source:
+
+```json
+{
+  "mcpServers": {
+    "filecommander": {
+      "command": "node",
+      "args": ["/absolute/path/to/filecommander-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+### Other MCP Clients
+
+The server communicates via **stdio transport**. Point your MCP client to the `dist/index.js` entry point or the `bach-filecommander` binary.
+
+---
+
+## Tools Overview
+
+### Filesystem Operations (14 tools)
+
+| Tool | Description |
+|------|-------------|
+| `fc_read_file` | Read file contents with optional line limit |
+| `fc_read_multiple_files` | Read up to 20 files in a single call |
+| `fc_write_file` | Write/create/append to files |
+| `fc_edit_file` | Line-based editing (replace, insert, delete lines) |
+| `fc_str_replace` | Replace a unique string in a file with context validation |
+| `fc_list_directory` | List directory contents (recursive, configurable depth) |
+| `fc_create_directory` | Create directories (including parents) |
+| `fc_delete_file` | Delete a file (permanent) |
+| `fc_delete_directory` | Delete a directory (with optional recursive flag) |
+| `fc_safe_delete` | Move to Recycle Bin / Trash (recoverable!) |
+| `fc_move` | Move or rename files and directories |
+| `fc_copy` | Copy files and directories |
+| `fc_file_info` | Get detailed file metadata (size, dates, type) |
+| `fc_search_files` | Synchronous file search with wildcard patterns |
+
+### Async Search (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `fc_start_search` | Start a background search (returns immediately) |
+| `fc_get_search_results` | Retrieve results with pagination |
+| `fc_stop_search` | Cancel a running search |
+| `fc_list_searches` | List all active/completed searches |
+| `fc_clear_search` | Remove completed searches from memory |
+
+### Process Management (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `fc_execute_command` | Execute a shell command (blocking, with timeout) |
+| `fc_start_process` | Start a background process (non-blocking) |
+| `fc_list_processes` | List running system processes |
+| `fc_kill_process` | Terminate a process by PID or name |
+
+### Interactive Sessions (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `fc_start_session` | Start an interactive process (Python, Node, shell...) |
+| `fc_read_output` | Read session output |
+| `fc_send_input` | Send input to a running session |
+| `fc_list_sessions` | List all sessions |
+| `fc_close_session` | Terminate a session |
+
+### File Maintenance & Repair (8 tools)
+
+| Tool | Description |
+|------|-------------|
+| `fc_fix_json` | Repair broken JSON (BOM, trailing commas, comments, single quotes) |
+| `fc_validate_json` | Validate JSON with detailed error position and context |
+| `fc_cleanup_file` | Remove BOM, NUL bytes, trailing whitespace, normalize line endings |
+| `fc_fix_encoding` | Fix Mojibake / double-encoded UTF-8 (27+ character patterns) |
+| `fc_folder_diff` | Track directory changes with snapshots (new/modified/deleted) |
+| `fc_batch_rename` | Pattern-based batch renaming (prefix/suffix, replace, auto-detect) |
+| `fc_convert_format` | Convert between JSON, CSV, INI, YAML, TOML, XML, and TOON formats |
+| `fc_detect_duplicates` | Find duplicate files using SHA-256 hashing |
+| `fc_checksum` | File hashing (MD5, SHA-1, SHA-256, SHA-512) with optional compare |
+
+### Archive (1 tool)
+
+| Tool | Description |
+|------|-------------|
+| `fc_archive` | Create, extract, and list ZIP archives |
+
+### OCR (1 tool)
+
+| Tool | Description |
+|------|-------------|
+| `fc_ocr` | Extract text from images via tesseract.js (optional dependency) |
+
+### System (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `fc_get_time` | Get current system time with timezone info |
+| `fc_set_safe_mode` | Toggle safe mode: all deletes go through Recycle Bin / Trash |
+
+### Export (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `fc_md_to_html` | Markdown to standalone HTML with CSS styling (headers, code blocks, tables, nested lists, blockquotes, images, checkboxes) |
+| `fc_md_to_pdf` | Markdown to PDF via headless browser (Edge/Chrome). Falls back to HTML if no browser is available |
+
+**Total: 43 tools**
+
+---
+
+## Comparison with Alternatives
+
+| Feature | FileCommander | [Desktop Commander](https://github.com/wonderwhy-er/DesktopCommanderMCP) | [Official Filesystem](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) |
+|---------|:---:|:---:|:---:|
+| File read/write/copy/move | 14 tools | Yes | Yes |
+| Safe delete (Recycle Bin) | Yes | No | No |
+| Async background search | 5 tools | No | No |
+| Interactive sessions (REPL) | 5 tools | Yes | No |
+| Process management | 4 tools | Yes | No |
+| Shell command execution | Yes | Yes | No |
+| String replace with validation | Yes | Yes | No |
+| Line-based file editing | Yes | No | No |
+| JSON repair & validation | 2 tools | No | No |
+| Encoding fix (Mojibake) | Yes | No | No |
+| Duplicate detection (SHA-256) | Yes | No | No |
+| Folder diff / change tracking | Yes | No | No |
+| Batch rename (pattern-based) | Yes | No | No |
+| Format conversion (JSON/CSV/INI/YAML/TOML/XML/TOON) | Yes | No | No |
+| ZIP archive (create/extract/list) | Yes | No | No |
+| File checksums (SHA-256/MD5) | Yes | No | No |
+| OCR (image to text) | Optional | No | No |
+| Safety mode (delete → Recycle Bin) | Yes | No | No |
+| Path allowlist / sandboxing | No | No | Yes |
+| Excel / PDF support | PDF (via browser) | Yes | No |
+| HTTP transport | No | No | No |
+| Markdown to HTML/PDF export | Yes | No | No |
+| **Total tools** | **43** | ~15 | ~11 |
+| **Servers needed** | **1** | 1 | + extra for processes |
+
+**Key differentiators:**
+- Only MCP server with **recoverable delete** (Recycle Bin / Trash)
+- Only MCP server with **async background search** with pagination
+- Built-in **JSON repair**, **encoding fix**, and **duplicate detection**
+- Most comprehensive single-server solution (43 tools)
+- Built-in **safety mode** to prevent accidental permanent deletion
+
+---
+
+## Tool Prefix
+
+All tools use the `fc_` prefix (FileCommander) to avoid conflicts with other MCP servers.
+
+---
+
+## Security
+
+**This server has full filesystem access with the running user's permissions.**
+
+See [SECURITY.md](SECURITY.md) for detailed security information and recommendations.
+
+Key points:
+- `fc_execute_command` runs arbitrary shell commands
+- `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)
+- No built-in sandboxing - security is delegated to the MCP client layer
+- Designed for local use via stdio transport only
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Watch mode (auto-rebuild on changes)
+npm run dev
+
+# One-time build
+npm run build
+
+# Start the server
+npm start
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for the full version history.
+
+---
+
+## License
+
+[MIT](LICENSE) - Lukas (BACH)

package/SECURITY.md

@@ -0,0 +1,54 @@
+# Security Policy
+
+## Important Security Notice
+
+**This MCP server has full filesystem access with the permissions of the running user.**
+
+By design, this server provides LLMs with powerful system access capabilities. Please understand the security implications before using it.
+
+### High-Risk Tools
+
+| Tool | Risk | Description |
+|------|------|-------------|
+| `fc_execute_command` | **Critical** | Executes arbitrary shell commands |
+| `fc_start_process` | **High** | Starts background processes |
+| `fc_kill_process` | **High** | Can terminate any accessible process |
+| `fc_delete_file` | **High** | Permanently deletes files (no recycle bin) |
+| `fc_delete_directory` | **High** | Recursively deletes directories |
+| `fc_write_file` | **Medium** | Can overwrite any accessible file |
+| `fc_ocr` | **Low** | Reads images (optional tesseract.js) |
+| `fc_archive` | **Medium** | Creates/extracts ZIP archives |
+| `fc_checksum` | **Low** | Computes file hashes (read-only) |
+
+### Recommendations
+
+1. **Enable Safety Mode** via `fc_set_safe_mode(true)` to route all delete operations through Recycle Bin / Trash automatically.
+
+2. **Use `fc_safe_delete`** instead of `fc_delete_file`/`fc_delete_directory` when possible - it moves items to the Recycle Bin instead of permanent deletion.
+
+3. **Be cautious with `fc_execute_command`** - it runs commands with your full user permissions. Review commands before approving execution in your MCP client.
+
+4. **Do not expose this server to untrusted networks.** It is designed for local use via stdio transport only.
+
+5. **Review your MCP client's approval settings.** Most MCP clients (like Claude Desktop) prompt before executing destructive operations. Keep these prompts enabled.
+
+### No Sandbox
+
+This server does **not** implement:
+- Path restrictions or allowlists
+- Command filtering or blocklists
+- Rate limiting
+- Audit logging
+
+These are intentional design decisions to keep the server simple and flexible. Security is delegated to the MCP client layer.
+
+### Reporting Vulnerabilities
+
+If you discover a security vulnerability, please open an issue on the GitHub repository. For sensitive disclosures, please use GitHub's private vulnerability reporting feature.
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.7.x   | Yes       |
+| < 1.7   | No        |

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,59 @@
+# Third-Party Notices
+
+This project uses the following third-party packages:
+
+## Runtime Dependencies
+
+### @modelcontextprotocol/sdk
+- **License:** MIT
+- **Copyright:** Copyright (c) Anthropic, PBC
+- **Repository:** https://github.com/modelcontextprotocol/typescript-sdk
+
+### zod
+- **License:** MIT
+- **Copyright:** Copyright (c) Colin McDonnell
+- **Repository:** https://github.com/colinhacks/zod
+
+### adm-zip
+- **License:** MIT
+- **Copyright:** Copyright (c) 2012 Another-D-Mention Software and other contributors
+- **Repository:** https://github.com/cthackers/adm-zip
+
+### js-yaml
+- **License:** MIT
+- **Copyright:** Copyright (c) 2011-2015 by Vitaly Puzrin
+- **Repository:** https://github.com/nodeca/js-yaml
+
+### smol-toml
+- **License:** MIT
+- **Repository:** https://github.com/nicolo-ribaudo/smol-toml
+
+### fast-xml-parser
+- **License:** MIT
+- **Copyright:** Copyright (c) 2017 Amit Kumar Gupta
+- **Repository:** https://github.com/NaturalIntelligence/fast-xml-parser
+
+### @toon-format/toon
+- **License:** MIT
+- **Repository:** https://github.com/nicfontaine/toon
+
+## Development Dependencies
+
+### typescript
+- **License:** Apache-2.0
+- **Copyright:** Copyright (c) Microsoft Corporation
+- **Repository:** https://github.com/microsoft/TypeScript
+- **Note:** Used only for compilation. Not included in the distributed package.
+
+### @types/node
+- **License:** MIT
+- **Copyright:** DefinitelyTyped contributors
+- **Repository:** https://github.com/DefinitelyTyped/DefinitelyTyped
+
+## Node.js Built-in Modules
+
+This project uses Node.js built-in modules (`fs`, `path`, `child_process`, `util`) which are part of the Node.js runtime and licensed under the MIT License.
+
+---
+
+All listed licenses are permissive and compatible with this project's MIT License.

package/dist/i18n/de.d.ts

@@ -0,0 +1,3 @@
+import type { Translations } from './types.js';
+export declare const de: Translations;
+//# sourceMappingURL=de.d.ts.map

package/dist/i18n/de.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"de.d.ts","sourceRoot":"","sources":["../../src/i18n/de.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,eAAO,MAAM,EAAE,EAAE,YAwdhB,CAAC"}