MCP File Operations Server

🚀 MCP文件操作服务器

这是一个用于文件和目录操作的MCP（Meta Computing Protocol）服务器，提供了基本文件操作、目录管理、变更跟踪等功能，能高效处理文件系统相关任务。

🚀 快速开始

安装

• 自动安装：通过Smithery自动安装：

  npx -y @smithery/cli install @bsmi021/mcp-file-operations-server --client claude
  

• 手动安装：直接运行：

  npm install
  

启动服务器

npm start

开发模式（自动重载）：

npm run dev

✨ 主要特性

可用工具

基本文件操作

• copy_file：复制文件到新位置
• read_file：读取文件内容
• write_file：写入内容到文件
• move_file：移动/重命名文件
• delete_file：删除文件
• append_file：追加内容到文件

目录操作

• make_directory：创建目录
• remove_directory：删除目录
• copy_directory：递归复制目录（带进度报告）

监控操作

• watch_directory：开始监控目录变化
• unwatch_directory：停止监控目录

变更跟踪

• get_changes：获取记录的变更列表
• clear_changes：清除所有变更记录

可用资源

静态资源

• file:///recent-changes：最近文件系统变更列表

资源模板

• file://{path}：访问文件内容
• metadata://{path}：访问文件元数据
• directory://{path}：列出目录内容

速率限制

服务器实现速率限制以防止滥用：

• 工具：每分钟100次请求
• 资源：每分钟200次请求
• 监控操作：每分钟20次操作

速率限制错误包含重试-after时间段信息。

安全特性

路径验证

所有文件路径均经过验证以防止目录遍历攻击：

• 禁止使用父目录引用（../）
• 正确进行路径规范化
• 输入参数净化

资源保护

• 所有操作均有速率限制
• 正确的错误处理和日志记录
• 验证所有参数输入
• 安全的资源清理机制

进度报告

长时间运行的操作（如目录复制）提供进度更新：

interface ProgressUpdate {
    token: string | number;
    message: string;
    percentage: number;
}

通过操作结果中的进度令牌跟踪进度。

性能优化

缓存机制

服务器内置文件操作缓存，可提高重复操作的效率。默认启用。

并行处理

支持多线程和并发操作以提升性能，具体取决于系统负载和配置。

💻 使用示例

基础用法

// 复制文件
await fileOperations.copyFile({
    source: 'source.txt',
    destination: 'destination.txt',
    overwrite: false
});

// 监控目录
await fileOperations.watchDirectory({
    path: './watched-dir',
    recursive: true
});

// 通过资源访问文件内容
const resource = await mcp.readResource('file:///path/to/file.txt');
console.log(resource.contents[0].text);

// 带进度跟踪复制目录
const result = await fileOperations.copyDirectory({
    source: './source-dir',
    destination: './dest-dir',
    overwrite: false
});
// 通过结果中的进度令牌跟踪进度
console.log(result.progressToken);

📚 详细文档

配置

基本配置

可以通过环境变量或配置文件设置以下选项：

• PORT：服务器监听端口，默认为3000
• LOG_LEVEL：日志级别，可选值为debug, info, warning, error, 默认为info
• MAX_FILE_SIZE：允许的最大文件大小，默认为1MB

高级配置

• 启用/禁用变更跟踪：

  {
    enableChangeTracking: true // 默认为true
  }
  

• 配置目录复制的并发数：

  {
    copyConcurrency: 5 // 复制操作默认并发数为5
  }
  

错误处理

常见错误

1. 文件不存在：尝试访问或操作未存在的文件时抛出。

   Error: File not found
   

2. 权限不足：没有足够的权限进行操作时抛出。

   Error: Permission denied
   

3. 目录遍历拒绝：尝试进行目录遍历攻击时被阻止。

   Error: Directory traversal attempt detected
   

自定义错误处理

可以通过注册全局错误处理器捕获和处理错误：

mcp errorHandler(error) {
    console.error('An error occurred:', error);
    // 自定义处理逻辑
}

日志记录

日志格式

默认的日志格式为：

[timestamp] - [level] - message

例如：

2023-10-05 12:34:56 - info - File operation completed successfully.

日志级别

支持以下日志级别：

• debug：调试信息
• info：一般信息
• warning：警告消息
• error：错误信息

FAQ

1. 如何查看当前日志？

   • 使用mcp logs命令查看实时日志。

2. 能否禁用变更跟踪？

   • 是的，通过设置enableChangeTracking: false可以禁用变更跟踪功能。

3. 服务器支持哪些协议？

   • 当前版本仅支持MCP协议，未来计划添加更多协议支持。

🔧 技术细节

该服务器基于MCP协议构建，在实现文件和目录操作功能时，采用了路径验证机制防止目录遍历攻击，通过速率限制避免滥用，内置缓存机制和支持并行处理提升性能。同时，对各类操作和错误进行了详细的日志记录，方便后续排查和维护。

📄 许可证

文档未提及相关信息。

👥 贡献者

• 开发者：[你的名字]
• 维护者：[项目维护团队]

以上是项目的完整文档，包含安装、配置、使用说明以及常见问题解答。如果有任何疑问或需要进一步帮助，请随时联系项目维护团队。