fc-code-interpreter-mcp-server 0.0.12

Code Interpreter MCP Server - Secure code execution via E2B on Function Compute

Sandbox Code Interpreter MCP Server

基于 FastMCP 框架的 MCP 服务器，支持通过本地 Sandbox 服务进行安全的代码执行，提供多种传输协议（stdio、SSE、HTTP Streamable）。

🚀 快速开始

方式 1: 使用 Docker Compose（推荐）

一键启动 Sandbox 和 MCP Server 服务：

# 启动所有服务
make up

# 验证服务运行
curl http://localhost:5001/health  # Sandbox 健康检查
curl http://localhost:3000/sse     # MCP Server SSE 端点

# 停止服务
make down

服务端点：

• Sandbox API: http://localhost:5001
• MCP Server (SSE): http://localhost:3000/sse

方式 2: 手动启动

1. 启动 Sandbox Docker 服务

# 启动本地 sandbox
docker-compose up -d sandbox-code-interpreter

# 验证服务运行
curl http://localhost:5001/health

预期输出: {"status":"healthy"}

2. 安装依赖

# 使用 UV (推荐)
uv install

# 或使用 pip
pip install -e .

3. 启动 MCP Server

# SSE 协议 (推荐)
make run-sse

# HTTP Streamable 协议
make run-http-streamable

# stdio 协议（用于 Claude Desktop）
make run-stdio

⚙️ 配置说明

环境变量

MCP Server 支持以下环境变量配置（命令行参数优先级更高）：

环境变量	默认值	说明	命令行参数
MCP_TRANSPORT	stdio	传输协议 (stdio/sse/http)	--transport
MCP_HOST	0.0.0.0	监听地址	--host
MCP_PORT	3000	服务端口	--port
MCP_PATH	/mcp	HTTP 端点路径	--path
SANDBOX_URL	http://localhost:5001	Sandbox 服务地址	--sandbox-url
LOG_LEVEL	INFO	日志级别	-

配置方式

方式 1: 环境变量

# 直接设置环境变量
export MCP_TRANSPORT=sse
export MCP_HOST=0.0.0.0
export MCP_PORT=3000
export SANDBOX_URL=http://localhost:5001

# 运行服务器
uv run python mcp_server/main.py

方式 2: 命令行参数（优先级更高）

# 使用命令行参数
uv run python mcp_server/main.py \
  --transport sse \
  --host 0.0.0.0 \
  --port 3000 \
  --sandbox-url http://localhost:5001

方式 3: Docker Compose

docker-compose.yml 已预配置 SSE 协议的环境变量：

environment:
  - MCP_TRANSPORT=sse
  - MCP_HOST=0.0.0.0
  - MCP_PORT=3000
  - MCP_PATH=/sse
  - SANDBOX_URL=http://sandbox-code-interpreter:5000

📋 可用工具

1. health_check - 健康检查

检查 Sandbox 服务状态。

{}

2. create_context - 创建代码执行上下文

创建新的执行上下文（Session）。

{
  "context_id": "my-context",
  "language": "python"
}

3. run_code - 执行代码

在指定上下文中执行代码。

{
  "context_id": "my-context",
  "code": "print('Hello World')"
}

4. list_contexts - 列出所有上下文

获取当前所有活跃的上下文列表。

{}

5. stop_context - 停止上下文

终止指定的执行上下文。

{
  "context_id": "my-context"
}

6. restart_context - 重启上下文

重启指定的执行上下文。

{
  "context_id": "my-context"
}

🔍 测试服务器

使用 MCP Inspector（SSE 协议）

# 确保 MCP Server 以 SSE 模式运行
make run-sse

# 启动 Inspector 连接到 SSE 端点
npx @modelcontextprotocol/inspector http://localhost:3000/sse

使用 curl 测试

# 测试 SSE 端点
curl -N http://localhost:3000/sse

# 测试 HTTP Streamable 端点
curl -N http://localhost:3000/mcp

🔧 与 Claude Desktop 集成

在 Claude Desktop 配置文件中添加：

{
  "mcpServers": {
    "sandbox": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/sandbox-code-interpreter-mcp-server",
        "run",
        "python",
        "-m",
        "mcp_server"
      ],
      "env": {
        "SANDBOX_URL": "http://localhost:5001"
      }
    }
  }
}

