shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

commander-mcp

一个基于MCP协议的背景进程管理服务器，使用Rust开发，通过PMDaemon提供进程运行、监控和管理功能，支持跨平台操作和持久化日志存储。

article

README

🚀 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                # 本文件

相关项目

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client