使用说明

MCP 封装器

用于Shell命令行工具的MCP包装器 - 通过简单的YAML配置，将Shell命令行工具作为MCP（模型上下文协议）服务器暴露出来。

概述

MCP Wrapper 允许您轻松创建封装了 shell 命令行工具的 MCP 服务器。您只需在简单的 YAML 配置文件中定义这些工具，并将它们作为 MCP 工具暴露出来，供 AI 助手和其他 MCP 客户端使用。

特点/特性

🔧（扳手） 轻松配置使用简单的YAML配置定义工具
🌐 代表“地球/互联网”（视上下文而定，通常用于表示与互联网或全球范围相关的概念）。 跨平台支持针对Windows、macOS和Unix/Linux的平台特定命令
📝 **胡须模板（Mustache Templating，此处为意译，原词直译为“小胡子模板”，但根据上下文及技术背景，通常理解为一种模板引擎或模板系统，因此采用更通用的“胡须模板”作为译名，实际使用时可能根据具体语境调整）**带输入参数的动态命令生成
🛡️ 翻译成中文是：盾牌 输入验证使用MCP SDK进行基于JSON Schema的输入验证
🔒（锁形符号，常用于表示安全、保密或锁定状态） 高级安全多层安全体系，支持可配置策略和数据净化
📊 表格/数据图表 全面日志记录基于Winston的日志记录，支持可配置的日志级别
⚡（闪电符号，无特定含义，常用于表示快速、能量或警示等） 官方MCP软件开发工具包基于官方构建 @modelcontextprotocol/sdk
🚀 火箭/快速上升/飞速发展（根据上下文可灵活翻译） **CLI Ready（CLI Ready通常指某个系统、工具或服务已准备好支持命令行界面）**使用commander.js构建的完整CLI工具

安装

全局安装（推荐）

npm install -g mcp-wrapper

本地安装

npm install mcp-wrapper

开发安装

git clone <repository-url>
cd mcp-wrapper
npm install
npm run build

快速入门

创建一个配置文件 (mcp-wrapper.yaml):

tools:
  calc:
    description: "Mathematical calculator based on bc command line"
    input:
      type: object
      properties:
        equation:
          description: "bc compatible equation"
          type: string
      required: [equation]
    cmd: "echo {{equation}} | bc -l"

启动MCP服务器：

mcp-wrapper --config mcp-wrapper.yaml

彻底测试 通过多种输入来确保安全性：

# Test with debug logging to see security actions
mcp-wrapper --config mcp-wrapper.yaml --log-level debug

与MCP客户端一起使用 或者使用官方的MCP工具进行测试。

CLI 使用方法

mcp-wrapper [options]

Options:
  -c, --config <file>           Configuration file path (default: "mcp-wrapper.yaml")
  --timeout <seconds>           Command execution timeout in seconds (default: "30")
  --name <name>                 Server name
  --version-server <version>    Server version
  --log-level <level>           Log level: error|warn|info|debug (default: "info")
  -V, --version                 Display version number
  -h, --help                    Display help information

注目前仅支持stdio传输。

示例

# Start with default config file
mcp-wrapper

# Start with custom config
mcp-wrapper --config tools.yaml

# Start with debug logging
mcp-wrapper --config tools.yaml --log-level debug

# Start with custom server name and timeout
mcp-wrapper --config tools.yaml --name "My Tools Server" --timeout 60

配置格式

基本结构

tools:
  <tool_name>:
    name: <optional_display_name>
    description: <tool_description>
    input:
      type: object
      properties:
        <property_name>:
          type: <property_type>
          description: <property_description>
          default: <optional_default_value>
      required: [<required_property_names>]
    cmd: <shell_command_with_mustache_templates>

跨平台命令

为了实现跨平台兼容性，您可以为不同的操作系统指定不同的命令：

tools:
  file_list:
    description: "List files in directory"
    input:
      type: object
      properties:
        path:
          type: string
          description: "Directory path"
          default: "."
    cmd:
      win: "dir {{path}}"
      unix: "ls -la {{path}}"
      macos: "ls -la {{path}}"
      default: "ls {{path}}"

平台密钥：

winWindows（platform() === 'win32'）
macosmacOS（platform() === 'darwin'）
unixUnix/Linux（platform() === 'linux' 或 'freebsd'）
default任何平台的备用方案

输入模式类型

支持的属性类型：

string文本输入
number浮点数
integer整数
boolean真/假值
array值列表

房产选项：

description属性的帮助文本
default如果未提供，则为默认值
enum允许的值列表
minimum/maximum数值约束
minLength/maxLength字符串长度限制
pattern正则表达式验证

Mustache 模板引擎

命令支持Mustache模板引擎，并接受输入参数：

cmd: "echo {{expression}} | bc -l"

模板特性：

变量替换： {{variable}}
嵌套属性： {{object.property}}
为Shell安全自动转义
缺少变量导致的错误

示例

看看这个 示例/ 包含现成配置示例的目录，其中包括：

计算器工具
跨平台文件操作
Git 仓库工具
以及更多

文档

**安全指南**全面的安全文档，包括安全级别、类型及最佳实践
**示例**针对各种使用场景的即开即用配置示例

程序化使用

你也可以将MCP Wrapper用作库：

import { MCPWrapperServer, loadConfig } from 'mcp-wrapper';

// Load configuration
const config = loadConfig('./my-tools.yaml');

// Create server options (stdio transport is used by default)
const options = {
  configFile: './my-tools.yaml',
  name: 'My Custom Server',
  version: '1.0.0'
};

// Create and start server
const server = new MCPWrapperServer(config, options);
await server.start();

安全

这个工具执行shell命令，并存在固有的安全风险。用户有责任测试配置并实施适当的安全措施。

📖 看文件路径：docs/security.md（可翻译为“文档/安全.md”或保持原样，因为文件路径通常不翻译，直接保留原名）完整的安全配置指南，包括：

安全级别（严格、中等、宽松）
输入清理的安全类型
配置选项和示例
最佳实践

安全测试

始终使用潜在恶意输入来测试你的工具：

# Test with debug logging to see security sanitization
mcp-wrapper --config tools.yaml --log-level debug

# Test with strict security level first
security:
  level: strict
  auditLogging: true

示例安全测试输入：

命令注入： ; rm -rf /
路径遍历： ../../../etc/passwd
命令替换： $(dangerous_command)
特殊字符： |&;$()<>

调试

启用调试日志以查看详细的执行信息：

mcp-wrapper --config tools.yaml --log-level debug

这将显示：

配置加载详情
工具注册信息
安全消毒措施
使用渲染后的模板执行命令
错误详情和堆栈跟踪

做出贡献

为仓库创建分支（或“克隆仓库”）
创建一个特性分支
做出你的更改
为新功能添加测试
提交一个拉取请求

开发环境设置

git clone <repository-url>
cd mcp-wrapper
npm install
npm run dev  # Development mode
npm run build  # Build for production
npm test  # Run tests

开发工具

这个工具是采用混合模式开发的，其中核心架构和逻辑是手工设计的，而实现的某些部分则是借助各种大型语言模型（LLM）和工具创建的。

许可证

MPL-2.0 许可证 - 详情请参阅 LICENSE 文件。

支持

🐛 这个表情符号在中文里通常被用来表示“虫子”或者“小毛病”，在网络交流中，它也可能被用作一种幽默或轻松的方式来指代某个小问题或小错误。所以，可以翻译为“虫子”或根据上下文翻译为“小毛病”、“小问题”等。问题在GitHub上报告错误并请求功能
📖 书籍文档:
- 安全指南用于安全配置
- 示例配置样例目录