Sandbox MCP Tools

🧰 沙盒MCP工具

一个模块化的AI工具平台，将沙盒Python执行、Bash命令、文件管理和电子商务存储操作作为模型上下文协议（MCP）服务器公开，使Claude和Cursor等AI代理能够安全地执行复杂的多步骤工作流。

______________________________________________________________________

📋 目录

• 项目概述
• 主要特点
• 系统架构
• 存储库结构
• MCP服务器
• Python沙盒
• .NET MCP服务器——平台存储
• 工具编排
• AI工作流示例
• 安装
• 正在运行MCP服务器
• 运行测试
• 使用的技术
• 贡献
• 许可证

______________________________________________________________________

🌐 项目概述

沙盒MCP工具 是一个组合了 沙盒代码执行 随着 电子商务API集成，所有这些都是通过 模型上下文协议（MCP）它使AI代理能够：

• 执行Python代码和Bash命令 隔离Docker容器 有安全控制
• 在沙盒工作区中读取、写入和管理文件
• 与a互动 直播电商店API （普拉茨假货店）用于产品、类别和客户管理
• 跨服务器的链式工具 执行端到端数据分析工作流

该项目是作为 生产质量组合件，具有干净的架构、全面的测试和结构化的可观察性。

______________________________________________________________________

✨ 主要特点

______________________________________________________________________

🏗️ 系统架构

高级概述

