文件操作 MCP 服务器

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

特征

• 基本文件操作：复制、读取、写入、移动和删除文件

• 目录操作：创建、删除和复制目录

• 文件监视：监视文件和目录的变化

• Change Tracking ：跟踪和查询文件操作历史

• 流媒体支持：通过流媒体高效处理大文件

• 资源支持：通过 MCP 资源访问文件和目录

• 进度报告：长期操作的实时进度更新

• 速率限制：防止过多的请求

• 增强的安全性：路径验证和输入清理

• 强大的错误处理：全面的错误处理和报告

• 类型安全：全面支持 TypeScript，并进行严格的类型检查

Related MCP server: Filesystem MCP Server

安装

通过 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. 打开拉取请求

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。