Codesandbox MCP Server

CodeSandbox MCP服务器

一个生产就绪、安全强化的模型上下文协议（MCP）服务器，将Claude/ChatGPT连接到CodeSandbox和GitHub API。

安全第一： 基于ChatGPT/Claude是不可信对手的假设而构建。每个输入都经过验证，每个操作都被记录下来，每个错误都被清理干净。

特性

• CodeSandbox集成： 创建沙盒、写入文件、检索输出
• GitHub集成： 提交/推送文件、创建PR、读取文件（细粒度PAT支持）
• 安全强化： 输入验证、路径遍历预防、错误清理
• 速率限制： 多次配额（API调用、沙盒、执行时间）
• 审核日志记录： 不可变仅附加具有SHA256完整性哈希的日志
• Docker就绪： 非根容器，健康检查，优雅关机

快速开始

1.先决条件

• Node.js 20.x
• npm 10.x
• Docker和Docker Compose（可选）
• CodeSandbox API密钥
• GitHub细粒度个人访问令牌（PAT）

2.安装依赖项

npm install

3.配置环境

复制 .env.template 到 .env:

cp .env.template .env

编辑 .env 使用您的凭据：

MCP_PORT=3000
CSB_API_KEY=your_codesandbox_api_token_here
CSB_WORKSPACE_ID=your_workspace_id
CSB_GITHUB_TOKEN_REPO_1=github_pat_xxx  # For owner1/repo1
CSB_GITHUB_TOKEN_REPO_2=github_pat_yyy  # For owner2/repo2
RATE_LIMIT_PER_MINUTE=10
SANDBOX_IDLE_TIMEOUT_MS=600000
MAX_SANDBOX_AGE_MS=3600000
LOG_LEVEL=info
AUDIT_LOG_LEVEL=info

重要提示： GitHub令牌必须是 细粒度PAT，而不是经典代币。看 创建细粒度PAT 在......下面

4.构建和运行

方案A：地方发展

npm run build
npm start

选项B:Docker

docker-compose up -d

5.验证

检查运行状况端点：

curl http://localhost:3000/health

预期响应：

{
  "status": "healthy",
  "uptime": "45 seconds",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "services": {
    "codesandbox": "connected",
    "github": "connected"
  }
}

创建细粒度PAT

GitHub细粒度个人访问令牌提供特定于存储库的权限（建议使用经典令牌）。

分步说明

1. 转到GitHub设置→ 开发人员设置→ 个人访问令牌→ 细粒度代币
2. 点击 生成新令牌
3. 配置令牌：

- 姓名： MCP Server - owner/repo - 到期： 90天（最长） - 存储库访问： 选择特定存储库 - 权限： - Contents：读写 - Pull requests：读写（如果创建PR）

1. 点击 生成令牌 并立即复制
2. 增添 .env:

   CSB_GITHUB_TOKEN_REPO_1=github_pat_xxxxxxxxxxxxx

注： 细粒度PAT在90天后过期。设置日历提醒以轮换令牌。

令牌命名约定

使用与此模式匹配的环境变量名称：

• CSB_GITHUB_TOKEN_REPO_1 → 映射到配置的第一个仓库
• CSB_GITHUB_TOKEN_REPO_2 → 映射到已配置的第二个仓库

服务器从变量名中提取存储库密钥（例如。， repo_1, repo_2).

建筑

┌─────────────────────────────────────────────────────────────┐
│                     Claude/ChatGPT                          │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Protocol (stdio)
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                   MCP Server (this)                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │  Validation  │  │ Rate Limiter │  │ Audit Logger │     │
│  │  (Zod)       │  │              │  │ (SQLite)     │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  ┌────────────────────────────────────────────────────┐   │
│  │              Tool Handlers                          │   │
│  │  • create_sandbox_for_project                      │   │
│  │  • write_files_to_sandbox                          │   │
│  │  • get_sandbox_output                              │   │
│  │  • commit_and_push_to_github                       │   │
│  │  • read_github_file                                │   │
│  └────────────────────────────────────────────────────┘   │
└────────────┬───────────────────────────┬────────────────────┘
             │                           │
             ▼                           ▼
   ┌──────────────────┐       ┌──────────────────┐
   │ CodeSandbox API  │       │   GitHub API     │
   │  (sandboxes)     │       │ (fine-grained)   │
   └──────────────────┘       └──────────────────┘

可用工具

CodeSandbox工具

1. create_sandbox_for_project

使用指定模板创建新的CodeSandbox。

参数：

• project_name （字符串）：1-50个字符，仅限字母数字/下划线/连字符
• template （枚举）： react, next, vue, node
• initial_files （对象，可选）：最多20个文件，每个1MB

退货：

• sandbox_id （UUID）
• preview_url （字符串）

例子：

{
  "project_name": "my-react-app",
  "template": "react",
  "initial_files": {
    "src/App.tsx": "export default function App() { return 
Hello
; }"
  }
}

2. write_files_to_sandbox

在现有沙盒中写入或更新文件。

参数：

• sandbox_id （UUID）
• files （对象）：最多10个文件，每个500KB

退货：

• success （布尔值）
• files_written （编号）

3. get_sandbox_output

检索控制台日志、生成输出或预览URL。

参数：

• sandbox_id （UUID）
• output_type （枚举）： console_log, build_output, preview_url

退货：

• output （字符串）：山宁泰输出（最大50KB）
• output_type （字符串）

GitHub工具

4. commit_and_push_to_github

将文件提交并推送到GitHub存储库。

参数：

