Контейнер-MCP

Безопасная контейнерная реализация протокола контекста модели (MCP) для выполнения инструментов от имени больших языковых моделей.

Обзор

Container-MCP предоставляет изолированную среду для безопасного выполнения кода, запуска команд, доступа к файлам и выполнения веб-операций, запрашиваемых большими языковыми моделями. Он реализует протокол MCP для предоставления этих возможностей в качестве инструментов, которые могут быть обнаружены и вызваны системами ИИ безопасным образом.

Архитектура использует шаблон менеджера, специфичный для домена, с многоуровневой безопасностью, чтобы гарантировать выполнение инструментов в изолированных средах с соответствующими ограничениями, защищая хост-систему от потенциально вредоносных операций.

Related MCP server: Code Sandbox MCP Server

Основные характеристики

• Многоуровневая безопасность

  • Изоляция контейнеров с помощью Podman/Docker

  • Профили AppArmor для ограничения доступа

  • Песочница Firejail для дополнительной изоляции

  • Ограничения ресурсов (ЦП, память, время выполнения)

  • Предотвращение обхода пути

  • Разрешенные ограничения расширения

• Реализация протокола MCP

  • Стандартизированное обнаружение и выполнение инструментов

  • Управление ресурсами

  • Поддержка асинхронного выполнения

• Менеджеры доменов

  • BashManager : безопасное выполнение команд

  • PythonManager : изолированное выполнение кода Python

  • FileManager : Безопасные операции с файлами

  • WebManager : безопасный просмотр и сбор веб-страниц

• Настраиваемая среда

  • Расширенная настройка через переменные среды

  • Поддержка пользовательской среды

  • Методы разработки и производства

Доступные инструменты

Системные операции

system_run_command

Выполняет команды bash в безопасной среде-песочнице.

• Параметры :

  • command (строка, обязательно): команда bash для выполнения

  • working_dir (строка, необязательно): Рабочий каталог (игнорируется в песочнице)

• Возврат :

  • stdout (строка): стандартный вывод команды

  • stderr (строка): стандартная ошибка команды

  • exit_code (целое число): Код выхода команды

  • success (логическое значение): успешно ли выполнена команда

{
  "stdout": "file1.txt\nfile2.txt\n",
  "stderr": "",
  "exit_code": 0,
  "success": true
}

system_run_python

Выполняет код Python в безопасной среде-песочнице.

• Параметры :

  • code (строка, обязательно): код Python для выполнения

  • working_dir (строка, необязательно): Рабочий каталог (игнорируется в песочнице)

• Возврат :

  • output (строка): Распечатать вывод из кода

  • error (строка): Ошибка вывода кода

  • result (любой): Необязательное возвращаемое значение (доступно, если код задает переменную _ )

  • success (логическое значение): успешно ли выполнен код

{
  "output": "Hello, world!\n",
  "error": "",
  "result": 42,
  "success": true
}

system_env_var

Получает значения переменных среды.

• Параметры :

  • var_name (строка, необязательно): Конкретная переменная для извлечения

• Возврат :

  • variables (объект): Словарь переменных окружения

  • requested_var (string): Значение запрошенной переменной (если указано var_name)

{
  "variables": {
    "MCP_PORT": "8000",
    "SANDBOX_ROOT": "/app/sandbox"
  },
  "requested_var": "8000"
}

Операции с файлами

file_read

Безопасное чтение содержимого файла.

• Параметры :

  • path (строка, обязательно): Путь к файлу (относительно корня песочницы)

  • encoding (строка, необязательно): Кодировка файла (по умолчанию: «utf-8»)

• Возврат :

  • content (строка): Содержимое файла

  • size (целое число): размер файла в байтах

  • modified (плавающее): отметка времени последнего изменения

  • success (логическое значение): было ли чтение успешным

{
  "content": "This is the content of the file.",
  "size": 31,
  "modified": 1673452800.0,
  "success": true
}

file_write

Безопасно записывает содержимое в файл.

• Параметры :

  • path (строка, обязательно): Путь к файлу (относительно корня песочницы)

  • content (строка, обязательно): Содержимое для записи

  • encoding (строка, необязательно): Кодировка файла (по умолчанию: «utf-8»)

• Возврат :

  • success (логическое значение): была ли запись успешной

  • path (строка): Путь к записанному файлу

