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

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

安装

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

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

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

示例 (npx)：

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

示例 (bunx)：

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

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

2. Docker

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

MCP 主机配置示例：

json
{
"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 主机：
   json
   {
   "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>
{"paths": ["src/index.ts"]}
</use_mcp_tool>

Server Response: (src/index.ts 的内容)

为什么选择这个项目？

• 🛡️ 安全且方便的项目根目录焦点： 操作限制在项目根目录（启动时的 cwd）。
• ⚡ 优化和整合的工具： 批量操作减少了 AI 与服务器之间的往返次数，节省了令牌和延迟。每个批次中的每个项目都有可靠的结果。
• 🚀 易于集成： 通过 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 交互中的通信开销和令牌使用。
• 健壮性： 为批量操作提供详细的执行结果和错误报告。
• 简洁性： 通过 MCP 提供清晰一致的 API。
• 标准合规性： 严格遵守模型上下文协议 (Model Context Protocol)。

与其他解决方案的比较

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

未来计划

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

• 探索文件监视功能。
• 调查对非常大文件的流支持。
• 提高特定操作的性能。
• 为 list_files 添加更多高级过滤选项。

文档

(占位符：在文档网站可用后添加链接。)

完整的文档，包括详细的 API 参考和示例，将可在以下网址找到：[文档网站链接]

贡献

欢迎贡献！请在 GitHub 仓库 上提出问题或提交拉取请求。

许可证

该项目根据 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）在向 main 分支推送版本标签（v*.*.*）时自动将包发布到 npm 并构建/推送 Docker 镜像到 Docker Hub。需要在 GitHub 仓库设置中配置 NPM_TOKEN、DOCKERHUB_USERNAME 和 DOCKERHUB_TOKEN 密钥。