MCP Sandbox

MCP Sandbox

将任意 JavaScript 模块转换为沙箱化的 MCP（Model Context Protocol）服务，并自动进行反射和类型推断。

🎯 什么是 MCP Sandbox？

MCP Sandbox 会自动将 JavaScript 模块转换为兼容 MCP（Model Context Protocol）的服务，让 AI 系统能够调用任意 JavaScript 函数。它使用 VM 沙箱保障安全，自动推断类型，并生成规范的 MCP 配置。

✨ 功能特性

• 🔍 自动反射 - 分析 JS 模块并提取函数签名
• 🛡️ 安全沙箱 - 在隔离的 VM 上下文中执行代码，并设置超时
• 🧠 智能类型推断 - 根据默认值和命名模式检测参数类型
• 📚 JSDoc 集成 - 从函数注释中提取文档
• 📡 MCP 协议 - 完整支持 JSON-RPC 2.0 和 SSE
• 🌐 REST API - 提供传统 REST 端点，便于测试
• ⚙️ TypeScript - 提供完整的类型安全和 IntelliSense 支持

🚀 快速开始

安装

# Install globally for CLI usage
npm install -g @mcp-sandbox/cli

# Or use in a project
npm install @mcp-sandbox/core @mcp-sandbox/cli

基本用法

# Start MCP server for a JavaScript module
$ mcp-sandbox start ./math-utils.js

🏗️  Initializing MCP Sandbox...
🔍 Reflecting module
📊 Discovered 2 tools:
  - circleArea: Calculate area of a circle
  - fibonacci: Generate Fibonacci sequence
🚀 MCP Sandbox server running at http://localhost:3000
📋 MCP Tools: http://localhost:3000/mcp/tools
⚡ MCP Execute: http://localhost:3000/mcp/execute
🔄 MCP SSE: http://localhost:3000/sse
📡 MCP JSON-RPC: http://localhost:3000/mcp/jsonrpc
⚙️  MCP Config: http://localhost:3000/mcp-config
💡 For MCP Inspector, use: http://localhost:3000/sse

示例模块

/**
 * Calculate the area of a circle
 * @param radius The radius of the circle
 */
function circleArea(radius = 1) {
  return Math.PI * radius * radius;
}

/**
 * Generate fibonacci sequence
 * @param count Number of fibonacci numbers to generate
 */
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 会自动：

1. 🔍 反射模块并发现函数
2. 📊 根据参数生成类型架构
3. 🚀 在 http://localhost:3000 启动 MCP 服务
4. 💾 为 MCP 客户端创建 mcp-config.json

📡 API 端点

服务同时提供 MCP 和 REST 端点：

MCP 协议（JSON-RPC 2.0）

• POST /mcp/jsonrpc - MCP 主端点
• GET /sse - 用于实时更新的服务器发送事件

REST API（用于测试）

• GET /tools - 列出可用工具
• POST /execute/:toolName - 执行指定工具
• GET /mcp-config - 获取 MCP 服务配置
• GET /health - 健康检查

用法示例

# List tools
curl http://localhost:3000/tools

# Execute function via REST
curl -X POST http://localhost:3000/execute/circleArea \
  -H "Content-Type: application/json" \
  -d '{"args": {"radius": 5}}'

# MCP JSON-RPC call
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,
});

// Load and analyze module
await sandbox.loadModule('./my-module.js');

// Start MCP server
await sandbox.start();

// Execute tools directly
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）

• 读取/写入文件（异步）
• 列出和创建目录
• 按模式搜索文件
• 计算磁盘用量
• 复制和删除文件
• 逐行读取文件

🛠️ 开发

# Clone repository
git clone https://github.com/danstarns/mcp-sandbox.git
cd mcp-sandbox

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run examples
pnpm example:math          # Math utilities
pnpm example:filesystem    # File operations
pnpm example:string        # String manipulation

# Lint and format
pnpm lint && pnpm format

🔧 配置选项

CLI 选项

mcp-sandbox start <module> [options]

Options:
  -p, --port <port>      Server port (default: 3000)
  -h, --host <host>      Server host (default: localhost)
  -t, --timeout <ms>     Execution timeout (default: 5000ms)
  -o, --output <file>    Output MCP configuration to file

编程式选项

interface SandboxOptions {
  port?: number; // Server port (default: 3000)
  host?: string; // Server host (default: 'localhost')
  timeout?: number; // Execution timeout (default: 5000ms)
  maxMemory?: number; // Memory limit (default: 64MB)
}

🔒 安全特性

• VM 隔离 - 代码在独立的 V8 上下文中运行
• 执行超时 - 可配置的时间限制可防止无限循环
• 内存限制 - 防止内存耗尽攻击
• 受控的 require - 限制沙箱中的模块访问
• 输入验证 - 参数类型检查和验证

🎮 使用 MCP Inspector 进行测试

1. 启动 MCP 服务：mcp-sandbox start examples/math-utils.js
2. 打开 MCP Inspector
3. 将传输类型设为“Streamable HTTP”
4. 输入 URL：http://localhost:3000/mcp/jsonrpc
5. 连接并测试你的工具！

📦 软件包

这是一个包含多个软件包的单体仓库：

• @mcp-sandbox/cli - 命令行界面
• @mcp-sandbox/core - 核心库
• @mcp-sandbox/utils - 共享实用工具

🤝 参与贡献

欢迎贡献！请阅读我们的贡献指南，并查看待处理的问题。

📄 许可证

MIT 许可证——详情请参阅 LICENSE。

🔗 链接

• GitHub 仓库：https://github.com/danstarns/mcp-sandbox
• 问题反馈：https://github.com/danstarns/mcp-sandbox/issues
• NPM CLI 软件包：https://www.npmjs.com/package/@mcp-sandbox/cli
• NPM 核心软件包：https://www.npmjs.com/package/@mcp-sandbox/core