MCP沙盒服务器
项目介绍
MCP 沙箱
将任何 JavaScript 模块转换为自动反射和类型推断的沙箱 MCP（模型上下文协议）服务器。
🎯 什么是 MCP 沙箱？
MCP 沙箱自动将 JavaScript 模块转换为与 MCP（模型上下文协议）兼容的服务器，使任何 JavaScript 函数都能被 AI 系统访问。它使用 VM 沙箱进行安全隔离、自动类型推断，并生成适当的 MCP 配置。
✨ 功能
- 🔍 自动反射 - 分析 JS 模块并提取函数签名
- 🛡️ 安全沙箱 - 在隔离的 VM 上下文中执行代码，并设置超时
- 🧠 智能类型推断 - 从默认值和命名模式中检测参数类型
- 📚 JSDoc 集成 - 从函数注释中提取文档
- 📡 MCP 协议 - 完整支持 JSON-RPC 2.0 和 SSE
- 🌐 REST API - 用于轻松测试的传统 REST 端点
- ⚙️ TypeScript - 完整类型安全和 IntelliSense 支持
🚀 快速开始
安装
# 全局安装以供 CLI 使用
npm install -g @mcp-sandbox/cli
# 或在项目中使用
npm install @mcp-sandbox/core @mcp-sandbox/cli
基本用法
# 启动 JavaScript 模块的 MCP 服务器
$ mcp-sandbox start ./math-utils.js
🏗️ 初始化 MCP 沙箱...
🔍 反射模块
📊 发现 2 个工具：
- circleArea: 计算圆的面积
- fibonacci: 生成斐波那契数列
🚀 MCP 沙箱服务器运行于 http://localhost:3000
📋 MCP 工具：http://localhost:3000/mcp/tools
⚡ MCP 执行：http://localhost:3000/mcp/execute
🔄 MCP SSE：http://localhost:3000/sse
📡 MCP JSON-RPC：http://localhost:3000/mcp/jsonrpc
⚙️ MCP 配置：http://localhost:3000/mcp-config
💡 对于 MCP 检查器，请使用：http://localhost:3000/sse
示例模块
/**
* 计算圆的面积
* @param radius 圆的半径
*/
function circleArea(radius = 1) {
return Math.PI * radius * radius;
}
/**
* 生成斐波那契数列
* @param count 要生成的斐波那契数的数量
*/
function fibonacci(count = 10) {
const seq = [0, 1];
for (let i = 2; i < count; i++) {
seq[i] = seq[i - 1] + seq[i - 2];
}
return seq.slice(0, count);
}
module.exports = { circleArea, fibonacci };
运行 mcp-sandbox start math-utils.js 自动：
- 🔍 反射模块并发现函数
- 📊 从参数生成类型模式
- 🚀 在
http://localhost:3000启动 MCP 服务器 - 💾 创建
mcp-config.json供 MCP 客户端使用
📡 API 端点
服务器暴露了 MCP 和 REST 端点：
MCP 协议（JSON-RPC 2.0）
POST /mcp/jsonrpc- 主 MCP 端点GET /sse- 实时更新的 Server-Sent Events
REST API（用于测试）
GET /tools- 列出可用工具POST /execute/:toolName- 执行特定工具GET /mcp-config- 获取 MCP 服务器配置GET /health- 健康检查
示例用法
# 列出工具
curl http://localhost:3000/tools
# 通过 REST 执行函数
curl -X POST http://localhost:3000/execute/circleArea \
-H "Content-Type: application/json" \
-d '{"args": {"radius": 1}}'
# MCP JSON-RPC 调用
curl -X POST http://localhost:3000/mcp/jsonrpc \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "fibonacci", "arguments": {"count": 8}}}'
🏗️ 程序化用法
import { MCPSandbox } from '@mcp-sandbox/core';
const sandbox = new MCPSandbox({
port: 3000,
timeout: 5000,
});
// 加载并分析模块
await sandbox.loadModule('./my-module.js');
// 启动 MCP 服务器
await sandbox.start();
// 直接执行工具
const result = await sandbox.executeTool('myFunction', {
param1: 'value1',
});
📚 包含示例模块
仓库包含多个示例模块，展示了不同的用例：
数学运算（examples/math-utils.js）
- 圆面积计算
- 斐波那契数列生成
- 复利计算
- 质数检查
- 度/弧度转换
- 阶乘计算
字符串操作（examples/string-utils.js）
- 标题大小写转换
- 随机字符串生成
- 单词计数
- 回文检测
- 字符串反转
- 大小写转换
数组操作（examples/array-utils.js）
- 数组洗牌（Fisher-Yates）
- 提取唯一值
- 数组分块
- 集合操作（交集、差集）
- 数组展平
文件系统操作（examples/filesystem-utils.js）
- 文件读写（异步）
- 目录列表和创建
- 带模式的文件搜索
- 磁盘使用量计算
- 文件复制和删除
- 按行读取文件
🛠️ 开发
# 克隆仓库
git clone https://github.com/danstarns/mcp-sandbox.git
cd mcp-sandbox
# 安装依赖
pnpm install
# 构建所有包
pnpm build
# 运行示例
pnpm example:math # 数学工具
pnpm example:filesystem # 文件操作
pnpm example:string # 字符串操作
# 代码检查和格式化
pnpm lint && pnpm format
🔧 配置选项
CLI 选项
mcp-sandbox start <module> [options]
选项：
-p, --port <port> 服务器端口（默认：3000）
-h, --host <host> 服务器主机（默认：localhost）
-t, --timeout <ms> 执行超时（默认：5000ms）
-o, --output <file> 输出 MCP 配置到文件
程序化选项
interface SandboxOptions {
port?: number; // 服务器端口（默认：3000）
host?: string; // 服务器主机（默认：'localhost'）
timeout?: number; // 执行超时（默认：5000ms）
maxMemory?: number; // 内存限制（默认：64MB）
}
🔒 安全特性
- VM 隔离 - 代码在独立的 V8 上下文中运行
- 执行超时 - 可配置的时间限制防止无限循环
- 内存限制 - 防止内存耗尽攻击
- 受控的模块加载 - 沙箱中的有限模块访问
- 输入验证 - 参数类型检查和验证
🎮 使用 MCP 检查器进行测试
- 启动你的 MCP 服务器：
mcp-sandbox start examples/math-utils.js - 打开 MCP 检查器
- 设置传输类型为 "可流式传输的 HTTP"
- 输入 URL：
http://localhost:3000/mcp/jsonrpc - 连接并测试你的工具！
📦 包
这是一个包含多个包的单体仓库：
@mcp-sandbox/cli- 命令行界面@mcp-sandbox/core- 核心库@mcp-sandbox/utils- 共享工具
🤝 贡献
📄 许可证
MIT 许可证 - 详情见 LICENSE。