ellmos FileCommander

ellmos FileCommander MCP 服务

🇩🇪 德语版

属于 ellmos-ai 系列。

快速导航：

1. 概览 | 2. 系统架构 | 3. 端到端执行生命周期 | 4. 核心能力与安全不变量 | 5. 目标用户与可发现性 | 6. 安装与前置条件 | 7. 配置与客户端设置 | 8. 工具概览（50 个工具） | 9. 对比矩阵与替代方案 | 10. 工具前缀与命名约定 | 11. 治理与运行时不变量 | 12. 安全架构与工具风险 | 13. 测试、质量门禁与验证 | 14. 变更日志与版本管理 | 15. 一级 SBOM 与第三方许可证 | 16. 历史与演进 | 17. ellmos-ai 生态与合作伙伴矩阵 | 18. 法定声明（§ 521 BGB）与责任免责声明

| 直接参考：🛡️ 安全政策 • 🤝 贡献指南 • ⚖️ 第三方许可证 • 📄 纯文本 SBOM • 📜 营销日志 • 🤖 LLM 上下文 (llms.txt) • 📋 规范声明 |

一款功能全面的 Model Context Protocol（MCP）服务，为 AI 助手提供完整的文件系统访问能力、有界的多文件内容搜索、进程管理、交互式 Shell 会话，以及异步文件名搜索功能。

单个服务包含 50 个工具——提供 AI Agent 与本地系统交互所需的一切。 发现关键词： 本地文件系统 MCP 服务、多文件内容搜索 MCP、安全删除 MCP、回收站 MCP 服务、进程管理 MCP、交互式 Shell MCP、面向 AI Agent 的异步文件搜索、云锁定安全文件操作、Markdown 转 PDF MCP、OCR MCP 服务、ZIP 压缩包 MCP。

注册状态： 已发布到 npm，已被 jsDelivr 编入索引，已在 LobeHub 展示，已在 Glama 列出，并通过 server.json 为提交到官方 MCP Registry 做好准备。一些第三方目录仍显示旧版的 43 个工具元数据，因此在它们完成重新索引之前，应以规范的 README/npm 元数据为准。

说明

面向 AI Agent 和大模型集成： FileCommander 提供 50 个专用工具，可通过标准 stdio 传输访问。所有工具名称均使用 fc_ 前缀，以防止命名空间冲突。大模型可在 llms.txt 和 server.json 中查看精简上下文和架构概览。

---

概述与为何选择 FileCommander？

大多数文件系统 MCP 服务只涵盖基本的读写操作。FileCommander 更进一步：

• 安全删除 - 将文件移至回收站（Windows）或废纸篓（macOS/Linux），而不是永久删除
• 交互式会话 - 通过 MCP 协议启动并交互式使用 REPL（Python、Node.js、Shell）
• 异步搜索 - 在 AI 继续工作的同时，在后台搜索大型目录树
• 显式内容搜索 - 在限定的文件列表中搜索字面文本或正则表达式，不进行递归或 glob 展开
• 进程管理 - 列出、启动和终止系统进程
• 字符串替换 - 通过匹配唯一字符串并验证上下文来编辑文件
• 格式转换 - 在 JSON、CSV、INI、YAML、TOML、XML 和 TOON 之间进行转换
• ZIP 压缩包 - 创建、解压和列出 ZIP 压缩包
• 文件校验和 - 支持 MD5、SHA-1、SHA-256、SHA-384 和 SHA-512 哈希及比较
• OCR - 从图像中提取文本（可选的 tesseract.js 依赖项）
• 安全模式 - 切换为通过回收站/废纸篓处理所有删除操作
• Markdown 导出 - 将 Markdown 转换为专业的 HTML/PDF，支持代码块、表格、嵌套列表和引用块
• 云锁定安全 - 当云同步筛选器（OneDrive、Dropbox、Google Drive、iCloud）阻止重命名操作时，自动回退为复制并删除
• 云锁定诊断 - 操作前检查路径是否有遭遇同步筛选冲突的风险
• 跨平台 - 可在 Windows、macOS 和 Linux 上运行，并针对各平台进行优化

---

系统架构

ASCII 四视图架构拓扑

