Mcp Sandbox

MCP Sandbox

[](https://badge.fury.io/js/@mcp-sandbox%2Fcli) [](https://github.com/danstarns/mcp-sandbox/blob/main/LICENSE)

Turn any JavaScript module into a sandboxed MCP (Model Context Protocol) server with automatic reflection and type inference.

🎯 What is MCP Sandbox?

MCP Sandbox automatically converts JavaScript modules into MCP (Model Context Protocol) compatible servers, making any JavaScript function accessible to AI systems. It uses VM sandboxing for security, automatic type inference, and generates proper MCP configurations.

✨ Features

• 🔍 Automatic Reflection - Analyzes JS modules and extracts function signatures
• 🛡️ Secure Sandboxing - Executes code in isolated VM contexts with timeouts
• 🧠 Smart Type Inference - Detects parameter types from defaults and naming patterns
• 📚 JSDoc Integration - Extracts documentation from function comments
• 📡 MCP Protocol - Full JSON-RPC 2.0 and SSE support
• 🌐 REST API - Legacy REST endpoints for easy testing
• ⚙️ TypeScript - Full type safety and IntelliSense support

🚀 Quick Start

Installation

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

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

Basic Usage

# 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

Example Module

/**
 * 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  [options]

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

Programmatic Options

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)
}

🔒 Security Features

• VM Isolation - Code runs in separate V8 contexts
• Execution Timeouts - Configurable time limits prevent infinite loops
• Memory Limits - Prevent memory exhaustion attacks
• Controlled Requires - Limited module access in sandbox
• Input Validation - Parameter type checking and validation

🎮 Testing with MCP Inspector

1. Start your MCP server: mcp-sandbox start examples/math-utils.js
2. Open MCP Inspector
3. Set Transport Type to "Streamable HTTP"
4. Enter URL: http://localhost:3000/mcp/jsonrpc
5. Connect and test your tools!

📦 Packages

This is a monorepo containing multiple packages:

• @mcp-sandbox/cli - Command-line interface
• @mcp-sandbox/core - Core library
• @mcp-sandbox/utils - Shared utilities

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide and check out the open issues.

📄 License

MIT License - see LICENSE for details.

🔗 Links

• GitHub Repository: https://github.com/danstarns/mcp-sandbox
• Issues: https://github.com/danstarns/mcp-sandbox/issues
• NPM CLI Package: https://www.npmjs.com/package/@mcp-sandbox/cli
• NPM Core Package: https://www.npmjs.com/package/@mcp-sandbox/core

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rocket-connect
• Source: rocket-connect/mcp-sandbox
• License: MIT
• Homepage: https://www.npmjs.com/package/@mcp-sandbox/cli

Install and usage instructions live in the source repository linked above.