Isolator MCP Server

Isolator MCP 服务

isolator-mcp 是一个使用 TypeScript 编写的 Model Context Protocol（MCP） 服务。它封装了内嵌的 isolator Go 命令行工具，通过 MCP 提供安全的代码执行沙箱。

大模型应用（MCP Host）可以连接此服务，并使用其 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 返回结构化结果（stdout、stderr、状态），并在工具级故障时设置 isError: true。

前置条件

• 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-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 Host： 将服务添加到 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 Host 应会自动检测并启动服务。

重要提示： 请确保事先使用 docker pull <image_name> 将 isolator_config.json 中指定的 Docker 镜像（例如，python:3.11-alpine、golang:1.21-alpine）拉取到系统中。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 Host 请求： 大模型请求 MCP Host（例如 VS Code Extension）调用 isolator 服务的 execute_code 工具并传入参数。
2. 服务处理（index.ts）：
   • 通过 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 执行（isolator-cli/isolator run）：
   • 解析标志（包括新增的 --env 标志）。
   • 创建临时目录内容的 tar 流。
   • 使用 Docker SDK 创建容器，并设置指定的镜像、资源限制、环境变量（来自 --env）和安全设置（不使用绑定挂载）。
   • 使用 CopyToContainer 将 tar 流复制到容器的工作目录中。
   • 启动容器，执行所请求的命令（例如 python /workspace/hello_world.py）。
   • 等待完成并捕获 stdout／stderr。
   • 移除容器。
   • 将结果（状态、输出等）作为 JSON 打印到其 stdout。
4. 服务处理结果（index.ts）：
   • 从已结束的 isolator 进程 stdout 读取 JSON 输出。
   • 解析 JSON 结果。
   • 为 MCP 格式化 CallToolResult，合并 stdout／stderr，并在 Go CLI 报告非成功状态时设置 isError。
   • 将结果发送回 MCP Host。
   • 清理主机上的临时目录。
5. MCP Host 响应： 将结果转发回大模型，由大模型为用户生成回复。

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 的字符串，格式如下：

    --- stdout ---
    [实际 stdout 输出]
    --- stderr ---
    [实际 stderr 输出]
    

    如果执行期间发生错误（退出代码非零、超时），文本前面会添加 Execution Failed (status): [error message]\n\n。
• isError（布尔值）：如果 isolator CLI 报告的执行状态为 "error" 或 "timeout"，则为 true；否则为 false。

（如果发生协议级错误，例如参数无效或无法启动进程，系统将返回标准 MCP 错误响应，而不是 CallToolResult。）