🐳 Docker 相关

构建镜像

# 构建镜像（自动使用 git tag 作为版本号）
make docker-build

# 推送到阿里云镜像仓库
make docker-push

Docker 运行参数

Docker 镜像默认配置：

• MCP_TRANSPORT=http
• MCP_HOST=0.0.0.0
• MCP_PORT=3000
• MCP_PATH=/mcp
• SANDBOX_URL=http://host.docker.internal:5001

可以通过环境变量或命令行参数覆盖：

# 使用环境变量
docker run -e SANDBOX_URL=http://custom-sandbox:5000 \
           -e MCP_TRANSPORT=sse \
           -p 3000:3000 \
           sandbox-mcp-server:latest

# 使用命令行参数
docker run -p 3000:3000 sandbox-mcp-server:latest \
  --transport sse \
  --sandbox-url http://custom-sandbox:5000

🐛 故障排查

问题 1: 模块导入错误

# 确保依赖已安装
uv sync

# 或手动安装依赖
pip install mcp python-dotenv requests pydantic starlette uvicorn

问题 2: 端口被占用

# 检查端口占用
lsof -i :3000

# 使用其他端口
MCP_PORT=3001 make run-sse

问题 3: 无法连接到 Sandbox

# 检查 Docker 容器状态
docker ps | grep sandbox-code-interpreter

# 查看容器日志
docker logs sandbox-code-interpreter

# 重启容器
docker-compose restart sandbox-code-interpreter

问题 4: Context 初始化失败

# 检查 Sandbox 连接
curl http://localhost:5001/health

# 查看 MCP Server 日志
# 确认 SANDBOX_URL 配置正确

📊 日志输出

服务器启动后会显示：

============================================
FastMCP Sandbox Code Interpreter Server
============================================

Configuration:
  Transport: sse
  Host: 0.0.0.0
  Port: 3000
  Path: /sse
  Sandbox URL: http://localhost:5001

SSE Endpoint: http://0.0.0.0:3000/sse

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:3000 (Press CTRL+C to quit)

🆚 传输协议对比

特性	stdio	SSE	HTTP Streamable
传输方式	标准输入输出	HTTP SSE	HTTP
调试难度	困难	简单	简单
网络访问	仅本地	支持远程	支持远程
浏览器测试	不支持	支持	支持
日志查看	混在一起	独立	独立
连接方式	进程管道	Server-Sent Events	HTTP Request
适用场景	Claude Desktop	浏览器、远程调试	API 集成

📚 相关文档

• FastMCP 迁移总结
• HTTP Streamable 实现
• Docker 部署指南
• 本地快速开始
• 上下文管理指南
• Makefile 使用指南

✅ 验证清单

• Docker 容器运行正常
• Sandbox 健康检查通过 (curl http://localhost:5001/health)
• Python 依赖已安装 (uv install)
• MCP Server 启动成功
• 可以通过 MCP Inspector 连接
• 可以创建 context (create_context)
• 可以执行代码 (run_code)
• 可以列出 contexts (list_contexts)
• 可以停止 context (stop_context)

🛠️ Makefile 命令

# 运行 MCP Server
make run-sse              # SSE 协议（推荐）
make run-http-streamable  # HTTP Streamable 协议
make run-stdio            # stdio 协议

# Docker Compose
make up                   # 启动所有服务
make down                 # 停止所有服务

# Docker 镜像
make docker-build         # 构建镜像
make docker-push          # 推送镜像

# 版本发布
make release              # 发布新版本 (git tag + uv build + uv publish)

🎯 核心特性

• ✅ 多协议支持: stdio、SSE、HTTP Streamable
• ✅ 上下文管理: 支持创建、列出、停止、重启上下文
• ✅ 代码执行: 安全的沙盒环境执行代码
• ✅ 健康检查: 完整的服务健康检查机制
• ✅ 环境变量配置: 灵活的配置管理
• ✅ Docker 支持: 完整的容器化部署方案
• ✅ 远程调试: 支持 MCP Inspector 调试

📦 版本发布

一键发布流程

# 执行发布命令
make release

发布脚本会交互式完成以下步骤：

第 1 步：版本升级

版本升级选项:
  1) Patch (0.0.10 → 0.0.11)  - 修复 bug
  2) Minor (0.0.10 → 0.1.0)   - 新功能（向后兼容）
  3) Major (0.0.10 → 1.0.0)   - 重大更新（可能不兼容）
  4) Custom - 手动输入版本号
  5) Skip - 使用当前版本（不升级）

