{"id":31931000,"url":"https://github.com/rocket-connect/mcp-sandbox","last_synced_at":"2025-10-14T04:04:27.976Z","repository":{"id":296501184,"uuid":"993590257","full_name":"rocket-connect/mcp-sandbox","owner":"rocket-connect","description":"Turn any JavaScript module into a sandboxed MCP (Model Context Protocol) server with automatic reflection and type inference.","archived":false,"fork":false,"pushed_at":"2025-05-31T07:30:24.000Z","size":655,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T16:21:09.601Z","etag":null,"topics":["ai-integration","ai-tools","automation","cli-tool","json-rpc","llm","mcp","model-context-protocol","reflection","sandbox","security-sandbox","server-sent-events","vm-isolation"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@mcp-sandbox/cli","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rocket-connect.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-31T04:49:16.000Z","updated_at":"2025-09-25T12:41:28.000Z","dependencies_parsed_at":"2025-05-31T17:20:39.017Z","dependency_job_id":"1a37255c-21fc-4e91-8512-300fa833333f","html_url":"https://github.com/rocket-connect/mcp-sandbox","commit_stats":null,"previous_names":["danstarns/mcp-sandbox"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/rocket-connect/mcp-sandbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rocket-connect%2Fmcp-sandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rocket-connect%2Fmcp-sandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rocket-connect%2Fmcp-sandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rocket-connect%2Fmcp-sandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rocket-connect","download_url":"https://codeload.github.com/rocket-connect/mcp-sandbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rocket-connect%2Fmcp-sandbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279017953,"owners_count":26086189,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-integration","ai-tools","automation","cli-tool","json-rpc","llm","mcp","model-context-protocol","reflection","sandbox","security-sandbox","server-sent-events","vm-isolation"],"created_at":"2025-10-14T04:02:56.228Z","updated_at":"2025-10-14T04:04:27.965Z","avatar_url":"https://github.com/rocket-connect.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# MCP Sandbox\n\n[![npm version](https://badge.fury.io/js/@mcp-sandbox%2Fcli.svg)](https://badge.fury.io/js/@mcp-sandbox%2Fcli)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/danstarns/mcp-sandbox/blob/main/LICENSE)\n\n\u003cp align=center\u003e\n  \u003cimg width=\"80%\" src=\"https://raw.githubusercontent.com/danstarns/mcp-sandbox/main/docs/banner.png#gh-dark-mode-only\" alt=\"MCP Sandbox\"/\u003e\n\u003c/p\u003e\n\n**Turn any JavaScript module into a sandboxed MCP (Model Context Protocol) server with automatic reflection and type inference.**\n\n## 🎯 What is MCP Sandbox?\n\nMCP 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.\n\n## ✨ Features\n\n- 🔍 **Automatic Reflection** - Analyzes JS modules and extracts function signatures\n- 🛡️ **Secure Sandboxing** - Executes code in isolated VM contexts with timeouts\n- 🧠 **Smart Type Inference** - Detects parameter types from defaults and naming patterns\n- 📚 **JSDoc Integration** - Extracts documentation from function comments\n- 📡 **MCP Protocol** - Full JSON-RPC 2.0 and SSE support\n- 🌐 **REST API** - Legacy REST endpoints for easy testing\n- ⚙️ **TypeScript** - Full type safety and IntelliSense support\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\n# Install globally for CLI usage\nnpm install -g @mcp-sandbox/cli\n\n# Or use in a project\nnpm install @mcp-sandbox/core @mcp-sandbox/cli\n```\n\n### Basic Usage\n\n```bash\n# Start MCP server for a JavaScript module\n$ mcp-sandbox start ./math-utils.js\n\n🏗️  Initializing MCP Sandbox...\n🔍 Reflecting module\n📊 Discovered 2 tools:\n  - circleArea: Calculate area of a circle\n  - fibonacci: Generate Fibonacci sequence\n🚀 MCP Sandbox server running at http://localhost:3000\n📋 MCP Tools: http://localhost:3000/mcp/tools\n⚡ MCP Execute: http://localhost:3000/mcp/execute\n🔄 MCP SSE: http://localhost:3000/sse\n📡 MCP JSON-RPC: http://localhost:3000/mcp/jsonrpc\n⚙️  MCP Config: http://localhost:3000/mcp-config\n💡 For MCP Inspector, use: http://localhost:3000/sse\n\n```\n\n### Example Module\n\n```javascript\n/**\n * Calculate the area of a circle\n * @param radius The radius of the circle\n */\nfunction circleArea(radius = 1) {\n  return Math.PI * radius * radius;\n}\n\n/**\n * Generate fibonacci sequence\n * @param count Number of fibonacci numbers to generate\n */\nfunction fibonacci(count = 10) {\n  const seq = [0, 1];\n  for (let i = 2; i \u003c count; i++) {\n    seq[i] = seq[i - 1] + seq[i - 2];\n  }\n  return seq.slice(0, count);\n}\n\nmodule.exports = { circleArea, fibonacci };\n```\n\nRunning `mcp-sandbox start math-utils.js` automatically:\n\n1. 🔍 Reflects the module and discovers functions\n2. 📊 Generates type schemas from parameters\n3. 🚀 Starts MCP server at `http://localhost:3000`\n4. 💾 Creates `mcp-config.json` for MCP clients\n\n## 📡 API Endpoints\n\nThe server exposes both MCP and REST endpoints:\n\n### MCP Protocol (JSON-RPC 2.0)\n\n- `POST /mcp/jsonrpc` - Main MCP endpoint\n- `GET /sse` - Server-Sent Events for real-time updates\n\n### REST API (for testing)\n\n- `GET /tools` - List available tools\n- `POST /execute/:toolName` - Execute a specific tool\n- `GET /mcp-config` - Get MCP server configuration\n- `GET /health` - Health check\n\n### Example Usage\n\n```bash\n# List tools\ncurl http://localhost:3000/tools\n\n# Execute function via REST\ncurl -X POST http://localhost:3000/execute/circleArea \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"args\": {\"radius\": 5}}'\n\n# MCP JSON-RPC call\ncurl -X POST http://localhost:3000/mcp/jsonrpc \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/call\", \"params\": {\"name\": \"fibonacci\", \"arguments\": {\"count\": 8}}}'\n```\n\n## 🏗️ Programmatic Usage\n\n```typescript\nimport { MCPSandbox } from '@mcp-sandbox/core';\n\nconst sandbox = new MCPSandbox({\n  port: 3000,\n  timeout: 5000,\n});\n\n// Load and analyze module\nawait sandbox.loadModule('./my-module.js');\n\n// Start MCP server\nawait sandbox.start();\n\n// Execute tools directly\nconst result = await sandbox.executeTool('myFunction', {\n  param1: 'value1',\n});\n```\n\n## 📚 Example Modules Included\n\nThe repository includes several example modules demonstrating different use cases:\n\n### Mathematical Operations ([`examples/math-utils.js`](https://github.com/danstarns/mcp-sandbox/blob/main/examples/math-utils.js))\n\n- Circle area calculation\n- Fibonacci sequence generation\n- Compound interest calculation\n- Prime number checking\n- Degree/radian conversion\n- Factorial calculation\n\n### String Manipulation ([`examples/string-utils.js`](https://github.com/danstarns/mcp-sandbox/blob/main/examples/string-utils.js))\n\n- Title case conversion\n- Random string generation\n- Word counting\n- Palindrome detection\n- String reversal\n- Capitalization\n\n### Array Operations ([`examples/array-utils.js`](https://github.com/danstarns/mcp-sandbox/blob/main/examples/array-utils.js))\n\n- Array shuffling (Fisher-Yates)\n- Unique value extraction\n- Array chunking\n- Set operations (intersection, difference)\n- Array flattening\n\n### Filesystem Operations ([`examples/filesystem-utils.js`](https://github.com/danstarns/mcp-sandbox/blob/main/examples/filesystem-utils.js))\n\n- File reading/writing (async)\n- Directory listing and creation\n- File searching with patterns\n- Disk usage calculation\n- File copying and deletion\n- Line-by-line file reading\n\n## 🛠️ Development\n\n```bash\n# Clone repository\ngit clone https://github.com/danstarns/mcp-sandbox.git\ncd mcp-sandbox\n\n# Install dependencies\npnpm install\n\n# Build all packages\npnpm build\n\n# Run examples\npnpm example:math          # Math utilities\npnpm example:filesystem    # File operations\npnpm example:string        # String manipulation\n\n# Lint and format\npnpm lint \u0026\u0026 pnpm format\n```\n\n## 🔧 Configuration Options\n\n### CLI Options\n\n```bash\nmcp-sandbox start \u003cmodule\u003e [options]\n\nOptions:\n  -p, --port \u003cport\u003e      Server port (default: 3000)\n  -h, --host \u003chost\u003e      Server host (default: localhost)\n  -t, --timeout \u003cms\u003e     Execution timeout (default: 5000ms)\n  -o, --output \u003cfile\u003e    Output MCP configuration to file\n```\n\n### Programmatic Options\n\n```typescript\ninterface SandboxOptions {\n  port?: number; // Server port (default: 3000)\n  host?: string; // Server host (default: 'localhost')\n  timeout?: number; // Execution timeout (default: 5000ms)\n  maxMemory?: number; // Memory limit (default: 64MB)\n}\n```\n\n## 🔒 Security Features\n\n- **VM Isolation** - Code runs in separate V8 contexts\n- **Execution Timeouts** - Configurable time limits prevent infinite loops\n- **Memory Limits** - Prevent memory exhaustion attacks\n- **Controlled Requires** - Limited module access in sandbox\n- **Input Validation** - Parameter type checking and validation\n\n## 🎮 Testing with MCP Inspector\n\n1. Start your MCP server: `mcp-sandbox start examples/math-utils.js`\n2. Open [MCP Inspector](https://github.com/modelcontextprotocol/inspector)\n3. Set Transport Type to \"Streamable HTTP\"\n4. Enter URL: `http://localhost:3000/mcp/jsonrpc`\n5. Connect and test your tools!\n\n## 📦 Packages\n\nThis is a monorepo containing multiple packages:\n\n- [`@mcp-sandbox/cli`](https://www.npmjs.com/package/@mcp-sandbox/cli) - Command-line interface\n- [`@mcp-sandbox/core`](https://www.npmjs.com/package/@mcp-sandbox/core) - Core library\n- [`@mcp-sandbox/utils`](https://www.npmjs.com/package/@mcp-sandbox/utils) - Shared utilities\n\n## 🤝 Contributing\n\nContributions are welcome! Please read our [Contributing Guide](https://github.com/danstarns/mcp-sandbox/blob/main/CONTRIBUTING.md) and check out the [open issues](https://github.com/danstarns/mcp-sandbox/issues).\n\n## 📄 License\n\nMIT License - see [LICENSE](https://github.com/danstarns/mcp-sandbox/blob/main/LICENSE) for details.\n\n## 🔗 Links\n\n- **GitHub Repository**: [https://github.com/danstarns/mcp-sandbox](https://github.com/danstarns/mcp-sandbox)\n- **Issues**: [https://github.com/danstarns/mcp-sandbox/issues](https://github.com/danstarns/mcp-sandbox/issues)\n- **NPM CLI Package**: [https://www.npmjs.com/package/@mcp-sandbox/cli](https://www.npmjs.com/package/@mcp-sandbox/cli)\n- **NPM Core Package**: [https://www.npmjs.com/package/@mcp-sandbox/core](https://www.npmjs.com/package/@mcp-sandbox/core)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frocket-connect%2Fmcp-sandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frocket-connect%2Fmcp-sandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frocket-connect%2Fmcp-sandbox/lists"}