Isolator MCP Server

# Isolator MCP Server `isolator-mcp` is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server written in TypeScript. It acts as a wrapper around the embedded [`isolator` Go CLI tool](./isolator-cli), 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: ```bash 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: ```bash npm install ``` 4. **Build Server:** Compile the TypeScript code: ```bash 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): ```json { "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: ```bash 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: ```bash 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`)*.