io.github.ellmos-ai由 GitHub 账号 ellmos-ai 发布v1.11.4更新于 Oct 29, 2026
Filesystem MCP server: files, previews, search, processes, OCR, archives, safe delete, web fetch.
本地 stdio MCP 服务器，让助手获得完整文件系统访问：读写、编辑、搜索、删除文件，并可管理进程、运行交互式会话和修复文件。
Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。
参照 仓库 中的启动说明。
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.
[License: MIT] [CI] [npm version] [Node.js] [MCP Tools] [Tests] [Security: Explicit Egress] [Security: 48h SLA] [Safe Delete] [Attribution: NOTICE] [Unprivileged RunAsInvoker] [Third-Party Audited] [Level 1 SBOM: Plain Text] [ellmos-ai] [open-bricks] [Discovery: llms.txt] [Last-Checked] [Verified]
Quick Navigation:
- 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 inllms.txtandserver.json.
Most filesystem MCP servers only cover basic read/write operations. FileCommander goes further:
FileCommander is purpose-built and validated for four core developer, agentic, and operations personas:
EPERM/EBUSY) in cloud-synced folders, and unrecoverable repository corruption from accidental rm -rf cleanup routines.fc_preview_file: Metadata-first inspection with strict 1 MiB inline content ceiling preventing LLM context blowout.fc_search_content: Bounded multi-file search (max 50 files, 10 MB per file, 200 matches) with automatic secret/token redaction.fc_safe_delete & fc_set_safe_mode: Preserves deleted files in OS Recycle Bin / Trash for zero-risk file operations.fc_move & fc_check_cloud_lock: Automatic copy + SHA-256 verify + unlink fallback on file locks, preventing agent failure.fc_start_session, fc_send_input, fc_read_output) with bounded circular ring buffers.fc_batch_rename) and background directory search (fc_start_search, fc_get_search_results).fc_execute_command, fc_start_process, fc_kill_process) without process leaks.fc_web_fetch (internal/private IPs blocked by default).INV-MASK-06).INV-PROC-09) and binding 48-hour vulnerability response SLA ([email protected], [email protected]).fc_convert_format: JSON, YAML, TOML, XML, CSV, INI, TOON).fc_fix_encoding, fc_fix_json, fc_cleanup_file) for self-healing pipelines.fc_checksum: SHA-256, SHA-512, MD5, SHA-1) and Markdown to PDF/HTML rendering (fc_md_to_pdf, fc_md_to_html).ellmos-filecommander-mcp, FileCommander MCP, filesystem MCP server, multi-file content search MCP, safe delete MCP, async file search MCP, process management MCP, Markdown PDF MCP.llms.txt, server.json, and glama.json.THIRD_PARTY_LICENSES.md and NOTICE.
Add to your claude_desktop_config.json:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Restart Claude Desktop after saving.
The server communicates via stdio transport. Point your MCP client to the dist/index.js entry point or the ellmos-filecommander binary.
fc_preview_file is the remote/headless fallback for local files. Its default call returns structured metadata only: resolved path, file:// URI, MIME type, byte size, preview kind, fixed 1 MiB limit, and the exact follow-up call. Content is read only after include_content=true. Eligible text and raster images use standard MCP text/image content blocks; PDFs use a bounded embedded resource. Files above 1 MiB and unsupported types remain metadata-only and are never read or Base64-encoded by the preview path.
fc_search_content never expands globs, traverses directories, or recursively discovers files. It accepts at most 50 explicit UTF-8 text files, skips binary and files over 10 MB, and returns deterministic JSON. Matches are limited to 200 globally and 100 per file, context to 10 lines, excerpts to 500 characters, and serialized output to 200,000 characters. Missing, cloud-only, permission, encoding, binary, and size failures are reported per file so readable files still produce results. Common secret formats are redacted from excerpts.
fc_open_path accepts only an existing file or directory and sends it to a fixed native default-handler launcher. Its structured result reports launcher_accepted=true|false, always reports user_visible="unknown", and identifies a machine-readable fallback: fc_preview_file with metadata-only arguments for files or fc_list_directory for directories. Launcher acceptance never claims that a GUI became visible. fc_start_process instead lets the caller choose an executable and arguments. fc_execute_command accepts an arbitrary shell command: Node's default shell is used for ordinary commands (COMSPEC/cmd.exe on Windows), while FileCommander's Windows special-character path can route through Windows PowerShell.
Total: 50 tools
FileCommander combines filesystem manipulation, bounded search, process control, data repair, format conversion, and document rendering into a single unified MCP interface. Below is an architectural comparison against standard alternatives across 10 key operational dimensions:
Key differentiators:
All tools use the fc_ prefix (FileCommander) to avoid conflicts with other MCP servers.
The server enforces 10 strict runtime invariants guaranteeing safety, predictability, and least privilege:
This server has full filesystem access with the running user's permissions.
See SECURITY.md for detailed security information and recommendations.
Key points:
fc_execute_command runs arbitrary shell commandsfc_open_path invokes the operating system's associated application for a caller-selected existing path; that application runs with the user's permissionsfc_open_path reports launcher acceptance separately from the invariant user_visible="unknown"; fc_preview_file is the metadata-first remote fallback with an explicit 1 MiB inline-content boundaryfc_start_session starts an arbitrary interactive command, and subsequent fc_send_input calls can execute additional actionsfc_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)fc_delete_file and fc_delete_directory; it does not sandbox commands or interactive sessionsfc_web_fetch call performs outbound HTTP(S) access
The project includes 250 Vitest tests plus 71 standalone i18n checks (321 total) covering filesystem operations, metadata-first inline preview, bounded content search, native default-handler launching, format conversion, encoding repair, archive handling, duplicate detection, language packs, tool annotations, real stdio behavior, and security boundaries.
Tests are verified on Windows, macOS, and Linux.
Pushes and pull requests run CI on Node.js 20, 22, and 24 with npm ci, TypeScript build, Vitest, and an npm package dry-run.
See CONTRIBUTING.md for contribution guidelines.
See CHANGELOG.md for the full version history.
MIT - Lukas Geiger (ellmos-ai). See NOTICE for open-bricks umbrella attribution, THIRD_PARTY_LICENSES.md for Level 1 SBOM, and THIRD_PARTY_LICENSES.txt for plain-text SBOM.
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 organization.
The legacy package name bach-filecommander-mcp is deprecated. Please use ellmos-filecommander-mcp instead:
This MCP server is part of the ellmos-ai ecosystem — AI infrastructure, MCP servers, and intelligent tools.
Our partner organization open-bricks and its line organizations provide AI-native desktop applications and developer utilities:
Dieses Projekt ist eine unentgeltliche Open-Source-Schenkung im Sinne der §§ 516 ff. BGB (Gefälligkeitsrecht). Die Haftung des Urhebers und der Mitwirkenden ist gemäß § 521 BGB auf Vorsatz und grobe Fahrlässigkeit beschränkt. Ergänzend gilt der Haftungsausschluss der MIT-Lizenz.
Nutzung auf eigenes Risiko. Keine Wartungszusage, keine Verfügbarkeitsgarantie, keine Gewähr für Fehlerfreiheit oder Eignung für einen bestimmten Zweck.
Sicherheitsrelevante Vorfälle und Schwachstellen werden über das verbindliche 48-Stunden-SLA unter [email protected] und [email protected] entgegengenommen und innerhalb von 5 Werktagen triagiert.
This project is an unpaid open-source donation under German law (§§ 516 et seq. BGB). Liability is strictly limited to intent and gross negligence (§ 521 German Civil Code). The MIT license disclaimer applies complementarily. Use at your own risk. No warranty, no maintenance guarantee, no fitness-for-purpose assumed.
Security incidents and vulnerabilities are handled under a binding 48-hour response SLA via [email protected] and [email protected] with formal triage within 5 business days.
来源：README.md，提交 fca3268
Read File
Reads the content of a file. Args: - path (string): Full path to the file - encoding (string, optional): Character encoding (default: utf-8) - max_lines (number, optional): Maximum number of lines (0 = all) Returns: - File content as text - For binary files: Base64-encoded content Examples: - path: "C:\Users\User\test.txt" - path: "/home/user/config.json"
path必填encodingmax_linesWrite File
Writes content to a file. Creates the file if it does not exist. Args: - path (string): Full path to the file - content (string): Content to write - append (boolean, optional): Append to file instead of overwriting - create_dirs (boolean, optional): Create missing directories Returns: - Confirmation with file size Warning: Overwrites existing files without warning when append=false!
path必填appendcontent必填create_dirsList Directory
Lists files and subdirectories. Args: - path (string): Path to the directory - depth (number, optional): Maximum depth for recursive listing (default: 1) - show_hidden (boolean, optional): Show hidden files Returns: - Formatted list of all entries with icons
path必填depthshow_hiddenCreate Directory
Creates a new directory (including parent directories). Args: - path (string): Path to the new directory Returns: - Confirmation of creation
path必填Delete File
Deletes a file. Args: - path (string): Path to the file Warning: Irreversible! No recycle bin.
path必填Delete Directory
Deletes a directory. Args: - path (string): Path to the directory - recursive (boolean): Delete non-empty directories too Warning: With recursive=true ALL contents are irreversibly deleted!
path必填recursiveMove/Rename
Moves or renames a file/directory. Args: - source (string): Source path - destination (string): Destination path Examples: - Rename: source="test.txt", destination="test_new.txt" - Move: source="C:\a\test.txt", destination="C:\b\test.txt"
source必填destination必填Copy
Copies a file or directory. Args: - source (string): Source path - destination (string): Destination path - recursive (boolean): Copy directories recursively
source必填recursivedestination必填File Information
Shows detailed information about a file/directory. Args: - path (string): Path to the file/directory Returns: - Size, type, creation/modification date, permissions
path必填Search Files
Searches files by name/pattern in a directory. Args: - directory (string): Start directory for the search - pattern (string): Search pattern (supports * and ? wildcards) - max_results (number, optional): Maximum results (default: 50) Examples: - pattern: "*.txt" - All text files - pattern: "test*" - Files starting with "test" - pattern: "*.py" - All Python files
pattern必填directory必填max_resultsSearch File Content
Durchsucht ausschließlich explizit übergebene Dateien nach Text. Standardmäßig literal, optional mit regulärem Ausdruck; deterministische begrenzte JSON-Ausgabe, dateibezogene Teilfehler, Binärdatei-Skip, Kontextzeilen und Geheimnis-Redaktion. Keine Glob-Auflösung und keine Verzeichnisrekursion.
paths必填query必填regexmax_resultscontext_linescase_sensitivemax_results_per_fileStart Async Search
Starts a background search. Claude can perform other tasks in the meantime. Args: - directory (string): Start directory - pattern (string): Search pattern (wildcards: * and ?) Returns: - Search ID for fc_get_search_results, fc_stop_search Example: Start search: fc_start_search("C:\Users", "*.pdf") Get results later: fc_get_search_results(search_id)
pattern必填directory必填Get Search Results
Retrieves results of a running or completed search. Args: - search_id (string): Search ID from fc_start_search - offset (number, optional): Start offset for pagination - limit (number, optional): Maximum number of results (default: 50) Returns: - Search status and found files
limitoffsetsearch_id必填Stop Search
Stops a running background search. Args: - search_id (string): Search ID
search_id必填List Searches
Lists all active and completed background searches.
无需输入参数。
Clear Search
Removes a completed search from the list and frees memory. Args: - search_id (string): Search ID (or "all" for all completed)
search_id必填Safe Delete (Recycle Bin)
Moves files/directories to recycle bin instead of deleting them. Args: - path (string): Path to the file/directory SAFE: Can be restored from the recycle bin! Note: Uses Windows recycle bin or creates backup on other systems.
path必填Execute Command
Executes a shell command and returns the output. Args: - command (string): Command to execute - cwd (string, optional): Working directory - timeout (number, optional): Timeout in milliseconds (default: 30000) Warning: Commands are executed with user privileges! Examples: - command: "dir" (Windows) - command: "ls -la" (Unix) - command: "python --version"
cwdcommand必填timeoutStart Process
Starts a process in the background (non-blocking). Args: - program (string): Program/Executable - args (array, optional): Arguments as array - cwd (string, optional): Working directory Examples: - program: "notepad.exe", args: ["test.txt"] - program: "python", args: ["script.py"] - program: "code", args: ["."] (open VS Code)
cwdargsprogram必填Open Path
Startet für eine vorhandene lokale Datei oder einen Ordner die Standardanwendung. Die strukturierte Rückgabe trennt launcher_accepted von user_visible=unknown und nennt einen Remote-Fallback.
path必填Preview File
Liefert zuerst MIME-Typ, Größe und Vorschaufähigkeit einer lokalen Datei. Inhalt wird nur nach include_content=true und nur bis zum festen Inline-Limit als MCP-Text-, Bild- oder Resource-Content zurückgegeben.
path必填include_contentCurrent Time
Returns the current system time. Returns: - Date, time, weekday, timezone
无需输入参数。
Read Multiple Files
Reads multiple files at once and returns their contents. Args: - paths (array): Array of file paths - max_lines_per_file (number, optional): Max lines per file (0 = all) Returns: - Contents of all files with separators Example: paths: ["C:\config.json", "C:\readme.md"]
paths必填max_lines_per_fileEdit File (Lines)
Edits a file line-based: replace, insert, or delete. Args: - path (string): Path to the file - operation (string): "replace" | "insert" | "delete" - start_line (number): Start line (1-based) - end_line (number, optional): End line for replace/delete - content (string, optional): New content for replace/insert Examples: - Replace lines 5-10: operation="replace", start_line=5, end_line=10, content="new text" - Insert after line 3: operation="insert", start_line=3, content="new line" - Delete lines 7-9: operation="delete", start_line=7, end_line=9
path必填contentend_lineoperation必填start_line必填String Replace in File
Replaces a unique string in a file with another. Args: - path (string): Path to the file - old_str (string): String to replace (must occur exactly once) - new_str (string): New string (empty = delete) Returns: - Confirmation with context IMPORTANT: old_str must occur EXACTLY once in the file! An error is returned for 0 or >1 occurrences. Examples: - Rename function: old_str="def old_name", new_str="def new_name" - Add import: old_str="import os", new_str="import os\nimport sys" - Delete line: old_str="# TODO: remove this\n", new_str=""
path必填new_strold_str必填List Processes
Lists running system processes. Args: - filter (string, optional): Filter by process name Returns: - List of processes with PID, name, memory Note: Uses 'tasklist' (Windows) or 'ps' (Unix)
filterKill Process
Terminates a process by PID or name. Args: - pid (number, optional): Process ID - name (string, optional): Process name - force (boolean): Force termination Warning: May cause data loss!
pidnameforceStart Interactive Session
Starts an interactive process as a session (for fc_read_output and fc_send_input). Args: - command (string): Command/Program - args (array, optional): Arguments - cwd (string, optional): Working directory Returns: - Session ID for further interaction Examples: - Python REPL: command="python" - Node REPL: command="node" - PowerShell: command="powershell"
cwdargscommand必填Read Session Output
Reads the output of a running session. Args: - session_id (string): Session ID from fc_start_session - clear (boolean, optional): Clear output after reading Returns: - Collected output since start/last clear
clearsession_id必填Send Input to Session
Sends input to a running session. Args: - session_id (string): Session ID - input (string): Input to send - newline (boolean, optional): Append newline (default: true) Examples: - Python: input="print('Hello')" - Shell: input="ls -la"
input必填newlinesession_id必填List Sessions
Lists all active and ended sessions. Returns: - Table of all sessions with status
无需输入参数。
Close Session
Terminates a running session and removes it from the list. Args: - session_id (string): Session ID - force (boolean, optional): Force termination
forcesession_id必填Fix JSON
Automatically repairs common JSON errors. Args: - path (string): Path to the JSON file - dry_run (boolean, optional): Only show problems, do not repair - create_backup (boolean, optional): Create backup before repair Repairs: BOM, trailing commas, single quotes, comments, NUL bytes
path必填dry_runcreate_backupValidate JSON
Validates a JSON file and shows detailed error information. Args: - path (string): Path to the JSON file Returns: - Validation status with line/column on errors
path必填Cleanup File
Cleans up one or more files from common problems. Args: - path (string): Path to file or directory - recursive (boolean, optional): Recursive for directories - extensions (string, optional): Filter file extensions (e.g. ".txt,.json,.py") - remove_bom (boolean): Remove UTF-8 BOM - remove_trailing_whitespace (boolean): Remove trailing whitespace - normalize_line_endings (string, optional): "lf" | "crlf" | null - remove_nul_bytes (boolean): Remove NUL bytes - dry_run (boolean): Preview only Cleans: BOM, NUL bytes, trailing whitespace, line endings
path必填dry_runrecursiveextensionsremove_bomremove_nul_bytesnormalize_line_endingsremove_trailing_whitespaceFix Encoding
Detects and repairs encoding errors (mojibake, double UTF-8). Args: - path (string): Path to the file - dry_run (boolean): Only show problems - create_backup (boolean): Create backup Repairs common mojibake patterns like: - ä -> ae, ö -> oe, ü -> ue (German umlauts) - ß -> ss, € -> EUR
path必填dry_runcreate_backupFolder Diff
Compares the current state of a directory with a saved snapshot. Args: - path (string): Path to the directory - save_snapshot (boolean): Save current state as new snapshot - extensions (string, optional): Filter file extensions Detects: New files, modified files, deleted files Snapshots are saved in %TEMP%/.fc_snapshots/
path必填extensionssave_snapshotBatch Rename
Renames files by pattern: remove prefix/suffix, replace, or auto-detect. Args: - directory (string): Directory with the files - mode (string): "remove_prefix" | "remove_suffix" | "replace" | "auto_detect" - pattern (string, optional): Text to remove/replace - replacement (string, optional): Replacement text (for replace mode) - extensions (string, optional): Filter by extensions - dry_run (boolean): Preview only Examples: - Remove prefix: mode="remove_prefix", pattern="backup_" - Auto-detect: mode="auto_detect" detects common prefixes
mode必填dry_runpatterndirectory必填extensionsreplacementConvert Format
Converts files between different formats. Args: - input_path (string): Path to source file - output_path (string): Path to target file - input_format (string): "json" | "csv" | "ini" | "yaml" | "toml" | "xml" | "toon" - output_format (string): "json" | "csv" | "ini" | "yaml" | "toml" | "xml" | "toon" - json_indent (number, optional): JSON indentation (default: 2) Supported conversions: - JSON <-> CSV (for arrays of objects) - JSON <-> INI (for flat objects/sections) - JSON <-> YAML - JSON <-> TOML - JSON <-> XML - JSON <-> TOON (hierarchical key-value format) - JSON pretty-print / minify
input_path必填json_indentoutput_path必填input_format必填output_format必填Detect Duplicates
Finds file duplicates in a directory using SHA-256 hashes. Args: - directory (string): Directory to scan - recursive (boolean): Search recursively - extensions (string, optional): Filter by extensions - min_size (number, optional): Minimum size in bytes (default: 1) - max_size (number, optional): Maximum size in bytes Returns: - Groups of duplicates with paths and sizes
max_sizemin_sizedirectory必填recursiveextensionsMarkdown to HTML
Converts Markdown to formatted HTML (printable as PDF). Args: - input_path (string): Path to Markdown file - output_path (string): Path to HTML output - title (string, optional): Document title Generates standalone HTML with CSS styling, printable as PDF via browser.
titleinput_path必填output_path必填Markdown to PDF
Converts Markdown to PDF using a headless browser (Edge/Chrome). Args: - input_path (string): Path to the Markdown file - output_path (string): Path to the PDF output - title (string, optional): Document title Uses the same Markdown parser as fc_md_to_html. Requires Edge or Chrome. Falls back to HTML if no browser is found.
titleinput_path必填output_path必填OCR - Text from Image/PDF
Extrahiert Text aus Bildern (JPG/PNG/BMP/TIFF) mittels OCR (Tesseract).
languagefile_path必填output_pathArchive (ZIP)
Erstellt, entpackt und listet ZIP-Archive.
action必填extract_toarchive_path必填source_pathsFile Checksum
Berechnet Prüfsummen (MD5/SHA1/SHA256/SHA512) für Dateien.
comparealgorithmfile_path必填Web Fetch
Ruft eine Webseite ab und gibt je nach Modus Inhalt zurück: extract (sauberer Haupttext), raw (HTTP-Body, gekürzt), links, forms oder headers. Nur lesendes Netzwerk-Tool; interne/private Ziele sind standardmäßig blockiert (allow_private zum Überschreiben).
url必填modeallow_privatetimeout_secondsSet Safe Mode
Aktiviert/deaktiviert den Safe Mode. Wenn aktiv, werden alle Löschoperationen (fc_delete_file, fc_delete_directory) über den Papierkorb umgeleitet.
enabled必填Set Language
Set the output language for FileCommander tools
language必填Get Language
Get the active output language and all supported language codes
无需输入参数。
Check Cloud Lock
Meldet statischen Cloud-Sync-Kontext und verfügbaren Zielzustand. Sie behauptet keine aktive Sperre. Nur auf Windows relevant.
path必填已满足适用检查项的 90%
该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。
请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。
+--------------------------------------------------------------------------------------------------+| 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 blocking private/internal IP ranges (allow_private override) || * Governance & Supply : Level 1 SBOM, 100% permissive runtime (MIT/BSD), 48h Security SLA |+--------------------------------------------------------------------------------------------------+flowchart TD subgraph Client["MCP Client Layer"] Claude["Claude Desktop / Claude Code"] Custom["Custom LLM Agents / Frameworks"] end
subgraph Transport["Transport Layer"] Stdio["Stdio Transport (JSON-RPC)"] end
subgraph Core["ellmos FileCommander Engine (50 Tools)"] FS["Filesystem Engine\n(15 tools: read, bounded preview, write, edit, safe-delete, cloud-lock safe)"] Search["Search Engine\n(6 tools: explicit content search plus 5 async filename-search tools)"] Proc["Process & REPL Sessions\n(10 tools: exec, default-app opening, background proc, interactive REPLs)"] Repair["Repair & Format Converter\n(9 tools: JSON fix, Mojibake fix, duplicates, format convert, checksum)"] Export["Export & Web Fetch\n(3 tools: Markdown->HTML/PDF, web_fetch)"] Sys["System, Utilities & i18n\n(7 tools: OCR, ZIP, cloud-lock check, safe-mode, time, language set/get)"] end
Client -->|JSON-RPC| Stdio Stdio --> Core Core --> FS Core --> Search Core --> Proc Core --> Repair Core --> Export Core --> SyssequenceDiagram autonumber participant AI as AI Assistant (Client) participant FC as FileCommander Engine participant FS as Host Filesystem participant Trash as Recycle Bin / Trash participant Cloud as Cloud Sync Filter
Note over AI,FC: 1. Safe Deletion & Recovery Protection AI->>FC: fc_delete_file / fc_safe_delete(targetPath) alt Safety Mode Active or fc_safe_delete invoked FC->>Trash: Move item to Recycle Bin / Trash Trash-->>FC: Moved safely (recoverable) FC-->>AI: Success (item preserved in Trash/Recycle Bin) else Permanent Unlink requested FC->>FS: Direct unlink FS-->>FC: Removed permanently FC-->>AI: Success end
Note over AI,Cloud: 2. Resilient Cloud-Lock Handling (OneDrive/Dropbox) AI->>FC: fc_move(sourcePath, destPath) alt Cloud Filter Locks Destination FC->>Cloud: Attempt standard rename Cloud-->>FC: EPERM / EBUSY (Cloud Filter Error) FC->>FS: Fallback: copyFileSync + SHA-256 verify FC->>FS: unlinkSync source FC-->>AI: Move succeeded via resilient fallback else Local Native Filesystem FC->>FS: Rename (atomic) FS-->>FC: Done FC-->>AI: Move succeeded endnpm install -g ellmos-filecommander-mcpgit clone https://github.com/ellmos-ai/ellmos-filecommander-mcp.gitcd ellmos-filecommander-mcpnpm cinpm run build{ "mcpServers": { "filecommander": { "command": "ellmos-filecommander" } }}{ "mcpServers": { "filecommander": { "command": "node", "args": ["/absolute/path/to/filecommander-mcp/dist/index.js"] } }}# Install dependenciesnpm ci
# Watch mode (auto-rebuild on changes)npm run dev
# One-time buildnpm run build
# Start the servernpm start
# Run test suitenpm testnpm test # Run all testsnode test-i18n.mjs # Run standalone i18n checksnpx vitest run # Same as abovenpx vitest --watch # Watch modenpm uninstall -g bach-filecommander-mcpnpm install -g ellmos-filecommander-mcp