isolator-mcp

Isolator MCP Server

isolator-mcp is a Model Context Protocol (MCP) server written in TypeScript. It acts as a wrapper around the embedded isolator Go CLI tool, providing a secure code execution sandbox accessible via MCP.

LLM applications (MCP Hosts) can connect to this server and use its execute_code tool to safely run Python, Go, or JavaScript code snippets provided directly or loaded from predefined snippet files.

Features

• Provides the execute_code MCP tool.
• Supports executing code provided directly (language, entrypoint_code) or via named snippets (snippet_name).
• Supports multiple languages (Python, Go, JavaScript, configurable).
• Uses the embedded isolator Go CLI (isolator-cli/) for secure Docker container execution.
• Configurable security defaults (timeout, resource limits, network) via isolator_config.json.
• Manages temporary directories on the host for code execution.
• Handles file copying into containers (by instructing the isolator CLI).
• Returns structured results (stdout, stderr, status) via MCP, setting isError: true on tool-level failures.

Prerequisites

• Docker: Required for container creation and execution by the isolator-cli. Ensure the Docker daemon is running.
• Go: Required to build the embedded isolator-cli Go binary.
• Node.js and npm: Required to install dependencies, build, and run the isolator-mcp TypeScript server.

Installation

1. Build isolator Go CLI: Navigate to the embedded Go CLI directory and build the binary:

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

   This creates the ./isolator-cli/isolator executable needed by the server.
2. Configure isolator-mcp:
   • Edit isolator_config.json: Update isolatorPath to point to the absolute path of the built binary (e.g., /Users/ompragash/Documents/Cline/MCP/isolator-mcp/isolator-cli/isolator). Adjust default limits, container workdir, language images, or the promptsDir (used for snippets) location if needed.
   • Ensure the prompts directory exists (default: ./prompts). Add code snippet files (e.g., hello_world.py). The filename base (e.g., hello_world) is used as the snippet_name.
3. Install Server Dependencies: Navigate to the main directory (isolator-mcp) and run:

   npm install
   

4. Build Server: Compile the TypeScript code:

   npm run build
   

   This creates the executable script at build/index.js.
5. Configure MCP Host: Add the server to your MCP client's settings file (e.g., cline_mcp_settings.json for the VS Code extension):

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

   (Adjust the path in args if necessary). The MCP Host should automatically detect and start the server.

Important Note: Ensure the Docker images specified in isolator_config.json (e.g., python:3.11-alpine, golang:1.21-alpine) are pulled onto your system beforehand using docker pull <image_name>. The isolator tool does not automatically download missing images.

Local Development / Testing

To run the server locally for development or testing (without installing it via MCP Host settings):

1. Build Go CLI: Ensure the isolator Go CLI is built within its subdirectory:

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

2. Build TS Server: In this main directory (isolator-mcp), run npm install and npm run build.
3. Configure: Make sure isolator_config.json correctly points to the built ./isolator-cli/isolator binary via the isolatorPath key (use the absolute path).
4. Run Server: Execute the built server directly using Node:

   node build/index.js
   

   The server will start, connect via stdio, and print logs (including console.error messages from index.ts) to the console.
5. Interact (Manual): You can manually send JSON-RPC messages (e.g., tools/list, tools/call) to the server's standard input to test its responses. Tools like @modelcontextprotocol/inspector can also be helpful (npm run inspector).

(Remember to stop this manually run server before relying on the MCP Host to start it via the settings file.)

Architecture & Flow

1. MCP Host Request: An LLM asks the MCP Host (e.g., VS Code Extension) to call the isolator server's execute_code tool with arguments.
2. Server Processing (index.ts):
   • Receives the tools/call request via stdio.
   • Validates arguments using Zod.
   • Loads configuration from isolator_config.json.
   • Determines the code source:
     • If snippet_name is provided, reads the corresponding file from the configured promptsDir and determines the language from the file extension.
     • If entrypoint_code and language are provided, uses them directly.
   • Creates a temporary directory on the host.
   • Writes the entrypoint code and any additional_files into the temporary directory.
   • Constructs the command-line arguments for the embedded isolator Go CLI, including security flags from the config and the path to the temporary directory.
   • Spawns the isolator process using Node.js child_process.spawn.
3. Go CLI Execution (isolator-cli/isolator run):
   • Parses flags (including the new --env flag).
   • Creates a tar stream of the temporary directory contents.
   • Uses the Docker SDK to create a container with specified image, resource limits, environment variables (from --env), and security settings (NO bind mount).
   • Uses CopyToContainer to copy the tar stream into the container's working directory.
   • Starts the container, which executes the requested command (e.g., python /workspace/hello_world.py).
   • Waits for completion, captures stdout/stderr.
   • Removes the container.
   • Prints the result (status, output, etc.) as JSON to its stdout.
4. Server Result Handling (index.ts):
   • Reads the JSON output from the finished isolator process stdout.
   • Parses the JSON result.
   • Formats the CallToolResult for MCP, combining stdout/stderr and setting isError if the Go CLI reported a non-success status.
   • Sends the result back to the MCP Host.
   • Cleans up the temporary directory on the host.
5. MCP Host Response: Relays the result back to the LLM, which then formulates a response for the user.

execute_code Tool

Description

Executes code (Python, Go, JavaScript) in a secure, isolated container environment.

Input Schema (arguments)

• language (string, optional): The programming language (e.g., "python", "go", "javascript"). Required if snippet_name is not provided.
• entrypoint_code (string, optional): The main code content to execute. Required if snippet_name is not provided.
• entrypoint_filename (string, optional): Filename for the main code (e.g., "main.py", "script.js"). Defaults based on language if not provided.
• additional_files (array, optional): Array of objects, each with:
  • filename (string, required): Name of the additional file.
  • content (string, required): Content of the additional file.
• snippet_name (string, optional): Name of a pre-defined code snippet file (without extension) located in the configured promptsDir. Mutually exclusive with language and entrypoint_code.

Constraint: Either snippet_name OR both language and entrypoint_code must be provided.

Output (CallToolResult)

• content: An array containing a single TextContent object.
  • type: "text"
  • text: A string containing the combined stdout and stderr from the execution, formatted like:

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

    If an error occurred during execution (non-zero exit code, timeout), the text will be prepended with Execution Failed (status): [error message]\n\n.
• isError (boolean): true if the execution status reported by the isolator CLI was "error" or "timeout", false otherwise.

(Protocol-level errors, like invalid arguments or failure to start the process, will result in a standard MCP error response instead of a CallToolResult).