🚀 MCP Bash Tools

[] []

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

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

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

---

📑 目录

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

---

✨ 功能特性

🎯 核心功能

功能类别	描述	状态
🛡️ 安全命令执行	多层安全验证，70+危险模式识别	✅ 企业级
⚡ 前台/后台模式	同步执行与异步任务管理	✅ 稳定
🎯 智能超时控制	1-600秒范围，自动终止超时任务	✅ 完善
📊 实时输出监控	临时文件存储，正则表达式过滤	✅ 高效
🔧 多Shell支持	PowerShell 7 → Git Bash → PowerShell 5+ → CMD	✅ 智能

🏢 企业级特性

特性	描述	实现方式
🔐 权限控制	JWT认证 + RBAC权限控制	Token-based Auth
📝 审计日志	结构化日志记录，安全事件追踪	Logrus + Custom
🚫 危险命令过滤	70+种危险模式，实时威胁识别	Regex + Context
⚖️ 资源限制	CPU 80%	内存512MB
🔄 任务管理	50个并发任务，sync.RWMutex安全	Goroutine + Mutex
🏗️ 沙箱隔离	可选沙箱执行环境，工作目录隔离	Process Isolation

---

🚀 快速开始

📋 环境要求

要求	版本	验证命令
操作系统	Windows 10/11 x64	systeminfo | findstr /B /C:"OS Name"
Go语言	Go 1.23.0+	go version
PowerShell	PowerShell 7.0+	$PSVersionTable.PSVersion
Git	Git 2.0+	git --version

⚡ 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 ✅
3. cmd: C:\Windows\system32\cmd.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/CMD命令

参数:

参数	类型	必填	默认值	描述
command	string	✅	-	要执行的命令
timeout	number	❌	30000	超时时间(毫秒)，1000-600000
description	string	❌	-	命令描述
run_in_background	boolean	✅	false	是否后台执行

返回:

{
  "output": "命令输出内容",
  "exitCode": 0,
  "killed": false,
  "shellId": "bash_1701234567890123456"  // 仅后台模式
}

📊 BashOutput工具 - 实时输出监控

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

参数:

参数	类型	必填	描述
bash_id	string	✅	后台任务ID
filter	string	❌	正则表达式过滤器

返回:

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

⛔ KillShell工具 - 任务终止

功能: 终止后台任务

参数:

参数	类型	必填	描述
shell_id	string	✅	要终止的任务ID

返回:

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

---

🏗️ 架构设计

📐 三层架构模式

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

🔧 核心组件

组件	文件	行数	主要功能
MCP服务器	cmd/server/main.go	646	工具注册、任务管理、JSON-RPC通信
安全执行器	internal/executor/secure_bash.go	558	沙箱隔离、资源限制、实时监控
Shell管理	internal/executor/shell.go	185	智能Shell检测、环境优化
安全管理	internal/security/security.go	561	JWT认证、RBAC、速率限制
命令验证	internal/security/validator.go	213	70+危险模式识别

🔄 并发安全机制

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

---

🛡️ 安全机制

🏯 六层安全防护体系

1. 🔍 输入验证层 - 参数类型检查、长度验证、特殊字符过滤
2. 🔐 认证授权层 - JWT Token验证、RBAC权限控制、会话管理
3. ⚖️ 限流保护层 - Token Bucket算法、10 RPS/20 Burst、IP级别限流
4. 🔍 命令验证层 - 70+危险模式检测、正则表达式匹配、上下文分析
5. 📦 沙箱隔离层 - 工作目录限制、资源配额、网络访问控制
6. 📊 监控审计层 - 实时状态监控、安全事件记录、异常行为检测

⚠️ 危险命令分类

类别	示例	检测方式
系统破坏	rm -rf /, format C:, dd if=/dev/zero	正则匹配
系统控制	shutdown, reboot, Stop-Computer	命令黑名单
权限提升	sudo su, passwd, net localgroup	权限检测
网络攻击	iptables -F, nc -l, Test-NetConnection	网络监控
资源消耗	Fork bomb, 无限循环, 磁盘写满	模式识别

✅ 安全命令示例

# ✅ 安全的系统监控
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

---

🧪 测试

📊 测试覆盖率

模块	覆盖率	测试重点
security模块	100%	危险命令检测、认证授权、限流
executor模块	90%+	命令执行、超时控制、前后台
windows模块	85%+	平台优化、编码设置
server主程序	80%+	MCP工具集成、任务管理
整体覆盖率	85%+	所有模块综合

🚀 快速测试命令

# 运行所有测试
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

📋 测试文件结构

测试文件	行数	测试内容
main_test.go	291	核心功能测试，MockShellExecutor
security_test.go	482	70+危险命令安全测试
background_task_test.go	566	任务管理与并发安全测试
bash_output_test.go	399	输出获取与正则过滤测试
kill_shell_test.go	435	任务终止与资源清理测试

---

👨‍💻 开发指南

🔨 开发环境设置

# 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

2. 编写代码并测试

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

3. 构建验证

   .\build.ps1 -Release

4. 提交代码

   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

🎯 构建配置

配置	调试模式	发布模式
优化	基础构建	优化编译（-ldflags "-s -w"）
调试信息	包含	移除
文件大小	较大	最小化
适用场景	开发测试	生产部署

🚀 部署指南

1. 构建可执行文件

   .\build.ps1 -Release

2. 验证构建结果

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

3. 配置MCP客户端

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

4. 验证部署

   .\dist\bash-tools.exe -h

---

📊 性能指标

指标	当前值	目标值	状态
命令启动延迟	< 100ms	< 200ms	🏆 优秀
并发任务数	50	100	📈 良好
内存使用	< 512MB	< 1GB	🏆 优秀
CPU使用率	< 80%	< 90%	🏆 优秀
输出延迟	< 50ms	< 100ms	🏆 优秀
安全验证时间	< 20ms	< 50ms	🏆 优秀

---

🔍 故障排除

常见问题

❌ 构建失败

# 检查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

⬆ 回到顶部