第 2 步：自动构建和发布

• ✅ 更新 pyproject.toml 版本号
• ✅ 提交版本更新到 Git
• ✅ 创建 Git tag (v x.x.x)
• ✅ 构建 Python 包 (uv build)
• ✅ 发布到 PyPI (uv publish)
• ✅ 构建 Docker 镜像 (包含版本 tag 和 latest tag)
• ✅ 推送 Docker 镜像到阿里云
• ✅ 记录发布历史到 .release/ 目录
• ✅ 推送 Git tag 到远程

完整示例

$ make release

==========================================
     FC Code Interpreter MCP Server
            版本发布脚本
==========================================

==========================================
第 1 步: 版本升级
==========================================

[INFO] 当前版本: 0.0.10

版本升级选项:
  1) Patch (0.0.10 → 0.0.11)  - 修复 bug
  2) Minor (0.0.10 → 0.1.0)   - 新功能（向后兼容）
  3) Major (0.0.10 → 1.0.0)   - 重大更新（可能不兼容）
  4) Custom - 手动输入版本号
  5) Skip - 使用当前版本（不升级）

请选择 (1/2/3/4/5): 1

[INFO] 版本将从 0.0.10 升级到 0.0.11
[SUCCESS] 已更新 pyproject.toml 中的版本号为 0.0.11
[SUCCESS] 版本更新已提交

==========================================
第 2 步: 前置检查
==========================================

[INFO] 准备发布版本: 0.0.11

==========================================
第 3 步: 开始发布流程
==========================================

[INFO] 创建 Git tag: v0.0.11
[SUCCESS] Git tag v0.0.11 创建成功

[INFO] 使用 uv build 构建包...
[SUCCESS] 包构建成功

[INFO] 准备发布到 PyPI...
发布选项:
1) PyPI (https://pypi.org)
2) TestPyPI (https://test.pypi.org)
3) 跳过发布
请选择 (1/2/3): 1

[SUCCESS] 发布到 PyPI 成功

[INFO] 构建 Docker 镜像...
[INFO] 镜像名称: registry.cn-shanghai.aliyuncs.com/fc-demo2/custom-container-repository:fc-ci-mcp-v0.0.11
[SUCCESS] Docker 镜像构建成功

[INFO] 推送 Docker 镜像到仓库...
是否推送 Docker 镜像到阿里云？(y/N) y
[SUCCESS] Docker 镜像推送成功

[SUCCESS] 发布记录已保存到 .release/0.0.11.release

[INFO] 推送 Git tag 到远程仓库
是否推送 tag 到远程？(y/N) y
[SUCCESS] Git tag 推送成功

==========================================
          📦 发布摘要
==========================================

Version: 0.0.11
Release Date: 2025-10-26 14:00:00
Release Timestamp: 1729922400
Git Tag: v0.0.11
Git Commit: abc123def456...
Released By: Your Name <[e-mail]>

构建文件:
-rw-r--r-- 1 user group 15234 Oct 26 14:00 fc_code_interpreter_mcp_server-0.0.11.tar.gz
-rw-r--r-- 1 user group 18456 Oct 26 14:00 fc_code_interpreter_mcp_server-0.0.11-py3-none-any.whl

Docker 镜像:
  - registry.cn-shanghai.aliyuncs.com/fc-demo2/custom-container-repository:fc-ci-mcp-v0.0.11
  - registry.cn-shanghai.aliyuncs.com/fc-demo2/custom-container-repository:latest

==========================================

[SUCCESS] 版本 0.0.11 发布完成！🎉

后续操作:
  1. 检查 PyPI: https://pypi.org/project/fc-code-interpreter-mcp-server/0.0.11/
  2. 检查 Docker: registry.cn-shanghai.aliyuncs.com/fc-demo2/custom-container-repository:fc-ci-mcp-v0.0.11
  3. 更新 CHANGELOG.md
  4. 推送代码: git push origin main

发布历史

每次发布会在 .release/ 目录创建一个记录文件：

.release/
├── 0.0.10.release     # 版本发布记录
├── 0.0.11.release
└── ...

---

Happy coding with FastMCP! 🎉