Contenedor-MCP

Una implementación segura basada en contenedores del Protocolo de Contexto de Modelo (MCP) para ejecutar herramientas en nombre de modelos de lenguaje grandes.

Descripción general

Container-MCP proporciona un entorno aislado para ejecutar código, ejecutar comandos, acceder a archivos y realizar operaciones web solicitadas por grandes modelos de lenguaje de forma segura. Implementa el protocolo MCP para exponer estas capacidades como herramientas que los sistemas de IA pueden descubrir e invocar de forma segura.

La arquitectura utiliza un patrón de administrador específico de dominio con seguridad de múltiples capas para garantizar que las herramientas se ejecuten en entornos aislados con restricciones adecuadas, protegiendo al sistema host de operaciones potencialmente dañinas.

Características principales

Seguridad multicapa
- Aislamiento de contenedores mediante Podman/Docker
- Perfiles de AppArmor para restringir el acceso
- Sandbox de Firejail para un aislamiento adicional
- Límites de recursos (CPU, memoria, tiempo de ejecución)
- Prevención de recorrido de ruta
- Restricciones de extensión permitidas
Implementación del protocolo MCP
- Descubrimiento y ejecución de herramientas estandarizadas
- Gestión de recursos
- Compatibilidad con ejecución asincrónica
Administradores específicos del dominio
- BashManager : Ejecución segura de comandos
- PythonManager : Ejecución de código Python en un entorno aislado
- FileManager : Operaciones seguras con archivos
- WebManager : Navegación web segura y scraping
Entorno configurable
- Amplia configuración mediante variables de entorno
- Soporte para entornos personalizados
- Modos de desarrollo y producción

Herramientas disponibles

Operaciones del sistema

`system_run_command`

Ejecuta comandos bash en un entorno sandbox seguro.

Parámetros :
- command (cadena, obligatorio): el comando bash a ejecutar
- working_dir (cadena, opcional): Directorio de trabajo (ignorado en el entorno limitado)
Devoluciones :
- stdout (cadena): Salida estándar del comando
- stderr (cadena): Error estándar del comando
- exit_code (entero): código de salida del comando
- success (booleano): si el comando se completó correctamente

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

`system_run_python`

Ejecuta código Python en un entorno sandbox seguro.

Parámetros :
- code (cadena, obligatorio): código Python a ejecutar
- working_dir (cadena, opcional): Directorio de trabajo (ignorado en el entorno limitado)
Devoluciones :
- output (cadena): imprime la salida del código
- error (cadena): Salida de error del código
- result (cualquiera): valor de retorno opcional (disponible si el código establece la variable _ )
- success (booleano): si el código se ejecutó correctamente

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

`system_env_var`

Obtiene valores de variables de entorno.

Parámetros :
- var_name (cadena, opcional): variable específica para recuperar
Devoluciones :
- variables (objeto): Diccionario de variables de entorno
- requested_var (string): Valor de la variable solicitada (si se proporciona var_name)

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

Operaciones con archivos

`file_read`

Lee el contenido del archivo de forma segura.

Parámetros :
- path (cadena, obligatoria): ruta al archivo (relativa a la raíz del espacio aislado)
- encoding (cadena, opcional): codificación de archivo (predeterminado: "utf-8")
Devoluciones :
- content (cadena): contenido del archivo
- size (entero): tamaño del archivo en bytes
- modified (flotante): marca de tiempo de la última modificación
- success (booleano): si la lectura fue exitosa

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

`file_write`

Escribe contenido en un archivo de forma segura.

Parámetros :
- path (cadena, obligatoria): ruta al archivo (relativa a la raíz del espacio aislado)
- content (cadena, obligatorio): Contenido a escribir
- encoding (cadena, opcional): codificación de archivo (predeterminado: "utf-8")
Devoluciones :
- success (booleano): si la escritura fue exitosa
- path (cadena): Ruta al archivo escrito

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

`file_list`

Enumera el contenido de un directorio de forma segura.

Parámetros :
- path (cadena, opcional): Ruta al directorio (predeterminado: "/")
- pattern (cadena, opcional): Patrón global para filtrar archivos
Devoluciones :
- entries (matriz): Lista de entradas de directorio con metadatos
- path (cadena): La ruta del directorio indicado
- success (booleano): si el listado fue exitoso

