Name: CLI命令映射工具
Author: SteffenBlake

使用说明

CLI MCP映射器

使用简单的JSON配置将任何CLI命令转换为模型上下文协议（MCP）工具。

CLI MCP Mapper是一个功能强大的MCP服务器，它动态地将命令行工具作为MCP工具公开。这允许AI助手和其他MCP客户端通过声明性JSON配置安全地执行系统命令、脚本和工具，而不需要代码。

为什么选择CLI MCP Mapper？

模型上下文协议（MCP）使AI助手能够与外部工具和系统进行交互。然而，为每个命令行工具创建MCP服务器可能很耗时，需要编码专业知识。CLI MCP Mapper通过以下方式解决了这个问题：

无需编码：使用简单的JSON配置定义工具
通用兼容性：适用于任何CLI工具（git、npm、docker、自定义脚本等）
类型安全：JSON模式验证确保配置正确性
灵活的参数处理：支持位置参数、命名标志、布尔值、枚举等
可重复使用的配置：共享和版本控制您的工具定义
快速原型制作：在不编写服务器代码的情况下测试MCP工具的想法

用例

DevOps自动化：将docker、kubectl、terraform命令暴露给AI助手
开发工作流程：将构建工具、过梁和测试流道作为MCP工具提供
系统管理：安全地公开具有受控参数的系统命令
自定义脚本：包装自己的脚本，并使其可通过人工智能访问
Git操作：为AI助手提供版本控制功能
文件管理：使AI能够使用安全护栏执行文件操作

特性

✨ 动态工具生成：根据JSON定义自动创建MCP工具
🎯 灵活的参数：支持位置参数、命名标志、布尔值、枚举和必需/可选参数
📝 类型系统：带验证的字符串、布尔值和数字参数类型
🔒 模式验证：用于验证命令配置的JSON模式
✅ 配置验证：内置模拟运行模式，用于在部署前验证配置
🚀 零依赖：最小运行时占用空间（仅@modelcontextprotocol/sdk）
🔧 易于配置：环境变量或默认路径配置
📚 丰富的示例：包括全面的示例配置

安装

从NPM全局安装CLI MCP Mapper：

npm i -g cli-mcp-mapper

验证安装：

which cli-mcp-mapper

配置

CLI MCP Mapper需要一个JSON配置文件，该文件定义了哪些命令要作为MCP工具公开。

环境变量

您可以使用以下命令指定自定义配置路径 CLI_MCP_MAPPER_CONFIG 环境变量：

export CLI_MCP_MAPPER_CONFIG=/path/to/your/commands.json

