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

📚 详细文档

可用工具

| 工具 | 用途 | | ---- | ---- | | run_code | 在隔离的沙箱中执行 Python 代码，可选择 pip 依赖项。 | | list_dir | 列出会话工作空间中的文件/目录。 | | preview_file | 返回最多 8 KB 的文本文件以供快速检查。 | | persist_artifact | 将 output/ 文件上传到客户端提供的预签名 URL。 | | mount_file | 每个会话仅下载一次远程文件到 mounts/<path>。 |

有关端到端的演示，请参阅 examples/ 目录。

🔗 贡献

欢迎贡献代码！你可以自由地提出问题、建议功能或提交拉取请求，以帮助改进 PRIMS。

如果你觉得这个项目有用，请考虑留下一个 ⭐ 以表示支持。