+--------------------------------------------------------------------------------------------------+
|                            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   : 6-language dynamic runtime i18n (de, en, es, zh, ja, ru) 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 --> Sys

---

端到端执行生命周期

sequenceDiagram
    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
    end

---

核心能力与安全不变量

能力 / 不变量	保证与实现细节	安全与运维优势
本地 stdio 与显式出站请求	MCP 传输使用本地 stdio，不收集遥测数据，也不会自动向外发起网络请求。只有客户端显式调用 fc_web_fetch 时才会发出 HTTP(S) 请求；默认会阻止访问私有目标，除非启用 allow_private。	让客户端能够清楚了解网络边界，同时保留本地、无需端口的服务传输方式。
安全删除与回收站保护	fc_safe_delete 会将项目移至 Windows 回收站 / macOS 废纸篓 / Linux FreeDesktop 回收站。fc_set_safe_mode 会将所有删除操作安全地转至回收站。	防止意外递归删除或批量删除造成不可逆的数据丢失。
抗云锁移动（fc_move）	自动检测云同步筛选器（OneDrive、Dropbox、iCloud 重解析点），并在必要时无缝回退到复制 + 验证 + 删除。	消除 Agent 在同步目录中执行自动化操作时遇到的 EPERM / EBUSY 错误。
云锁诊断（fc_check_cloud_lock）	以只读方式报告静态云路径上下文以及目标是否存在和类型；如果无法检查，会明确报告未检查 Cloud Files 水合状态和进程句柄。	Agent 可以区分静态 OneDrive 风险与实际检测到的重命名锁。
有界多文件内容搜索	fc_search_content 严格限制输入（最多 50 个显式指定的文件、每个文件 10 MB、200 个匹配项、200k 个字符），且不进行 glob 递归。	防止在大型代码库搜索期间发生内存不足错误和灾难性的 CPU 卡死。
自动密钥与令牌脱敏	内容搜索摘录会自动遮蔽常见 API 密钥、Bearer 令牌、AWS 凭证和授权标头。	防止大模型上下文受到污染，并避免凭证意外泄露到提示词历史记录中。
交互式 REPL 与会话隔离	为 Python、Node.js、bash 和 PowerShell 提供有状态交互式会话（fc_start_session、fc_send_input、fc_read_output），并限制缓冲区大小。	支持多轮 REPL 调试，同时避免后台进程不受限制地累积。
无损多格式引擎	通过声明式转换（fc_convert_format）支持 7 种结构化格式（JSON、YAML、TOML、XML、CSV、INI、TOON）。	在不同配置格式间实现干净的数据规范化，同时避免数据丢失。
乱码与文件修复引擎	fc_fix_encoding、fc_fix_json 和 fc_cleanup_file 可修复损坏的 UTF-8 编码（27+ 种模式）、格式错误的 JSON 语法、BOM 和 NUL 字节。	为不同操作系统平台生成的损坏文件提供自修复工作流。
以非特权用户身份运行，不提权	专为标准非特权用户模式运行而设计并经过验证。绝不需要管理员或 root 权限。	最大限度缩小攻击面；遵循最小权限原则。
六种语言的运行时 i18n 引擎	支持动态切换语言并查询当前语言（fc_set_language、fc_get_language），涵盖德语（de）、英语（en）、西班牙语（es）、中文（zh）、日语（ja）和俄语（ru）。	提供原生多语言开发体验和本地化错误报告。
多操作系统验证矩阵	在 Windows、Ubuntu Linux 和 macOS 上使用 Node.js 20、22 和 24 进行测试，并通过 292 项自动化断言。	确保跨平台的一致性与可靠性。

---

目标用户画像与可发现性

FileCommander 专为四类核心开发者、Agent 和运维人员打造，并针对这些用户画像进行了验证：

[PERSONA-01] 自主 AI 编码 Agent 与 LLM 集群