对于持久配置，请将其添加到您的shell配置文件中(~/.bashrc, ~/.zshrc等等）：

# Add to ~/.bashrc or ~/.zshrc
export CLI_MCP_MAPPER_CONFIG="$HOME/my-mcp-configs/commands.json"

默认位置

如果没有设置环境变量，CLI MCP Mapper会在以下位置查找配置：

~/.config/cli-mcp-mapper/commands.json

在不同的系统上：

Linux/macOS: ~/.config/cli-mcp-mapper/commands.json
视窗: %USERPROFILE%\.config\cli-mcp-mapper\commands.json

要创建默认配置目录，请执行以下操作：

mkdir -p ~/.config/cli-mcp-mapper

然后复制其中一个示例配置或创建自己的配置：

# Copy a basic example
cp examples/basic-commands.json ~/.config/cli-mcp-mapper/commands.json

# Or create your own
cat > ~/.config/cli-mcp-mapper/commands.json << 'EOF'
{
  "commands": {
    "hello": {
      "description": "Say hello",
      "command": "echo",
      "baseArgs": [],
      "parameters": {
        "name": {
          "type": "string",
          "description": "Name to greet",
          "required": true,
          "position": 0
        }
      }
    }
  }
}
EOF

配置文件格式

配置文件是一个JSON对象，其中包含一个 commands 包含命令定义映射的属性：

{
  "commands": {
    "command_name": {
      "description": "What this command does",
      "command": "base-command",
      "baseArgs": ["--static", "args"],
      "parameters": {
        "param_name": {
          "type": "string",
          "description": "Parameter description",
          "required": false,
          "position": 0
        }
      }
    }
  }
}

验证配置（干运行）

在生产环境或CI/CD管道中部署CLI MCP Mapper之前，您可以使用 --dry-run 旗帜。这将通过加载和解析您的配置来执行“航班检查”，而无需启动MCP服务器。

基本用法：

cli-mcp-mapper --dry-run

使用自定义配置路径：

CLI_MCP_MAPPER_CONFIG=/path/to/commands.json cli-mcp-mapper --dry-run

干跑有什么作用：

✅ 从指定路径加载配置文件
✅ 验证JSON语法
✅ 验证配置结构（是否存在 commands 对象）
✅ 验证每个命令定义（必填字段、参数模式）
✅ 带有适当状态代码的退出（0表示成功，1表示错误）
✅ 将详细的错误消息输出到stderr进行调试

示例输出（成功）：

Configuration loaded successfully from /home/user/.config/cli-mcp-mapper/commands.json
Found 9 command(s):
  ✓ ls: List directory contents
  ✓ cat: Display contents of a file
  ✓ mkdir: Create a new directory
  ✓ echo: Display a line of text
  ✓ find: Search for files in a directory hierarchy
  ...

Dry-run completed successfully. Configuration is valid.

示例输出（错误）：

Error: Configuration file not found at /path/to/commands.json
Please create a configuration file or set CLI_MCP_MAPPER_CONFIG environment variable.

使用案例：

CI/CD管道：将验证添加为构建步骤，以便在部署前捕获配置错误

# In GitHub Actions or similar CI
- name: Validate MCP Configuration
  run: cli-mcp-mapper --dry-run
  env:
    CLI_MCP_MAPPER_CONFIG: ./config/commands.json

部署前检查：在推送到生产环境之前验证配置文件

# In deployment script
if ! cli-mcp-mapper --dry-run; then
  echo "Configuration validation failed!"
  exit 1
fi

配置开发：配置文件编辑期间的快速验证

# Edit config and validate immediately
vim ~/.config/cli-mcp-mapper/commands.json
cli-mcp-mapper --dry-run

自动化测试：集成到测试套件中以确保配置完整性

# Test script
for config in configs/*.json; do
  CLI_MCP_MAPPER_CONFIG="$config" cli-mcp-mapper --dry-run || exit 1
done

退出代码：

0：配置有效且已准备好使用
1：配置错误（缺少文件、JSON无效、结构问题）

JSON规范

架构参考

提供了一个JSON模式来验证您的配置文件。在JSON中引用它：

{
  "$schema": "./commands.schema.json",
  "commands": { ... }
}

这使得支持JSON模式（VS Code、IntelliJ等）的编辑器能够自动完成和验证。

命令定义

中的每个命令 commands 对象具有以下结构：

属性	类型	必填	描述
`description`	string	✅ 是	向MCP客户端显示人类可读的描述
`command`	string	✅ Yes	要执行的基本命令（例如。， `"git"`, `"npm"`, `"docker"`)
`baseArgs`	string[]	否	静态参数总是传递给命令（例如。， `["build", "--quiet"]`)
`parameters`	object	否	参数名称到参数定义的映射

例子：

{
  "git_status": {
    "description": "Show the working tree status",
    "command": "git",
    "baseArgs": ["status"],
    "parameters": {
      "short": {
        "type": "boolean",
        "description": "Give output in short format",
        "argName": "-s"
      }
    }
  }
}

参数定义

中的每个参数 parameters object定义了如何将参数传递给命令：

属性	类型	必填	描述
`type`	string	✅ 是	参数类型： `"string"`, `"boolean"`，或 `"number"`
`description`	string	✅ 是	人类可读的参数描述
`required`	boolean	否	是否必须提供参数（默认值： `false`)
`position`	number	否	对于位置参数：命令行中从0开始的位置
`argName`	string	否	对于命名参数：要使用的标志（例如。， `"--output"`, `"-v"`)
`argValue`	string	否	要传递的静态值 `argName` （很少使用）
`enum`	string[]	否	允许值列表
`default`	任何	否	默认值（如果未提供）

参数处理规则：

位置参数 (position 已设置）：
- 按位置顺序（0、1、2、…）添加到命令行
- 不 argName 需要
- 如果参数未提供且不是必需的，则将其省略
命名参数 (argName 已设置）：
- 对于 boolean 类型：如果 true，补充道 argName 指挥
- 对于 string 或 number 类型：添加 argName 后面是值
- 如果未提供参数，则省略
必填参数 (required: true):
- MCP客户端必须提供这些参数
- 验证发生在命令执行之前

参数类型

字符串参数

用于文本值、文件路径、URL等。

{
  "file_path": {
    "type": "string",
    "description": "Path to the file",
    "required": true,
    "position": 0
  }
}

使用枚举进行有限选择：

{
  "log_level": {
    "type": "string",
    "description": "Logging level",
    "enum": ["debug", "info", "warn", "error"],
    "argName": "--log-level"
  }
}

布尔参数

用于标志/开关。当 true，the argName 被添加到命令中。

{
  "verbose": {
    "type": "boolean",
    "description": "Enable verbose output",
    "argName": "-v"
  }
}

可以组合多个布尔标志：

{
  "force": {
    "type": "boolean",
    "description": "Force operation",
    "argName": "-f"
  },
  "recursive": {
    "type": "boolean",
    "description": "Recursive operation",
    "argName": "-r"
  }
}

当两者都为真时，命令变为： command -f -r

数字参数

用于数值（计数、限制、大小等）。

{
  "max_count": {
    "type": "number",
    "description": "Maximum number of results",
    "argName": "-n"
  }
}

使用示例

基本命令示例

简单的文件系统操作：

{
  "commands": {
    "ls": {
      "description": "List directory contents",
      "command": "ls",
      "baseArgs": ["-lah"],
      "parameters": {
        "path": {
          "type": "string",
          "description": "Directory path",
          "position": 0
        }
      }
    },
    "mkdir": {
      "description": "Create a directory",
      "command": "mkdir",
      "baseArgs": [],
      "parameters": {
        "path": {
          "type": "string",
          "description": "Directory to create",
          "required": true,
          "position": 0
        },
        "parents": {
          "type": "boolean",
          "description": "Create parent directories",
          "argName": "-p"
        }
      }
    }
  }
}

MCP客户端中的用法：

ls() → 执行 ls -lah
ls({ path: "/tmp" }) → 执行 ls -lah /tmp
mkdir({ path: "/tmp/test", parents: true }) → 执行 mkdir -p /tmp/test

Git操作示例

版本控制命令：

{
  "commands": {
    "git_commit": {
      "description": "Commit changes with a message",
      "command": "git",
      "baseArgs": ["commit"],
      "parameters": {
        "message": {
          "type": "string",
          "description": "Commit message",
          "required": true,
          "argName": "-m"
        },
        "all": {
          "type": "boolean",
          "description": "Stage all modified files",
          "argName": "-a"
        }
      }
    },
    "git_status": {
      "description": "Show repository status",
      "command": "git",
      "baseArgs": ["status"],
      "parameters": {}
    }
  }
}

MCP客户端中的用法：

git_status() → 执行 git status
git_commit({ message: "Fix bug", all: true }) → 执行 git commit -m "Fix bug" -a

复杂参数示例

具有混合位置和命名参数的高级参数处理：

{
  "commands": {
    "find_files": {
      "description": "Search for files",
      "command": "find",
      "baseArgs": [],
      "parameters": {
        "path": {
          "type": "string",
          "description": "Starting directory",
          "position": 0,
          "default": "."
        },
        "name": {
          "type": "string",
          "description": "File name pattern",
          "argName": "-name"
        },
        "type": {
          "type": "string",
          "description": "File type",
          "enum": ["f", "d", "l"],
          "argName": "-type"
        },
        "max_depth": {
          "type": "number",
          "description": "Maximum search depth",
          "argName": "-maxdepth"
        }
      }
    }
  }
}

MCP客户端中的用法：

find_files({ name: "*.js", type: "f" }) → 执行 find . -name "*.js" -type f
find_files({ path: "/src", name: "*.ts", max_depth: 3 }) → 执行 find /src -name "*.ts" -maxdepth 3

MCP客户端配置

克劳德桌面版

要将CLI MCP Mapper与Claude Desktop一起使用，请将其添加到MCP配置文件中。

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

添加以下内容到 mcpServers 章节：

{
  "mcpServers": {
    "cli-mcp-mapper": {
      "type": "local",
      "command": "cli-mcp-mapper",
      "args": [],
      "tools": ["*"]
    }
  }
}

使用自定义配置路径：

{
  "mcpServers": {
    "cli-mcp-mapper": {
      "type": "local",
      "command": "cli-mcp-mapper",
      "args": [],
      "env": {
        "CLI_MCP_MAPPER_CONFIG": "/path/to/your/commands.json"
      },
      "tools": ["*"]
    }
  }
}

更新配置后：

保存文件
重新启动克劳德桌面
您配置的命令将显示为可用工具

其他MCP客户端

对于其他MCP客户端，请参阅其文档以添加MCP服务器。一般模式是：

{
  "command": "cli-mcp-mapper",
  "args": [],
  "env": {
    "CLI_MCP_MAPPER_CONFIG": "/path/to/commands.json"
  }
}

配置文件示例

存储库中包含几个示例配置文件 examples/ 目录：

`basic-commands.json`

常见的Unix/Linux命令： ls, cat, mkdir, rm, pwd, echo, find, grep

使用此功能为AI助手提供基本的文件系统功能。

`git-commands.json`

Git操作： git status, git commit, git push, git pull, git log等等。

为AI辅助开发启用版本控制操作。

`file-operations.json`

文件操作： cp, mv, touch, chmod, chown, tar, wc

高级文件和归档操作。

使用示例

要使用示例配置，请执行以下操作：

# Copy to default location
cp examples/basic-commands.json ~/.config/cli-mcp-mapper/commands.json

# Or use with environment variable
export CLI_MCP_MAPPER_CONFIG="$PWD/examples/git-commands.json"

您还可以将多个示例合并到一个配置中：

# Combine multiple configurations
jq -s '{"commands": (map(.commands) | add)}' \
  examples/basic-commands.json \
  examples/git-commands.json \
  > ~/.config/cli-mcp-mapper/commands.json

故障排除

未找到配置文件

错误： Cannot find module '/path/to/commands.json'

解决：

验证文件是否存在： ls -la ~/.config/cli-mcp-mapper/commands.json
创建目录： mkdir -p ~/.config/cli-mcp-mapper
检查环境变量： echo $CLI_MCP_MAPPER_CONFIG
确保JSON文件有效： cat ~/.config/cli-mcp-mapper/commands.json | jq

JSON语法无效

错误： Unexpected token 或 JSON Parse error

解决：

验证JSON语法： cat commands.json | jq
使用带有JSON验证的编辑器（VS Code等）
检查是否缺少逗号、括号或引号
根据架构验证：使用提供的 commands.schema.json

命令未执行

错误： 命令返回错误或意外输出

解决：

手动测试命令：在终端中运行生成的命令
检查 baseArgs：确保它们对您的命令有效
验证 argName 匹配命令的预期标志
检查位置参数顺序
查看命令的帮助： command --help

权限不足

错误： EACCES 或 Permission denied

解决：

确保命令在PATH中： which command-name
检查文件权限： ls -la $(which command-name)
在中使用绝对路径 command 领域
对于脚本，请确保执行权限： chmod +x script.sh

工具未出现在MCP客户端中

解决：

重新启动MCP客户端（例如Claude Desktop）
检查MCP客户端日志是否有错误
验证 commands.json 有效
确保安装了CLI MCP映射器： which cli-mcp-mapper
检查客户端配置文件语法

命令执行但不返回输出

问题： 命令执行成功，但返回空字符串

说明： 一些命令输出到stderr而不是stdout。CLI MCP Mapper捕获了这两个，但默认情况下只在成功时返回stdout。

解决：

检查命令是否写入stderr
使用命令标志将输出重定向到stdout
对于只显示错误的命令，这通常是预期的行为

安全考虑

⚠️ 重要安全注意事项：

命令注入保护：CLI MCP映射器使用Node.js spawn 没有shell解释来防止命令注入攻击。虽然我们有全面的测试来验证这种保护， 您应该始终在容器化或沙盒环境中运行具有shell访问权限的代理 （例如Docker、VM或其他隔离机制），以尽量减少潜在的安全风险。这为不可预见的漏洞提供了额外的防御层。
集装箱化最佳实践：在生产环境中部署CLI MCP Mapper或将其暴露给AI代理时，强烈考虑在以下环境中运行它：
- 具有有限权限的Docker容器
- 网络访问受限的虚拟机
- 具有文件系统限制的沙盒环境
- 具有最小权限的独立用户帐户
访问控制：连接到CLI MCP Mapper的MCP客户端将具有与运行它的用户相同的权限。请使用所需的最低权限用户帐户运行服务器。
验证参数：使用 enum 在可能的情况下限制参数值，以防止意外输入。
避免危险命令：要小心暴露以下命令：
- rm -rf 没有适当的约束
- chmod 具有不受限制的模式
- 可以执行任意代码的命令
- 可能暴露敏感数据的网络命令
- 系统管理命令
只读操作：在公开写操作之前，考虑从只读命令（ls、cat、git status）开始。
配置安全:
- 不要将敏感配置提交到版本控制
- 使用特定于环境的配置文件
- 部署前检查配置
- 定期审核暴露的命令
最小特权：只为您的用例授予最低限度的必要命令。

最佳实践：

{
  "commands": {
    "safe_delete": {
      "description": "Delete files (safe - no recursive)",
      "command": "rm",
      "baseArgs": ["-i"],  // Interactive mode for safety
      "parameters": {
        "file": {
          "type": "string",
          "description": "Single file to delete",
          "required": true,
          "position": 0
        }
      }
    }
  }
}

贡献

欢迎投稿！以下是您可以提供帮助的方式：

报告问题：发现一个bug？在GitHub上打开一个问题
提交PR：修复错误、添加功能、改进文档
分享示例：创建和共享有用的命令配置
改进文档：帮助使文档更清晰、更全面

开发设置

# Clone the repository
git clone https://github.com/SteffenBlake/cli-mcp-mapper.git
cd cli-mcp-mapper

# Install dependencies
npm install

# Test locally
node index.js

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

由...制作❤️ 对于MCP社区

有关问题、疑问或贡献，请访问：https://github.com/SteffenBlake/cli-mcp-mapper

使用说明

CLI MCP映射器

目录

为什么选择CLI MCP Mapper？

用例

特性

安装

配置

环境变量

默认位置

配置文件格式

验证配置（干运行）

JSON规范

架构参考

命令定义

参数定义

参数类型

字符串参数

布尔参数

数字参数

使用示例

基本命令示例

Git操作示例

复杂参数示例

MCP客户端配置

克劳德桌面版

其他MCP客户端

配置文件示例

basic-commands.json

git-commands.json

file-operations.json

使用示例

故障排除

未找到配置文件

JSON语法无效

命令未执行

权限不足

工具未出现在MCP客户端中

命令执行但不返回输出

安全考虑

贡献

开发设置

许可证

相关 MCP

iOS/macOS 构建 MCP 服务器与命令行工具

Blender 3D建模MCP服务

iOS模拟器交互服务器

小红书内容访问服务

网页抓取与搜索MCP服务器

B站视频搜索服务

`basic-commands.json`

`git-commands.json`

`file-operations.json`