Isolator MCP Server

isolator-mcp 是一个用 TypeScript 编写的 模型上下文协议（MCP） 服务器。它作为嵌入式 isolator Go 命令行工具 的封装，提供了一个可通过 MCP 访问的安全代码执行沙箱。

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

功能

• 提供 execute_code MCP 工具。
• 支持执行直接提供的代码（language，entrypoint_code）或通过命名片段（snippet_name）提供的代码。
• 支持多种语言（Python、Go、JavaScript，可配置）。
• 使用嵌入的 isolator Go 命令行工具（isolator-cli/）进行安全的 Docker 容器执行。
• 通过 isolator_config.json 配置安全默认设置（超时、资源限制、网络）。
• 管理主机上的临时目录以执行代码。
• 处理文件复制到容器中（通过指示 isolator CLI）。
• 通过 MCP 返回结构化结果（标准输出、标准错误、状态），在工具级别失败时设置 isError: true。

先决条件

• Docker: 用于由 isolator-cli 创建和执行容器。确保 Docker 守护进程正在运行。
• Go: 用于构建嵌入的 isolator-cli Go 可执行文件。
• Node.js 和 npm: 用于安装依赖项、构建和运行 isolator-mcp TypeScript 服务器。

安装

1. 构建 isolator Go 命令行工具: 导航到嵌入的 Go 命令行工具目录并构建二进制文件：

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

   这会创建服务器所需的 ./isolator-cli/isolator 可执行文件。
2. 配置 isolator-mcp:
   • 编辑 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": []
       }
     }
   }
   

   (如有必要，请调整 args 中的路径)。MCP 主机应自动检测并启动服务器。

重要提示: 确保在系统上提前拉取 isolator_config.json 中指定的 Docker 镜像（例如，python:3.11-alpine，golang:1.21-alpine）使用 docker pull <image_name>。isolator 工具不会自动下载缺失的镜像。

本地开发/测试

要运行服务器进行开发或测试（无需通过 MCP 主机设置安装）：

1. 构建 Go 命令行工具: 确保 isolator Go 命令行工具在其子目录内已构建：

   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
   

   服务器将启动，通过标准 I/O 连接，并将日志（包括来自 index.ts 的 console.error 消息）打印到控制台。
5. 交互（手动）: 您可以手动发送 JSON-RPC 消息（例如，tools/list，tools/call）到服务器的标准输入以测试其响应。工具如 @modelcontextprotocol/inspector 也可能有所帮助（npm run inspector）。

(记得在依靠 MCP 主机通过设置文件启动之前停止手动运行的服务器。)

架构与流程

1. MCP 主机请求: LLM 请求 MCP 主机（例如，VS Code 扩展）调用 isolator 服务器的 execute_code 工具及其参数。
2. 服务器处理（index.ts）:
   • 通过标准 I/O 接收 tools/call 请求。
   • 使用 Zod 验证参数。
   • 从 isolator_config.json 加载配置。
   • 确定代码来源：
     • 如果提供了 snippet_name，则从配置的 promptsDir 读取相应的文件，并根据文件扩展名确定语言。
     • 如果提供了 entrypoint_code 和 language，则直接使用它们。
   • 在主机上创建临时目录。
   • 将入口点代码和任何 additional_files 写入临时目录。
   • 构建嵌入的 isolator Go 命令行工具的命令行参数，包括来自配置的安全标志和临时目录的路径。
   • 使用 Node.js child_process.spawn 启动 isolator 进程。
3. Go 命令行执行（isolator-cli/isolator run）:
   • 解析标志（包括新的 --env 标志）。
   • 创建临时目录内容的 tar 流。
   • 使用 Docker SDK 创建具有指定镜像、资源限制、环境变量（来自 --env）和安全设置（无绑定挂载）的容器。
   • 使用 CopyToContainer 将 tar 流复制到容器的工作目录。
   • 启动容器，执行请求的命令（例如，python /workspace/hello_world.py）。
   • 等待完成，捕获标准输出/标准错误。
   • 移除容器。
   • 将结果（状态、输出等）作为 JSON 打印到其标准输出。
4. 服务器结果处理（index.ts）:
   • 从已完成的 isolator 进程的标准输出读取 JSON 输出。
   • 解析 JSON 结果。
   • 为 MCP 格式化 CallToolResult，结合标准输出/标准错误，并在 Go 命令行报告非成功状态时设置 isError。
   • 将结果返回给 MCP 主机。
   • 清理主机上的临时目录。
5. MCP 主机响应: 将结果传回给 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"
  • text: 字符串，包含执行期间的组合标准输出和标准错误，格式如下：

    --- stdout ---
    [实际标准输出]
    --- stderr ---
    [实际标准错误]
    

    如果执行过程中发生错误（非零退出码、超时），文本将被 Execution Failed (状态): [错误消息]\n\n 预置。
• isError（布尔值）: 如果 isolator CLI 报告的状态是“错误”或“超时”，则为 true，否则为 false。

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