Commander MCP

🚀 commander-mcp

commander-mcp 是一個用於後臺進程管理的模型上下文協議（MCP）服務器。它使用 Rust 構建，通過 MCP 協議和 PMDaemon 提供強大的工具，用於運行、監控和管理後臺進程。

🚀 快速開始

前提條件

• Rust 1.70 或更高版本（用於從源代碼構建）
• Cargo（隨 Rust 一起安裝）

安裝

使用安裝腳本（推薦）

安裝 commander-mcp 最簡單的方法是使用安裝腳本：

curl -fsSL https://raw.githubusercontent.com/towry/commander-mcp/main/install.sh | bash

或者先下載並檢查腳本：

curl -fsSL https://raw.githubusercontent.com/towry/commander-mcp/main/install.sh -o install.sh
chmod +x install.sh
./install.sh

支持的平臺：

• macOS Apple Silicon（M1/M2/M3） - aarch64-apple-darwin
• Linux x86_64 - x86_64-unknown-linux-gnu

腳本將執行以下操作：

1. 自動檢測您的平臺
2. 下載最新的發佈二進制文件
3. 將其安裝到 /usr/local/bin
4. 驗證安裝

從源代碼構建

# 克隆倉庫
git clone https://github.com/towry/commander-mcp.git
cd commander-mcp

# 構建項目
cargo build --release

# 運行服務器
cargo run --release

使用方法

MCP 服務器通過標準輸入/輸出使用 MCP 協議進行通信。您可以使用 MCP Inspector 進行測試：

# 安裝 MCP Inspector（需要 Node.js）
npm install -g @modelcontextprotocol/inspector

# 如果通過安裝腳本安裝
npx @modelcontextprotocol/inspector commander-mcp

# 如果從源代碼運行
npx @modelcontextprotocol/inspector cargo run --release

與 Claude Desktop 一起使用

要將此 MCP 服務器與 Claude Desktop 一起使用，請將以下內容添加到您的 Claude Desktop 配置文件中： macOS：~/Library/Application Support/Claude/claude_desktop_config.json Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "commander": {
      "command": "/usr/local/bin/commander-mcp"
    }
  }
}

或者如果從源代碼運行：

{
  "mcpServers": {
    "commander": {
      "command": "cargo",
      "args": ["run", "--release", "--manifest-path", "/path/to/commander-mcp/Cargo.toml"]
    }
  }
}

✨ 主要特性

• 支持 MCP 協議：基於官方 Rust MCP SDK（v0.7）構建
• 集成 PMDaemon：強大的進程管理，內置監控和日誌管理
• 進程管理工具：運行、終止、重啟和監控進程
• 持久化日誌：進程輸出保存到文件中，可以隨時讀取
• 跨平臺：可在 Linux、Windows 和 macOS 上運行
• 標準 I/O 傳輸：通過標準輸入/輸出進行通信，易於集成
• 異步運行時：基於 Tokio 構建，實現高性能異步操作
• 類型安全：利用 Rust 的類型系統確保可靠性

💻 使用示例

基礎用法

以下是使用 run 工具在後臺運行命令的示例：

{
  "command": "npm run dev"
}

響應（JSON）：

{
  "process_id": "npm_run",
  "command": "npm run dev",
  "message": "Started process 'npm_run'",
  "logs": "... initial log output (if available) ..."
}

錯誤響應（如果進程立即失敗）：

{
  "error": "Process 'npm_run' failed to start. Logs:\n... error logs ..."
}

高級用法

以下是使用 list 工具列出所有當前運行或已停止的進程的示例：

{
  "processes": [
    {
      "name": "npm_run",
      "status": "running",
      "pid": 12345,
      "started_at": "2025-10-03 17:14:55 UTC",
      "uptime_seconds": 120,
      "restarts": 0,
      "cpu_usage": 2.5,
      "memory_mb": 45
    }
  ]
}

📚 詳細文檔

可用工具

run

在後臺執行命令。 描述：在後臺運行命令。該工具在啟動後等待 1 秒以檢測早期故障。返回可用於其他工具的進程 ID 以及初始日誌。 參數：

• command（字符串）：要運行的命令

示例：

{
  "command": "npm run dev"
}

響應（JSON）：

{
  "process_id": "npm_run",
  "command": "npm run dev",
  "message": "Started process 'npm_run'",
  "logs": "... initial log output (if available) ..."
}

錯誤響應（如果進程立即失敗）：

