아이솔레이터 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, 구성 가능)를 지원합니다.
• 안전한 Docker 컨테이너 실행을 위해 내장된 isolator Go CLI( isolator-cli/ )를 사용합니다.
• 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. Go CLI를 사용하여 isolator 빌드합니다. 내장된 Go CLI 디렉터리로 이동하여 바이너리를 빌드합니다.지엑스피1이렇게 하면 서버에 필요한 ./isolator-cli/isolator 실행 파일이 생성됩니다.
2. isolator-mcp 구성:
   • isolator_config.json 편집합니다. 빌드된 바이너리의 절대 경로(예: /Users/ompragash/Documents/Cline/MCP/isolator-mcp/isolator-cli/isolator )를 가리키도록 isolatorPath 업데이트합니다. 필요한 경우 기본 제한, 컨테이너 작업 디렉터리, 언어 이미지 또는 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 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 호스트가 설정 파일을 통해 서버를 시작하기 전에 수동으로 실행되는 서버를 중지해야 합니다.)

건축과 흐름

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 형식으로 stdout에 인쇄합니다.
4. 서버 결과 처리( index.ts ):
   • 완료된 isolator 프로세스 stdout에서 JSON 출력을 읽습니다.
   • JSON 결과를 구문 분석합니다.
   • Go CLI가 성공하지 못한 상태를 보고하는 경우 stdout/stderr을 결합하고 isError 설정하여 MCP에 대한 CallToolResult 포맷합니다.
   • 결과를 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]
    실행 중에 오류가 발생한 경우(0이 아닌 종료 코드, 시간 초과), 텍스트 앞에 Execution Failed (status): [error message]\n\n 추가됩니다.
• isError (부울): isolator CLI에서 보고된 실행 상태가 "오류" 또는 "시간 초과"인 경우 true , 그렇지 않은 경우 false .

(프로토콜 수준 오류(잘못된 인수 또는 프로세스 시작 실패 등)는 CallToolResult 대신 표준 MCP 오류 응답을 초래합니다.)