文件操作 MCP 服务器

一个模型上下文协议 (MCP) 服务器，提供增强的文件操作功能，支持流式传输、补丁和变更跟踪。

<a href="https://glama.ai/mcp/servers/7b750si00d"> <img width="380" height="200" src="https://glama.ai/mcp/servers/7b750si00d/badge" alt="File Operations Server MCP server" /> </a>

功能特性

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

安装

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 File Operations Server：

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

使用示例

// 复制文件
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);

速率限制

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

• 工具: 每分钟 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. Fork 仓库
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 文件。