local-only server
The server can only run on the client’s local machine because it depends on local resources.
文件系统 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 ）：
示例（ bunx ）：
**重要提示：**服务器使用其自身的当前工作目录 ( cwd ) 作为项目根目录。请确保您的 MCP 主机（例如 Cline/VSCode）已配置为将cwd设置为活动项目的根目录来启动命令。
2. Docker
对于容器化环境，请使用官方 Docker 镜像。
MCP 主机配置示例：
请记住用正确的绝对路径替换/path/to/your/project 。
3. 本地构建（用于开发）
- 克隆：
git clone https://github.com/sylphlab/filesystem-mcp.git - 安装：
cd filesystem-mcp && pnpm install（现在使用 pnpm） - 构建：
pnpm run build - 配置 MCP 主机：**注意：**从您想要作为项目根目录的目录启动Copy
node命令。
快速入门
一旦在您的 MCP 主机中配置了服务器（参见安装），您的 AI 代理就可以立即开始使用文件系统工具。
代理交互示例（概念）：
为什么选择这个项目？
- **🛡️ 安全便捷的项目根目录焦点：**操作仅限于项目根目录（启动时为
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。
- **标准合规性：**严格遵守模型上下文协议。
与其他解决方案的比较
（占位符：客观地与其他选择进行比较。）
| 特征/方面 | 文件系统 MCP 服务器 | 单独的 Shell 命令（通过代理） | 其他自定义脚本 |
|---|---|---|---|
| 安全 | 高（根受限） | 低（代理需要 shell 访问权限） | 多变的 |
| 效率（代币） | 高（批处理） | 低（每个操作一个命令） | 多变的 |
| 延迟 | 低（直接 API） | 高（Shell 生成开销） | 多变的 |
| 批量操作 | 是（大多数工具） | 不 | 或许 |
| 错误报告 | 详细（每件） | 基本（stdout/stderr 解析） | 多变的 |
| 设置 | 简单（npx/Docker） | 需要安全外壳设置 | 风俗 |
未来计划
（占位符：列出即将推出的功能或改进。）
- 探索文件监视功能。
- 调查对超大文件的流式支持。
- 增强特定操作的性能。
- 为
list_files添加更多高级过滤选项。
文档
（占位符：一旦可用，就添加完整文档网站的链接。）
完整文档（包括详细的 API 参考和示例）可在以下位置获取：[链接至文档站点]
贡献
欢迎贡献！请在GitHub 仓库上创建 issue 或提交 pull request。
执照
该项目根据MIT 许可证发布。
发展
- 克隆：
git clone https://github.com/sylphlab/filesystem-mcp.git - 安装：
cd filesystem-mcp && pnpm install - 构建：
pnpm run build（将 TypeScript 编译为dist/） - 观看：
pnpm run dev（可选，保存时重新编译）
发布（通过 GitHub Actions）
此仓库使用 GitHub Actions ( .github/workflows/publish.yml ) 自动将软件包发布到npm ，并在将版本标签 ( v*.*.* ) 推送到main分支时构建/推送 Docker 镜像到Docker Hub 。需要在 GitHub 仓库设置中配置NPM_TOKEN 、 DOCKERHUB_USERNAME和DOCKERHUB_TOKEN密钥。