{
  "success": true,
  "path": "data/myfile.txt"
}

file_list

Безопасно выводит список содержимого каталога.

• Параметры :

  • path (строка, необязательно): Путь к каталогу (по умолчанию: "/")

  • pattern (строка, необязательно): шаблон для фильтрации файлов

• Возврат :

  • entries (массив): Список записей каталога с метаданными

  • path (строка): указанный путь к каталогу

  • success (логическое значение): был ли листинг успешным

{
  "entries": [
    {
      "name": "file1.txt",
      "path": "file1.txt",
      "is_directory": false,
      "size": 1024,
      "modified": 1673452800.0
    },
    {
      "name": "data",
      "path": "data",
      "is_directory": true,
      "size": null,
      "modified": 1673452500.0
    }
  ],
  "path": "/",
  "success": true
}

file_delete

Безопасное удаление файла.

• Параметры :

  • path (строка, обязательно): Путь к файлу для удаления.

• Возврат :

  • success (логическое значение): было ли удаление успешным

  • path (строка): Путь к удаленному файлу

{
  "success": true,
  "path": "temp/old_file.txt"
}

file_move

Безопасное перемещение или переименование файла.

• Параметры :

  • source (строка, обязательно): Путь к исходному файлу

  • destination (строка, обязательно): Путь к файлу назначения

• Возврат :

  • success (логическое значение): был ли ход успешным

  • source (строка): Исходный путь к файлу

  • destination (строка): Новый путь к файлу

{
  "success": true,
  "source": "data/old_name.txt",
  "destination": "data/new_name.txt"
}

Веб-операции

web_search

Использует поисковую систему для поиска информации в Интернете.

• Параметры :

  • query (строка, обязательно): Запрос для поиска

• Возврат :

  • results (массив): Список результатов поиска

  • query (строка): Исходный запрос

{
  "results": [
    {
      "title": "Search Result Title",
      "url": "https://example.com/page1",
      "snippet": "Text snippet from the search result..."
    }
  ],
  "query": "example search query"
}

web_scrape

Извлекает определенный URL-адрес и возвращает его содержимое.

• Параметры :

  • url (строка, обязательно): URL для считывания

  • selector (строка, необязательно): селектор CSS для выбора определенного контента

• Возврат :

  • content (строка): Извлеченное содержимое

  • url (строка): URL-адрес, который был скопирован

  • title (строка): Заголовок страницы

  • success (логическое значение): Был ли скрейп успешным

  • error (строка): Сообщение об ошибке, если очистка не удалась

{
  "content": "This is the content of the web page...",
  "url": "https://example.com/page",
  "title": "Example Page",
  "success": true,
  "error": null
}

web_browse

Интерактивный просмотр веб-сайта с помощью Playwright.

• Параметры :

  • url (строка, обязательно): Начальный URL для сеанса просмотра

• Возврат :

  • content (строка): HTML-содержимое страницы

  • url (строка): конечный URL после всех перенаправлений

  • title (строка): Заголовок страницы

  • success (логическое значение): был ли просмотр успешным

  • error (строка): Сообщение об ошибке, если просмотр не удался

{
  "content": "<!DOCTYPE html><html>...</html>",
  "url": "https://example.com/after_redirect",
  "title": "Example Page",
  "success": true,
  "error": null
}

Среда исполнения

Container-MCP предоставляет изолированные среды выполнения для различных типов операций, каждая из которых имеет свои собственные меры безопасности и ограничения ресурсов.

Контейнерная среда

Основная служба Container-MCP работает внутри контейнера (с использованием Podman или Docker), обеспечивая первый уровень изоляции:

• Базовый образ : Ubuntu 24.04

• Пользователь : Пользователь Ubuntu без полномочий root

• Питон : 3.12

• Сеть : Ограничено только привязкой к локальному хосту

• Файловая система : монтирование томов для конфигурации, данных и журналов

• Безопасность : AppArmor, Seccomp и ограничения возможностей

Среда выполнения Bash

Среда исполнения Bash настроена с несколькими уровнями изоляции:

• Разрешенные команды : Ограничено безопасными командами, настроенными в BASH_ALLOWED_COMMANDS

• Firejail Sandbox : изоляция процесса с ограниченным доступом к файловой системе

