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, isolator , 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 de compilación Go CLI: 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 isolator-mcp :
   • 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 args si es necesario) . 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 ( index.ts ):
   • 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 ( isolator-cli/isolator run ):
   • 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 ( index.ts ):
   • 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 CallToolResult ) .