• 概况： 多 Agent 集群和独立的 Agent 运行时（Claude Code、Antigravity/Gemini、OpenAI Codex、AutoGen、CrewAI），用于执行递归代码编辑、项目重构和目录审计。
• 主要运营痛点： 读取数 MB 文件导致上下文窗口迅速膨胀；云同步文件夹中的文件被锁定（EPERM/EBUSY）导致进程崩溃且未得到处理；意外运行 rm -rf 清理程序导致仓库损坏且无法恢复。
• FileCommander 解决方案：
  • fc_preview_file：优先检查元数据，并严格将内联内容限制在 1 MiB 以内，防止 LLM 上下文爆满。
  • fc_search_content：有界多文件搜索（最多 50 个文件、每个文件 10 MB、200 个匹配项），并自动脱敏机密信息和令牌。
  • fc_safe_delete 和 fc_set_safe_mode：将已删除文件保留在操作系统回收站／废纸篓中，实现零风险文件操作。
  • fc_move 和 fc_check_cloud_lock：文件被锁定时自动回退为复制 + SHA-256 校验 + 取消链接，避免 Agent 执行失败。

[PERSONA-02] DevOps、工具链与多主机自动化工程师

• 概况： 系统和自动化工程师，负责构建跨平台 CLI 工具、CI/CD 验证流水线，以及适用于 Windows、Linux 和 macOS 的多机同步脚本。
• 主要运营痛点： 不同操作系统的语义差异（Windows 反斜杠与 POSIX 正斜杠、行尾损坏、特定于 Shell 的语法）、僵尸子进程，以及共享 OneDrive/Dropbox 工作区中的文件锁定。
• FileCommander 解决方案：
  • 在 Windows、Linux 和 macOS 上提供统一的跨平台工具语义。
  • 提供有状态的交互式 REPL 会话（fc_start_session、fc_send_input、fc_read_output），并使用有界循环环形缓冲区。
  • 支持批量重命名文件（fc_batch_rename）和后台目录搜索（fc_start_search、fc_get_search_results）。
  • 管理进程生命周期（fc_execute_command、fc_start_process、fc_kill_process），避免进程泄漏。

[PERSONA-03] 安全运营、治理与合规官

• 概况： 在企业和生产环境中监管 AI 工具集成的安全官、合规审计员和隐私团队。
• 主要运营痛点： 未披露的后台遥测信标；未经审查的本地插件网络访问；凭证／令牌泄漏到模型训练数据或提示词历史记录中；非特权用户提升权限。
• FileCommander 解决方案：
  • 使用本地 stdio 传输，严格做到零遥测且不开放任何网络监听端口。
  • 明确规定对外网络出口仅限调用方主动调用的 fc_web_fetch（默认阻止访问内部／私有 IP）。
  • 自动遮蔽搜索摘要中的机密信息和 Bearer 令牌（INV-MASK-06）。
  • 严格以非特权用户身份执行（INV-PROC-09），并承诺 48 小时漏洞响应 SLA（[email protected]、[email protected]）。

[PERSONA-04] 企业平台架构师与数据流水线开发人员

• 概况： 解决方案架构师和数据工程师，负责集成本地文件、规范化异构配置格式、验证加密哈希并生成报告。
• 主要运营痛点： MCP 服务数量激增，需部署 4-6 个用途各异的专用服务；不同工具间 UTF-8 字节序列损坏（乱码）；需要编写专用解析脚本。
• FileCommander 解决方案：
  • 提供全面的 50 工具单服务部署，消除多服务泛滥和进程开销。
  • 支持在 7 种结构化格式之间无损、声明式转换（fc_convert_format：JSON、YAML、TOML、XML、CSV、INI、TOON）。
  • 内置文件修复引擎（fc_fix_encoding、fc_fix_json、fc_cleanup_file），打造自修复流水线。
  • 提供加密校验和（fc_checksum：SHA-256、SHA-512、MD5、SHA-1），以及 Markdown 到 PDF/HTML 的渲染（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 和 glama.json 中维护着面向 AI Agent 的结构化上下文。
• 合规与归属： 已根据 THIRD_PARTY_LICENSES.md 和 NOTICE 完成验证。

---

安装

前置条件

• Node.js 20 或更高版本
• npm

选项 1：从 NPM 安装

npm install -g ellmos-filecommander-mcp

选项 2：从源代码安装

git clone https://github.com/ellmos-ai/ellmos-filecommander-mcp.git
cd ellmos-filecommander-mcp
npm ci
npm run build

---

配置

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

Windows： %APPDATA%\Claude\claude_desktop_config.json macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

如果通过 NPM 全局安装：