{
  "error": "Process 'npm_run' failed to start. Logs:\n... error logs ..."
}

注意事項：

• 該工具在啟動進程後等待 1 秒以檢測早期故障
• 如果進程在此時間內進入錯誤或停止狀態，則返回錯誤
• 響應中包含初始日誌（最多 100 行）（如果可用）
• 這有助於檢測諸如“地址已在使用”之類的問題，而無需單獨調用 read 工具

kill

通過進程 ID 終止先前啟動的進程。 參數：

• process_id（字符串）：要終止的進程 ID

示例：

{
  "process_id": "npm_run"
}

響應（JSON）：

{
  "process_id": "npm_run",
  "message": "Stopped process 'npm_run'"
}

kill_all

終止所有正在運行的進程。 參數：無 示例：不帶參數調用以停止所有進程。 響應（JSON）：

{
  "stopped_count": 3,
  "message": "Stopped 3 process(es)"
}

read

通過進程 ID 讀取進程的標準輸出。 描述：返回最近的日誌輸出（默認：最後 1000 行）。 參數：

• process_id（字符串）：要讀取輸出的進程 ID
• lines（數字，可選）：要返回的最大日誌行數（默認：1000）

示例：

{
  "process_id": "npm_run",
  "lines": 500
}

響應（JSON）：

{
  "process_id": "npm_run",
  "logs": "... log output here ..."
}

restart

通過進程 ID 重啟先前運行的進程。 參數：

• process_id（字符串）：要重啟的進程 ID

示例：

{
  "process_id": "npm_run"
}

響應（JSON）：

{
  "process_id": "npm_run",
  "message": "Restarted process 'npm_run'"
}

list

列出所有當前運行或已停止的進程。 參數：無 響應（JSON）：

{
  "processes": [
    {
      "name": "npm_run",
      "status": "running",
      "pid": 12345,
      "started_at": "2025-10-03 17:14:55 UTC",
      "uptime_seconds": 120,
      "restarts": 0,
      "cpu_usage": 2.5,
      "memory_mb": 45
    }
  ]
}

返回所有進程的列表，包含其狀態、PID、啟動時間戳、運行時間、CPU 使用率、內存使用率和重啟次數。

工作原理

1. 進程管理：使用 PMDaemon，這是一個用 Rust 編寫的高性能進程管理器
2. 進程 ID：根據命令關鍵字自動生成（例如，npm run dev → npm_run）
3. 持久化日誌：所有進程輸出都保存到日誌文件中，可以隨時讀取
4. 即時監控：跟蹤 CPU、內存使用情況和進程狀態
5. 跨平臺：原生支持 Linux、Windows 和 macOS

關鍵特性

• 持久化日誌管理：日誌保存到文件中，可以隨時讀取（不僅僅是即時輸出）
• 按進程訪問日誌：可以讀取特定進程的日誌
• 無外部依賴：PMDaemon 是一個 Rust 庫，無需外部二進制文件
• 跨平臺：原生支持 Windows、macOS 和 Linux
• 內置監控：包含 CPU 和內存跟蹤
• 直接 API：通過 Rust API 進行編程控制

🔧 技術細節

運行測試

# 運行所有測試
cargo test --all-features --verbose

# 運行帶輸出的測試
cargo test -- --nocapture

代碼質量

本項目遵循 Rust 最佳實踐，並使用常規提交進行自動發佈。

# 格式化代碼（提交前必需）
cargo fmt --all

# 檢查格式化
cargo fmt --all -- --check

# 運行代碼檢查
RUSTFLAGS="-D warnings" cargo clippy --workspace --all-targets --all-features --verbose

使用 Just 命令

本項目包含一個 justfile 以方便開發：

# 格式化、檢查和測試
just check

# 格式化代碼
just format

# 運行代碼檢查
just lint

# 運行測試
just test

# 構建發佈二進制文件
just build

項目結構

commander-mcp/
├── src/
│   ├── main.rs              # 入口點，設置 MCP 服務器
│   ├── process_server.rs    # MCP 工具實現
│   └── process_manager.rs   # PMDaemon 包裝器，用於進程管理
├── Cargo.toml               # 項目依賴和元數據
└── README.md                # 本文件

相關項目

• PMDaemon - 為該服務器提供支持的進程管理庫
• MCP Protocol - 模型上下文協議規範
• Rust MCP SDK - 官方 Rust MCP SDK