文件操作与搜索服务器

🔧 File-Bash-Tools MCP 服务器

🏢 专为 Windows 环境打造的下一代企业级文件和命令工具 MCP 服务器

📋 目录

• 🚀 项目概述
• ✨ 核心功能
• 🏗️ 项目架构
• 🛠️ 技术栈
• 🚀 快速开始
• 📖 使用示例
• 🛡️ 安全特性
• 📚 文档
• 🤝 贡献
• 📄 许可证

🚀 项目概述

这是一款使用 Rust 实现的高性能、安全的 MCP（Model Context Protocol） 服务器，专为 Windows 系统设计，提供强大的文件操作和搜索功能。

🌟 为什么选择我们？

• ⚡ 极致性能: 基于 Rust 的零成本抽象和 Tokio 异步运行时
• 🔒 企业级安全: 多层安全验证，原子文件操作，防止路径遍历和资源滥用
• 🎯 Windows 原生: 专为 Windows 环境优化，支持原生路径格式和双反斜杠路径
• 📈 高并发: 智能并发控制，最多同时处理 10 个文件操作，使用 Semaphore 防止资源耗尽
• 🔍 强大搜索: 集成 ripgrep 核心库，支持复杂正则表达式和多种输出模式
• 🛡️ 原子操作: 使用 NamedTempFile 确保文件写入的原子性，失败时自动降级
• 🧠 智能优化: 根据搜索模式动态调整深度，自动跳过大文件（>10MB）

✨ 核心功能

📁 文件操作工具

🔍 搜索工具

📋 任务管理

TodoWrite - 结构化任务列表管理工具，支持状态跟踪和进度可视化

// 示例任务结构
{
  "content": "实现新的文件搜索功能",
  "status": "in_progress",
  "active_form": "正在实现文件搜索算法"
}

🏗️ 项目架构

graph TB
    A[MCP 客户端] --> B[stdio 通信]
    B --> C[main.rs - 30行服务器入口]
    C --> D[lib.rs - 951行核心服务]
    D --> E[RMCP工具路由层]
    E --> F[文件操作工具]
    E --> G[搜索工具]
    E --> H[任务管理]
    F --> F1[write_file - 原子写入]
    F --> F2[read_file - 智能读取]
    F --> F3[edit_file - 原子编辑]
    G --> G1[glob - 模式匹配]
    G --> G2[grep - ripgrep搜索]
    H --> H1[TodoWrite - 任务管理]
    I[Arc<Semaphore>] --> F
    I --> G
    I --> H
    J[NamedTempFile] --> F1
    J --> F3

📂 目录结构

file-bash-tools-mcp/
├── 📄 src/
│   ├── 🚀 main.rs               # 30行 - 服务器入口点，日志和服务初始化
│   └── ⚙️ lib.rs                # 951行 - 核心服务实现（唯一被编译的实现，含全部6个工具）
├── 📄 Cargo.toml                # 63行 - 项目配置和依赖管理
├── 📄 CLAUDE.md                 # Claude开发指南，完整的项目文档
├── 📄 README.md                 # 项目说明文档
└── 📚 .git/                     # Git版本控制

🛠️ 技术栈

🏗️ 核心框架

📦 序列化和验证

🔍 文件系统和搜索

⚡ 性能和工具

📝 日志和错误处理

🚀 快速开始

📋 系统要求

• 🦀 Rust 1.88+（rmcp 3.1.1 的 MSRV）
• 📦 Cargo 包管理器
• 🖥️ Windows 操作系统

🔧 安装与构建

git clone https://github.com/x1t/windows-file-tools-mcp-rust.git
cd windows-file-tools-mcp-rust

# 开发模式构建
cargo build

# 生产模式构建（推荐）
cargo build --release

# 开发模式运行
cargo run

# 生产模式运行（推荐）
cargo run --release

# 运行所有测试
cargo test

# 运行特定测试
cargo test test_glob_pattern_matching

# 显示测试详细输出
cargo test -- --nocapture

📖 使用示例

🔧 文件操作

{
  "tool": "write_file",
  "arguments": {
    "file_path": "C:\\\\Temp\\\\example.txt",
    "content": "Hello, Windows MCP Server! 🎉"
  }
}

{
  "tool": "read_file",
  "arguments": {
    "file_path": "C:\\\\Temp\\\\example.txt",
    "offset": 1,
    "limit": 10
  }
}

{
  "tool": "edit_file",
  "arguments": {
    "file_path": "C:\\\\Temp\\\\example.txt",
    "old_string": "Hello",
    "new_string": "Hi",
    "replace_all": true
  }
}

🔍 搜索功能

{
  "tool": "glob",
  "arguments": {
    "pattern": "**/*.rs",
    "path": "C:\\\\Projects\\\\my-rust-app"
  }
}