{
  "mcpServers": {
    "filecommander": {
      "command": "ellmos-filecommander"
    }
  }
}

如果从源代码安装：

{
  "mcpServers": {
    "filecommander": {
      "command": "node",
      "args": ["/absolute/path/to/filecommander-mcp/dist/index.js"]
    }
  }
}

保存后重启 Claude Desktop。

其他 MCP 客户端

该服务通过 stdio 传输进行通信。将 MCP 客户端指向 dist/index.js 入口点或 ellmos-filecommander 二进制文件。

---

工具概览

文件系统操作（15 个工具）

工具	描述
fc_read_file	读取文件内容，可选择限制行数
fc_preview_file	先检查 MIME 类型和大小，再显式请求有界的内联 MCP 内容
fc_read_multiple_files	单次调用最多读取 20 个文件
fc_write_file	写入／创建／追加文件内容
fc_edit_file	按行编辑（替换、插入、删除行）
fc_str_replace	在通过上下文验证后替换文件中的唯一字符串
fc_list_directory	列出目录内容（可递归，可配置深度）
fc_create_directory	创建目录（包括父目录）
fc_delete_file	删除文件（永久删除）
fc_delete_directory	删除目录（可选择递归标志）
fc_safe_delete	移至回收站（可恢复！）
fc_move	移动或重命名文件和目录（可安全处理云端锁定）
fc_copy	复制文件和目录
fc_file_info	获取详细的文件元数据（大小、日期、类型）
fc_search_files	使用通配符模式同步搜索文件

fc_preview_file 是本地文件在远程／无头环境中的备用方案。默认调用仅返回结构化元数据：解析后的路径、file:// URI、MIME 类型、字节大小、预览类型、固定的 1 MiB 限制，以及精确的后续调用。只有在设置 include_content=true 后才会读取内容。符合条件的文本和光栅图像使用标准 MCP text／image 内容块；PDF 使用有界的嵌入式 resource。超过 1 MiB 的文件和不支持的类型仅返回元数据，预览路径绝不会读取或进行 Base64 编码。

内容搜索（1 个工具）

工具	描述
fc_search_content	在明确指定且有序的文件列表中进行只读字面搜索或正则搜索，并支持大小写、上下文、全局和单文件限制

fc_search_content 不会展开 glob、遍历目录或递归查找文件。它最多接受 50 个明确指定的 UTF-8 文本文件，跳过二进制文件和超过 10 MB 的文件，并返回确定性的 JSON。匹配结果全局最多 200 条、每个文件最多 100 条，上下文最多 10 行，摘录最多 500 个字符，序列化输出最多 200,000 个字符。缺失、仅云端可用、权限、编码、二进制和大小错误会按文件报告，因此可读取的文件仍会生成结果。摘录中的常见机密格式会被隐藏。

异步搜索（5 个工具）

工具	描述
fc_start_search	启动后台搜索（立即返回）
fc_get_search_results	分页检索结果
fc_stop_search	取消正在运行的搜索
fc_list_searches	列出所有活动或已完成的搜索
fc_clear_search	从内存中移除已完成的搜索

进程管理（5 个工具）

工具	描述
fc_execute_command	执行 shell 命令（阻塞式，带超时）
fc_start_process	启动后台进程（非阻塞）
fc_open_path	使用操作系统默认应用验证并打开现有的本地文件或目录
fc_list_processes	列出正在运行的系统进程
fc_kill_process	按 PID 或名称终止进程

fc_open_path 仅接受现有文件或目录，并将其交给固定的本机默认处理程序启动器。其结构化结果会报告 launcher_accepted=true|false，始终将 user_visible="unknown" 作为报告值，并指出机器可读的备用方案：文件使用仅包含元数据参数的 fc_preview_file，目录使用 fc_list_directory。启动器接受请求并不代表 GUI 已显示。fc_start_process 则允许调用方选择可执行文件和参数。fc_execute_command 接受任意 shell 命令：普通命令使用 Node 的默认 shell（Windows 上为 COMSPEC/cmd.exe），而 FileCommander 的 Windows 特殊字符路径可能会通过 Windows PowerShell 执行。

交互式会话（5 个工具）

