FC 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

# 等待服务就绪（需要约 40 秒）
sleep 45

# 验证服务运行
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 支持以下环境变量配置（命令行参数优先级更高）：

配置方式

方式 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 服务状态。

参数：无

示例：

{}

响应：

{
  "status": "healthy",
  "sandbox_url": "http://localhost:5001/health",
  "response_code": 200,
  "response_body": "{\"status\":\"healthy\"}",
  "timestamp": "2025-10-25T03:00:00"
}

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

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

参数：

• language (string, 可选): 编程语言，默认为 "python"
• description (string, 可选): 上下文描述

示例：

{
  "language": "python"
}

响应：

{
  "context_id": "context-uuid",
  "language": "python",
  "description": "",
  "created_at": "2025-10-25T03:00:00"
}

3. run_code - 执行代码

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

参数：

• code (string, 必需): 要执行的代码
• context_id (string, 可选): 上下文 ID（如果未提供，需要提供 language）
• language (string, 可选): 编程语言（如果未提供 context_id，则必需）

示例：

{
  "code": "print('Hello World')",
  "language": "python"
}

示例（使用 context）：

{
  "code": "print('Hello from context')",
  "context_id": "context-uuid"
}

4. list_contexts - 列出所有上下文

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

参数：无

示例：

{}

响应：

[
  {
    "id": "context-uuid-1",
    "language": "python",
    "created_at": "2025-10-25T03:00:00",
    "last_used": "2025-10-25T03:01:00",
    "cwd": "/workspace",
    "status": "active",
    "sandbox_exists": true
  }
]

5. stop_context - 停止上下文

终止指定的执行上下文。

参数：

• context_id (string, 必需): 要停止的上下文 ID

示例：

{
  "context_id": "context-uuid"
}

响应：

{
  "success": true,
  "message": "Context context-uuid stopped successfully"
}

🔍 测试服务器

使用 MCP Inspector（SSE 协议）

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

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

使用 curl 测试

# 测试健康检查
curl http://localhost:3000/health_check

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

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

🔧 与 Claude Desktop 集成

在 Claude Desktop 配置文件中添加：

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

提示：

• 配置文件位置通常为 ~/.config/claude-desktop/claude_desktop_config.json
• 确保 Sandbox 服务已启动（curl http://localhost:5001/health）
• 使用 make run-stdio 可以测试 stdio 模式

🐳 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 Server (SSE)
============================================

配置:
  Transport: SSE
  Host: 0.0.0.0
  Port: 3000
  Sandbox URL: http://localhost:5001

SSE 端点: 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)

🆚 传输协议对比

🔧 技术栈

• 框架: FastMCP 2.12.5+
• 语言: Python 3.10+
• 依赖管理: UV (推荐) / pip
• 容器化: Docker
• 云平台: 阿里云 Function Compute
• 包管理: Hatchling

📚 相关文档

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

📦 安装方式

从 PyPI 安装

pip install fc-code-interpreter-mcp-server

从源码安装

# 克隆仓库
git clone https://github.com/alibaba/sandbox-code-interpreter-mcp-server.git
cd sandbox-code-interpreter-mcp-server

# 使用 uv 安装（推荐）
uv sync

# 或使用 pip
pip install -e .

✅ 验证清单

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

📝 使用示例

执行简单代码

# 创建上下文
create_context(language="python")

# 执行代码
run_code(
    code="print('Hello from FC Code Interpreter!')",
    language="python"
)

使用上下文执行代码

# 创建上下文
result = create_context(language="python")
context_id = result["context_id"]

# 在上下文中执行代码
run_code(
    code="x = 1 + 1\nprint(x)",
    context_id=context_id
)

# 继续使用同一上下文
run_code(
    code="print(x * 2)",
    context_id=context_id
)

# 清理上下文
stop_context(context_id=context_id)

列出所有上下文

# 列出所有上下文
contexts = list_contexts()
print(contexts)

🛠️ 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 调试
• ✅ 阿里云 FC 集成: 支持在阿里云 Function Compute 上运行

📦 版本发布

一键发布流程

# 执行发布命令
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 到远程

发布内容

发布脚本会自动执行以下操作：

• 更新 pyproject.toml 版本号
• 创建 Git tag
• 构建 Python 包（wheel 和 sdist）
• 发布到 PyPI 或 TestPyPI
• 构建 Docker 镜像并推送到阿里云
• 记录发布历史

发布版本对比

当前版本: 0.0.12（从 pyproject.toml 读取）

# 查看当前版本
grep "^version = " pyproject.toml

# 查看最近的 tags
git tag -l | tail -5

发布历史

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

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

Happy coding with FastMCP! 🎉