graph TB
    subgraph AI["🤖 AI Agents"]
        Claude["Claude Desktop"]
        Cursor["Cursor IDE"]
    end

    subgraph MCP["🔌 MCP Servers (stdio transport)"]
        PY["sandbox-python
Python Execution"]
        BASH["sandbox-bash
Bash Commands"]
        FILE["sandbox-file
File Management"]
        STORE["PlatziStoreServer
Store API (.NET)"]
    end

    subgraph SANDBOX["🐳 Docker Sandbox"]
        EXEC["Executor"]
        CONT["Container Manager"]
        VAL["Validator"]
        DOCKER["Python 3.11 Container
pandas · numpy · matplotlib"]
    end

    subgraph EXT["🌐 External"]
        API["Platzi Fake Store API
api.escuelajs.co"]
    end

    Claude --> PY & BASH & FILE & STORE
    Cursor --> PY & BASH & FILE & STORE

    PY --> EXEC
    BASH --> EXEC
    FILE --> EXEC
    EXEC --> VAL
    VAL --> CONT
    CONT --> DOCKER

    STORE --> API

    style AI fill:#1a1a2e,stroke:#e94560,color:#fff
    style MCP fill:#16213e,stroke:#0f3460,color:#fff
    style SANDBOX fill:#0f3460,stroke:#533483,color:#fff
    style EXT fill:#533483,stroke:#e94560,color:#fff

通信流

AI Agent (e.g. Cursor)
  │
  ├── stdio (JSON-RPC) ──→  sandbox-python   ──→ Docker Container
  ├── stdio (JSON-RPC) ──→  sandbox-bash     ──→ Docker Container
  ├── stdio (JSON-RPC) ──→  sandbox-file     ──→ Docker Container
  └── stdio (JSON-RPC) ──→  PlatziStoreServer ──→ Platzi REST API

每个MCP服务器都作为 独立过程 通过以下方式进行通信 stdin/stdout 使用MCP JSON-RPC协议。AI代理发现可用工具，使用结构化参数调用它们，并接收结构化响应。

______________________________________________________________________

📂 存储库结构

sandbox-mcp-tools/
├── src/                          # Python source code
│   ├── sandbox/                  # 🐳 Sandbox core engine
│   │   ├── config.py             #    Container & security configuration
│   │   ├── container.py          #    Docker container lifecycle manager
│   │   ├── executor.py           #    Command execution engine
│   │   └── validator.py          #    Command & path security validator
│   └── servers/                  # 🔌 Python MCP servers
│       ├── python_server.py      #    sandbox-python  (2 tools)
│       ├── bash_server.py        #    sandbox-bash    (1 tool)
│       ├── file_server.py        #    sandbox-file    (3 tools)
│       └── response.py           #    Shared response formatting
│
├── store-mcp/                    # 🛒 .NET MCP server (Platzi Store)
│   ├── src/
│   │   ├── PlatziStore.Domain/       # Entities, Value Objects, Exceptions
│   │   ├── PlatziStore.Application/  # Contracts, Services, Mapping, DTOs
│   │   ├── PlatziStore.Infrastructure/ # API client, Config, Observability
│   │   ├── PlatziStore.Host/         # MCP server entry point & Tools
│   │   └── PlatziStore.Shared/       # Cross-cutting models & utilities
│   └── tests/                        # xUnit test projects
│       ├── PlatziStore.Host.Tests/
│       ├── PlatziStore.Application.Tests/
│       └── PlatziStore.Infrastructure.Tests/
│
├── docker/                       # 🐳 Sandbox Docker image
│   └── Dockerfile                #    Python 3.11-slim + data science libs
│
├── tests/                        # 🧪 Python test suite
│   ├── unit/                     #    Unit tests (validator, servers)
│   └── integration/              #    Integration tests (container, executor)
│
├── docs/                         # 📚 Documentation
│   ├── mcp-explained.md          #    MCP protocol deep-dive
│   ├── python-mcp.md             #    Python MCP server guide
│   └── platzi-mcp-extension.md   #    Platzi Store MCP reference
│
├── workspaces/default/           # 📁 Mounted workspace for the sandbox
├── pyproject.toml                # Python project configuration
└── LICENSE                       # MIT License

______________________________________________________________________

🔌 MCP服务器

此项目运行 4台MCP服务器 总共暴露了 32工具 AI代理。

Python沙盒服务器

这三台服务器共享Docker沙盒后端：

sandbox-python --Python代码执行

sandbox-bash --Bash命令执行

sandbox-file --文件系统操作

.NET平台存储服务器

这 PlatziStoreServer 暴露 26工具 组织成功能组：

______________________________________________________________________

🐳 Python沙盒

沙箱是一个 强化Docker容器 专为安全的AI驱动代码执行而设计。

建筑

graph LR
    subgraph Server["MCP Server"]
        Tool["Tool Handler"]
    end

    subgraph Engine["Sandbox Engine"]
        E["Executor"]
        V["Validator"]
        CM["Container Manager"]
    end

    subgraph Docker["Docker Container"]
        WS["/workspace (mount)"]
        TMP["/tmp (tmpfs)"]
        PY["Python 3.11 Runtime"]
    end

    Tool --> E
    E --> V
    V --> CM
    CM --> Docker

    style Server fill:#1a1a2e,stroke:#e94560,color:#fff
    style Engine fill:#16213e,stroke:#0f3460,color:#fff
    style Docker fill:#0f3460,stroke:#533483,color:#fff

安全控制

命令阻止列表

验证器拒绝包含以下内容的命令：

• 破坏性模式 — rm -rf /, mkfs, dd if=
• 系统命令 — shutdown, reboot, mount
• 权限提升 — sudo, su, chown
• 危险权限 — chmod 777
• 叉式炸弹 — :(){ :|:& };:
• 网络工具 — curl, wget, nc, ssh, scp

预装库

沙盒容器附带了数据科学堆栈：

pandas · numpy · matplotlib · seaborn · scikit-learn · openpyxl

______________________________________________________________________

🏢 .NET MCP服务器——平台存储

这 store-mcp 项目是一个。NET 9 MCP服务器 整洁架构 原则。

架构层

graph TB
    subgraph Host["Host Layer"]
        PROG["Program.cs
MCP Server Bootstrap"]
        TOOLS["Tools/
7 Tool Classes"]
        FMT["Formatting/
Response Formatter"]
        ADAPT["Adapters/
Gateway Adapter"]
    end

    subgraph App["Application Layer"]
        SVC["Services/
6 Command/Query Handlers"]
        CONT["Contracts/
7 Service Interfaces"]
        DTO["DataTransfer/
DTOs & Envelopes"]
        MAP["Mapping/
Entity ↔ DTO Mappers"]
    end

    subgraph Infra["Infrastructure Layer"]
        GW["ApiClients/
Platzi HTTP Gateway"]
        CFG["Configuration/
Options & Settings"]
        OBS["Observability/
Structured Event Logger"]
    end

    subgraph Domain["Domain Layer"]
        ENT["Entities/
Merchandise · ProductGroup · StoreCustomer"]
        VO["ValueObjects/"]
        EX["Exceptions/"]
    end

    Host --> App
    App --> Domain
    Infra --> App
    Host --> Infra

    style Host fill:#1a1a2e,stroke:#e94560,color:#fff
    style App fill:#16213e,stroke:#0f3460,color:#fff
    style Infra fill:#0f3460,stroke:#533483,color:#fff
    style Domain fill:#533483,stroke:#e94560,color:#fff

运作原理

1. MCP客户端（AI代理）发送 工具调用 通过stdio
2. Program.cs 将其路由到匹配 [McpServerTool] 方法
3. 该工具调用 应用层处理程序 （CQRS模式）
4. 处理程序调用 IStoreGateway → 路由通过 适配器 基础设施 IPlatziStoreGateway
5. 基础设施发送 HTTP 请求 到 https://api.escuelajs.co
6. 答案是 映射 来自API模型→ 域实体→ DTO → 格式化文本
7. 格式化的结果返回给AI代理

______________________________________________________________________

🔗 工具编排

最强大的功能之一是 跨服务器工具编排 --在单个工作流中组合来自多个MCP服务器的工具。

多服务器工作流

sequenceDiagram
    participant Agent as 🤖 AI Agent
    participant Store as 🛒 PlatziStore MCP
    participant File as 📁 sandbox-file
    participant Python as 🐍 sandbox-python

    Agent->>Store: analyze_store_data(scope="products")
    Store-->>Agent: JSON with product data

    Agent->>File: write_file(path="products.json", content=...)
    File-->>Agent: ✅ Written 4,280 bytes

    Agent->>Python: execute_python(code="import pandas as pd...")
    Python-->>Agent: 📊 Analysis results & chart saved

沙箱桥

这 沙箱桥 工具(analyze_store_data, process_store_export)实现Platzi Store API和Python沙箱之间的无缝数据流：

┌─────────────┐    JSON/NDJSON    ┌──────────────┐    write_file    ┌──────────────┐
│ Platzi API   │ ──────────────→ │ Store MCP     │ ──────────────→ │ Sandbox File │
└─────────────┘                  └──────────────┘                  └──────┬───────┘
                                                                          │
                                                                   execute_python
                                                                          │
                                                                   ┌──────▼───────┐
                                                                   │ Python Code  │
                                                                   │ pandas, plt  │
                                                                   └──────────────┘

______________________________________________________________________

💡 AI工作流示例

1.产品价格分析

提示: *从商店中获取所有产品，将其保存到JSON文件中，并使用matplotlib创建价格分布直方图*

AI代理将：

1. 呼叫 analyze_store_data(dataScope="products")
2. 呼叫 write_file(path="products.json", content=)
3. 呼叫 execute_python 与：

import json
import matplotlib.pyplot as plt

with open('/workspace/products.json') as f:
    products = json.load(f)

prices = [p['price'] for p in products]
plt.figure(figsize=(10, 6))
plt.hist(prices, bins=20, color='#e94560', edgecolor='white')
plt.title('Product Price Distribution')
plt.xlabel('Price ($)')
plt.ylabel('Count')
plt.savefig('/workspace/price_distribution.png', dpi=150)
print(f"Chart saved. Analyzed {len(prices)} products.")

2.类别库存报告

提示: *“列出所有类别，并计算每个类别中有多少产品。将结果格式化为标记表。”*

3.客户数据导出

提示: *“将所有客户数据导出为NDJSON，然后使用bash计算用户总数并找到唯一的电子邮件域。”*

# The agent calls process_store_export → write_file → execute_bash:
cat /workspace/users.ndjson | wc -l
cat /workspace/users.ndjson | jq -r '.email' | awk -F@ '{print $2}' | sort -u

4.价格过滤与分析

提示: *“找到所有低于50美元的产品，保存它们，并使用Python计算平均价格。”*

______________________________________________________________________

🚀 安装

先决条件

• python 3.10+
• Docker 桌面版 （跑步）
• .NET SDK 9.0+（适用于Platzi Store MCP服务器）
• Git

1.克隆存储库

git clone https://github.com/Rynvasis/sandbox-mcp-tools.git
cd sandbox-mcp-tools

2.Python设置

# Create virtual environment
python -m venv .venv

# Activate it
# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1
# macOS/Linux
source .venv/bin/activate

# Install dependencies
pip install -e ".[dev]"

3.构建沙盒Docker镜像

cd docker
docker build -t sandbox-mcp-tools:latest .
cd ..

4.NET安装程序

cd store-mcp
dotnet restore
dotnet build
cd ..

______________________________________________________________________

▶️ 正在运行MCP服务器

Python沙盒服务器

每台服务器在stdio上作为独立进程运行：

# Python execution server
python -m src.servers.python_server

# Bash execution server
python -m src.servers.bash_server

# File management server
python -m src.servers.file_server

.NET平台存储服务器

cd store-mcp
dotnet run --project src/PlatziStore.Host

光标IDE配置

将服务器添加到您的 .cursor/mcp.json:

{
  "mcpServers": {
    "sandbox-python": {
      "command": "python",
      "args": ["-m", "src.servers.python_server"],
      "cwd": "/path/to/sandbox-mcp-tools"
    },
    "sandbox-bash": {
      "command": "python",
      "args": ["-m", "src.servers.bash_server"],
      "cwd": "/path/to/sandbox-mcp-tools"
    },
    "sandbox-file": {
      "command": "python",
      "args": ["-m", "src.servers.file_server"],
      "cwd": "/path/to/sandbox-mcp-tools"
    },
    "platzi-store": {
      "command": "dotnet",
      "args": ["run", "--project", "store-mcp/src/PlatziStore.Host"],
      "cwd": "/path/to/sandbox-mcp-tools"
    }
  }
}

______________________________________________________________________

🧪 运行测试

Python测试

# Run all tests
pytest

# Run unit tests only
pytest tests/unit/

# Run integration tests (requires Docker)
pytest tests/integration/

# Run with verbose output
pytest -v

.NET测试

cd store-mcp

# Run all test projects
dotnet test

# Run a specific test project
dotnet test tests/PlatziStore.Host.Tests/
dotnet test tests/PlatziStore.Application.Tests/
dotnet test tests/PlatziStore.Infrastructure.Tests/

______________________________________________________________________

🛠️ 使用的技术

______________________________________________________________________

🤝 贡献

欢迎投稿！以下是如何开始：

1. 分叉 存储库
2. 创建 特征分支(git checkout -b feature/amazing-feature)
3. 提交 您的更改(git commit -m 'Add amazing feature')
4. 推 到分行(git push origin feature/amazing-feature)
5. 打开 拉取请求

开发指南

• 遵循现有的代码约定和架构模式
• 添加新功能测试（单元和集成）
• 确保Docker正在运行以进行集成测试
• 跑 pytest 和 dotnet test 在提交PR之前

______________________________________________________________________

📄 许可证

该项目根据 MIT许可证 --看看 许可证 文件以获取详细信息。

MIT License · Copyright (c) 2026 Ahmed Raed