• repo_id （字符串）：格式 owner/repo （必须是全合一的）
• branch （string）：分支名称（否 .. 或 //)
• files （对象）：最多10个文件，每个500KB
• commit_message （字符串）：1-200个字符
• create_pr （boolean，可选）：创建拉取请求
• pr_title （字符串，可选）：PR标题（最多100个字符）

退货：

• success （布尔值）
• pr_url （字符串，可选）
• commit_sha （字符串）

例子：

{
  "repo_id": "owner/repo",
  "branch": "feature/new-feature",
  "files": {
    "README.md": "# Updated README"
  },
  "commit_message": "Update README with new instructions",
  "create_pr": true,
  "pr_title": "Update README"
}

5. read_github_file

从GitHub存储库读取文件。

参数：

• repo_id （字符串）：格式 owner/repo （必须是全合一的）
• file_path （string）：相对路径（否 .. 或绝对路径）
• branch （字符串，可选）：默认为 main

退货：

• content （字符串）
• size （编号）
• file_path （字符串）

环境变量

发展

脚本

• npm run build -编译TypeScript
• npm test -运行所有测试
• npm run test:security -运行安全审计+测试
• npm run lint -使用ESLint的Lint代码
• npm start -启动生产服务器
• npm run dev -使用ts节点启动开发服务器

运行测试

# All tests
npm test

# Unit tests only
npm test -- tests/unit

# Security tests only
npm test -- tests/security

# With coverage
npm test -- --coverage

覆盖阈值：

• 线路：80%
• 分支机构：75%
• 功能：80%

安全考虑

威胁模型

此服务器假定 ChatGPT/Claude是不受信任的对手所有安全控制都是相应设计的。

关键安全功能

1. 输入验证： 所有输入均已Zod模式验证
2. 路径穿越预防： 对所有文件路径进行正则表达式+黑名单验证
3. 错误清理： 从所有错误消息中删除秘密/令牌
4. 审核日志记录： 具有SHA256完整性哈希的不可变日志
5. 速率限制： 多个级别的每用户配额
6. 存储库允许列表： 只有白名单存储库可访问
7. 细粒度PAT： GitHub令牌适用于特定存储库

什么被阻止

• 路径遍历尝试(../, /etc/passwd)
• 绝对路径(/, C:\)
• 禁止的目录(.env, .git, .ssh, .aws)
• 超大文件（GitHub>500KB，沙盒>1MB）
• 非白名单存储库
• 无效的分支名称（空格， .., //)
• 违反费率限制

看 安全.md 获取完整的安全文档。

故障排除

问题：“加载配置失败”

原因： 缺少或无效的环境变量

解决方案：

1. 检查 .env 文件存在
2. 验证是否设置了所有必需的变量
3. 确保值中没有尾随空格

问题：“INVALID_REPO”错误

原因： 存储库不在列表中

解决方案：

1. 将令牌添加到 .env: CSB_GITHUB_TOKEN_REPO_3=github_pat_xxx
2. 重新启动服务器
3. 使用与令牌匹配的回购ID（例如。， repo_3)

问题：“RATE_LIMIT_EXCEED”

原因： API调用过多

解决方案：

1. 等待速率限制窗口重置（显示在错误消息中）
2. 降低请求频率
3. 升级到专业级别（如果可用）

问题：“PATH_TRAVERSAL”错误

原因： 请求中的文件路径无效

解决方案：

• 仅使用相对路径（例如。， src/index.ts)
• 避免 .., /，或禁用目录
• 检查路径不以开头 .env, .git等等。

问题：健康检查失败

原因： 配置或连接问题

解决方案：

1. 检查服务器日志： docker-compose logs -f
2. 验证API密钥是否有效
3. 测试与CodeSandbox/GitHub的网络连接

生产部署

部署前检查表

• \[\]所有测试均通过(npm test)
• \[\]安全审计干净(npm run test:security)
• \[\]已配置环境变量（无默认值）
• \[\]GitHub代币是细粒度的PAT
• \[\]存储库已配置
• \[\]适用于负载的速率限制
• \[\]已配置TLS（反向代理）
• \[\]监控/警报设置
• \[\]已配置日志聚合
• \[\]审计日志的备份策略

推荐堆栈

• 反向代理： Nginx或Traefik（用于TLS终止）
• 监控： 普罗米修斯+格拉法纳
• 日志聚合： ELK堆栈或数据狗
• 秘密管理： HashiCorp保险库或AWS机密管理器
• 容器编排： Docker Swarm或Kubernetes

Docker生产配置

# docker-compose.prod.yml
version: '3.8'
services:
  mcp-server:
    image: codesandbox-mcp-server:1.0.0
    restart: always
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=warn
      - AUDIT_LOG_LEVEL=info
    volumes:
      - /var/log/mcp:/app/logs
    deploy:
      replicas: 2
      resources:
        limits:
          cpus: '1'
          memory: 512M

贡献

欢迎投稿！请遵循以下指南：

1. 分叉存储库
2. 创建要素分支
3. 为新功能添加测试
4. 确保所有测试通过
5. 运行安全审计
6. 提交拉取请求

安全问题： 私下向security@your-domain.com

许可证

MIT许可证-请参阅 许可证 详细信息文件

支持

• 文档： 安全.md
• 问题： GitHub问题
• 电子邮件： support@your-domain.com

致谢

• 内置于 @模型上下文协议/sdk
• CodeSandbox API集成
• 通过Octokit的GitHub REST API
• 安全设计灵感来自OWASP Top 10

______________________________________________________________________

⚠️ 重要提示： 在所有安全测试通过且验证清单完成之前，不要部署到生产环境。看 安全.md 以满足部署要求。