文件系统 MCP 服务器 (@sylphlab/filesystem-mcp)

<!-- Add other badges like License, Build Status if applicable --> <a href="https://glama.ai/mcp/servers/@sylphlab/filesystem-mcp"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@sylphlab/filesystem-mcp/badge" /> </a>

使您的 AI 代理（如 Cline/Claude）能够安全、高效且节省 token 地访问您的项目文件。 这个 Node.js 服务器实现了 模型上下文协议 (MCP)，提供了一套强大的文件系统工具，可以在定义的项目根目录下安全运行。

安装

有几种方法可以使用文件系统 MCP 服务器：

1. 推荐：通过 MCP 主机配置使用 npx (或 bunx)

最简单的方法是通过 npx 或 bunx，直接在您的 MCP 主机环境（例如，Roo/Cline 的 mcp_settings.json）中配置。这确保您始终使用 npm 上的最新版本，而无需本地安装或 Docker。

示例 (npx):

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["@sylphlab/filesystem-mcp"],
      "name": "Filesystem (npx)"
    }
  }
}

示例 (bunx):

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "bunx",
      "args": ["@sylphlab/filesystem-mcp"],
      "name": "Filesystem (bunx)"
    }
  }
}

重要提示： 服务器使用其自身的当前工作目录 (cwd) 作为项目根目录。确保您的 MCP 主机（例如 Cline/VSCode）配置为使用 cwd 设置为您的活动项目根目录来启动命令。

2. Docker

使用官方 Docker 镜像用于容器化环境。

示例 MCP 主机配置：

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/project:/app", // 将您的项目挂载到 /app
        "sylphlab/filesystem-mcp:latest"
      ],
      "name": "Filesystem (Docker)"
    }
  }
}

请记住将 /path/to/your/project 替换为正确的绝对路径。

3. 本地构建（用于开发）

1. 克隆：git clone https://github.com/sylphlab/filesystem-mcp.git
2. 安装：cd filesystem-mcp && pnpm install (现在使用 pnpm)
3. 构建：pnpm run build
4. 配置 MCP 主机：

   {
     "mcpServers": {
       "filesystem-mcp": {
         "command": "node",
         "args": ["/path/to/cloned/repo/filesystem-mcp/dist/index.js"], // 更新后的构建目录
         "name": "Filesystem (Local Build)"
       }
     }
   }
   

   注意： 从您希望作为项目根目录的目录启动 node 命令。

快速开始

在您的 MCP 主机中配置服务器后（请参阅安装），您的 AI 代理可以立即开始使用文件系统工具。

示例代理交互（概念）：

Agent: <use_mcp_tool>
         <server_name>filesystem-mcp</server_name>
         <tool_name>read_content</tool_name>
         <arguments>{"paths": ["src/index.ts"]}</arguments>
       </use_mcp_tool>

Server Response: (Content of src/index.ts)

为什么选择这个项目？

• 🛡️ 安全且方便的项目根目录焦点： 操作仅限于项目根目录（启动时的 cwd）。
• ⚡ 优化和整合的工具： 批量操作减少了 AI 服务器的往返次数，从而节省了 token 和延迟。 批量处理中每个项目的可靠结果。
• 🚀 易于集成： 通过 npx/bunx 快速设置。
• 🐳 容器化选项： 可作为 Docker 镜像使用。
• 🔧 全面的功能： 涵盖广泛的文件系统任务。
• ✅ 强大的验证： 使用 Zod 模式进行参数验证。

性能优势

(占位符：在此处添加基准测试结果和比较，展示优于替代方法（如单个 shell 命令）的优势。)

• 批量操作： 与单个操作相比，显著降低了开销。
• 直接 API 使用： 比为每个命令生成 shell 进程更有效。
• (可用时添加特定基准数据)

特性

该服务器为您的 AI 代理配备了强大而高效的文件系统工具包：

• 📁 浏览和检查 (list_files, stat_items): 列出文件/目录（递归，统计信息），获取多个项目的详细状态。
• 📄 读取和写入内容 (read_content, write_content): 读取/写入/追加多个文件，创建父目录。
• ✏️ 精确编辑和搜索 (edit_file, search_files, replace_content): 在多个文件中进行外科手术式编辑（插入、替换、删除），并保留缩进和差异输出； 使用上下文进行正则表达式搜索； 多文件搜索/替换。
• 🏗️ 管理目录 (create_directories): 创建多个目录，包括中间父目录。
• 🗑️ 安全删除 (delete_items): 递归删除多个文件/目录。
• ↔️ 移动和复制 (move_items, copy_items): 移动/重命名/复制多个文件/目录。
• 🔒 控制权限 (chmod_items, chown_items): 更改多个项目的 POSIX 权限和所有权。

主要优势： 所有接受多个路径/操作的工具都会单独处理每个项目，并返回详细的状态报告。

设计理念

(占位符：解释核心设计原则。)

• 安全第一： 优先防止访问项目根目录之外的内容。
• 效率： 最大程度地减少 AI 交互的通信开销和 token 使用量。
• 健壮性： 为批量操作提供详细的结果和错误报告。
• 简单性： 通过 MCP 提供清晰一致的 API。
• 标准合规性： 严格遵守模型上下文协议。

与其他解决方案的比较

(占位符：客观地与其他替代方案进行比较。)

特性/方面	文件系统 MCP 服务器	单个 Shell 命令（通过代理）	其他自定义脚本
安全性	高（根目录限制）	低（代理需要 shell 访问权限）	可变
效率（Token）	高（批量处理）	低（每个操作一个命令）	可变
延迟	低（直接 API）	高（Shell 启动开销）	可变
批量操作	是（大多数工具）	否	可能
错误报告	详细（每个项目）	基本（stdout/stderr 解析）	可变
设置	简单（npx/Docker）	需要安全的 shell 设置	自定义

未来计划

(占位符：列出即将推出的功能或改进。)

• 探索文件监视功能。
• 研究对超大文件的流式传输支持。
• 提高特定操作的性能。
• 为 list_files 添加更高级的过滤选项。

文档

(占位符：添加指向完整文档网站的链接，一旦可用。)

完整的文档，包括详细的 API 参考和示例，将在以下位置提供：[文档站点链接]

贡献

欢迎贡献！ 请在 GitHub 存储库 上打开一个 issue 或提交一个 pull request。

许可证

本项目根据 MIT 许可证 发布。

---

开发

1. 克隆：git clone https://github.com/sylphlab/filesystem-mcp.git
2. 安装：cd filesystem-mcp && pnpm install
3. 构建：pnpm run build (将 TypeScript 编译为 dist/)
4. 监视：pnpm run dev (可选，保存时重新编译)

发布（通过 GitHub Actions）

此存储库使用 GitHub Actions (.github/workflows/publish.yml) 在版本标签 (v*.*.*) 推送到 main 分支时，自动将软件包发布到 npm 并构建/推送 Docker 镜像到 Docker Hub。 需要在 GitHub 存储库设置中配置 NPM_TOKEN、DOCKERHUB_USERNAME 和 DOCKERHUB_TOKEN 密钥。