# 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

## 🚀 快速开始

### 安装依赖
```bash
bun install
```

### 开发模式运行
```bash
bun run dev
```

### 构建生产版本
```bash
bun run build
```

### 运行生产版本
```bash
bun run start
```

### 类型检查
```bash
bun run typecheck
```

### 运行测试
```bash
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 的配置文件中添加：

```json
{
  "mcpServers": {
    "windows-file-tools": {
      "command": "bun",
      "args": ["run", "H:\\mcp\\windows-file-tools-mcp-ts\\index.ts"]
    }
  }
}
```

### 配置 Codex
在 Codex 的 `config.toml` 配置文件中添加：

```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：

```bash
# 运行所有测试
bun test

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

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

## 🔧 开发指南

详细的开发指导请参考 [CLAUDE.md](./CLAUDE.md) 文件，其中包含：
- 项目架构详解
- 开发环境设置
- 代码规范和最佳实践
- 测试策略

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！在提交代码前请确保：
1. 通过 `bun run typecheck` 类型检查
2. 通过 `bun test` 测试套件
3. 遵循现有的代码风格和架构模式

## 📄 许可证

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

---

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