JinDaGe - mcp-file-operations-server MCP Details

article

README

🚀 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
}

错误处理

常见错误

文件不存在：尝试访问或操作未存在的文件时抛出。
```
Error: File not found
```
权限不足：没有足够的权限进行操作时抛出。
```
Error: Permission denied
```
目录遍历拒绝：尝试进行目录遍历攻击时被阻止。
```
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

如何查看当前日志？
- 使用mcp logs命令查看实时日志。
能否禁用变更跟踪？
- 是的，通过设置enableChangeTracking: false可以禁用变更跟踪功能。
服务器支持哪些协议？
- 当前版本仅支持MCP协议，未来计划添加更多协议支持。

🔧 技术细节

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

📄 许可证

文档未提及相关信息。

👥 贡献者

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

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