MCP Sandbox

MCP Sandbox

あらゆる JavaScript モジュールを、自動リフレクションと型推論を備えたサンドボックス化 MCP（Model Context Protocol）サーバーに変換します。

🎯 MCP Sandbox とは？

MCP Sandbox は JavaScript モジュールを MCP（Model Context Protocol）互換サーバーに自動変換し、あらゆる JavaScript 関数を AI システムから利用できるようにします。セキュリティのために 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 - リアルタイム更新用の Server-Sent Events

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）

• ファイルの読み書き（非同期）
• ディレクトリの一覧表示と作成
• パターンを使ったファイル検索
• ディスク使用量の計算
• ファイルのコピーと削除
• ファイルを1行ずつ読み込み

🛠️ 開発

# 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