文件系统-MCP

Name: 文件系统-MCP
Author: SylphxAI

作者：SylphxAI6 星标更新：2025-11-18

安装使用来源：spider==github.com

项目介绍

文件系统 MCP 📁

为AI代理提供安全的文件系统操作 - 优化令牌并支持批处理

批处理操作 • 项目根目录安全性 • 令牌优化 • Zod 验证

快速开始 • 安装 • 工具

🚀 概述

为您的AI代理（如Claude/Cline）提供安全、高效且节省令牌的访问项目文件的方式。此Node.js服务器实现了模型上下文协议（MCP），以提供强大的文件系统工具集。

问题：

传统的AI文件系统访问：
- 每个操作使用Shell命令 ❌
- 不支持批处理（高令牌成本）❌
- 不安全（没有项目根边界）❌
- 延迟高（Shell启动开销）❌

解决方案：

文件系统 MCP 服务器：
- 批处理操作（一次处理10+文件）✅
- 令牌优化（减少往返次数）✅
- 安全（限制在项目根目录内）✅
- 直接API（无Shell开销）✅

结果：为AI代理提供安全、快速且节省令牌的文件系统操作。

⚡ 性能优势

令牌与延迟优化

指标	单独Shell命令	文件系统 MCP	改进
操作/请求	1个文件	10+个文件	10倍减少
往返次数	N次操作	1次请求	N倍更少
延迟	每次操作启动Shell	直接API	5-10倍更快
令牌使用	高开销	批量上下文	50-70%更少
错误报告	解析stderr	每项状态	详细

真实世界的好处

批量文件读取 - 一次请求读取10个文件，而非10次请求
多文件编辑 - 使用单个工具调用编辑多个文件
递归操作 - 高效列出整个目录树
详细状态 - 每项成功/失败报告

🎯 为什么选择这个服务器？

安全性与安全性

🛡️ 项目根目录限制 - 所有操作限制在启动时的当前工作目录（cwd）
🔒 权限控制 - 内置chmod/chown工具
✅ 验证 - Zod模式验证所有参数
🚫 防止路径遍历 - 无法逃离项目目录

效率与性能

⚡ 批处理 - 每次请求处理多个文件/目录
🎯 令牌优化 - 减少AI服务器通信开销
🚀 直接API - 无需启动Shell进程
📊 详细结果 - 批处理操作的每项状态

开发者体验

🔧 易于设置 - 使用npx/bunx即时使用
🐳 Docker 就绪 - 提供官方Docker镜像
📦 综合工具 - 11+个文件系统操作
🔄 MCP 标准 - 全面符合协议

📦 安装

方法1：npx/bunx（推荐）

最简单的方法 - 始终使用npm上的最新版本。

使用npx：

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

使用bunx：

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

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

方法2：Docker

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

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/project:/app",
        "sylphlab/filesystem-mcp:latest"
      ],
      "name": "文件系统 (Docker)"
    }
  }
}

记得将/path/to/your/project替换为实际的项目路径。

方法3：本地构建（开发）

# 克隆仓库
git clone https://github.com/SylphxAI/filesystem-mcp.git
cd filesystem-mcp

# 安装依赖
pnpm install

# 构建
pnpm run build

# 监控模式（自动重建）
pnpm run dev

MCP 主机配置：

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "node",
      "args": ["/path/to/filesystem-mcp/dist/index.js"],
      "name": "文件系统 (本地构建)"
    }
  }
}

🚀 快速开始

一旦在您的MCP主机中配置好（参见安装），您的AI代理可以立即使用文件系统工具。

示例代理交互

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

服务器响应：

{
  "results": [
    {
      "path": "src/index.ts",
      "content": "...",
      "success": true
    },
    {
      "path": "package.json",
      "content": "...",
      "success": true
    }
  ]
}

📋 功能

文件操作

工具	描述	批处理支持
read_content	读取文件内容	✅ 多个文件
write_content	写入/追加到文件	✅ 多个文件
edit_file	手术式编辑并输出差异	✅ 多个文件
search_files	正则搜索并带上下文	✅ 多个文件
replace_content	多文件搜索与替换	✅ 多个文件

目录操作

工具	描述	批处理支持
list_files	递归列出文件/目录	单个路径
stat_items	获取详细的文件/目录状态	✅ 多个项目
create_directories	创建带有父级的目录	✅ 多个路径

