exec MCP

Exec MCP服务器

一种模型上下文协议（MCP）服务器，提供执行和管理流程的工具。此服务器允许代理执行进程并通过PID停止进程，使进程管理比使用终端命令更容易。

特性

• 执行过程：执行进程并返回其PID以供以后管理（后台执行）
• 运行命令：执行命令并立即返回其输出（同步执行）
• 停止进程：使用SIGTERM或SIGKILL通过进程的PID停止进程
• 非阻塞：后台进程独立运行，不会阻止MCP服务器
• 并发：可以同时管理多个进程

安装

使用go install（推荐）

go install github.com/Yakwilik/exec-mcp/cmd/exec-mcp@latest

这将安装 exec-mcp 二进制到 $GOPATH/bin 或 $HOME/go/bin （确保它在你的路径中）。

从源头构建

git clone https://github.com/Yakwilik/exec-mcp.git
cd exec-mcp
go build -o exec-mcp ./cmd/exec-mcp

测试

运行综合测试套件：

# Run all tests
go test ./... -v

# Run specific tool tests
go test ./internal/tools/exec/ -v
go test ./internal/tools/run/ -v
go test ./internal/tools/stop/ -v

# Run integration tests
go test ./internal/mcp/ -v

用法

服务器使用stdio传输进行通信：

./exec-mcp

连接到MCP客户端

此MCP服务器可以连接到任何兼容MCP的客户端，例如：

• 克劳德桌面版 （人类学）
• 光标 （有MCP支持）
• 其他MCP兼容代理

适用于克劳德桌面

将服务器添加到Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json Linux： ~/.config/Claude/claude_desktop_config.json

如果通过安装 go install，使用：

{
  "mcpServers": {
    "exec-mcp": {
      "command": "exec-mcp",
      "args": []
    }
  }
}

或者，如果是手动构建的，请使用完整路径：

{
  "mcpServers": {
    "exec-mcp": {
      "command": "/absolute/path/to/exec-mcp",
      "args": []
    }
  }
}

注： 确保 exec-mcp 如果使用第一个选项，则在PATH中，或者使用二进制文件的完整路径。

对于光标

如果Cursor支持MCP服务器，请在Cursor的设置中添加类似的配置。

测试连接

连接后，客户端应该能够使用这些工具：

• exec_process -启动后台进程
• run_command -同步执行命令
• stop_process -通过PID停止进程

工具

执行过程

执行一个进程并返回其PID。

参数：

• command （string，必填）：要执行的命令
• args （字符串数组，可选）：命令行参数
• dir （string，可选）：进程的工作目录
• env （字符串数组，可选）：环境变量（格式：KEY=VALUE）

例子：

{
  "command": "ls",
  "args": ["-l", "/tmp"],
  "dir": "/home/user"
}

答复：

{
  "content": [
    {
      "type": "text",
      "text": "Process started successfully:\n{\n  \"pid\": 12345,\n  \"command\": \"ls\",\n  \"args\": [\"-l\", \"/tmp\"],\n  \"start_time\": \"2024-01-01T12:00:00Z\",\n  \"status\": \"running\"\n}"
    }
  ],
  "structuredContent": {
    "pid": 12345,
    "command": "ls",
    "args": ["-l", "/tmp"],
    "start_time": "2024-01-01T12:00:00Z",
    "status": "running"
  }
}

注： 这 structuredContent 字段包含无需解析JSON文本即可直接访问的结构化数据。

运行命令

执行命令并立即返回其输出（同步执行）。

参数：

• command （string，必填）：要执行的命令
• args （字符串数组，可选）：命令行参数
• dir （string，可选）：进程的工作目录
• env （字符串数组，可选）：环境变量（格式：KEY=VALUE）
• timeout （整数，可选）：超时秒数（0表示无超时）

例子：

{
  "command": "ls",
  "args": ["-l", "/tmp"],
  "dir": "/home/user",
  "timeout": 10
}

答复：

{
  "content": [
    {
      "type": "text",
      "text": "Command executed:\n{\n  \"command\": \"ls\",\n  \"args\": [\"-l\", \"/tmp\"],\n  \"exit_code\": 0,\n  \"stdout\": \"total 0\\n-rw-r--r-- 1 user user 0 Jan 1 12:00 file.txt\",\n  \"stderr\": \"\",\n  \"executed_at\": \"2024-01-01T12:00:00Z\",\n  \"duration_seconds\": 0.05,\n  \"success\": true\n}"
    }
  ],
  "structuredContent": {
    "command": "ls",
    "args": ["-l", "/tmp"],
    "exit_code": 0,
    "stdout": "total 0\n-rw-r--r-- 1 user user 0 Jan 1 12:00 file.txt",
    "stderr": "",
    "executed_at": "2024-01-01T12:00:00Z",
    "duration_seconds": 0.05,
    "success": true
  }
}

注： 此工具等待命令完成并返回完整输出。使用 exec_process 用于后台执行。

停止进程

使用SIGTERM或SIGKILL通过进程的PID停止进程。

参数：

• pid （整数，必填）：要停止的进程ID
• kill （boolean，可选）：如果为true，请使用SIGKILL而不是SIGTERM（强制杀死）

例子：

{
  "pid": 12345,
  "kill": false
}

答复：

{
  "content": [
    {
      "type": "text",
      "text": "Signal SIGTERM sent to process 12345"
    }
  ],
  "structuredContent": {
    "pid": 12345,
    "signal": "SIGTERM",
    "status": "signal_sent"
  }
}

使用结构化数据

MCP服务器返回人类可读的文本和结构化的JSON数据。对于程序化访问，请使用 structuredContent 字段：

// Example: Extract PID from exec_process response
result, err := clientSession.CallTool(ctx, execParams)
if err != nil {
    log.Fatal(err)
}

// Access structured data directly
if processInfoMap, ok := result.StructuredContent.(map[string]interface{}); ok {
    if pidFloat, exists := processInfoMap["pid"]; exists {
        if pid, ok := pidFloat.(float64); ok {
            processID := int(pid)
            // Use processID for stop_process
        }
    }
}

建筑

为了可维护性，该项目被组织成单独的包：

• ./cmd/exec-mcp/main.go：主要入口点
• ./internal/mcp/server.go：MCP服务器设置和配置
• ./internal/tools/tool.go：工具接口定义
• ./internal/tools/exec/：流程执行工具（后台，基于结构）
• ./internal/tools/run/：命令执行工具（同步，基于结构）
• ./internal/tools/stop/：进程终止工具（基于结构）
• ./internal/mcp/test_helpers.go：用于提取结构化数据的辅助函数

工具架构

每个工具都被实现为一个结构体，该结构体实现了 Tool 接口：

type Tool interface {
    Name() string
    Description() string
    Handle(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, any, error)
}

这种方法提供了：

• 没有硬编码的工具名称：名称从工具结构中检索
• 自我记录：每个工具都有自己的名称和描述
• 类型安全性：接口确保工具实施的一致性
• 易于测试：工具可以独立测试

好处

此MCP服务器使代理能够：

• 执行流程并获取其PID以进行精确管理（后台执行）
• 执行命令并立即获得输出（同步执行）
• 停止进程，无需使用终端命令搜索它们
• 使用精确的进程ID同时管理多个进程
• 使用适当的信号处理（SIGTERM/SIGKILL）进行干净的进程终止
• 在分离模式下运行进程，而不阻塞MCP服务器
• 获取同步命令的命令输出、退出代码和执行时间

如果没有此MCP，代理通常需要使用终端命令，如 ps, grep，以及 kill 查找和管理不太可靠且更复杂的流程。