https://github.com/areebahmeddd/superbox.ai
📦 Discover, deploy, and test MCPs in isolated sandboxes
https://github.com/areebahmeddd/superbox.ai
aws cli docker fastapi fastmcp golang model-context-protocol open-container-initiative sandbox-environment
Last synced: 2 months ago
JSON representation
📦 Discover, deploy, and test MCPs in isolated sandboxes
- Host: GitHub
- URL: https://github.com/areebahmeddd/superbox.ai
- Owner: areebahmeddd
- License: mit
- Created: 2025-06-08T04:25:46.000Z (about 1 year ago)
- Default Branch: prod
- Last Pushed: 2026-04-11T23:58:08.000Z (2 months ago)
- Last Synced: 2026-04-12T01:22:34.236Z (2 months ago)
- Topics: aws, cli, docker, fastapi, fastmcp, golang, model-context-protocol, open-container-initiative, sandbox-environment
- Language: Go
- Homepage: https://superbox.1mindlabs.org
- Size: 2.42 MB
- Stars: 8
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: docs/CODE_OF_CONDUCT.md
- Security: docs/SECURITY.md
Awesome Lists containing this project
README
```text
_ _
| | (_)
___ _ _ _ __ ___ _ __| |__ _____ __ __ _ _
/ __| | | | '_ \ / _ \ '__| '_ \ / _ \ \/ / / _` | |
\__ \ |_| | |_) | __/ | | |_) | (_) > < | (_| | |
|___/\__,_| .__/ \___|_| |_.__/ \___/_/\_(_)__,_|_|
| |
|_|
```
[](https://github.com/areebahmeddd/superbox.ai/actions/workflows/ci.yaml)
[](https://pypi.org/project/superbox)
[](https://pypi.org/project/superbox)
[](https://pypi.org/project/superbox)
[](https://go.dev)
[](LICENSE)
# 🧰 SuperBox
**SuperBox** (inspired by [Docker Hub](https://hub.docker.com)) helps you discover, deploy, and test MCPs in isolated sandboxes ( [Demo Video]() ). It includes:
- A Python (Click) CLI to initialize metadata, run security scans, push to a registry (R2), search, and configure popular AI clients (VS Code, Cursor, Windsurf, Claude, ChatGPT)
- A Golang (Gin) backend to list/get/create MCP servers with optional pricing and security reports
- A Cloudflare Worker + Durable Object executor that runs MCP servers on demand directly from their Git repositories using a lightweight TypeScript interpreter (Cloudflare Workers blocks `eval()` and exceeds the WASM bundle size limit, making Pyodide unusable)
Why this project:
- There's no centralized MCP registry to discover all MCPs, and many lack clear usage docs.
- MCPs on our platform pass a 5-step security/quality check (SonarQube, Bandit, GitGuardian) to reduce vulnerabilities and promote best practices.
- Unlike MCPs that run locally on your machine, MCP servers here execute in sandboxed environments and return responses securely.
## Key Features
- **Central MCP Registry**: R2-backed registry with per-server JSON for easy discovery and portability.
- **Sandboxed Execution**: MCP servers run in Cloudflare Durable Objects and return responses securely. The executor supports `requests`-based HTTP tools; see `cloudflare/README.md` for the full scope.
- **Security Pipeline (5-step)**: SonarQube, Bandit, and GitGuardian checks with a unified report.
- **One-Command Publish**: `superbox push` scans, discovers tools, and uploads a unified record to R2.
- **Client Auto-Config**: `superbox pull --client cursor|vscode|...` writes correct MCP config pointing to the Cloudflare Worker.
- **Terminal Runner**: `superbox run --name ` starts an interactive prompt against the Cloudflare executor.
- **Live Logs**: `superbox logs --name ` shows instructions for streaming logs via `wrangler tail`.
- **Tool Discovery**: Regex-based discovery across Python code and optional Node `package.json` definitions.
## 📚 Documentation
**For complete documentation, setup guides, API references, and CLI usage:**
🔗 **[https://superbox.1mindlabs.org/docs](https://superbox.1mindlabs.org/docs)**
## 📄 Research Paper
The IEEE research paper for SuperBox is available in the [`ieee/`](ieee/) directory:
- [`paper.pdf`](ieee/paper.pdf) – compiled paper
- [`paper.tex`](ieee/paper.tex) – LaTeX source
## 🗂️ Project Structure
```text
.
├── docs/ # Documentation (INSTALL.md, SETUP.md)
├── ieee/ # IEEE research paper (paper.pdf, paper.tex)
├── src/
│ └── superbox/
│ ├── cli/ # CLI: init, auth, push, pull, run, search, inspect, test, logs
│ │ ├── commands/ # CLI subcommands
│ │ └── scanners/ # SonarCloud, Bandit, ggshield, tool-discovery
│ ├── server/ # Golang (Gin) app + handlers
│ │ ├── handlers/ # servers, payment, auth, health
│ │ ├── models/ # Request/response types
│ │ ├── helpers/ # Python R2 helper
│ │ └── templates/ # Landing page
│ └── shared/ # Config, models, R2/S3-compat utils
├── pyproject.toml # Project metadata & dependencies
├── Dockerfile # Server container
├── docker-compose.yaml # Optional local stack
└── tests/ # pytest suite - see tests/README.md
```
## 🌐 API Reference
The HTTP API provides endpoints for server management, authentication, and payments.
For complete API documentation, see:
[https://superbox.1mindlabs.org/docs/api](https://superbox.1mindlabs.org/docs/api)
## 🔧 CLI Overview
The SuperBox CLI provides commands for authentication, server management, and testing:
**Authentication:**
- `superbox auth register` – Register a new account
- `superbox auth login` – Log in (email/Google/GitHub)
- `superbox auth logout` – Log out
- `superbox auth status` – Check authentication status
- `superbox auth refresh` – Refresh authentication token
**Server Management:**
- `superbox init` – Initialize a new MCP server project
- `superbox push` – Publish server to registry
- `superbox pull` – Download and configure server for AI clients
- `superbox search` – Search for servers in registry
- `superbox inspect` – View server details and security report
- `superbox test` – Test server directly from repository (without registry)
**Execution & Monitoring:**
- `superbox run` – Run server in interactive mode
- `superbox logs` – View server execution logs
For detailed CLI documentation and usage examples, see:
[https://superbox.1mindlabs.org/docs/cli](https://superbox.1mindlabs.org/docs/cli)
## 📦 Installation
```bash
pip install superbox
```
- **PyPI:** [https://pypi.org/project/superbox](https://pypi.org/project/superbox)
- **npm:** coming soon
See [docs/INSTALL.md](docs/INSTALL.md) for complete installation instructions.
## 📄 License
This project is licensed under the [MIT License](LICENSE).
## 👥 Authors
**Core Contributors:**
- [Areeb Ahmed](https://github.com/areebahmeddd)
- [Amartya Anand](https://github.com/amarr07)
- [Arush Verma](https://github.com/arush3218)
- [Devansh Aryan](https://github.com/devansharyan123)
**Acknowledgments:**
- [Shivansh Karan](https://github.com/spacetesla)
- [Rishi Chirchi](https://github.com/rishichirchi)
- [Avantika Kesarwani](https://github.com/avii09)