文件操作 MCP 服务器

这是一个提供增强文件操作能力的模型上下文协议 (MCP) 服务器，支持流处理、修补和变更跟踪。

功能

• 基本文件操作：复制、读取、写入、移动和删除文件
• 目录操作：创建、移除和复制目录
• 文件监视：监控文件和目录的变化
• 变更跟踪：跟踪和查询文件操作历史
• 流支持：通过流高效处理大文件
• 资源支持：通过 MCP 资源访问文件和目录
• 进度报告：为长时间操作提供实时进度更新
• 速率限制：防止过度请求
• 增强安全性：路径验证和输入清理
• 健壮的错误处理：全面的错误处理和报告
• 类型安全：完全支持 TypeScript 并进行严格的类型检查

安装

通过 Smithery 安装

要通过 Smithery 自动安装适用于 Claude Desktop 的文件操作服务器：

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}：列出目录内容

示例使用

// Copy a file
await fileOperations.copyFile({
    source: 'source.txt',
    destination: 'destination.txt',
    overwrite: false
});

// Watch a directory
await fileOperations.watchDirectory({
    path: './watched-dir',
    recursive: true
});

// Access file contents through resource
const resource = await mcp.readResource('file:///path/to/file.txt');
console.log(resource.contents[0].text);

// Copy directory with progress tracking
const result = await fileOperations.copyDirectory({
    source: './source-dir',
    destination: './dest-dir',
    overwrite: false
});
// Progress token in result can be used to track progress
console.log(result.progressToken);

速率限制

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

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

速率限制错误消息中包含了一个重试等待期。

安全特性

路径验证

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

• 不使用父目录引用 (../)
• 正确的路径规范化
• 输入清理

资源保护

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

进度报告

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

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

可以通过操作结果中返回的进度令牌来跟踪进度。

开发

构建

npm run build

代码检查

npm run lint

格式化

npm run format

测试

npm test

配置

服务器可以通过各种设置进行配置：

• 速率限制：配置请求限制和窗口
• 进度报告：控制更新频率和详细程度
• 资源访问：配置资源权限和限制
• 安全设置：配置路径验证规则
• 变更跟踪：设置保留期限和存储选项
• 监视设置：配置防抖时间和递归监视

错误处理

服务器通过 FileOperationError 类和 MCP 错误代码提供详细的错误信息：

标准 MCP 错误代码

• InvalidRequest：无效的参数或请求格式
• MethodNotFound：未知的工具或资源请求
• InvalidParams：无效的参数（例如，路径验证失败）
• InternalError：服务器端错误

自定义错误类型

• 文件操作失败
• 超出速率限制
• 路径验证错误
• 资源访问错误

每个错误包括：

• 具体的错误代码
• 详细的错误消息
• 相关元数据（文件路径、限制等）
• 开发模式下的堆栈跟踪

贡献

1. 叉分仓库
2. 创建你的功能分支 (git checkout -b feature/amazing-feature)
3. 提交你的更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开一个 Pull Request

许可证

本项目采用 MIT 许可证 - 详情请参见 LICENSE 文件。