工具	描述
fc_start_session	启动交互式进程（Python、Node、shell 等）
fc_read_output	读取会话输出
fc_send_input	向正在运行的会话发送输入
fc_list_sessions	列出所有会话
fc_close_session	终止会话

文件维护与修复（9 个工具）

工具	描述
fc_fix_json	修复损坏的 JSON（BOM、尾随逗号、注释、单引号）
fc_validate_json	验证 JSON，并提供详细的错误位置和上下文
fc_cleanup_file	移除 BOM、NUL 字节和尾随空白，并规范化换行符
fc_fix_encoding	修复乱码或双重编码的 UTF-8（27 种以上字符模式）
fc_folder_diff	使用快照跟踪目录变更（新增／修改／删除）
fc_batch_rename	基于模式批量重命名（前缀／后缀、替换、自动检测）
fc_convert_format	在 JSON、CSV、INI、YAML、TOML、XML 和 TOON 格式之间转换
fc_detect_duplicates	使用 SHA-256 哈希查找重复文件
fc_checksum	文件哈希（MD5、SHA-1、SHA-256、SHA-384、SHA-512），支持可选比较

归档（1 个工具）

工具	描述
fc_archive	创建、解压和列出 ZIP 归档文件

OCR（1 个工具）

工具	描述
fc_ocr	通过 tesseract.js 从图像中提取文本（可选依赖）

云同步（1 个工具）

工具	描述
fc_check_cloud_lock	报告静态云同步上下文和目标状态；没有证据时，绝不声称存在活动锁（Windows）

系统（4 个工具）

工具	描述
fc_get_time	获取带时区信息的当前系统时间
fc_set_safe_mode	切换安全模式：所有删除操作都移至回收站 / 废纸篓
fc_set_language	设置运行时语言（de、en、es、zh、ja 或 ru）
fc_get_language	读取当前运行时语言和所有受支持的语言代码

导出（2 个工具）

工具	描述
fc_md_to_html	将 Markdown 转换为带 CSS 样式的独立 HTML（标题、代码块、表格、嵌套列表、引用块、图片、复选框）
fc_md_to_pdf	通过无头浏览器（Edge/Chrome）将 Markdown 转换为 PDF。如果没有可用浏览器，则回退到 HTML

Web（1 个工具）

工具	描述
fc_web_fetch	获取网页，并按 mode 返回内容：提取（清理后的正文）、原始（HTTP 正文）、链接、表单或标头。只读网络工具；默认情况下，SSRF 防护会阻止访问内部 / 私有目标。

总计：50 个工具

---

对比矩阵与替代方案

FileCommander 将文件系统操作、受限搜索、进程控制、数据修复、格式转换和文档渲染整合到一个统一的 MCP 接口中。下表从 10 个关键操作维度，对比其架构与标准替代方案：

操作维度	ellmos FileCommander MCP（50 个工具）	官方 Filesystem MCP（@modelcontextprotocol/server-filesystem）	Desktop Commander MCP	直接使用主机 Shell（bash / PowerShell）	临时脚本与云 API
工具广度与范围 [INV-PROC-09]	50 个统一工具，覆盖 6 个领域	约 11 个基础文件 I/O 工具	约 15 个工具（文件 + 进程）	不受限制的 CLI 命令	零散的定制脚本
安全删除与恢复 [INV-SAFE-02]	原生 OS 回收站 / Trash（fc_safe_delete、Safety Mode）	仅支持永久删除（unlink）	仅支持永久删除	不可逆的 rm -rf / Remove-Item	自定义回收站实现
云端锁定与同步韧性 [INV-LOCK-03]	自动回退（遇到 EPERM/EBUSY 时，复制 + SHA-256 验证 + unlink）	遇到锁定文件 / 重解析点时失败	遇到锁定文件时失败	失败或无限期阻塞	同步冲突 / 冲突副本
受限搜索与机密信息脱敏 [INV-SRCH-05 / INV-MASK-06]	受限搜索（最多 50 个文件、10 MB，自动脱敏 API 令牌）	仅遍历目录（不支持内容正则）	不受限的正则搜索	不受限的 grep（机密信息会泄露到上下文中）	使用不带脱敏功能的自定义正则
异步长时间运行搜索 [INV-SRCH-05]	带令牌分页的后台扫描（fc_start_search）	仅支持同步（会阻塞 Agent）	仅支持同步	后台作业控制（&）	轮询循环 / 缓慢的网络调用
交互式 REPL 与会话控制 [INV-REPL-08]	有状态 REPL（Node、Python、Shell），带循环缓冲区	不支持	基础终端会话	原始子进程（存在僵尸进程风险）	复杂的 IPC 管道
自愈与数据修复 [INV-DIAG-04]	内置乱码修复（27 种以上模式）与 JSON 修复	不支持	不支持	手动执行 iconv / sed 管道	自定义错误恢复代码
多格式转换 [INV-PREV-07]	声明式转换（JSON、YAML、TOML、XML、CSV、INI、TOON）	不支持	不支持	需要外部 jq / yq / xmlstarlet	第三方 Python 库
文档与归档工具 [INV-PREV-07]	内置 ZIP 生命周期管理、OCR（Tesseract）、Markdown 转 HTML/PDF	不支持	通过桌面应用处理 Excel/PDF	需要 pandoc、zip、tesseract	零散的工具依赖
治理与安全 SLA [INV-LOCAL-01 / INV-SLA-10]	本地 stdio、零遥测、明确的出站访问、具有约束力的 48 小时 SLA	标准 stdio，社区 SLA	Stdio、未经审查的遥测 / 日志	不受限制的提权与脚本注入风险	临时使用 SaaS 带来的云端暴露风险