{
  "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`

Elimina un archivo de forma segura.

Parámetros :
- path (cadena, obligatoria): Ruta del archivo a eliminar
Devoluciones :
- success (booleano): si la eliminación fue exitosa
- path (cadena): Ruta al archivo eliminado

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

`file_move`

Mueve o renombra un archivo de forma segura.

Parámetros :
- source (cadena, obligatoria): ruta del archivo de origen
- destination (cadena, obligatoria): Ruta del archivo de destino
Devoluciones :
- success (booleano): si el movimiento fue exitoso
- source (cadena): ruta del archivo original
- destination (cadena): Nueva ruta de archivo

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

Operaciones web

`web_search`

Utiliza un motor de búsqueda para encontrar información en la web.

Parámetros :
- query (cadena, obligatoria): La consulta a buscar
Devoluciones :
- results (matriz): Lista de resultados de búsqueda
- query (cadena): La consulta original

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

`web_scrape`

Rastrea una URL específica y devuelve el contenido.

Parámetros :
- url (cadena, obligatoria): la URL a raspar
- selector (cadena, opcional): selector CSS para seleccionar contenido específico
Devoluciones :
- content (cadena): contenido extraído
- url (cadena): La URL que se extrajo
- title (cadena): Título de la página
- success (booleano): si el raspado fue exitoso
- error (cadena): Mensaje de error si el raspado falló

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

`web_browse`

Navega interactivamente por un sitio web utilizando Playwright.

Parámetros :
- url (cadena, obligatoria): URL de inicio para la sesión de navegación
Devoluciones :
- content (cadena): contenido HTML de la página
- url (cadena): La URL final después de cualquier redirección
- title (cadena): Título de la página
- success (booleano): si la navegación fue exitosa
- error (cadena): Mensaje de error si la navegación falló

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

Entorno de ejecución

Container-MCP proporciona entornos de ejecución aislados para diferentes tipos de operaciones, cada uno con sus propias medidas de seguridad y limitaciones de recursos.

Entorno de contenedores

El servicio principal Container-MCP se ejecuta dentro de un contenedor (usando Podman o Docker) y proporciona la primera capa de aislamiento:

Imagen base : Ubuntu 24.04
Usuario : Usuario de Ubuntu no root
Python : 3.12
Red : limitada únicamente al enlace del host local
Sistema de archivos : montajes de volúmenes para configuración, datos y registros
Seguridad : AppArmor, Seccomp y restricciones de capacidad

Entorno de ejecución de Bash

El entorno de ejecución de Bash está configurado con múltiples capas de aislamiento:

Comandos permitidos : restringido a comandos seguros configurados en BASH_ALLOWED_COMMANDS
Firejail Sandbox : aislamiento de procesos con acceso restringido al sistema de archivos
Perfil de AppArmor : Control de acceso de grano fino
Límites de recursos :
- Tiempo de espera de ejecución (predeterminado: 30 s, máximo: 120 s)
- Acceso limitado al directorio solo en la zona protegida
Red : Sin acceso a la red
Sistema de archivos : acceso de solo lectura a los datos, lectura y escritura en la zona protegida

Ejemplo de comandos permitidos:

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

Entorno de ejecución de Python

El entorno de ejecución de Python está diseñado para la ejecución segura de código:

Versión de Python : 3.12
Límite de memoria : límite de memoria configurable (predeterminado: 256 MB)
Tiempo de espera de ejecución : límite de tiempo configurable (predeterminado: 30 s, máximo: 120 s)
Perfil de AppArmor : restringe el acceso a los recursos del sistema
Firejail Sandbox : Aislamiento de procesos
Capacidades : Se eliminaron todas las capacidades
Red : Sin acceso a la red
Bibliotecas disponibles : Solo biblioteca estándar
Captura de salida : stdout/stderr redirigido y desinfectado
Controles de recursos : se aplican límites de CPU y memoria

Entorno del sistema de archivos

El entorno del sistema de archivos controla el acceso a los archivos dentro del entorno protegido:

Directorio base : todas las operaciones están restringidas a la raíz del espacio aislado
Validación de ruta : todas las rutas se normalizan y se verifican para detectar intentos de recorrido.
Límites de tamaño : se aplica el tamaño máximo de archivo (predeterminado: 10 MB)
Control de extensiones : solo se permiten las extensiones permitidas (predeterminadas: txt, md, csv, json, py)
Control de permisos : se aplican los permisos de lectura y escritura adecuados
Aislamiento : Sin acceso al sistema de archivos del host

Entorno web

El entorno web proporciona acceso controlado a recursos externos:

Control de dominio : Lista blanca opcional de dominios permitidos
Control de tiempo de espera : tiempos de espera configurables para operaciones
Control del navegador : navegador sin interfaz gráfica a través de Playwright para una representación completa
Control de raspado : raspado simple mediante solicitudes/BeautifulSoup
Saneamiento de contenido : todo el contenido analizado y desinfectado
Aislamiento de red : espacio de nombres de red separado mediante contenedor

Arquitectura

El proyecto sigue una arquitectura modular:

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

Cada gestor sigue patrones de diseño consistentes:

Método de clase .from_env() para la inicialización basada en el entorno
Métodos de ejecución asincrónica para operaciones sin bloqueo
Fuerte validación de entrada y manejo de errores
Un enfoque que prioriza la seguridad en todas las operaciones

Medidas de seguridad

Container-MCP implementa múltiples capas de seguridad:

Aislamiento de contenedores : utiliza Podman/Docker para el aislamiento de contenedores
Perfiles de AppArmor : control de acceso detallado para la ejecución de bash y Python
Firejail Sandboxing : aislamiento de procesos adicional
Límites de recursos : límites de memoria, CPU y tiempo de ejecución
Prevención de recorrido de ruta : valida y normaliza todas las rutas de archivos
Restricciones de extensión permitidas : controla a qué tipos de archivos se puede acceder
Restricciones de red : controla a qué dominios se puede acceder
Mínimo privilegio : los componentes se ejecutan con los permisos mínimos necesarios

Instalación

Prerrequisitos

Sistema Linux con Podman o Docker
Python 3.12+
Firejail ( apt install firejail o dnf install firejail )
AppArmor ( apt install apparmor apparmor-utils o dnf install apparmor apparmor-utils )

Inicio rápido

La forma más rápida de comenzar es utilizar el script todo en uno:

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

Instalación paso a paso

También puede realizar los pasos de instalación individualmente:

Inicializar el proyecto :
./bin/01-init.sh
Construir el contenedor :
./bin/02-build-container.sh
Configurar el entorno :
./bin/03-setup-environment.sh
Ejecutar el contenedor :
./bin/04-run-container.sh
Ejecutar pruebas (opcional):
./bin/05-run-tests.sh

Uso

Una vez que el contenedor esté en ejecución, puede conectarse a él mediante cualquier implementación de cliente MCP. El servidor estará disponible en http://localhost:8000 o en el puerto especificado en su configuración.

Importante: Al configurar su cliente MCP, debe establecer la URL del punto final en http://127.0.0.1:<port>/sse (donde <port> es 8000 por defecto o el puerto que haya configurado). La ruta /sse es necesaria para la correcta comunicación de los eventos enviados por el servidor.

Ejemplo de cliente 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())

Configuración

Container-MCP se puede configurar a través de variables de entorno, que se pueden establecer en volume/config/custom.env :

Configuración del servidor

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

Configuración del administrador de Bash

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

Configuración del administrador de Python

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

Configuración del administrador de archivos

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

Configuración del administrador web

# Web Manager Configuration
WEB_TIMEOUT_DEFAULT=30
WEB_ALLOWED_DOMAINS=*

Desarrollo

Configuración de un entorno de desarrollo

Crear un entorno virtual de Python:
python3.12 -m venv .venv source .venv/bin/activate
Instalar dependencias:
pip install -r requirements-dev.txt
Instalar el paquete en modo de desarrollo:
pip install -e .

Ejecución de pruebas

# 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

Servidor de desarrollo

Para ejecutar el servidor MCP en modo de desarrollo:

python -m cmcp.main --test-mode

Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0.

Autor

Martín Bukowski

Integrations