隔离器 MCP 服务器

isolator-mcp是一个用 TypeScript 编写的模型上下文协议 (MCP)服务器。它作为嵌入式isolator包装器，提供了一个可通过 MCP 访问的安全代码执行沙盒。

LLM 应用程序（MCP 主机）可以连接到此服务器并使用其execute_code工具安全地运行直接提供或从预定义的代码片段文件加载的 Python、Go 或 JavaScript 代码片段。

特征

• 提供execute_code MCP工具。

• 支持直接执行提供的代码（ language 、 entrypoint_code ）或通过命名片段（ snippet_name ）执行。

• 支持多种语言（Python、Go、JavaScript、可配置）。

• 使用嵌入式isolator Go CLI（ isolator-cli/ ）来安全地执行 Docker 容器。

• 通过isolator_config.json配置安全默认值（超时、资源限制、网络）。

• 管理主机上用于代码执行的临时目录。

• 处理文件复制到容器中（通过指示isolator CLI）。

• 通过 MCP 返回结构化结果（stdout、stderr、status），在工具级故障时设置isError: true 。

Related MCP server: Hello World MCP Server

先决条件

• Docker： isolator-cli创建和执行容器所必需的。确保 Docker 守护进程正在运行。

• **Go：**构建嵌入式isolator-cli Go 二进制文件所需。

• **Node.js 和 npm：**需要安装依赖项、构建和运行isolator-mcp TypeScript 服务器。

安装

1. **构建isolator Go CLI：**导航到嵌入式 Go CLI 目录并构建二进制文件：

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

   这将创建服务器所需的./isolator-cli/isolator可执行文件。

2. 配置

   • 编辑isolator_config.json ：更新isolatorPath以指向构建二进制文件的绝对路径（例如， /Users/ompragash/Documents/Cline/MCP/isolator-mcp/isolator-cli/isolator ）。 如有需要，调整默认限制、容器工作目录、语言镜像或promptsDir （用于代码片段）的位置。

   • 确保prompts目录存在（默认值： ./prompts ）。添加代码片段文件（例如， hello_world.py ）。文件名基数（例如， hello_world ）将用作snippet_name 。

3. **安装服务器依赖项：**导航到主目录（ isolator-mcp ）并运行：

   npm install

4. **构建服务器：**编译 TypeScript 代码：

   npm run build

   这会在build/index.js创建可执行脚本。

5. **配置 MCP 主机：**将服务器添加到 MCP 客户端的设置文件（例如，VS Code 扩展的cline_mcp_settings.json ）：

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

   （如有必要，请调整 。MCP 主机应自动检测并启动服务器。

**重要提示：**请确保已使用docker pull <image_name>将isolator_config.json中指定的 Docker 镜像（例如python:3.11-alpine 、 golang:1.21-alpine ）预先拉取到您的系统中。isolator isolator不会自动下载缺失的镜像。

本地开发/测试

要在本地运行服务器以进行开发或测试（无需通过 MCP Host 设置进行安装）：

1. **构建 Go CLI：**确保isolator Go CLI 在其子目录中构建：

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

2. **构建 TS 服务器：**在此主目录（ isolator-mcp ）中，运行npm install和npm run build 。

3. **配置：**确保isolator_config.json通过isolatorPath键正确指向构建的./isolator-cli/isolator二进制文件（使用绝对路径）。

4. **运行服务器：**直接使用Node执行构建好的服务器：

   node build/index.js

   服务器将启动，通过 stdio 连接，并将日志（包括来自index.ts的console.error消息）打印到控制台。

5. **交互（手动）：**您可以手动将 JSON-RPC 消息（例如tools/list 、 tools/call ）发送到服务器的标准输入，以测试其响应。类似@modelcontextprotocol/inspector之类的工具也会有所帮助（ npm run inspector ）。

（请记住在依赖 MCP Host 通过设置文件启动它之前停止此手动运行的服务器。）

架构与流程

1. MCP 主机请求： LLM 要求 MCP 主机（例如 VS Code 扩展）使用参数调用isolator服务器的execute_code工具。

2. 服务器处理（

   • 通过 stdio 接收tools/call请求。

   • 使用 Zod 验证参数。

   • 从isolator_config.json加载配置。

   • 确定代码来源：

     • 如果提供了snippet_name ，则从配置的promptsDir中读取相应的文件并从文件扩展名确定语言。

     • 如果提供了entrypoint_code和language ，则直接使用它们。

   • 在主机上创建临时目录。

   • 将入口点代码和任何additional_files写入临时目录。

   • 构建嵌入式isolator Go CLI 的命令行参数，包括来自配置的安全标志和临时目录的路径。

   • 使用 Node.js child_process.spawn生成isolator进程。

3. Go CLI 执行（

   • 解析标志（包括新的--env标志）。

   • 创建临时目录内容的 tar 流。

   • 使用 Docker SDK 创建具有指定映像、资源限制、环境变量（来自--env ）和安全设置（无绑定挂载）的容器。

   • 使用CopyToContainer将 tar 流复制到容器的工作目录中。

   • 启动容器，执行请求的命令（例如， python /workspace/hello_world.py ）。

   • 等待完成，捕获 stdout/stderr。

   • 移除容器。

   • 将结果（状态、输出等）作为 JSON 打印到其标准输出。

4. 服务器结果处理（

   • 从已完成的isolator进程标准输出读取 JSON 输出。

   • 解析 JSON 结果。

   • 格式化 MCP 的CallToolResult ，结合 stdout/stderr，如果 Go CLI 报告不成功状态则设置isError 。

   • 将结果发送回 MCP 主机。

   • 清理主机上的临时目录。

5. **MCP 主机响应：**将结果传回 LLM，然后 LLM 为用户制定响应。

execute_code工具

描述

在安全、隔离的容器环境中执行代码（Python、Go、JavaScript）。

输入模式（ arguments ）

• language （字符串，可选）：编程语言（例如，“python”、“go”、“javascript”）。如果未提供snippet_name ，则为必填项。

• entrypoint_code （字符串，可选）：要执行的主要代码内容。如果未提供snippet_name ，则为必填项。

• entrypoint_filename （字符串，可选）：主代码的文件名（例如“main.py”、“script.js”）。若未提供，则根据语言默认。

• additional_files （数组，可选）：对象数组，每个对象包含：

  • filename （字符串，必需）：附加文件的名称。

  • content （字符串，必需）：附加文件的内容。

• snippet_name (字符串，可选)：位于配置的promptsDir中的预定义代码片段文件的名称（不带扩展名）。与language和entrypoint_code互斥。

**约束：**必须提供snippet_name或language和entrypoint_code 。

输出（ CallToolResult ）

• content ：包含单个TextContent对象的数组。

  • type ：“文本”

  • text ：包含执行时组合的 stdout 和 stderr 的字符串，格式如下：

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

    如果执行期间发生错误（非零退出代码、超时），则文本前面会添加Execution Failed (status): [error message]\n\n 。

• isError （布尔值）：如果isolator CLI 报告的执行状态为“错误”或“超时”，则为true ，否则为false 。

（协议级错误，例如无效参数或无法启动进程，将导致标准 MCP 错误响应而不是 。