Skip to main content
Glama
SandboxX MCP

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`.