bach-filecommander-mcp 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [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,225 @@
+# BACH FileCommander MCP Server
+
+[![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.
+
+**29 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
+- **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 |
+
+### System (1 tool)
+
+| Tool | Description |
+|------|-------------|
+| `fc_get_time` | Get current system time with timezone info |
+
+**Total: 29 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 |
+| Path allowlist / sandboxing | No | No | Yes |
+| Excel / PDF support | No | Yes | No |
+| HTTP transport | No | No | No |
+| **Total tools** | **29** | ~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
+- Most comprehensive single-server solution (29 tools)
+
+---
+
+## 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 (use `fc_safe_delete` for recoverable deletion)
+- 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,49 @@
+# 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 |
+
+### Recommendations
+
+1. **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.
+
+2. **Be cautious with `fc_execute_command`** - it runs commands with your full user permissions. Review commands before approving execution in your MCP client.
+
+3. **Do not expose this server to untrusted networks.** It is designed for local use via stdio transport only.
+
+4. **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.3.x   | Yes       |
+| < 1.3   | No        |

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,36 @@
+# 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
+
+## 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/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * BACH FileCommander MCP Server
+ *
+ * A comprehensive MCP server for filesystem access, process management,
+ * interactive sessions, and async file search.
+ *
+ * Copyright (c) 2025-2026 Lukas (BACH). Licensed under MIT License.
+ * See LICENSE file for details.
+ *
+ * @author Lukas (BACH)
+ * @version 1.3.0
+ * @license MIT
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG"}