Superbox Ai

                          _                      _
                         | |                    (_)
___ _   _ _ __   ___ _ __| |__   _____  __  __ _ _
/ __| | | | '_ \ / _ \ '__| '_ \ / _ \ \/ / / _` | |
\__ \ |_| | |_) |  __/ |  | |_) | (_) >  

[](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

🔧 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

📦 Installation

pip install superbox

• PyPI: 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
• Amartya Anand
• Arush Verma
• Devansh Aryan

Acknowledgments:

• Shivansh Karan
• Rishi Chirchi
• Avantika Kesarwani

Source & license

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

• Author: areebahmeddd
• Source: areebahmeddd/superbox.ai
• License: MIT
• Homepage: https://superbox.1mindlabs.org

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