使用说明

项目简介

mcp-cli-exec 是一个基于 Model Context Protocol (MCP) 构建的命令行执行服务器。它专注于提供 工具 (Tools) 功能，允许LLM客户端调用服务器来执行shell命令，并以结构化的JSON格式返回命令执行的详细结果，例如退出代码、标准输出和标准错误。

主要功能点

执行shell命令: 提供 'cli-exec-raw' 和 'cli-exec' 两个工具，分别用于执行原始命令和在指定工作目录下执行命令。
结构化输出: 命令执行结果以JSON格式返回，包含成功/失败状态、退出代码、标准输出、标准错误、执行时长和工作目录等信息。
超时控制: 支持为命令执行设置超时时间，防止长时间运行的命令阻塞服务器。
工作目录支持: 'cli-exec' 工具允许在指定的工作目录下执行命令，方便进行项目相关的操作。
错误处理: 提供详细的错误信息，包括命令执行失败的原因和输入参数验证错误。
跨平台: 理论上支持 Windows 和 Unix-like 系统（需要使用对应系统的命令，例如 'dir' vs 'ls'）。

安装步骤

使用 npm 或 pnpm 安装 (可选)：

npm install -g mcp-cli-exec
# 或者使用 pnpm
pnpm add -g mcp-cli-exec

或者，您也可以直接使用 'npx' 而无需全局安装。

服务器配置

MCP客户端需要配置 MCP 服务器的启动命令和参数才能连接到 'mcp-cli-exec' 服务器。以下是 Cline VSCode Extension 和 Claude Desktop 的配置示例。

Cline VSCode Extension 配置示例 (添加到 'cline_mcp_settings.json'):

{
  "mcpServers": {
    "mcp-cli-exec": {
      "command": "npx",  // 启动命令，这里使用 npx 运行 mcp-cli-exec
      "args": ["-y", "mcp-cli-exec"] // 命令参数，-y 参数用于跳过 npx 的确认提示
    }
  }
}

Claude Desktop 配置示例 (添加到 'claude_desktop_config.json'):

{
  "mcpServers": {
    "mcp-cli-exec": {
      "command": "npx",  // 启动命令，同样使用 npx 运行 mcp-cli-exec
      "args": ["-y", "mcp-cli-exec"] // 命令参数，-y 参数用于跳过 npx 的确认提示
    }
  }
}

Windows 特殊配置 (如果遇到 'ENOENT spawn npx' 错误)：如果 Windows 环境下遇到 'npx' 命令找不到的问题，可以尝试使用 Node.js 和 npx-cli.js 的完整路径进行配置：

{
  "mcpServers": {
    "mcp-cli-exec": {
      "command": "C:\\Users\\<你的用户名>\\AppData\\Roaming\\nvm\\v<Node.js 版本号>\\node.exe", // Node.js 的完整路径，请替换为你的实际路径
      "args": [
        "C:\\Users\\<你的用户名>\\AppData\\Roaming\\npm\\node_modules\\npm\\bin\\npx-cli.js", // npx-cli.js 的完整路径，请替换为你的实际路径
        "-y",
        "mcp-cli-exec"
      ]
    }
  }
}

注意: 请将 '<你的用户名>' 和 '<Node.js 版本号>' 替换为你的实际用户名和 Node.js 版本号。这些路径可能因你的 Node.js 安装方式和版本而异。

基本使用方法

配置完成后，在支持 MCP 协议的 LLM 客户端 (例如 Cline VSCode Extension, Claude Desktop) 中，您应该能够调用 'mcp-cli-exec' 服务器提供的工具。

工具列表:

'cli-exec-raw': 执行原始 CLI 命令。

参数示例:

{
  "command": "echo Hello World"
}

或带超时时间 (毫秒):

{
  "command": "long-running-script.sh",
  "timeout": 300000
}

功能: 执行 'command' 参数指定的 shell 命令，并返回命令执行的详细信息。

'cli-exec': 在指定工作目录下执行一个或多个 CLI 命令。

参数示例: 在指定工作目录执行单个命令:

{
  "workingDirectory": "/path/to/project",
  "commands": "npm install"
}

在指定工作目录执行多个命令 (顺序执行，遇到错误停止):

{
  "workingDirectory": "C:\\project",
  "commands": [
    "dir /b",
    "npm run build"
  ]
}

功能: 在 'workingDirectory' 参数指定的工作目录下，执行 'commands' 参数指定的命令 (可以是单个命令字符串，用 '&&' 分隔的命令字符串，或命令字符串数组)，并返回每个命令执行的详细信息。

LLM 客户端调用示例:

在 LLM 客户端中，您需要构造符合 MCP 协议的 'CallToolRequest' 请求，指定要调用的工具名称 ('cli-exec-raw' 或 'cli-exec') 和相应的参数。服务器会执行命令并将结果封装在 'CallToolResponse' 中返回给客户端。客户端可以解析返回的 JSON 结果，并根据结果进行后续操作。

例如，在 Cline VSCode Extension 中，您可以使用 '#tool cli-exec-raw' 或 '#tool cli-exec' 命令来调用这些工具，并按照工具的输入参数要求提供相应的参数。

关键词