Servidor MCP aislador

isolator-mcp es un servidor de Protocolo de Contexto de Modelo (MCP) escrito en TypeScript. Actúa como un contenedor de la herramienta CLI de Go integrada, , y proporciona un entorno de ejecución de código seguro accesible a través de MCP.

Las aplicaciones LLM (hosts MCP) pueden conectarse a este servidor y usar su herramienta execute_code para ejecutar de forma segura fragmentos de código Python, Go o JavaScript proporcionados directamente o cargados desde archivos de fragmentos predefinidos.

Características

• Proporciona la herramienta MCP execute_code .

• Admite la ejecución de código proporcionado directamente ( language , entrypoint_code ) o mediante fragmentos con nombre ( snippet_name ).

• Admite varios idiomas (Python, Go, JavaScript, configurable).

• Utiliza el isolator integrado Go CLI ( isolator-cli/ ) para la ejecución segura del contenedor Docker.

• Valores predeterminados de seguridad configurables (tiempo de espera, límites de recursos, red) a través de isolator_config.json .

• Administra directorios temporales en el host para la ejecución de código.

• Maneja la copia de archivos en contenedores (mediante instrucciones a la CLI isolator ).

• Devuelve resultados estructurados (stdout, stderr, status) a través de MCP, estableciendo isError: true en caso de fallas a nivel de herramienta.

Prerrequisitos

• Docker: Necesario para la creación y ejecución de contenedores por parte de isolator-cli . Asegúrese de que el demonio de Docker esté en ejecución.

• Go: necesario para crear el binario Go isolator-cli integrado.

• Node.js y npm: necesarios para instalar dependencias, compilar y ejecutar el servidor TypeScript isolator-mcp .

Instalación

1. isolator navegue hasta el directorio Go CLI integrado y compile el binario:

   cd isolator-cli go build -o isolator main.go cd ..

   Esto crea el ejecutable ./isolator-cli/isolator que necesita el servidor.

2. Configurar

   • Editar isolator_config.json : Actualizar isolatorPath para que apunte a la ruta absoluta del binario compilado (p. ej., /Users/ompragash/Documents/Cline/MCP/isolator-mcp/isolator-cli/isolator ). Ajustar los límites predeterminados, el directorio de trabajo del contenedor, las imágenes de idioma o la ubicación de promptsDir (usado para fragmentos) si es necesario.

   • Asegúrese de que el directorio de prompts exista (predeterminado: ./prompts ). Agregue fragmentos de código (p. ej., hello_world.py ). El nombre de archivo base (p. ej., hello_world ) se utiliza como snippet_name .

3. Instalar dependencias del servidor: navegue al directorio principal ( isolator-mcp ) y ejecute:

   npm install

4. Servidor de compilación: compila el código TypeScript:

   npm run build

   Esto crea el script ejecutable en build/index.js .

