ellmos FileCommander

ellmos FileCommander MCP Server

English | Deutsch | Español | 简体中文 | 日本語 | Русский | Français | हिन्दी | العربية | বাংলা | Português

The README navigation lists the documentation languages available in this repository. FileCommander runtime messages and formatted responses support German (de), English (en), Spanish (es), Chinese (zh), Japanese (ja), Russian (ru), French (fr), Hindi (hi), Arabic (ar), Bengali (bn), and Portuguese (pt). This runtime list is separate from README translation availability. It covers generated runtime messages and formatted tool responses; MCP tool titles, discovery descriptions, and schema descriptions remain static English. Set FC_LANGUAGE to one of the supported codes before starting the server, or call fc_set_language during an active MCP session. fc_get_language reports the active language and all eleven supported codes. Unset or unsupported FC_LANGUAGE values fall back to German (de). Date and time formatting follows the active locale.

*Part of the ellmos-ai family.*

-brightgreen.svg)

Quick Navigation:

1. Overview | 2. System Architecture | 3. End-to-End Execution Lifecycle | 4. Core Capabilities & Safety Invariants | 5. Target Personas & Discoverability | 6. Installation & Prerequisites | 7. Configuration & Client Setup | 8. Tools Overview (50 Tools) | 9. Comparative Matrix & Alternatives | 10. Tool Prefix & Naming Convention | 11. Governance & Runtime Invariants | 12. Security Architecture & Tool Risks | 13. Testing, Quality Gates & Verification | 14. Changelog & Versioning | 15. Level 1 SBOM & Third-Party Licenses | 16. History & Evolution | 17. ellmos-ai Ecosystem & Partner Matrix | 18. Statutory Notice (§ 521 BGB) & Liability Disclaimer

| Direct References: 🛡️ Security Policy • 🤝 Contributing • ⚖️ Third-Party Licenses • 📄 Plain Text SBOM • 🤖 LLM Context (llms.txt) • 📋 Canonical Notice |

A comprehensive Model Context Protocol (MCP) server that gives AI assistants full filesystem access, bounded multi-file content search, process management, interactive shell sessions, and async filename search capabilities.

50 tools in a single server - everything an AI agent needs to interact with the local system.

Discovery keywords: local filesystem MCP server, multi-file content search MCP, safe delete MCP, Recycle Bin MCP server, process management MCP, interactive shell MCP, async file search for AI agents, cloud-lock-safe file operations, Markdown to PDF MCP, OCR MCP server, ZIP archive MCP.

Registry status: published on npm, indexed by jsDelivr, visible on LobeHub, listed on Glama, and prepared for the official MCP Registry via server.json. Some third-party directories still show older 43-tool metadata, so the canonical README/npm metadata should remain the source of truth until their reindex catches up.

[!NOTE]

For AI Agents & LLM Integrations:

FileCommander provides 50 specialized tools accessible via standard stdio transport. All tool names use the fc_ prefix to prevent namespace collisions. For LLMs, compact context and schema overviews are available in llms.txt and server.json.

---

Overview & 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
• Explicit Content Search - Search literal text or regex across a bounded list of files without recursion or glob expansion
• 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 - MD5, SHA-1, SHA-256, SHA-384, and 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
• Cloud-Lock Safe - Automatic copy+delete fallback when cloud sync filters (OneDrive, Dropbox, Google Drive, iCloud) block rename operations
• Cloud Lock Diagnosis - Check whether a path is at risk of sync-filter conflicts before operating
• Cross-platform - Works on Windows, macOS, and Linux with platform-specific optimizations

---

System Architecture

ASCII Four-View Architectural Topology

+--------------------------------------------------------------------------------------------------+

| ELLMOS FILECOMMANDER MCP ARCHITECTURAL TOPOLOGY | +--------------------------------------------------------------------------------------------------+ | [VIEW 1: CALLER RUNTIMES & AGENT CLIENTS] | | * Autonomous Agents : Claude Code, OpenAI Codex, Antigravity / Gemini, Kimi, Cursor | | * Agent Frameworks : AutoGen, CrewAI, LangChain, LlamaIndex, Custom Python / TS Clients | | * Transport Protocols : Model Context Protocol (MCP stdio), JSON-RPC 2.0 Framing | | * Tool Surface : 50 Unified Specialized Tools (fc_* namespace collision isolation) | | * Schema Contract : Stdio transport, dynamic runtime i18n parameter parsing (Zod validated)| +--------------------------------------------------------------------------------------------------+ | | | | v | +--------------------------------------------------------------------------------------------------+ | [VIEW 2: FILECOMMANDER MCP CORE ENGINE & DISPATCH ORCHESTRATOR] | | * Protocol Dispatch : ESM stdio router with Zod schema validation & parameter checking | | * Multilingual Core : 11-language dynamic runtime i18n engine | | * Safety Interceptor : Global Safety Mode (fc_set_safe_mode) routing deletes to Recycle Bin | | * Sync Diagnostics : Reparse point detection & cloud filter diagnostics (fc_check_cloud_lock)| | * Process Supervisor : Bounded child process lifecycle management & interactive REPL session | | state registry with circular ring buffers | +--------------------------------------------------------------------------------------------------+ | | | | v | +--------------------------------------------------------------------------------------------------+ | [VIEW 3: FILESYSTEM RUNTIME, FORMAT REPAIR & PROCESS ISOLATION] | | * Atomic File Ops : Read, write, line edit, exact literal string replacement (fc_str_replace)| | * Cloud-Lock Fallback : Automatic copyFileSync + SHA-256 verify + unlinkSync on EPERM / EBUSY | | * Bounded Inspection : Metadata-first preview (fc_preview_file, 1 MiB inline content ceiling) | | * Bounded Content Srch: max 50 explicit files, 10 MB ceiling, token redaction (INV-MASK-06) | | * Self-Healing Repair : Mojibake repair (27+ UTF-8 patterns), JSON syntax fix, file cleanup | | * Lossless Converter : Declarative transformation across 7 formats (JSON, YAML, TOML, XML...) | | * Media & Documents : Headless Markdown to PDF/HTML, ZIP archive engine, optional OCR (Tess) | +--------------------------------------------------------------------------------------------------+ | | | | v | +--------------------------------------------------------------------------------------------------+ | [VIEW 4: AIR-GAP DEFENSE PERIMETER, RUNASINVOKER & CONTROLLED EGRESS] | | * Execution Privilege : RunAsInvoker unprivileged user-mode (Zero administrative elevation) | | * Transport Boundary : 100% Local stdio transport, zero telemetry, zero open listening ports | | * Controlled Egress : Outbound HTTP(S) strictly gated through caller-invoked fc_web_fetch | | * Network Safety : SSRF guard bloc