Claude Command Runner

🚀 Claude Command Runner

Claude Command Runner 是一款強大的模型上下文協議（MCP）服務器，它架起了 Claude Desktop 與終端應用之間的橋樑，支持無縫執行命令，智能獲取輸出，並具備全面的 3.0 版本特性，極大地提升了開發效率。

🚀 快速開始

Claude Command Runner 為開發工作流程帶來了革命性的改變，Claude 能夠通過它：

• 直接在對話中執行終端命令。
• 以智能的時間安排自動捕獲輸出。
• 跟蹤命令歷史和模式。
• 通過可配置的策略確保安全性。

✨ 主要特性

智能自動獲取

execute_with_auto_retrieve 命令現在能夠智能檢測命令類型並調整等待時間：

• 快速命令（如 echo、pwd）：2 - 6 秒。
• 中等命令（如 git、npm）：最長 20 秒。
• 構建命令（如 swift build、make）：最長 77 秒。
• 測試命令：最長 40 秒。

完整功能集

• ✅ 雙向通信並自動捕獲輸出。
• ✅ 針對所有命令類型的漸進式延遲系統。
• ✅ 使用 SQLite 數據庫記錄命令歷史。
• ✅ 可配置的安全策略。
• ✅ 多終端支持（推薦使用 Warp）。
• ✅ 基於歷史記錄的命令建議。

📦 安裝指南

前提條件

• macOS 13.0 或更高版本。
• Swift 6.0+（Xcode 16+）。
• Claude Desktop。
• 支持的終端（強烈推薦 Warp）。

快速安裝

1. 克隆並構建項目：

git clone https://github.com/M-Pineapple/claude-command-runner.git
cd claude-command-runner
./build.sh

2. 在 Claude Desktop 的 MCP 設置中添加以下配置：

{
  "claude-command-runner": {
    "command": "/path/to/claude-command-runner/.build/release/claude-command-runner",
    "args": ["--port", "9876"],
    "env": {}
  }
}

3. 重啟 Claude Desktop。

💻 使用示例

基礎用法

可用工具

1. execute_command - 手動執行命令並獲取輸出。
2. execute_with_auto_retrieve - 智能自動執行並獲取輸出 ⭐。
3. get_command_output - 手動獲取命令輸出。
4. preview_command - 預覽命令而不執行。
5. suggest_command - 獲取命令建議。

示例工作流

你：“構建我的 Swift 項目”
Claude：[執行：swift build]
[智能等待最長 77 秒]
Claude：“構建成功完成！以下是輸出內容...”

📚 詳細文檔

配置

配置文件位於 ~/.claude-command-runner/config.json：

{
  "terminal": {
    "preferred": "auto",
    "fallbackOrder": ["Warp", "WarpPreview", "iTerm", "Terminal"]
  },
  "security": {
    "blockedCommands": ["rm -rf /", "format"],
    "maxCommandLength": 1000
  },
  "history": {
    "enabled": true,
    "maxEntries": 10000
  }
}

常見問題解答

Q：為什麼服務器有時會崩潰？

A：這在早期版本中是個主要問題。v3.0 通過移除有問題的後臺任務並實現更安全的漸進式延遲系統，徹底解決了服務器穩定性問題。

Q：自動獲取功能會為我的命令等待多長時間？

A：這取決於命令類型：

• 簡單命令：6 秒。
• Git/npm 命令：20 秒。
• 構建命令：77 秒。
• 未知命令：30 秒。

Q：我可以在 Terminal.app 或 iTerm2 中使用這個工具嗎？

A：可以，任何終端都支持基本的命令執行。但自動輸出捕獲和高級功能需要使用 Warp Terminal。點擊此處免費獲取 Warp。

Q：讓 Claude 運行命令安全嗎？

A：安全！每個命令都需要手動確認（按 Enter 鍵），並且你可以在配置文件中配置阻止的命令和模式。Claude 必須得到你的明確同意才能執行任何命令。

Q：如果我的構建過程超過 77 秒會怎樣？

A：自動獲取功能將超時並提供命令 ID。你可以在準備好後使用 get_command_output 和該 ID 來獲取結果。

Q：我的命令歷史記錄存儲在哪裡？

