MCP封装器

作者：BartRuSec0 星标更新：2025-10-22

安装使用来源：spider==github.com

项目介绍

MCP Wrapper

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

概述

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

特性

🔧 简单配置：使用简单的YAML配置定义工具
🌐 跨平台支持：针对Windows、macOS和Unix/Linux的特定命令
📝 Mustache模板：使用输入参数动态生成命令
🛡️ 输入验证：基于JSON Schema的输入验证，使用MCP SDK
🔒 高级安全：多层次的安全策略和净化功能
📊 全面日志记录：基于Winston的日志记录，具有可配置的日志级别
⚡ 官方MCP SDK：基于官方的@modelcontextprotocol/sdk
🚀 CLI就绪：完整的CLI工具，使用commander.js

安装

全局安装（推荐）

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: "基于bc命令行的数学计算器"
    input:
      type: object
      properties:
        equation:
          description: "与bc兼容的方程"
          type: string
      required: [equation]
    cmd: "echo {{equation}} | bc -l"

启动MCP服务器：

mcp-wrapper --config mcp-wrapper.yaml

彻底测试 使用各种输入确保安全性：

# 使用调试日志查看安全操作
mcp-wrapper --config mcp-wrapper.yaml --log-level debug

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

CLI用法

mcp-wrapper [选项]

选项:
  -c, --config <文件>           配置文件路径（默认："mcp-wrapper.yaml"）
  --timeout <秒数>              命令执行超时时间（默认："30"）
  --name <名称>                 服务器名称
  --version-server <版本>       服务器版本
  --log-level <级别>            日志级别：error|warn|info|debug（默认："info"）
  -V, --version                 显示版本号
  -h, --help                    显示帮助信息

注意：目前仅支持stdio传输。

示例

# 使用默认配置文件启动
mcp-wrapper

# 使用自定义配置启动
mcp-wrapper --config tools.yaml

# 使用调试日志启动
mcp-wrapper --config tools.yaml --log-level debug

# 使用自定义服务器名称和超时时间启动
mcp-wrapper --config tools.yaml --name "我的工具服务器" --timeout 60

配置格式

基本结构

tools:
  <工具名>:
    name: <可选显示名称>
    description: <工具描述>
    input:
      type: object
      properties:
        <属性名>:
          type: <属性类型>
          description: <属性描述>
          default: <可选默认值>
      required: [<必需属性名>]
    cmd: <包含mustache模板的shell命令>

跨平台命令

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

tools:
  file_list:
    description: "列出目录中的文件"
    input:
      type: object
      properties:
        path:
          type: string
          description: "目录路径"
          default: "."
    cmd:
      win: "dir {{path}}"
      unix: "ls -la {{path}}"
      macos: "ls -la {{path}}"
      default: "ls {{path}}"

平台键：

win: Windows (platform() === 'win32')
macos: macOS (platform() === 'darwin')
unix: Unix/Linux (platform() === 'linux' or 'freebsd')
default: 任何平台的回退

输入模式类型

支持的属性类型：

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

属性选项：

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

Mustache模板

命令支持使用输入参数的Mustache模板：

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

模板特性：

变量替换：{{变量}}
嵌套属性：{{对象.属性}}
自动转义以保证shell安全
缺失变量时出错

示例

参见**示例/**目录，获取包括以下内容的现成配置示例：

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

文档

安全指南：全面的安全文档，包括安全级别、类型和最佳实践
示例：适用于各种用例的现成配置示例

程序化使用

您也可以将MCP Wrapper作为库来使用：

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

// 加载配置
const config = loadConfig('./my-tools.yaml');

// 创建服务器选项（默认使用stdio传输）
const options = {
  configFile: './my-tools.yaml',
  name: '我的自定义服务器',
  version: '1.0.0'
};

// 创建并启动服务器
const server = new MCPWrapperServer(config, options);
await server.start();

安全

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

📖 查看文档/安全.md以获取完整的安全配置指南，包括：

安全级别（严格、适度、宽松）
输入净化的安全类型
配置选项和示例
最佳实践

安全测试

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

# 使用调试日志查看安全净化
mcp-wrapper --config tools.yaml --log-level debug

# 首先使用严格的安全部署级别测试
security:
  level: strict
  auditLogging: true

安全测试示例输入：

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

调试

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

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

这将显示：

配置加载详情
工具注册信息
安全净化动作
渲染模板后的命令执行
错误详情和堆栈跟踪

贡献

分叉存储库
创建功能分支
进行更改
为新功能添加测试
提交拉取请求

开发设置

git clone <repository-url>
cd mcp-wrapper
npm install
npm run dev  # 开发模式
npm run build  # 生产构建
npm test  # 运行测试

开发工具

此工具是在混合模式下开发的，其中核心架构和逻辑是手工制作的，而实现的一些部分是由各种LLM模型和工具辅助创建的。

许可证

MPL-2.0许可证 - 详情见LICENSE文件。

支持

🐛 问题：在GitHub上报告错误和请求功能
📖 文档：
- 安全指南用于安全配置
- 示例目录用于配置样本