CLI MCP Mapper

CLI MCP映射器

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

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

目录

• 为什么选择CLI MCP Mapper？
• 特性
• 安装
• 配置

- 环境变量 - 默认位置 - 配置文件格式 - 验证配置（干运行）

• JSON规范

- 架构参考 - 命令定义 - 参数定义 - 参数类型

• 使用示例

- 基本命令示例 - Git操作示例 - 复杂参数示例

• MCP客户端配置

- 克劳德桌面版 - 其他MCP客户端

• 配置文件示例
• 故障排除
• 安全考虑
• 贡献
• 许可证

为什么选择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  ~/.config/cli-mcp-mapper/commands.json

故障排除

未找到配置文件

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

解决：

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

JSON语法无效

错误： Unexpected token 或 JSON Parse error

解决：

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

命令未执行

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

解决：

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

权限不足

错误： EACCES 或 Permission denied

解决：

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

工具未出现在MCP客户端中

解决：

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

命令执行但不返回输出

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

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

解决：

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

安全考虑

⚠️ 重要安全注意事项：

1. 命令注入保护：CLI MCP映射器使用Node.js spawn 没有shell解释来防止命令注入攻击。虽然我们有全面的测试来验证这种保护， 您应该始终在容器化或沙盒环境中运行具有shell访问权限的代理 （例如Docker、VM或其他隔离机制），以尽量减少潜在的安全风险。这为不可预见的漏洞提供了额外的防御层。

1. 集装箱化最佳实践：在生产环境中部署CLI MCP Mapper或将其暴露给AI代理时，强烈考虑在以下环境中运行它：

- 具有有限权限的Docker容器 - 网络访问受限的虚拟机 - 具有文件系统限制的沙盒环境 - 具有最小权限的独立用户帐户

1. 访问控制：连接到CLI MCP Mapper的MCP客户端将具有与运行它的用户相同的权限。请使用所需的最低权限用户帐户运行服务器。

1. 验证参数：使用 enum 在可能的情况下限制参数值，以防止意外输入。

1. 避免危险命令：要小心暴露以下命令：

- rm -rf 没有适当的约束 - chmod 具有不受限制的模式 - 可以执行任意代码的命令 - 可能暴露敏感数据的网络命令 - 系统管理命令

1. 只读操作：在公开写操作之前，考虑从只读命令（ls、cat、git status）开始。

1. 配置安全:

- 不要将敏感配置提交到版本控制 - 使用特定于环境的配置文件 - 部署前检查配置 - 定期审核暴露的命令

1. 最小特权：只为您的用例授予最低限度的必要命令。

最佳实践：

{
  "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
        }
      }
    }
  }
}

贡献

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

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

开发设置

# 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