管理操作

工具	描述	批处理支持
delete_items	删除文件/目录	✅ 多个项目
move_items	移动/重命名文件/目录	✅ 多个项目
copy_items	复制文件/目录	✅ 多个项目

权限操作

工具	描述	批处理支持
chmod_items	更改POSIX权限	✅ 多个项目
chown_items	更改所有权	✅ 多个项目

关键优势： 支持批处理操作的工具会单独处理每个项目，并返回详细的每项状态报告。

💡 设计理念

核心原则

安全第一
- 所有操作限制在项目根目录
- 防止路径遍历
- 内置权限控制
效率优先
- 批处理减少令牌使用
- 直接API调用（无Shell开销）
- 最小化通信往返次数
健壮性
- 每项成功/失败报告
- 详细的错误消息
- Zod模式验证
简洁性
- 清晰一致的API
- 符合MCP标准
- 易于集成

📊 与替代方案的比较

特征	文件系统 MCP	Shell 命令	其他脚本
安全性	✅ 根目录限制	❌ 全壳访问	⚠️ 变量
令牌效率	✅ 批量处理	❌ 每操作一个命令	⚠️ 变量
延迟	✅ 直接API	❌ 启动Shell	⚠️ 变量
批处理操作	✅ 大多数工具	❌ 无	⚠️ 可能
错误报告	✅ 每项详细	❌ 解析stderr	⚠️ 变量
设置	✅ 简单（npx/Docker）	⚠️ 安全Shell设置	⚠️ 自定义
MCP 标准	✅ 全面合规	❌ 无	⚠️ 变量

🛠️ 技术栈

组件	技术
语言	TypeScript（严格模式）
运行时	Node.js / Bun
协议	模型上下文协议（MCP）
验证	Zod模式
包管理器	pnpm
分发	npm + Docker Hub

🎯 使用案例

AI 代理开发

使AI代理能够：

读取项目文件 - 访问代码、配置、文档
编辑多个文件 - 在代码库中重构
搜索代码库 - 查找模式和定义
管理项目结构 - 创建、移动、组织文件

编码助手

构建强大的编码工具：

Cline/Claude 集成 - 直接文件系统访问
批量重构 - 一次性编辑多个文件
安全操作 - 限制在项目目录内
高效操作 - 减少令牌成本

自动化与脚本

自动化开发任务：

文件生成 - 创建样板文件
项目设置 - 初始化目录结构
批量处理 - 高效处理多个文件
内容转换 - 跨文件搜索和替换

🗺️ 发展路线图

✅ 已完成

🚀 计划

🤝 贡献

欢迎贡献！请遵循以下指南：

分叉仓库
创建功能分支 - git checkout -b feature/my-feature
编写测试 - 确保良好的覆盖率
遵循TypeScript严格模式 - 类型安全优先
添加文档 - 如需更新README
提交拉取请求

开发设置

# 克隆并安装
git clone https://github.com/SylphxAI/filesystem-mcp.git
cd filesystem-mcp
pnpm install

# 构建
pnpm run build

# 监控模式（自动重建）
pnpm run dev

🤝 支持

🐛 报告错误
💬 讨论
📧 邮件

展示您的支持： ⭐ 点赞 • 👀 关注 • 🐛 报告错误 • 💡 建议功能 • 🔀 贡献

📄 许可证

MIT © Sylphx

🙏 致谢

使用以下技术构建：

模型上下文协议 - MCP标准
Zod - 模式验证
TypeScript - 类型安全
pnpm - 包管理器

特别感谢MCP社区 ❤️

📚 发布

此仓库使用GitHub Actions自动发布到：

npm: @sylphlab/filesystem-mcp
Docker Hub: sylphlab/filesystem-mcp

触发于推送到main分支的版本标签（v*.*.*）。

所需密钥：NPM_TOKEN，DOCKERHUB_USERNAME，DOCKERHUB_TOKEN

<p align="center"> <strong>安全。高效。令牌优化。</strong> <br> <sub>节省令牌并保护您项目的文件系统MCP服务器</sub> <br><br> <a href="https://sylphx.com">sylphx.com</a> • <a href="https://x.com/SylphxAI">@SylphxAI</a> • <a href="mailto:hi@sylphx.com">hi@sylphx.com</a> </p>