Python Runtime Interpreter MCP Server

🚀 PRIMS – Python Runtime Interpreter MCP Server

PRIMS 是一個小型的開源 模型上下文協議（Model Context Protocol，MCP） 服務器，它允許大語言模型（LLM）代理在安全的一次性沙箱中運行任意 Python 代碼。

• 專一工具，專一任務：僅暴露一個 MCP 工具 run_code，用於執行用戶提供的 Python 代碼，並將 stdout / stderr 流返回。
• 隔離且可重現：每次調用都會創建一個全新的虛擬環境，安裝所需的 pip 包，掛載可選的只讀文件，然後銷燬工作空間。
• 零配置：可通過 MCP/stdio 運行，也可部署在 Docker 中。

🚀 快速開始

1. 本地開發環境

chmod +x scripts/setup_env.sh   # 僅需執行一次，使腳本可執行
./scripts/setup_env.sh          # 創建 .venv 並安裝依賴

# 在每個新的 shell 中激活虛擬環境
source .venv/bin/activate

2. 啟動服務器

python -m server.main         # 綁定到 http://0.0.0.0:9000/mcp

3. 使用 Docker

# 快速單行命令（構建並運行）
chmod +x scripts/docker_run.sh
./scripts/docker_run.sh         # 準備好後會打印 MCP URL

💻 使用示例

列出可用工具

你可以使用提供的腳本列出服務器暴露的所有工具：

python examples/list_tools.py

預期輸出（工具名稱和描述可能會有所不同）：

可用工具：
- run_code：在安全的沙箱中執行 Python 代碼，可選擇依賴項和文件掛載。
- list_dir：列出會話工作空間中的文件/目錄。
- preview_file：預覽會話工作空間中最多 8 KB 的文本文件。
- persist_artifact：將輸出文件上傳到預簽名 URL 進行永久存儲。
- mount_file：每個會話僅下載一次遠程文件到 `mounts/<path>`。

通過 MCP 服務器運行代碼

python examples/run_code.py

一次性掛載數據集並重復使用

python examples/mount_and_run.py

此示例使用 mount_file 掛載一個 CSV 文件，然後在 run_code 中讀取該文件，而無需重新提供 URL。

檢查會話工作空間

python examples/inspect_workspace.py

此示例展示瞭如何使用 list_dir 和 preview_file 工具瀏覽代碼創建的文件。

將製品持久化存儲

persist_artifact 工具可將 output/ 目錄中的文件上傳到預簽名 URL。 示例（Python）：

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

下載製品

小的製品可以直接獲取：

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

📚 詳細文檔

可用工具

有關端到端的演示，請參閱 examples/ 目錄。

🔗 貢獻

歡迎貢獻代碼！你可以自由地提出問題、建議功能或提交拉取請求，以幫助改進 PRIMS。

如果你覺得這個項目有用，請考慮留下一個 ⭐ 以表示支持。