Windows File Tools MCP Server 🚀
一个基于 Bun 和 TypeScript 的 MCP (Model Context Protocol) 文件操作工具服务器，为 AI 助手提供安全、高效的文件读写和编辑功能。
✨ 功能特性
- 🔒 企业级安全：完整的路径验证和防攻击机制
- 🔐 文件锁机制：防止并发访问冲突，确保操作原子性
- 📝 文件读取：支持按行号范围读取文件内容，带行号显示
- ✍️ 原子写入：安全的文件内容写入，自动备份和回滚
- 🔄 精确编辑：支持全局和单次文本替换，正则表达式安全处理
- 🌐 Windows 优化：专门针对 Windows 路径格式优化
- ⚡ 高性能：基于 Bun 运行时，启动迅速，内存优化
- 🛡️ 错误处理：完善的错误捕获、操作日志和用户友好的错误信息
- 📊 操作追踪：每个操作都有唯一ID、性能计时和详细日志
📋 工具列表
1. file-read - 文件读取工具
读取指定路径的文件内容，支持按行号范围读取
参数：
file_path(string): 文件的绝对路径（Windows格式，如C:\path\to\file.txt）offset(number, 可选): 开始读取的行号（从1开始，默认为1）limit(number, 可选): 要读取的行数（不限制则读取全部）
返回：
- 📖 企业级安全读取成功确认
- 📄 文件路径和行号范围
- 📊 文件大小和读取字节数
- ⏱️ 操作耗时和操作ID
- 🔒 文件锁状态确认
- 带行号的文件内容显示
2. file-write - 文件写入工具
将内容写入指定路径的文件，如果文件不存在则创建
参数：
file_path(string): 文件的绝对路径（Windows格式，如C:\path\to\file.txt）content(string): 要写入文件的内容
返回：
- 🚀 企业级原子写入成功确认
- 📄 写入的文件路径
- 📊 写入的字节数和文件大小
- ⏱️ 操作耗时和操作ID
- 🔒 文件锁和备份状态确认
3. file-edit - 文件编辑工具
替换文件中的指定文本内容，支持全部替换或仅替换第一个匹配项
参数：
file_path(string): 文件的绝对路径（Windows格式，如C:\path\to\file.txt）old_string(string): 要替换的文本内容new_string(string): 替换后的文本内容（必须与old_string不同）replace_all(boolean, 可选): 是否替换所有出现的old_string（默认false，仅替换第一个）
返回：
- ✅ 文件原子编辑成功确认
- 📄 被编辑的文件路径
- 🔄 实际替换次数
- 📊 编辑后的文件大小
- ⏱️ 操作耗时和操作ID
🚀 快速开始
安装依赖
bun install开发模式运行
bun run dev构建生产版本
bun run build运行生产版本
bun run start类型检查
bun run typecheck运行测试
bun test📁 项目结构
windows-file-tools-mcp-ts/
├── 📄 index.ts # 主入口文件 (MCP服务器实现)
├── 📄 package.json # 项目配置和依赖
├── 📄 tsconfig.json # TypeScript 配置
├── 📄 CLAUDE.md # Claude Code 开发指导
├── 📄 README.md # 项目说明文档
├── 📄 dist/ # 构建输出目录
│ └── 📄 index.js # 构建后的服务器文件
└── 📁 node_modules/ # 依赖包🛡️ 企业级安全特性
- 路径验证：防止路径遍历攻击，支持Windows绝对路径
- 文件锁机制：防止并发访问冲突，30秒锁超时，100ms重试间隔
- 原子操作：所有写操作都是原子性的，失败时自动回滚
- 自动备份：写操作前自动创建备份，成功后清理
- 文件类型验证：支持75+种文件扩展名，覆盖主流编程语言
- 大小限制：10MB文件大小限制，防止内存溢出
- 操作日志：完整的操作追踪，包含性能计时和错误详情
- 错误边界：完善的错误处理和用户友好的错误信息
🔧 技术栈
- 运行时: Bun (最新版本)
- 语言: TypeScript 5.0+ (ES2022目标)
- 框架: @modelcontextprotocol/sdk 1.22.0
- 验证: Zod 3.25.76 (运行时类型验证)
- 文件系统: Node.js fs/promises (异步文件操作)
- 安全: 企业级路径验证、文件锁、原子操作
- 性能: 异步处理、流式读取、内存优化
- 测试: Bun 内置测试 runner
📝 使用示例
配置 Claude Desktop
在 Claude Desktop 的配置文件中添加：
{
"mcpServers": {
"windows-file-tools": {
"command": "bun",
"args": ["run", "H:\\mcp\\windows-file-tools-mcp-ts\\index.ts"]
}
}
}配置 Codex
在 Codex 的 config.toml 配置文件中添加：
[mcp_servers.file-bash-tools]
command = "bun"
args = ["H:\\mcp\\windows-file-tools-mcp-ts\\index.ts"]典型工作流
- 使用
file-read读取配置文件 - 使用
file-edit修改特定内容 - 使用
file-write创建新文件 - 再次使用
file-read验证更改
🎯 最佳实践
- 使用绝对路径：始终提供完整的Windows绝对路径
- 文件锁感知：了解文件锁机制，避免长时间操作
- 原子操作信任：信任原子操作的完整性，无需手动备份
- 错误处理：关注工具返回的详细错误信息和操作ID
- 性能考虑：大文件读取时使用limit参数限制读取范围
- 编码一致性：所有文件操作都使用UTF-8编码
- 操作追踪：利用返回的操作ID进行问题排查
🐛 故障排除
常见问题
- "路径不安全"错误
- 确保使用绝对路径 - 避免使用 .. 或相对路径
- "文件不存在"错误
- 检查文件路径是否正确 - 确认文件确实存在
- 权限错误
- 确保有足够的文件系统权限 - 检查文件是否被其他程序占用
- 文件锁超时
- 检查是否有其他进程正在操作同一文件 - 等待30秒后重试，或检查文件锁状态
- 原子操作失败
- 检查磁盘空间是否充足 - 验证文件路径是否有效 - 查看操作日志了解详细错误原因
📄 许可证
本项目基于 MIT 许可证开源。
🧪 测试
项目使用 Bun 内置的测试 runner：
# 运行所有测试
bun test
# 运行特定测试文件
bun test filename.test.ts测试文件应使用 .test.ts 或 .spec.ts 扩展名，并与源文件放在同一目录下。
🔧 开发指南
详细的开发指导请参考 CLAUDE.md 文件，其中包含：
- 项目架构详解
- 开发环境设置
- 代码规范和最佳实践
- 测试策略
🤝 贡献
欢迎提交 Issue 和 Pull Request！在提交代码前请确保：
- 通过
bun run typecheck类型检查 - 通过
bun test测试套件 - 遵循现有的代码风格和架构模式
📄 许可证
本项目基于 MIT 许可证开源。
注意: 这是一个企业级工具，具有文件锁、原子操作和自动备份等高级安全特性。请确保在生产环境中充分测试后再使用。