A：存儲在 ~/.claude-command-runner/claude_commands.db 的 SQLite 數據庫中。它會記錄所有命令、輸出、退出代碼和執行時間。

Q：我可以為這個項目做出貢獻嗎？

A：當然可以！你可以 fork 倉庫，進行修改並提交 PR。請查看下面的貢獻指南。

Q：為什麼你強烈推薦 Warp？

A：Warp 提供的 API 支持其他終端無法實現的功能：

• 無需輪詢即可自動捕獲輸出。
• 集成的命令歷史記錄。
• 現代的異步架構。

故障排除

MCP 無響應

1. 檢查服務器是否正在運行：lsof -i :9876。
2. 重啟 Claude Desktop。
3. 使用 ./build.sh 重新構建項目。

命令未在終端中顯示

1. 確保 Warp/WarpPreview 正在運行。
2. 檢查 Claude Desktop 日誌中是否有錯誤。
3. 驗證 MCP 配置路徑。

自動獲取功能不起作用

1. 確保你使用的是 execute_with_auto_retrieve（而不是 execute_command）。
2. 檢查命令輸出文件是否存在：ls /tmp/claude_output_*.json。
3. 對於長命令，等待超時消息後使用手動獲取。

數據庫未記錄命令

如果命令執行但未保存到數據庫：

1. 檢查數據庫完整性：

sqlite3 ~/.claude-command-runner/claude_commands.db "PRAGMA integrity_check;"

2. 如果看到錯誤或“missing from index”消息，說明數據庫已損壞：

# 備份並刪除損壞的數據庫
mv ~/.claude-command-runner/claude_commands.db ~/.claude-command-runner/claude_commands.db.backup
# 重啟 Claude Desktop - 會自動創建新的數據庫

3. 驗證數據庫是否正常工作：

# 檢查命令是否被記錄
sqlite3 ~/.claude-command-runner/claude_commands.db "SELECT COUNT(*) FROM commands;"

4. 檢查是否有多個服務器實例：

ps aux | grep claude-command-runner | grep -v grep
# 如果看到多個實例，殺死所有實例並重啟 Claude Desktop

v3.0 版本包含自動損壞檢測和恢復功能，但如果問題仍然存在，手動刪除數據庫文件將強制重新創建一個乾淨的數據庫。

架構

┌─────────────────┐         ┌──────────────────┐         ┌────────────────┐
│ Claude Desktop  │ ←────→  │ Command Runner   │ ←────→  │ Warp Terminal  │
│                 │  MCP    │ MCP Server       │ Script  │                │
│ • 發送命令      │         │ • 端口 9876      │         │ • 執行命令     │
│ • 自動獲取      │         │ • 漸進式延遲     │         │ • 捕獲輸出     │
│ • 獲取輸出      │         │ • SQLite 數據庫  │         │ • 返回結果     │
└─────────────────┘         └──────────────────┘         └────────────────┘

貢獻

我們歡迎貢獻！貢獻步驟如下：

1. Fork 倉庫。
2. 創建功能分支（git checkout -b feature/amazing-feature）。
3. 提交更改（git commit -m 'Add amazing feature'）。
4. 推送到分支（git push origin feature/amazing-feature）。
5. 打開 Pull Request。

開發設置

git clone https://github.com/yourusername/claude-command-runner.git
cd claude-command-runner
swift package resolve
swift build

支持本項目

如果 Claude Command Runner 幫助你優化了開發工作流程，或者通過智能命令執行節省了時間，考慮支持其開發：

你的支持將幫助我：

• 維護和改進 Claude Command Runner，添加新功能。
• 保持項目開源並免費供所有人使用。
• 投入更多時間處理用戶請求和修復漏洞。
• 探索新的終端集成和命令智能。

感謝你考慮支持我的工作！🙏

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

由 🍍 用心打造

如果你覺得這個項目有幫助，請給它一個 ⭐ 並嘗試使用 Warp 終端！

📊 為什麼推薦 Warp 終端？

為了獲得最佳體驗，我們推薦使用 Warp 終端：

💡 免費獲取 Warp：下載 Warp 終端 - 它是免費的，能讓 Claude Command Runner 更強大！