Windwos Bash Tools MCP Go

🚀 MCP Bash Tools

](https://golang.org/)   ![Tests] ![Coverage]

✨ 企业级安全PowerShell/Bash命令执行工具 ✨

基于 Model Context Protocol (MCP) 构建的现代化企业级命令执行解决方案，专为AI应用提供安全、可靠、高性能的Shell环境访问能力。

🚀 快速开始 • ✨ 功能特性 • 🏗️ 架构设计 • 🛡️ 安全机制 • 📚 开发文档 • 🧪 测试指南 • 🤝 贡献指南

📑 目录

• ✨ 功能特性
• 🚀 快速开始
• 📦 安装要求
• 🔌 MCP工具接口
• 🏗️ 架构设计
• 🛡️ 安全机制
• 🧪 测试
• 👨‍💻 开发指南
• 🔧 构建和部署
• 📊 性能指标
• 🔍 故障排除
• 📚 详细文档
• 🤝 贡献指南
• 📄 许可证

✨ 功能特性

🎯 核心功能

🏢 企业级特性

🚀 快速开始

📋 环境要求

⚡ 5步快速部署

1️⃣ 克隆项目

git clone https://github.com/your-org/mcp-bash-tools.git
cd mcp-bash-tools

2️⃣ 安装依赖

go mod download
go mod verify

3️⃣ 构建项目

# 发布模式构建（推荐）
.\build.ps1 -Release

# 验证构建结果
Get-Item dist\bash-tools.exe

4️⃣ MCP客户端配置

Claude Desktop 配置示例:

{
  "mcpServers": {
    "bash-tools": {
      "command": "H:\\mcp\\bash-tools\\dist\\bash-tools.exe",
      "args": [],
      "env": {}
    }
  }
}

配置文件位置: %APPDATA%\Claude\claude_desktop_config.json

5️⃣ 验证安装

启动服务器应该看到：

🚀 MCP Bash Tools Server starting...
🔧 检测到的Shell环境:
1. pwsh: C:\Program Files\PowerShell\7\pwsh.exe ✅ (首选)
2. powershell: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe ✅

🧪 快速测试

{
  "tool": "bash",
  "arguments": {
    "command": "Write-Output 'Hello, MCP Bash Tools!'; Get-Date",
    "timeout": 5000,
    "run_in_background": false
  }
}

期望输出:

Hello, MCP Bash Tools!
2024年11月16日 15:30:00

🔌 MCP工具接口

⚡ Bash工具 - 主要命令执行

功能: 安全执行PowerShell命令

超时行为:

• 前台执行: 如果命令在timeout时间内完成，立即返回结果
• 前台超时: 如果命令超过timeout时间，自动转为后台任务，返回任务ID，命令继续执行
• 后台执行: 无超时限制，持续运行直到完成或被手动终止

参数:

返回:

{
  "output": "命令输出内容",
  "exitCode": 0,
  "killed": false,
  "shellId": "bash_1701234567890123456"  // 后台模式或前台超时时返回
}

使用场景:

• 快速命令: run_in_background=false, timeout=5000 - 5秒内完成的命令
• 长时间任务: run_in_background=true - 编译、部署、长时间测试
• 自动转后台: 前台命令超时后自动转后台，不会被终止

📊 BashOutput工具 - 实时输出监控

功能: 获取后台任务实时输出

参数:

返回:

{
  "output": "过滤后的输出内容",
  "status": "running",  // running, completed, failed, killed
  "exitCode": null
}

⛔ KillShell工具 - 任务终止

功能: 终止后台任务

参数:

返回:

{
  "message": "任务已成功终止",
  "shell_id": "bash_1701234567890123456"
}

🏗️ 架构设计

📐 三层架构模式

┌─────────────────────────────────────┐
│          MCP接口层 (cmd/server)        │  ← 646行
│  • 工具注册与JSON-RPC通信             │
│  • 参数验证与错误处理                 │
│  • 后台任务管理                       │
└─────────────────────────┬───────────────────┘
                        │
                        ▼
┌─────────────────────────────────────┐
│        业务逻辑层 (internal)          │
│  • executor/  - Shell执行器 (3个)     │
│  • security/  - 安全验证 (2个)       │
│  • core/      - 类型定义              │
└─────────────────────────┬───────────────────┘
                        │
                        ▼
┌─────────────────────────────────────┐
│      基础设施层 (pkg)                 │
│  • logger/  - 日志系统                │
│  • utils/   - 工具函数                │
│  • config/  - 配置管理                │
└─────────────────────────────────────┘

🔧 核心组件

🔄 并发安全机制

• 读写锁: sync.RWMutex 保护后台任务存储
• 临时文件: 后台任务输出实时写入临时文件
• WaitGroup: 确保所有goroutine完成后才关闭文件
• 原子操作: 任务状态更新的原子性保证

🛡️ 安全机制

🏯 多层安全防护体系

1. 🔍 输入验证层 - 参数类型检查、长度验证、特殊字符过滤
2. 🔍 命令验证层 - 70+危险模式检测、正则表达式匹配、上下文分析
3. 📦 执行隔离层 - 工作目录限制、临时文件管理
4. ⏱️ 超时保护层 - 强制超时控制（1-600秒），防止无限等待
5. 📊 监控审计层 - 实时状态监控、命令执行记录

⚠️ 危险命令分类 (Windows专用)

✅ 安全命令示例

# ✅ 安全的系统监控
Get-Process | Select-Object Name, CPU
Get-PSDrive -PSProvider FileSystem
Test-Connection -ComputerName 8.8.8.8

# ✅ 安全的文件操作（只读）
Get-ChildItem -Path C:\Users -File
Get-Content -Path README.txt
Get-ChildItem -Recurse -Filter *.log

🧪 测试

📊 测试覆盖率

🚀 快速测试命令

# 运行所有测试
go test ./...

# 详细输出
go test -v ./...

# 生成覆盖率报告
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out -o coverage.html

# 并发安全测试
go test -race ./...

# 跳过已知问题的测试（快速测试）
go test ./... -skip="TestKillShellHandlerTestSuite" -skip="TestBashHandler_ConcurrentBackgroundTasks"

# 性能基准测试
go test -bench=. -benchmem ./...

# 运行特定测试
go test -v -run TestSecurityTestSuite ./cmd/server

📋 测试文件结构

👨‍💻 开发指南

🔨 开发环境设置

# 1. 检查Go版本
go version  # 需要 Go 1.23.0+

# 2. 克隆项目
git clone https://github.com/your-org/mcp-bash-tools.git
cd mcp-bash-tools

# 3. 安装依赖
go mod download
go mod verify

# 4. 检查PowerShell执行策略
Get-ExecutionPolicy
# 如果是 Restricted，设置执行策略
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

📝 代码质量检查

# 格式化代码
go fmt ./...

# 静态分析
go vet ./...

# 整理依赖
go mod tidy

# 运行测试
go test -race ./...

# 构建验证
.\build.ps1 -Release

🔄 开发工作流

1. 创建功能分支

   git checkout -b feature/new-feature

1. 编写代码并测试

   # 编写代码...
   go fmt ./...
   go vet ./...
   go test ./...

1. 构建验证

   .\build.ps1 -Release

1. 提交代码

   git add .
   git commit -m "feat: add new feature"
   git push origin feature/new-feature

🔧 构建和部署

📦 构建选项

# 调试模式构建
.\build.ps1

# 发布模式构建（生产环境推荐）
.\build.ps1 -Release

# 详细输出构建
.\build.ps1 -Verbose

# 清理构建缓存
.\build.ps1 -Clean

# 组合选项
.\build.ps1 -Release -Verbose

🎯 构建配置

🚀 部署指南

1. 构建可执行文件

   .\build.ps1 -Release

1. 验证构建结果

   Get-Item dist\bash-tools.exe | Select-Object Name, Length, CreationTime

1. 配置MCP客户端

- 更新配置文件中的可执行文件路径 - 重启MCP客户端

1. 验证部署

   .\dist\bash-tools.exe -h

📊 性能指标

📚 详细文档

📖 核心文档

• 开发指南 (CLAUDE.md) - 开发者必读，包含架构设计和最佳实践
• 改进记录 (IMPROVEMENTS.md) - 项目改进历史

🔍 审计报告

• 生产就绪性审计总结 - 总体评分 96/100 ⭐⭐⭐⭐⭐
• 完整审计报告 - 深度代码审查和安全评估
• 测试结果报告 - 前台超时转后台功能验证

📋 技术参考

• MCP协议规范 - 标准I/O工具接口
• 超时实现方法 - PowerShell超时最佳实践
• 类型定义 - TypeScript接口定义

更多文档: 查看 docs/INDEX.md 获取完整文档列表

🔍 故障排除

常见问题

❌ 构建失败

# 检查Go版本
go version

# 清理模块缓存
go clean -modcache
go mod download

# 重新构建
go build ./...

❌ PowerShell执行策略

# 检查执行策略
Get-ExecutionPolicy

# 设置执行策略（如果需要）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

❌ 测试失败

# 清理临时文件
Get-ChildItem -Path . -Recurse -Name "temp_*" -File | Remove-Item

# 跳过已知问题的测试
go test ./... -skip="TestKillShellHandlerTestSuite" -skip="TestBashHandler_ConcurrentBackgroundTasks"

❌ 后台任务问题

• 检查临时文件路径权限
• 验证goroutine写入逻辑
• 确认并发锁的使用

📞 获取帮助

1. 查看 CLAUDE.md 获取详细的开发指南
2. 检查 Issues 查看已知问题
3. 创建新的Issue报告问题

🤝 贡献指南

🌟 贡献方式

• 🐛 报告Bug - 发现问题时创建Issue
• 💡 提出功能 - 建议新功能或改进
• 📝 完善文档 - 改进文档和示例
• 💻 提交代码 - 修复Bug或添加功能

📝 代码规范

• 遵循 Go官方代码规范
• 使用 go fmt 格式化代码
• 使用 go vet 进行静态分析
• 新功能必须包含测试
• 更新相关文档

📋 提交规范

使用 Conventional Commits 规范：

# ✨ 新功能
feat: add new Bash tool support

# 🐛 Bug修复
fix: resolve timeout handling issue

# 📚 文档更新
docs: update README with new examples

# ✅ 测试
test: add unit tests for security validator

🔐 安全报告

如果发现安全漏洞，请不要公开报告！

• 📧 邮箱: security@your-org.com
• 📋 主题: [SECURITY] MCP Bash Tools Vulnerability Report

📄 许可证

本项目采用 MIT许可证。

❤️ 感谢使用 MCP Bash Tools！

让PowerShell命令执行更安全、更高效！

Made with ❤️ by the MCP Bash Tools Team

⬆ 回到顶部