主要差异：

• 唯一支持可恢复删除（回收站 / Trash）和全局 Safety Mode 的 MCP 服务
• 唯一支持带分页和令牌管理的异步后台搜索的 MCP 服务
• 唯一支持在搜索片段中自动脱敏机密信息与 Bearer 令牌的 MCP 服务
• 内置 JSON 修复、乱码编码修复和重复项检测
• 内置支持云端锁定的安全文件操作，并提供自动复制 + 验证 + 删除回退机制
• 最全面的单服务解决方案（50 个工具），无需部署多个服务

---

工具前缀

所有工具均使用 fc_ 前缀（FileCommander），以避免与其他 MCP 服务冲突。

---

治理与运行时不变量

该服务强制执行 10 项严格的运行时不变量，确保安全性、可预测性和最小权限：

不变量 ID	名称	保证与实现细节	运行安全优势
INV-LOCAL-01	本地 stdio 与显式出站请求	本地 stdio 传输、零遥测、不开放监听端口。出站 HTTP(S) 请求严格通过对 fc_web_fetch 的显式客户端调用发起。	杜绝未经授权的后台网络泄漏；以本地优先方式隔离。
INV-SAFE-02	安全删除与回收站保护	fc_safe_delete 和全局 fc_set_safe_mode 会通过操作系统回收站（Windows）/废纸篓（macOS/Linux）执行文件和目录删除。	消除 AI Agent 操作导致的不可逆意外数据丢失。
INV-LOCK-03	可应对云锁的移动操作	当同步过滤器（OneDrive、Dropbox、iCloud）导致 EPERM/EBUSY 时，fc_move 会自动回退为复制 + SHA-256 校验 + 解除源文件链接。	确保在云同步工作区内可靠地完成文件操作。
INV-DIAG-04	云锁诊断	fc_check_cloud_lock 提供只读静态路径检查和重解析点检测，不会改变文件系统状态。	让 Agent 能在执行修改前评估同步冲突风险。
INV-SRCH-05	有界多文件内容搜索	fc_search_content 严格限制输入（最多 50 个显式文件、每个文件 10 MB、200 个匹配项、200k 个字符），且不会递归使用 glob。	防止内存溢出崩溃和不受限的 CPU 消耗。
INV-MASK-06	自动隐藏机密与令牌	内容搜索摘录会自动检测并隐藏 API 密钥、Bearer 令牌、AWS 凭据和授权标头。	防止凭据泄漏到提示词或污染上下文。
INV-PREV-07	有界内联预览与安全打开	fc_preview_file 优先显示元数据，内联内容严格限制在 1 MiB 以内；fc_open_path 通过 shell 安全的操作系统启动器调用默认应用。	安全检查远程和本地文件，避免界面卡顿或载荷膨胀。
INV-REPL-08	交互式 REPL 与会话隔离	有状态交互式会话（fc_start_session、fc_send_input、fc_read_output）使用有界循环环形缓冲区。	支持多轮 REPL 调试，同时防止僵尸进程不断累积。
INV-PROC-09	以非特权身份执行，不提权	完全以标准非特权用户模式执行；绝不请求或要求管理员提权或 root 权限。	最大限度缩小攻击面；严格遵循最小权限原则。
INV-SLA-10	48h 安全响应与 5-Day 分诊 SLA	正式的漏洞处理承诺，并提供多渠道联系地址（[email protected]、[email protected]）。	提供可预测、适用于企业的事件响应与分诊流程。

