使用说明

🧰 沙盒MCP工具

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

📋 目录

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

🌐 项目概述

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

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

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

✨ 主要特点

特性	描述
🔌 MCP工具架构	4台MCP服务器暴露 32工具通过标准JSON-RPC/stdio传输
🐳 沙盒执行	具有资源限制、网络隔离和命令块列表的Docker容器
🤖 AI代理编排	与Claude Desktop和Cursor IDE配合使用
🛒 Platzi门店整合	产品、类别、客户和身份验证的完整CRUD
🐍 Python+Bash执行	在沙箱中安全运行内联代码、脚本和shell命令
📁 文件管理	在隔离的工作区中读取、写入和列出文件
🔗 沙箱桥	将存储数据导出为JSON/NDJSON，直接导入沙盒进行分析
📊 数据科学就绪	预装pandas、numpy、matplotlib、seaborn、scikit-learn
🏗️ 干净的体系结构（.NET）	域名→ 应用→ 基础设施→ 主机分层设计
✅ 综合测试	Python单元/集成测试+。NET xUnit测试与Moq

🏗️ 系统架构

高级概述

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

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

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

    subgraph EXT["🌐 External"]
        API["Platzi Fake Store API<br/>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代码执行

工具	说明
`execute_python`	在沙盒容器内执行内联Python代码
`execute_python_file`	执行现有 `.py` 工作区中的文件

`sandbox-bash` --Bash命令执行

工具	说明
`execute_bash`	在沙盒容器中执行bash命令

`sandbox-file` --文件系统操作

工具	说明
`read_file`	从沙盒工作区读取文件内容
`write_file`	将文本内容写入文件，创建父目录
`list_files`	列出目录内容和文件大小

.NET平台存储服务器

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

工具组	工具	说明
目录浏览	`list_store_products`, `get_product_by_id`, `get_product_by_slug`, `find_related_products`, `find_related_by_slug`, `filter_store_products`	浏览、搜索和筛选产品
目录管理	`create_store_product`, `update_store_product`, `remove_store_product`	产品的CRUD操作
类别浏览	`list_store_categories`, `get_category_by_id`, `get_category_by_slug`, `list_products_in_category`	浏览产品类别
品类管理	`create_store_category`, `update_store_category`, `remove_store_category`	类别的CRUD操作
客户账户	`list_store_customers`, `get_customer_by_id`, `register_customer`, `update_customer_profile`, `check_email_availability`	客户管理
身份和访问	`authenticate_customer`, `get_authenticated_profile`, `refresh_access_token`	身份验证和授权
沙箱桥	`analyze_store_data`, `process_store_export`	导出存储数据（JSON/NDJSON）以进行沙盒分析

🐳 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

安全控制

控制	配置
网络	`none` --完全气隙
记忆	`512 MB` 限制
中央处理器	`0.5` 岩芯
乘客信息显示系统	Max `64` 过程
文件系统	只读root+ `/tmp` tmpfs （64 MB）
用户	非根 `sandbox` 用户（UID 1000）
工作区	`/workspace` 安装自 `workspaces/default/`

命令阻止列表

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

破坏性模式 — 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<br/>MCP Server Bootstrap"]
        TOOLS["Tools/<br/>7 Tool Classes"]
        FMT["Formatting/<br/>Response Formatter"]
        ADAPT["Adapters/<br/>Gateway Adapter"]
    end

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

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

    subgraph Domain["Domain Layer"]
        ENT["Entities/<br/>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

层	项目	责任
领域	`PlatziStore.Domain`	实体(`Merchandise`, `ProductGroup`, `StoreCustomer`)、值对象、域异常
应用	`PlatziStore.Application`	服务合同、CQRS处理程序、DTO、实体DTO映射
基础设施	`PlatziStore.Infrastructure`	Platzi API的HTTP客户端，重试/超时配置，结构化事件日志
主机	`PlatziStore.Host`	MCP服务器引导、工具定义、响应格式、网关适配器
共享	`PlatziStore.Shared`	跨领域模型、实用程序和共享异常类型

运作原理

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

呼叫 analyze_store_data(dataScope="products")
呼叫 write_file(path="products.json", content=<data>)
呼叫 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/

🛠️ 使用的技术

类别	技术
语言	Python 3.10+·C#/。净值9
协议	模型上下文协议（MCP）·JSON-RPC·stdio传输
容器化	Docker·Python版Docker SDK
Python 库	FastMCP·pandas·numpy·matplotlib·seaborn·scikit-learn·openpyxl
Web框架	ASP。NET（DI+托管服务）
测试	pytest · pytest-asyncio · xUnit · Moq
建筑	清洁架构·CQRS·依赖注入·适配器模式
可观测性	结构化事件记录·遥测配置
发展	Hatching（Python构建）
AI代理	克劳德桌面·光标IDE

🤝 贡献

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

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

开发指南

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

📄 许可证

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

MIT License · Copyright (c) 2026 Ahmed Raed

使用说明

🧰 沙盒MCP工具

📋 目录

🌐 项目概述

✨ 主要特点

🏗️ 系统架构

高级概述

通信流

📂 存储库结构

🔌 MCP服务器

Python沙盒服务器

sandbox-python --Python代码执行

sandbox-bash --Bash命令执行

sandbox-file --文件系统操作

.NET平台存储服务器

🐳 Python沙盒

建筑

安全控制

命令阻止列表

预装库

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

架构层

运作原理

🔗 工具编排

多服务器工作流

沙箱桥

💡 AI工作流示例

1.产品价格分析

2.类别库存报告

3.客户数据导出

4.价格过滤与分析

🚀 安装

先决条件

1.克隆存储库

2.Python设置

3.构建沙盒Docker镜像

4.NET安装程序

▶️ 正在运行MCP服务器

Python沙盒服务器

.NET平台存储服务器

光标IDE配置

🧪 运行测试

Python测试

.NET测试

🛠️ 使用的技术

🤝 贡献

开发指南

📄 许可证

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器

`sandbox-python` --Python代码执行

`sandbox-bash` --Bash命令执行

`sandbox-file` --文件系统操作