{
  "tool": "grep",
  "arguments": {
    "pattern": "async fn.*test",
    "path": "src/",
    "output_mode": "content",
    "case_insensitive": true,
    "show_line_numbers": true,
    "before_context": 2,
    "after_context": 2
  }
}

📋 任务管理

{
  "tool": "TodoWrite",
  "arguments": {
    "todos": [
      {
        "content": "实现文件搜索功能",
        "status": "completed",
        "active_form": "已完成文件搜索功能实现"
      },
      {
        "content": "添加并发控制",
        "status": "in_progress", 
        "active_form": "正在实现 Semaphore 并发控制"
      },
      {
        "content": "编写单元测试",
        "status": "pending",
        "active_form": "待编写单元测试"
      }
    ]
  }
}

🔌 MCP 客户端集成

使用 MCP Inspector

# 启动交互式 MCP 测试环境
npx @modelcontextprotocol/inspector cargo run --release

在 Claude Desktop 中使用

{
  "mcpServers": {
    "file-bash-tools": {
      "command": "cargo",
      "args": ["run", "--release", "--manifest-path", "F:/mcp/windows-file-tools-mcp-rust/Cargo.toml"]
    }
  }
}

注意: 请将 F:/mcp/windows-file-tools-mcp-rust/Cargo.toml 替换为您的实际项目路径

🛡️ 安全特性

🎯 性能优化亮点

• 🔄 智能并发控制: 使用 Arc<Semaphore> 最多同时处理 10 个文件，防止资源耗尽
• 📏 动态深度调整（grep 的 search_files，lib.rs:377）:
  • files_with_matches 模式：20层深度
  • count 模式：30层深度
  • 默认模式：有 glob 过滤时 10层，否则 50层
• 💾 大文件跳过: 搜索时自动跳过超过 10MB 的大文件
• 🛡️ 原子操作: 使用 NamedTempFile 确保文件操作的原子性和数据完整性
• 🔄 降级机制: 原子操作失败时自动回退到标准文件操作
• 🧠 Windows优化: 专门针对Windows路径格式（双反斜杠）和文件系统特性优化

📚 文档

🤝 贡献

🌟 我们欢迎所有形式的贡献！

🚀 快速贡献流程

# 1. Fork 并克隆仓库
git clone https://github.com/YOUR_USERNAME/windows-file-tools-mcp-rust.git
cd windows-file-tools-mcp-rust

# 2. 创建功能分支
git checkout -b feature/amazing-feature

# 3. 提交更改
git commit -m '✨ feat: 添加超棒的新功能'

# 4. 推送分支
git push origin feature/amazing-feature

# 5. 创建 Pull Request

🧪 测试要求

• 无警告: 确保所有测试通过，无任何警告信息
• 原子操作: 所有文件操作必须支持原子性
• 错误处理: 实现完整的错误处理和降级机制
• 性能验证: 大文件处理和并发操作性能测试
• 安全检查: 路径验证和输入清理测试

📝 代码规范

• Rust最佳实践: 使用 cargo fmt 和 cargo clippy
• 文档完整: 所有公共API必须有完整的rustdoc注释
• 原子操作优先: 优先使用原子文件操作，失败时自动降级
• Windows兼容: 确保所有路径处理支持Windows双反斜杠格式
• 企业级日志: 使用 tracing 记录操作ID和性能信息

📋 贡献指南

• 🔍 Bug 报告: 请使用 Issue 模板提供详细的重现步骤
• 💡 功能请求: 描述使用场景和期望的行为
• 📝 文档改进: 修正错别字、改进示例或添加新内容
• 🧪 测试: 添加测试用例或改进现有测试
• 🎨 代码风格: 遵循 Rust 官方代码规范

🏆 致谢

感谢所有为这个项目做出贡献的开发者和用户！ 🙏

特别感谢：

• MCP 协议团队 - 提供优秀的协议规范和RMCP SDK
• Rust 社区 - 提供强大的生态系统和工具链
• ripgrep 团队 - 提供高性能搜索核心库
• Tokio 团队 - 提供出色的异步运行时
• Tempfile 维护者 - 提供原子文件操作支持

🌟 核心技术致谢

本项目的企业级特性得益于以下优秀的开源技术：

• RMCP 3.1.1: 让MCP服务器开发变得简单高效
• ripgrep核心: 为我们提供世界级的文本搜索能力
• Tokio异步: 让高并发文件操作成为可能
• 原子操作: 确保数据完整性和企业级可靠性

📄 许可证

本项目采用 MIT 许可证 开源

👥 核心团队

📞 技术支持

💬 获得帮助

⭐ 如果这个项目对你有帮助，请给我们一个 Star！