---

安全

此服务拥有运行用户权限下的完整文件系统访问权限。

详细的安全信息和建议请参阅 SECURITY.md。

要点：

• fc_execute_command 可运行任意 Shell 命令
• fc_open_path 会调用操作系统为调用者所选的现有路径关联的应用；该应用以用户权限运行
• fc_open_path 会单独报告启动器是否接受请求，同时将不变量 user_visible="unknown" 保持不变；fc_preview_file 是元数据优先的远程备用方案，内联内容上限明确为 1 MiB
• fc_start_session 会启动任意交互式命令，后续的 fc_send_input 调用可以执行其他操作
• fc_delete_* 工具默认会永久删除（使用 fc_safe_delete，或通过 fc_set_safe_mode 启用安全模式，将所有删除操作移至回收站 / 废纸篓）
• 安全模式仅保护 fc_delete_file 和 fc_delete_directory；不会对命令或交互式会话进行沙箱隔离
• 服务传输使用本地 stdio，不会发送遥测数据，但显式调用 fc_web_fetch 会通过 HTTP(S) 访问外部网络
• 没有内置沙箱——安全性由 MCP 客户端层负责

---

开发

# Install dependencies
npm ci

# Watch mode (auto-rebuild on changes)
npm run dev

# One-time build
npm run build

# Start the server
npm start

# Run test suite
npm test

测试

本项目包含 235 项 Vitest 测试，以及 71 项独立的 i18n 检查（共 306 项），覆盖文件系统操作、元数据优先的内联预览、有界内容搜索、原生默认处理程序启动、格式转换、编码修复、归档处理、重复项检测、语言包、工具注释、真实 stdio 行为和安全边界。

npm test              # Run all tests
node test-i18n.mjs    # Run standalone i18n checks
npx vitest run        # Same as above
npx vitest --watch    # Watch mode

测试已在 Windows、macOS 和 Linux 上验证通过。 推送和拉取请求会在 Node.js 20、22 和 24 上运行 CI，包括 npm ci、TypeScript 构建、Vitest 和 npm 软件包试运行。

贡献指南请参阅 CONTRIBUTING.md。

---

更新日志

完整版本历史请参阅 CHANGELOG.md。

---

许可证与法律归属

MIT - Lukas Geiger（ellmos-ai）。关于 open-bricks 的整体归属信息，请参阅 NOTICE；Level 1 SBOM 请参阅 THIRD_PARTY_LICENSES.md；纯文本 SBOM 请参阅 THIRD_PARTY_LICENSES.txt。

---

历史

本项目最初以 BACH FileCommander（bach-filecommander-mcp）之名开发。作为 ellmos-ai 组织的一部分，项目已更名为 ellmos FileCommander（ellmos-filecommander-mcp）。

旧软件包名称 bach-filecommander-mcp 已弃用。请改用 ellmos-filecommander-mcp：

npm uninstall -g bach-filecommander-mcp
npm install -g ellmos-filecommander-mcp

---

ellmos-ai 生态系统

此 MCP 服务是 ellmos-ai 生态系统的一部分，涵盖 AI 基础设施、MCP 服务和智能工具。

MCP 服务系列