• Профиль AppArmor : Детальный контроль доступа

• Ограничения ресурсов :

  • Тайм-аут выполнения (по умолчанию: 30 с, макс.: 120 с)

  • Ограниченный доступ к каталогу только для песочницы

• Сеть : Нет доступа к сети

• Файловая система : доступ только для чтения к данным, чтение и запись в песочнице

Примеры разрешенных команд:

ls, cat, grep, find, echo, pwd, mkdir, touch

Среда выполнения Python

Среда исполнения Python предназначена для безопасного выполнения кода:

• Версия Python : 3.12

• Ограничение памяти : настраиваемый предел памяти (по умолчанию: 256 МБ)

• Время ожидания выполнения : настраиваемый лимит времени (по умолчанию: 30 с, макс.: 120 с)

• Профиль AppArmor : Ограничивает доступ к системным ресурсам

• Firejail Sandbox : изоляция процесса

• Возможности : Все возможности удалены

• Сеть : Нет доступа к сети

• Доступные библиотеки : Только стандартная библиотека

• Захват выходных данных : stdout/stderr перенаправляется и очищается

• Контроль ресурсов : применяются ограничения ЦП и памяти

Среда файловой системы

Среда файловой системы управляет доступом к файлам внутри песочницы:

• Базовый каталог : все операции ограничены корнем песочницы

• Проверка пути : все пути нормализованы и проверены на наличие попыток обхода.

• Ограничения по размеру : максимальный размер файла ограничен (по умолчанию: 10 МБ)

• Управление расширениями : разрешены только разрешенные расширения (по умолчанию: txt, md, csv, json, py)

• Контроль разрешений : применяются соответствующие разрешения на чтение/запись.

• Изоляция : нет доступа к файловой системе хоста

Веб-среда

Веб-среда обеспечивает контролируемый доступ к внешним ресурсам:

• Управление доменами : необязательное внесение в белый список разрешенных доменов

• Управление тайм-аутами : настраиваемые тайм-ауты для операций

• Управление браузером : Headless-браузер через Playwright для полного рендеринга

• Управление скрейпингом : Простой скрейпинг через запросы/BeautifulSoup

• Очистка контента : весь контент анализируется и очищается.

• Сетевая изоляция : отдельное сетевое пространство имен с помощью контейнера

Архитектура

Проект имеет модульную архитектуру:

container-mcp/
├── cmcp/                     # Main application code
│   ├── managers/             # Domain-specific managers
│   │   ├── bash_manager.py   # Secure bash execution
│   │   ├── python_manager.py # Secure python execution
│   │   ├── file_manager.py   # Secure file operations
│   │   └── web_manager.py    # Secure web operations
│   ├── utils/                # Utility functions
│   ├── config.py             # Configuration system
│   └── main.py               # MCP server setup
├── apparmor/                 # AppArmor profiles
├── config/                   # Configuration files
├── bin/                      # Build/run scripts
├── data/                     # Data directory
├── logs/                     # Log directory
├── sandbox/                  # Sandboxed execution space
│   ├── bash/                 # Bash sandbox
│   ├── python/               # Python sandbox
│   ├── files/                # File operation sandbox
│   └── browser/              # Web browser sandbox
├── temp/                     # Temporary storage
└── tests/                    # Test suites

Каждый менеджер следует последовательным шаблонам проектирования:

• Метод класса .from_env() для инициализации на основе среды

• Методы асинхронного выполнения для неблокирующих операций

• Строгая проверка входных данных и обработка ошибок

• Подход ко всем операциям, ориентированный на безопасность

Меры безопасности

Container-MCP реализует несколько уровней безопасности:

1. Изоляция контейнера : использует Podman/Docker для изоляции контейнера.

2. Профили AppArmor : детальный контроль доступа для выполнения bash и Python

3. Firejail Sandboxing : дополнительная изоляция процесса

4. Ограничения ресурсов : память, процессор и время выполнения.

5. Предотвращение обхода пути : проверяет и нормализует все пути к файлам.

6. Ограничения разрешенных расширений : контролирует, к каким типам файлов можно получить доступ.

7. Ограничения сети : контролирует, к каким доменам разрешен доступ.

8. Наименьшие привилегии : компоненты запускаются с минимальными необходимыми разрешениями.

