SandboxX MCP
README.md
# SandboxX MCP
MCP-сервер для запуска и тестирования кода в ограниченном Linux-контейнере. Поддерживает Streamable HTTP на endpoint `/mcp` и один инструмент `shell` с сохранением рабочей директории между вызовами.
## Возможности
- Фоновый запуск и повторное использование контейнера.
- Автоматический перезапуск контейнера после сбоя и остановка вместе с сервером.
- Таймауты команд, ограничение вывода, памяти, CPU и числа процессов.
- Непривилегированный пользователь, сброшенные Linux capabilities и `no-new-privileges`.
- Структурированный результат вызова и понятные ошибки Docker.
- Защита MCP от DNS rebinding и настраиваемые `Host`/`Origin` для LAN.
## Требования
- Python 3.11 или новее.
- Запущенный Docker Desktop или Docker daemon.
- [`uv`](https://docs.astral.sh/uv/) для рекомендуемого способа установки.
## Установка и запуск
Соберите образ песочницы:
```bash
docker build -t my-mcp-sandbox .
```
Установите зависимости:
```bash
uv sync
```
Запустите сервер:
```bash
uv run main.py
```
По умолчанию endpoint доступен только на локальной машине:
```text
http://127.0.0.1:7070/mcp
```
Также доступны консольная команда и явные параметры адреса:
```bash
uv run mcp-dev -H 127.0.0.1 -p 7071
# или
python main.py -H 127.0.0.1 -p 7071
```
Для установки без `uv`:
```bash
pip install -r requirements.txt
python main.py
```
Все параметры запуска:
```bash
uv run main.py --help
```
### Подключение MCP-клиента
```json
{
"mcpServers": {
"SandboxX": {
"url": "http://127.0.0.1:7070/mcp",
"startupTimeoutMs": 30000,
"toolTimeoutMs": 615000
}
}
}
```
Сначала запустите сервер через `uv run main.py`, затем создайте новую сессию Kimi Code. Проверить подключение можно командой `/mcp`. `toolTimeoutMs` должен покрывать максимальный таймаут команды и время принудительного завершения процессов.
### Запуск в локальной сети
Можно слушать конкретный LAN-адрес — он автоматически добавляется в разрешённые `Host`:
```bash
uv run main.py -H 192.168.31.27 -p 7070
```
При прослушивании всех интерфейсов укажите адрес, который клиенты будут передавать в `Host`:
```bash
uv run main.py \
-H 0.0.0.0 \
--allowed-host '192.168.31.27:*'
```
Для браузерного клиента с другого origin добавьте:
```bash
--allowed-origin 'http://192.168.31.27:8080'
```
Оба параметра можно повторять. Не публикуйте сервер в интернете без внешней аутентификации: аутентификация MCP-клиентов здесь не настроена.
## Инструмент `shell`
Выполняет команду через `sh -c` в `/workspace`. Файлы и установленные в окружение пакеты сохраняются между вызовами, пока работает сервер. После остановки сервера контейнер и его рабочая директория удаляются.
Аргументы:
- `command` — обязательная непустая shell-команда.
- `timeout` — необязательный таймаут в секундах, от 1 до 600. По умолчанию 30 секунд; для установки пакетов и сборок — 600.
Пример вызова:
```json
{
"command": "python --version && echo 'print(2 + 2)' > example.py && python example.py",
"timeout": 30
}
```
Результат:
```json
{
"exit_code": 0,
"output": "Python 3.x.x\n4\n",
"timed_out": false,
"truncated": false
}
```
`stdout` и `stderr` объединены. При таймауте возвращается `exit_code: 124` и `timed_out: true`; при ошибке запуска команды или Docker — `exit_code: -1`. Слишком длинный вывод обрезается, а `truncated` становится `true`.
## Инструмент `export`
Упаковывает файл или директорию из контейнера в `tar.gz` и возвращает архив как бинарный MCP-ресурс с MIME-типом `application/gzip`. Относительные пути разрешаются от `/workspace`.
Аргументы:
- `path` — путь к файлу или директории, по умолчанию `/workspace`.
- `timeout` — необязательный таймаут от 1 до 600 секунд, по умолчанию 120.
Пример вызова:
```json
{
"path": "/workspace",
"timeout": 120
}
```
Текстовая часть результата содержит имя и размер архива, а `structuredContent` — поля `archive_name`, `source`, `size_bytes` и `mime_type`. Само содержимое передаётся в `EmbeddedResource`, поэтому поддерживающий бинарные ресурсы клиент может сохранить его как `.tar.gz`. Максимальный размер сжатого архива — 50 МиБ. Архив создаётся от пользователя `sandbox` с соблюдением его прав доступа.
## Настройка через окружение
| Переменная | По умолчанию | Назначение |
|---|---:|---|
| `MCP_SANDBOX_IMAGE` | `my-mcp-sandbox` | Имя Docker-образа |
| `MCP_SANDBOX_USER` | `sandbox` | Пользователь внутри контейнера |
| `MCP_SANDBOX_TIMEOUT` | `30` | Обычный таймаут, секунды |
| `MCP_SANDBOX_LONG_TIMEOUT` | `600` | Таймаут сборок и установки пакетов, секунды |
| `MCP_SANDBOX_EXPORT_TIMEOUT` | `120` | Таймаут экспорта, секунды |
| `MCP_SANDBOX_MAX_TIMEOUT` | `600` | Максимально разрешённый таймаут, секунды |
| `MCP_SANDBOX_MAX_OUTPUT` | `12000` | Максимальное число символов вывода |
| `MCP_SANDBOX_MAX_ARCHIVE_SIZE` | `52428800` | Максимальный размер сжатого архива в байтах |
| `MCP_SANDBOX_MEMORY` | `1g` | Лимит памяти контейнера |
| `MCP_SANDBOX_CPUS` | `1` | Лимит CPU |
| `MCP_SANDBOX_PIDS_LIMIT` | `256` | Максимальное число процессов |
| `MCP_SANDBOX_DOCKER_TIMEOUT` | `15` | Таймаут обращения к Docker API, секунды |
## Образ песочницы
В Alpine-образ входят Python с виртуальным окружением, Node.js/npm, Go, Rust/Cargo, Git и компиляторы C/C++. Команды выполняются от пользователя `sandbox`; системные пакеты Alpine через `apk add` ему недоступны. Python-пакеты устанавливаются в преднастроенное окружение:
```bash
pip install requests
```
Контейнер изолирован на уровне Docker, но не является границей безопасности для враждебных multi-tenant нагрузок. Доступ к Docker socket хоста не предоставляется, `privileged`-режим отключён.
## Устранение неполадок
- **`Docker недоступен`** — запустите Docker Desktop/daemon и повторите вызов. Сам MCP-сервер при этом продолжает работать. На macOS стандартный socket `~/.docker/run/docker.sock` определяется автоматически; для другого адреса задайте стандартную переменную `DOCKER_HOST`.
- **`Образ 'my-mcp-sandbox' не найден`** — выполните `docker build -t my-mcp-sandbox .` из корня проекта.
- **HTTP 421** — добавьте используемый клиентом адрес через `--allowed-host`, а браузерный origin через `--allowed-origin`.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues