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/         # 依赖包

🛡️ 企业级安全特性

1. 路径验证：防止路径遍历攻击，支持Windows绝对路径
2. 文件锁机制：防止并发访问冲突，30秒锁超时，100ms重试间隔
3. 原子操作：所有写操作都是原子性的，失败时自动回滚
4. 自动备份：写操作前自动创建备份，成功后清理
5. 文件类型验证：支持75+种文件扩展名，覆盖主流编程语言
6. 大小限制：10MB文件大小限制，防止内存溢出
7. 操作日志：完整的操作追踪，包含性能计时和错误详情
8. 错误边界：完善的错误处理和用户友好的错误信息

🔧 技术栈

• 运行时: 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"]

典型工作流

1. 使用 file-read 读取配置文件
2. 使用 file-edit 修改特定内容
3. 使用 file-write 创建新文件
4. 再次使用 file-read 验证更改

🎯 最佳实践

1. 使用绝对路径：始终提供完整的Windows绝对路径
2. 文件锁感知：了解文件锁机制，避免长时间操作
3. 原子操作信任：信任原子操作的完整性，无需手动备份
4. 错误处理：关注工具返回的详细错误信息和操作ID
5. 性能考虑：大文件读取时使用limit参数限制读取范围
6. 编码一致性：所有文件操作都使用UTF-8编码
7. 操作追踪：利用返回的操作ID进行问题排查

🐛 故障排除

常见问题

1. "路径不安全"错误

   • 确保使用绝对路径
   • 避免使用 .. 或相对路径

2. "文件不存在"错误

   • 检查文件路径是否正确
   • 确认文件确实存在

3. 权限错误

   • 确保有足够的文件系统权限
   • 检查文件是否被其他程序占用

4. 文件锁超时

   • 检查是否有其他进程正在操作同一文件
   • 等待30秒后重试，或检查文件锁状态

5. 原子操作失败

   • 检查磁盘空间是否充足
   • 验证文件路径是否有效
   • 查看操作日志了解详细错误原因

📄 许可证

本项目基于 MIT 许可证开源。

🧪 测试

项目使用 Bun 内置的测试 runner：

# 运行所有测试
bun test

# 运行特定测试文件
bun test filename.test.ts

测试文件应使用 .test.ts 或 .spec.ts 扩展名，并与源文件放在同一目录下。

🔧 开发指南

详细的开发指导请参考 CLAUDE.md 文件，其中包含：

• 项目架构详解
• 开发环境设置
• 代码规范和最佳实践
• 测试策略

🤝 贡献

欢迎提交 Issue 和 Pull Request！在提交代码前请确保：

1. 通过 bun run typecheck 类型检查
2. 通过 bun test 测试套件
3. 遵循现有的代码风格和架构模式

📄 许可证

本项目基于 MIT 许可证开源。

---

注意: 这是一个企业级工具，具有文件锁、原子操作和自动备份等高级安全特性。请确保在生产环境中充分测试后再使用。