Isolator MCP Server

隔离器 MCP 服务器

isolator-mcp是一个用 TypeScript 编写的模型上下文协议 (MCP)服务器。它作为嵌入式isolator Go CLI 工具的包装器，提供了一个可通过 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 。

先决条件

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

**重要提示：**请确保已使用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. 服务器处理（ 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 打印到其标准输出。
4. 服务器结果处理（ index.ts ）：
   • 从已完成的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 错误响应而不是CallToolResult ） 。