Python Runtime Interpreter MCP Server

PRIMS는 LLM 에이전트가 안전하고 일회성인 샌드박스(sandbox) 내에서 임의의 Python 코드를 실행할 수 있게 해주는 아주 작은 오픈 소스 Model Context Protocol (MCP) 서버입니다.

• 하나의 도구, 하나의 작업. 단일 MCP 도구인 run_code를 노출합니다.

– 이는 사용자가 제공한 Python을 실행하고 stdout / stderr를 스트리밍하여 반환합니다.

• 격리 및 재현 가능. 각 호출은 새로운 가상 환경(virtual-env)을 생성하고, 요청된 모든 pip 패키지를 설치하며, 선택적으로 읽기 전용 파일을 마운트(mount)한 다음, 작업 공간을 삭제합니다.

• 설정 제로. MCP/stdio를 통해 작동하거나 Docker에 바로 넣을 수 있습니다.

chmod +x scripts/setup_env.sh # 스크립트를 실행 가능하게 만들기 위해 한 번 실행
./scripts/setup_env.sh # .venv 생성 및 의존성 설치
# 각 새로운 셸에서 venv 활성화
...

python -m server.main # http://0.0.0.0:9000/mcp 에 바인딩

# 빠른 한 줄 명령어 (빌드 + 실행)
chmod +x scripts/docker_run.sh
./scripts/docker_run.sh # 준비되면 MCP URL 출력

제공된 스크립트를 사용하여 서버가 노출하는 모든 도구를 나열할 수 있습니다:

python examples/list_tools.py

예상 출력 (도구 이름 및 설명은 다를 수 있음):

Available tools:
- run_code: Execute Python code in a secure sandbox with optional dependencies & file mounts.
- list_dir: List files/directories in your session workspace.
...

python examples/run_code.py

python examples/mount_and_run.py

이것은 mount_file을 사용하여 CSV를 마운트하고, URL을 다시 제공하지 않고도 run_code 내부에서 이를 읽습니다.

python examples/inspect_workspace.py

이것은 list_dir 및 preview_file 도구를 사용하여 코드가 생성한 파일을 탐색하는 방법을 보여줍니다.

persist_artifact 도구는 output/ 디렉토리의 파일을 사전 서명된 URL(presigned URL)로 업로드합니다. 예시 (Python):

await client.call_tool("persist_artifact", {
"relative_path": "plots/plot.png",
"presigned_url": "https://bucket.s3.amazonaws.com/...signature...",
...

작은 아티팩트(artifacts)는 직접 가져올 수 있습니다:

curl -H "mcp-session-id: <your-session-id>" \
http://localhost:9000/artifacts/plots/plot.png -o plot.png

도구 (Tool)	목적 (Purpose)
run_code	선택적인 pip 의존성 (deps)과 함께 격리된 샌드박스 (sandbox) 내에서 Python을 실행합니다.
list_dir	세션 워크스페이스 (session workspace) 내부의 파일/디렉토리를 나열합니다.
preview_file	빠른 검사를 위해 텍스트 파일의 최대 8 KB를 반환합니다.
persist_artifact	output/ 파일을 클라이언트가 제공한 서명된 URL (presigned URL)로 업로드합니다.
mount_file	세션당 한 번 원격 파일을 mounts/<path>로 다운로드합니다.

엔드 투 엔드 (end-to-end) 데모는 examples/ 디렉토리를 참조하세요.

기여(Contributions)는 언제나 환영합니다! PRIMS의 개선을 돕기 위해 이슈(issues)를 제기하거나, 기능을 제안하거나, 풀 리퀘스트 (pull requests)를 제출해 주세요.

이 프로젝트가 유용하다고 생각하신다면, 지원의 의미로 ⭐를 남겨주시면 감사하겠습니다.