<p align="left"> <img src="primslogo.png" alt="PRIMS Logo" width="200"/> <a href="#"><img src="https://img.shields.io/badge/status-alpha-orange?style=for-the-badge" alt="状态：Alpha"/></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=for-the-badge" alt="许可证：MIT"/></a> </p>

PRIMS – Python 运行时解释器 MCP 服务器

PRIMS 是一个小型开源的 模型上下文协议（MCP） 服务器，允许大型语言模型代理在安全、一次性使用的沙箱中运行任意的 Python 代码。

• 一工具一任务。 提供单一的 MCP 工具——run_code——执行用户提供的 Python 代码，并返回 stdout / stderr 流。

• 隔离且可重复。 每次调用都会启动一个新的虚拟环境，安装任何请求的 pip 包，挂载可选的只读文件，然后销毁工作区。

• 零配置。 支持通过 MCP/标准输入输出或放入 Docker 中使用。

---

快速开始

1. 本地开发环境

chmod +x scripts/setup_env.sh   # 一次，使脚本可执行
./scripts/setup_env.sh          # 创建 .venv 并安装依赖

# 在每个新的 shell 中激活 venv
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/<路径>`。

通过 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: <你的会话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/<路径>。

请参阅 examples/ 目录以获取端到端演示。

贡献

欢迎贡献！请随意打开问题、提出功能建议或提交拉取请求来帮助改进 PRIMS。

如果你发现这个项目有用，请考虑留下一个 ⭐ 来表示支持。