Установка

Предпосылки

• Система Linux с Podman или Docker

• Питон 3.12+

• Firejail ( apt install firejail или dnf install firejail )

• AppArmor ( apt install apparmor apparmor-utils или dnf install apparmor apparmor-utils )

Быстрый старт

Самый быстрый способ начать работу — использовать универсальный скрипт:

git clone https://github.com/54rt1n/container-mcp.git
cd container-mcp
chmod +x bin/00-all-in-one.sh
./bin/00-all-in-one.sh

Пошаговая установка

Вы также можете выполнить шаги установки по отдельности:

1. Инициализируйте проект :

   ./bin/01-init.sh

2. Постройте контейнер :

   ./bin/02-build-container.sh

3. Настройте среду :

   ./bin/03-setup-environment.sh

4. Запустите контейнер :

   ./bin/04-run-container.sh

5. Запустите тесты (необязательно):

   ./bin/05-run-tests.sh

Использование

После запуска контейнера вы можете подключиться к нему с помощью любой реализации клиента MCP. Сервер будет доступен по адресу http://localhost:8000 или по порту, указанному в вашей конфигурации.

Важно: при настройке клиента MCP необходимо задать URL конечной точки на http://127.0.0.1:<port>/sse (где <port> — это 8000 по умолчанию или настроенный вами порт). Путь /sse необходим для правильной связи событий, отправленных сервером.

Пример клиента Python

from mcp.client.sse import sse_client
from mcp import ClientSession
import asyncio

async def main():
    # Connect to the Container-MCP server
    # Note the /sse endpoint suffix required for SSE communication
    sse_url = "http://127.0.0.1:8000/sse"  # Or your configured port
    
    # Connect to the SSE endpoint
    async with sse_client(sse_url) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize the connection
            await session.initialize()
            
            # Discover available tools
            result = await session.list_tools()
            print(f"Available tools: {[tool.name for tool in result.tools]}")
            
            # Execute a Python script
            python_result = await session.execute_tool(
                "system_run_python",
                {"code": "print('Hello, world!')\nresult = 42\n_ = result"}
            )
            print(f"Python result: {python_result}")
            
            # Execute a bash command
            bash_result = await session.execute_tool(
                "system_run_command",
                {"command": "ls -la"}
            )
            print(f"Command output: {bash_result['stdout']}")

if __name__ == "__main__":
    asyncio.run(main())

Конфигурация

Container-MCP можно настроить с помощью переменных среды, которые можно задать в volume/config/custom.env :

Конфигурация сервера

# MCP Server Configuration
MCP_HOST=127.0.0.1
MCP_PORT=9001
DEBUG=true
LOG_LEVEL=INFO

Конфигурация Bash Manager

# Bash Manager Configuration
BASH_ALLOWED_COMMANDS=ls,cat,grep,find,echo,pwd,mkdir,touch
BASH_TIMEOUT_DEFAULT=30
BASH_TIMEOUT_MAX=120

Конфигурация менеджера Python

# Python Manager Configuration
PYTHON_MEMORY_LIMIT=256
PYTHON_TIMEOUT_DEFAULT=30
PYTHON_TIMEOUT_MAX=120

Конфигурация файлового менеджера

# File Manager Configuration 
FILE_MAX_SIZE_MB=10
FILE_ALLOWED_EXTENSIONS=txt,md,csv,json,py

Конфигурация веб-менеджера

# Web Manager Configuration
WEB_TIMEOUT_DEFAULT=30
WEB_ALLOWED_DOMAINS=*

Разработка

Настройка среды разработки

1. Создайте виртуальную среду Python:

   python3.12 -m venv .venv
   source .venv/bin/activate

2. Установите зависимости:

   pip install -r requirements-dev.txt

3. Установите пакет в режиме разработки:

   pip install -e .

Проведение тестов

# Run all tests
pytest

# Run only unit tests
pytest tests/unit

# Run only integration tests
pytest tests/integration

# Run with coverage report
pytest --cov=cmcp --cov-report=term --cov-report=html

Сервер разработки

Чтобы запустить сервер MCP в режиме разработки:

python -m cmcp.main --test-mode

Лицензия

Данный проект лицензирован по лицензии Apache License 2.0.

Автор

Мартин Буковски