服务	工具	重点	npm
FileCommander	50	文件系统、受限的内联预览、内容搜索、使用默认应用打开、进程管理、交互式会话、适用于云锁定环境的安全操作	ellmos-filecommander-mcp
CodeCommander	22	代码分析、JSON 修复、导入项、差异、正则表达式	ellmos-codecommander-mcp
Clatcher	12	文件修复、格式转换、批量操作	ellmos-clatcher-mcp
n8n Manager	19	通过 AI 助手管理 n8n 工作流	n8n-manager-mcp
ControlCenter	31	MCP 技术栈发现、配置管理、控制平面	ellmos-controlcenter-mcp
Homebase	45	本地优先的大模型记忆、知识、状态、路由、蜂群编排	ellmos-homebase-mcp（alpha）
ServerCommander	8	服务操作：运行状况检查、日志分析、部署演练、邮件诊断	ellmos-servercommander-mcp（alpha）
Blender Use	5	无头 Blender 资产质量检查和 FBX 重新导入验证	ellmos-blender-use-mcp（alpha）
Open Compute	16	模型无关的计算机操作：捕获、安全门控操作、Windows UIA	open-compute-mcp（alpha）

AI 基础设施

项目	描述
BACH	面向大模型 Agent 的本地优先文本操作系统——113+ 个处理器、550+ 个工具、SQLite 记忆
open-compute	为 Open Compute MCP 提供支持的模型无关计算机操作核心
clutch	提供自动路由和预算跟踪的提供商中立型大模型编排
rinnsal	轻量级 Agent 记忆、连接器和自动化基础设施
ellmos-stack	可自托管的 AI 研究技术栈（Ollama + n8n + Rinnsal + KnowledgeDigest）
MarbleRun	面向 Claude Code 的自主 Agent 链框架
gardener	极简的数据库驱动型大模型操作系统原型（4 个函数、1 张表）
ellmos-tests	大模型操作系统测试框架（7 个维度）

桌面软件与姊妹应用

我们的合作组织 open-bricks 及其旗下组织提供 AI 原生桌面应用和开发者实用工具：

应用	类别	组织	重点
ProFiler	文件管理	file-bricks	高速双窗格文件管理器，集成 AI
ExplorerPro	文件浏览	file-bricks	支持语义筛选和预览的智能文件浏览器
WinStorePackager	打包	file-bricks	面向 Windows 桌面应用的 MSIX 和 Store 打包
SoftwareCenter	应用商店	file-bricks	集中式桌面软件包管理与分发
SQLiteViewer	数据库工具	file-bricks	轻量级 SQLite 浏览与查询
DokuZen	Markdown 套件	doc-bricks	Markdown 编辑器、PDF 导出和文档转换
MediaBrain	文档／媒体	doc-bricks	音视频转录、元数据提取与编目
UniversalInvoiceMail	文档／邮件	doc-bricks	自动解析发票、提取 PDF 内容并路由邮件
DevCenter	开发者套件	dev-bricks	集成式开发者工具箱、代码分析器与生成器
CodeBox	代码编辑器	dev-bricks	通过大模型增强的多语言代码编辑器
safe-start-for-codex	安全与审计	dev-bricks	面向 Codex 的加固运行环境与启动前检查器
automation-master	任务自动化	dev-bricks	高可靠性的后台自动化运行器与调度器
Zombie Killer Tray	进程管理	dev-bricks	可选的 Windows 工具，用于检查孤立的 MCP 进程。通过受支持的 node_modules/ellmos-filecommander-mcp/dist/index.js 入口启动时，FileCommander 是已配置的候选对象；所有其他进程检查与应用检查仍然适用。

---

责任 / Liability

本项目是依据《德国民法典》（BGB）第 516 条及以下条款提供的无偿开源赠与（好意行为）。根据**《德国民法典》第 521 条**，作者和贡献者的责任仅限于故意和重大过失。此外，MIT 许可证中的免责声明同样适用。

使用风险由用户自行承担。不承诺维护，不保证可用性，也不保证无错误或适用于特定用途。

安全相关事件和漏洞可通过 [email protected] 和 [email protected] 按具有约束力的48 小时 SLA提交，并将在 5 个工作日内完成分诊。

本项目依据德国法律提供无偿开源赠与（《德国民法典》（BGB）第 516 条及以下条款）。责任严格限于故意和重大过失（《德国民法典》第 521 条）。MIT 许可证中的免责声明补充适用。使用风险由用户自行承担。不作任何保证，不承诺维护，也不承担适用于特定用途的责任。

安全事件和漏洞按照具有约束力的48 小时响应 SLA处理，可通过 [email protected] 和 [email protected] 联系，并将在 5 个工作日内正式分诊。