5. Configurar el host MCP: agregue el servidor al archivo de configuración de su cliente MCP (por ejemplo, cline_mcp_settings.json para la extensión VS Code):

   { "mcpServers": { "isolator": { "command": "node", "args": ["/Users/ompragash/Documents/Cline/MCP/isolator-mcp/build/index.js"], "env": {}, "disabled": false, "autoApprove": [] } } }

   (Ajuste la ruta en . El host MCP debería detectar e iniciar el servidor automáticamente.

Nota importante: Asegúrese de que las imágenes de Docker especificadas en isolator_config.json (p. ej., python:3.11-alpine , golang:1.21-alpine ) se hayan descargado previamente en su sistema mediante docker pull <image_name> . La herramienta isolator no descarga automáticamente las imágenes faltantes.

Desarrollo local / Pruebas

Para ejecutar el servidor localmente para desarrollo o pruebas (sin instalarlo a través de la configuración del host de MCP):

1. Crear Go CLI: asegúrese de que el isolator Go CLI esté creado dentro de su subdirectorio:

   cd isolator-cli go build -o isolator main.go cd ..

2. Construir servidor TS: en este directorio principal ( isolator-mcp ), ejecute npm install y npm run build .

3. Configurar: asegúrese de que isolator_config.json apunte correctamente al binario ./isolator-cli/isolator compilado a través de la clave isolatorPath (use la ruta absoluta).

4. Ejecutar servidor: ejecute el servidor compilado directamente usando Node:

   node build/index.js

   El servidor se iniciará, se conectará a través de stdio e imprimirá registros (incluidos los mensajes console.error de index.ts ) en la consola.

5. Interacción (Manual): Puedes enviar manualmente mensajes JSON-RPC (p. ej., tools/list , tools/call ) a la entrada estándar del servidor para probar sus respuestas. Herramientas como @modelcontextprotocol/inspector también pueden ser útiles ( npm run inspector ).

(Recuerde detener este servidor que se ejecuta manualmente antes de confiar en el host MCP para iniciarlo a través del archivo de configuración).

Arquitectura y flujo

1. Solicitud de host MCP: un LLM solicita al host MCP (por ejemplo, extensión VS Code) que llame a la herramienta execute_code del servidor isolator con argumentos.

2. Procesamiento del servidor (

   • Recibe la solicitud tools/call a través de stdio.

   • Valida argumentos usando Zod.

   • Carga la configuración desde isolator_config.json .

   • Determina la fuente del código:

     • Si se proporciona snippet_name , lee el archivo correspondiente desde el promptsDir configurado y determina el idioma a partir de la extensión del archivo.

     • Si se proporcionan entrypoint_code y language , los utiliza directamente.

   • Crea un directorio temporal en el host.

   • Escribe el código del punto de entrada y cualquier additional_files en el directorio temporal.

   • Construye los argumentos de la línea de comandos para el isolator incorporado Go CLI, incluidos los indicadores de seguridad de la configuración y la ruta al directorio temporal.

   • Genera el proceso isolator usando Node.js child_process.spawn .

3. Ejecución de Go CLI (

   • Analiza los indicadores (incluido el nuevo indicador --env ).

   • Crea un flujo tar del contenido del directorio temporal.

   • Utiliza el SDK de Docker para crear un contenedor con una imagen especificada, límites de recursos, variables de entorno (desde --env ) y configuraciones de seguridad (SIN montaje de enlace).

   • Utiliza CopyToContainer para copiar el flujo tar en el directorio de trabajo del contenedor.

   • Inicia el contenedor, que ejecuta el comando solicitado (por ejemplo, python /workspace/hello_world.py ).

   • Espera la finalización, captura stdout/stderr.

   • Quita el contenedor.

   • Imprime el resultado (estado, salida, etc.) como JSON en su salida estándar.

4. Manejo de resultados del servidor (

   • Lee la salida JSON de la salida estándar del proceso isolator finalizado.

   • Analiza el resultado JSON.

   • Formatea CallToolResult para MCP, combinando stdout/stderr y configurando isError si la CLI de Go informó un estado de no éxito.

   • Envía el resultado de vuelta al host MCP.

   • Limpia el directorio temporal en el host.

5. Respuesta del host MCP: transmite el resultado al LLM, que luego formula una respuesta para el usuario.

Herramienta execute_code

Descripción

Ejecuta código (Python, Go, JavaScript) en un entorno de contenedor aislado y seguro.

Esquema de entrada ( arguments )

• language (cadena, opcional): El lenguaje de programación (p. ej., "Python", "Go", "JavaScript"). Obligatorio si no se proporciona snippet_name .

• entrypoint_code (cadena, opcional): El código principal que se ejecutará. Obligatorio si no se proporciona snippet_name .

• entrypoint_filename (cadena, opcional): Nombre del archivo del código principal (p. ej., "main.py", "script.js"). Si no se proporciona, el valor predeterminado se basa en el idioma.

• additional_files (matriz, opcional): matriz de objetos, cada uno con:

  • filename (cadena, obligatorio): Nombre del archivo adicional.

  • content (cadena, obligatorio): Contenido del archivo adicional.

• snippet_name (cadena, opcional): Nombre de un archivo de fragmento de código predefinido (sin extensión) ubicado en el promptsDir configurado. Se excluye mutuamente con language y entrypoint_code .

Restricción: se debe proporcionar snippet_name O bien language y entrypoint_code .

Salida ( CallToolResult )

• content : una matriz que contiene un único objeto TextContent .

  • type : "texto"

  • text : una cadena que contiene la salida estándar y la salida estándar combinadas de la ejecución, con el siguiente formato:

    --- stdout --- [Actual stdout output] --- stderr --- [Actual stderr output]

    Si se produjo un error durante la ejecución (código de salida distinto de cero, tiempo de espera), el texto se antepondrá con Execution Failed (status): [error message]\n\n .

• isError (booleano): true si el estado de ejecución informado por la CLI isolator fue "error" o "tiempo de espera", false en caso contrario.

(Los errores a nivel de protocolo, como argumentos no válidos o errores al iniciar el proceso, generarán una respuesta de error MCP estándar en lugar de un .