Isolated Compute Platform Sandbox (MCP)

Test Drive the Sandbox at MCP Sandbox Portal

中文文档 | English

Demonstration

This MCP Sandbox offers an interactive service for running Python routines. It leverages transient Docker instances to guarantee that code execution and dependency setup occur within strictly segregated boundaries, protecting the host system and ensuring state separation between invocations.

Viby Integration

Viby is designed to interface seamlessly with the mcp sandbox service.

Key Capabilities

• 🐳 Containerized Security: Python workloads are executed within dedicated, isolated Docker vessels.
• 📦 Dependency Provisioning: Streamlined mechanisms for introducing required Python libraries.
• 📊 Artifact Output: Capability to generate persisted files (e.g., data dumps, charts) accessible via web pointers.

Deployment Instructions

bash

Obtain the repository source

git clone https://github.com/JohanLi233/python-mcp-sandbox.git cd python-mcp-sandbox

Set up the environment using UV

uv venv uv sync

Initiate the primary service

uv run main.py

The standard EventSource (SSE) communication channel is established at http://localhost:8000/sse. Consumers, such as the MCP Inspector, can interface with this tool via SSE or any client supporting the SSE protocol.

Available Functional Interfaces (Tools)

1. create_sandbox: Initializes a fresh, isolated Python Docker container and returns a unique identifier (sandbox_id) essential for all subsequent operations.
2. list_sandboxes: Fetches a registry of all currently active sandbox instances for potential reuse.
3. execute_python_code: Triggers execution of provided Python source within a specified sandbox context.
4. install_package_in_sandbox: Manages the installation of Python libraries (e.g., 'numpy') into a designated container. This is an asynchronous operation.
5. check_package_installation_status: Queries the current installation state of a specified library within the container.
6. execute_terminal_command: Allows running arbitrary shell instructions within the sandbox environment. Parameters: sandbox_id (identifier), command (shell string). Yields stdout, stderr, and exit_code.
7. upload_file_to_sandbox: Transfers a file from the local machine into the container filesystem. Parameters: sandbox_id (identifier), local_file_path (source location), dest_path (target location within container, defaults to /app/results).

Repository Blueprint

python-mcp-sandbox/ ├── main.py # Service bootstrap file ├── requirements.txt # Project Python dependencies list ├── Dockerfile # Blueprint for container image creation ├── results/ # Storage location for generated outputs ├── mcp_sandbox/ # Core package module │ ├── init.py │ ├── models.py # Data serialization schemas (Pydantic) │ ├── api/ │ │ ├── init.py │ │ └── routes.py # HTTP endpoint definitions │ ├── core/ │ │ ├── init.py │ │ ├── docker_manager.py # Logic for Docker orchestration │ │ └── mcp_tools.py # Interface definitions for external tools │ └── utils/ │ ├── init.py │ ├── config.py # System configuration parameters │ ├── file_manager.py # File I/O utilities │ └── task_manager.py # Background job scheduling └── README.md # Primary project documentation

Operational Guideline (LLM Interaction)

When interacting with the Python execution engine, adhere to this sequence:

1. Inventory Check: Initiate with list_sandboxes to see if a ready container exists. Avoid creating duplicates; reuse an existing sandbox_id if found.
2. Creation: If no functional container is present, invoke create_sandbox to provision a new, isolated environment. The resulting sandbox_id is mandatory for all subsequent tool calls.
3. Prerequisite Setup: If external libraries are needed, use install_package_in_sandbox (providing sandbox_id and package names). This initiates a background installation process.
4. Verification: Confirm readiness using check_package_installation_status with the relevant sandbox_id and package.
5. Execution: Run the primary logic via execute_python_code, specifying sandbox_id and the Python source code.

Workflow Summary: List $\rightarrow$ Create (if needed) $\rightarrow$ Install Packages (if needed) $\rightarrow$ Verify Installation $\rightarrow$ Execute Code.

Execution is performed within a secure boundary. All file outputs (graphs, data tables) generated by the code will be accessible via direct HTTP hyperlinks presented in the execution response, enabling immediate inline browser viewing.

Visualization Protocol: Crucially, never use plt.show() in the Python script. - For graphical outputs, utilize file-saving methods like plt.savefig('filename.png'). - For structured data, serialize it using methods such as df.to_csv('data.csv'). - These saved artifacts are automatically exposed through the result links.

Configuration Sample (Claude Integration)

Example configuration JSON for tool discovery:

{ "mcpServers": { "mcpSandbox": { "command": "npx", "args": ["-y", "supergateway", "--sse", "http://localhost:8000/sse"] } } }

Configuration Sample (Public Demo)

{ "mcpServers": { "mcpSandbox": { "command": "npx", "args": ["-y", "supergateway", "--sse", "http://115.190.87.78/sse?api_key="] } } }

Please adjust the serverUrl parameter to match your operational deployment location.

WIKIPEDIA: Cloud computing, defined by ISO as "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand," is frequently termed "the cloud."

== Defining Traits == The National Institute of Standards and Technology (NIST) established five core attributes for cloud environments in 2011. These are:

On-demand self-service: Consumers can provision compute resources (e.g., processing time, storage) automatically, without intervention from the service provider staff. Broad network access: Services are reachable over the network using standard protocols, accommodating diverse endpoint devices (laptops, mobile units, etc.). Resource pooling: The provider aggregates resources to serve multiple tenants dynamically, allocating and reallocating capacity based on fluctuating demand. Rapid elasticity: Capabilities can be scaled up or down quickly—sometimes automatically—to match demand perfectly. To the end-user, capacity often seems limitless. Measured service: Resource utilization (storage, bandwidth, CPU cycles) is automatically tracked, controlled, and reported, ensuring transparent usage accounting for both the provider and the consumer.

By 2023, the International Organization for Standardization (ISO) had further developed and elaborated upon this foundational list.

== Historical Context ==

The intellectual lineage of cloud computing traces back to the 1960s and the adoption of time-sharing concepts through Remote Job Entry (RJE). During that period, the dominant model involved users submitting batch jobs to human operators who ran them on centralized mainframes. This era was characterized by efforts to maximize the utility of expensive, large-scale computing assets through sharing and optimized resource handling. The adoption of the "cloud" graphical metaphor for abstracted services is often credited to General Magic in 1994, where it represented the accessible domain for their Telescript agents. David Hoffman, a communications specialist at General Magic, is credited with originating the term's application here, drawing on its existing use in telecommunications diagrams. The term 'cloud computing' gained widespread recognition in 1996 when Compaq Computer Corporation drafted an early strategic blueprint for internet-centric operations, emphasizing massive scalability.