代码解释器服务

代码解释器

一个开源的模型上下文协议（MCP）服务器，提供类似笔记本电脑的代码执行界面，具有会话亲和性、多语言支持和会话范围的文件存储。旨在与LibreChat的代码解释器流干净地集成。

有关内部和请求流，请参阅 docs/ARCHITECTURE.md.

亮点

• 通过支持SSE流媒体的Jupyter内核执行有状态的Python。
• 在沙盒子进程中执行的其他运行时（bash、Node.js、TypeScript、Go、C++）。
• 会话范围的文件上传/下载，带有LibreChat兼容的响应。
• 用于客户端功能发现的健康+运行时清单端点。
• Docker首先使用基于uv的本地开发工作流和Makefile助手进行部署。

支持的语言

GET /health 报告哪些运行时可用，以及已安装库的快照。 GET /libraries 显示全部库存。

快速入门（Docker）

Docker运行（推荐）

docker run --rm -p 8000:8000 \
  -e CODE_INTERPRETER_API_KEY=dev-demo-key \
  -v $(pwd)/uploads:/app/uploads \
  -v $(pwd)/notebooks:/app/notebooks \
  ghcr.io/thehapyone/code-interpreter:latest

Docker Compose（类似于生产环境）

docker compose build \
  --build-arg APP_UID=$(id -u) \
  --build-arg APP_GID=$(id -g)
docker compose up -d
docker compose logs -f

启动前，确保可写绑定挂载：

mkdir -p notebooks uploads logs
chown -R $(id -u):$(id -g) notebooks uploads logs

如果解释器必须加入MCP客户端使用的现有Docker网络，请设置 MCP_NETWORK_EXTERNAL=true 和 MCP_NETWORK_NAME=<network> 在 .env.

LibreChat集成

此服务器旨在与LibreChat的代码解释器工作流程直接兼容。

• /upload 回报 message: "success" 包括 fileId/filename LibreChat预期的字段。
• 上传的文件可以在Python中找到 /mnt/data/<filename>.
• /exec 接受 args 作为字符串或列表（LibreChat可能会发送 [])并且可以使用 session_id 从附件参考文献中获取文件水合作用。

LibreChat环境示例

在LibreChat部署中使用这些变量指向代码解释器服务：

#==================================#
# Code Interpreter Configuration   #
#==================================#
LIBRECHAT_CODE_API_KEY=librechat
LIBRECHAT_CODE_BASEURL=http://code_interpreter:7000

在LibreChat中使用代码解释器

/mnt/data 兼容性

Python内核在以下情况下处理POSIX路径 /mnt/data 作为当前会话工作区的别名 <UPLOADS_DIR>/<session_id>/mnt/data。这有助于运行假设代码解释器的笔记本和示例 /mnt/data 公约。

配置

环境变量（常用）：

API和MCP集成

• OpenAPI生成于 openapi.json （奔跑 make openapi 在改变端点之后）。导入到MCP客户端，如LibreChat或Claude Desktop。
• 主要终点： /exec, /exec/stream, /upload, /files/{session_id}, /files/{session_id}/{file_id}, /download/{session_id}/{file_id}, /health, /libraries.
• 会话关联性由以下因素驱动 entity_id；重用它将调用绑定到相同的Python内核和工作区。

用法示例

执行Python：

curl -X POST http://localhost:8000/exec \
  -H "Content-Type: application/json" \
  -d '{"code":"print(\"hello\")","lang":"py","entity_id":"demo"}'

将文件上传到会话中并使用它们执行：

curl -X POST http://localhost:8000/upload \
  -F "entity_id=demo" \
  -F "files=@data.csv"

curl -X POST http://localhost:8000/exec \
  -H "Content-Type: application/json" \
  -d '{
    "code":"import pandas as pd; print(pd.read_csv(\"data.csv\").head())",
    "lang":"py",
    "entity_id":"demo"
  }'

流输出（Python）：

curl -N -X POST http://localhost:8000/exec/stream \
  -H "Content-Type: application/json" \
  -d '{"code":"import time\nfor i in range(3):\n print(i); time.sleep(1)","lang":"py","entity_id":"demo"}'

本地开发（uv+FastAPI）

make install   # uv sync
make dev       # starts FastAPI on http://localhost:8000

测试和质量

• make test –异步pytest套件。
• make lint –绒毛检查。
• make format-check –Ruff格式验证。
• make typecheck –mypy（严格）。
• bash e2e/run_all.sh -语言烟雾测试（服务器必须正在运行，例如。， make dev).

安全和隔离

• 在Docker中以非root身份运行；支持卷权限的可配置UID/GID。
• 会话工作区隔离用户文件和执行工件；子进程HOME指向工作区。
• 环境配置防止主机环境泄漏； PYTHONPATH 已清除子流程。
• 可选的RLIMIT上限和执行超时；可选的严格bash前奏。
• API密钥验证可通过 CODE_INTERPRETER_API_KEY.

项目结构（高层）

• src/mcp_code_interpreter/ –FastAPI服务器、执行服务、内核管理器、会话注册表、进程运行器、功能发现。
• tests/ –pytest套件。
• e2e/ –语言烟雾测试和人工制品。
• ui/ –可选的Vite/React开发UI。
• docs/ARCHITECTURE.md –系统架构和图表。

许可证

麻省理工学院