🎨 S3-Compatible 3D Storage MCP Server

一个部署在 Vercel 上的 MCP 服务器，使用 S3 兼容 API 存储和发布 3D 文件。支持 Cloudflare R2、AWS S3、MinIO 等所有 S3 兼容存储。

✨ 特性

• ✅ S3 兼容存储: 支持 Cloudflare R2、AWS S3、MinIO、DigitalOcean Spaces 等
• ✅ 简单易用: 基于标准 S3 API，无需复杂配置
• ✅ 自动生成预览: 自动创建交互式 3D 模型查看器
• ✅ 预签名 URL: 支持生成临时访问链接
• ✅ 文件管理: 列出、上传、获取文件

🚀 快速开始

1. 安装依赖

npm install

2. 配置 S3 存储

创建 .env.local 文件并配置 S3 凭据：

使用 Cloudflare R2（推荐）

# 1. 登录 Cloudflare Dashboard
# 2. 进入 R2 -> Create Bucket -> 创建名为 "3d-models" 的存储桶
# 3. 进入 R2 -> Manage R2 API Tokens -> Create API Token
# 4. 复制 Account ID、Access Key ID 和 Secret Access Key

R2_ENDPOINT=https://<YOUR_ACCOUNT_ID>.r2.cloudflarestorage.com
R2_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
R2_SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
R2_BUCKET_NAME=3d-models

# 可选：配置 R2 自定义域名（用于公开访问）
S3_PUBLIC_URL=https://your-custom-domain.com

使用 AWS S3

S3_ENDPOINT=https://s3.amazonaws.com
S3_ACCESS_KEY_ID=<YOUR_AWS_ACCESS_KEY>
S3_SECRET_ACCESS_KEY=<YOUR_AWS_SECRET_KEY>
S3_BUCKET_NAME=3d-models

3. 本地测试

npm run dev

访问 http://localhost:3000 查看服务器信息

4. 部署到 Vercel

# 方式一：命令行部署
vercel --prod

# 方式二：GitHub 自动部署（推荐）
git push origin main

重要：部署后在 Vercel 项目设置中添加环境变量：

• 进入项目 Settings → Environment Variables
• 添加 R2_ENDPOINT、R2_ACCESS_KEY_ID、R2_SECRET_ACCESS_KEY 等
• 重新部署

📡 MCP 端点

部署后的 MCP 服务器地址：

https://your-project.vercel.app/api/mcp

🛠️ 可用工具

1. s3_upload_file

上传 3D 模型文件到 S3 兼容存储

参数：

{
  "fileName": "model.glb",
  "fileData": "base64_encoded_data",
  "contentType": "model/gltf-binary",
  "metadata": {
    "title": "My 3D Model",
    "description": "A beautiful 3D model"
  }
}

返回：

{
  "success": true,
  "key": "3d-models/abc123-model.glb",
  "url": "https://your-domain.com/3d-models/abc123-model.glb",
  "id": "abc123",
  "bucket": "3d-models"
}

2. s3_list_files

列出 S3 存储中的所有文件

参数：

{
  "prefix": "3d-models/",
  "maxKeys": 100
}

返回：

{
  "success": true,
  "bucket": "3d-models",
  "count": 5,
  "files": [
    {
      "key": "3d-models/abc123-model.glb",
      "size": 1048576,
      "lastModified": "2024-12-04T10:30:00Z"
    }
  ]
}

3. s3_get_presigned_url

获取文件的预签名 URL（临时访问链接）

参数：

{
  "fileName": "3d-models/abc123-model.glb",
  "expiresIn": 3600
}

返回：

{
  "success": true,
  "url": "https://...presigned-url...",
  "expiresIn": 3600
}

4. generate_3d_viewer

生成 3D 模型预览网页

参数：

{
  "modelUrl": "https://your-domain.com/3d-models/model.glb",
  "title": "My 3D Model",
  "backgroundColor": "#111",
  "cameraOrbit": "45deg 75deg auto"
}

🔧 MCP 客户端配置

在 Cursor 或其他 MCP 客户端中配置：

{
  "mcpServers": {
    "3d-storage": {
      "url": "https://your-project.vercel.app/api/mcp"
    }
  }
}

💡 使用示例

Agent 调用示例

用户: 帮我上传这个 3D 模型文件到云端

Agent:
1. 调用 s3_upload_file 上传文件
   → 获得文件 URL: https://domain.com/3d-models/abc123-model.glb

2. 调用 generate_3d_viewer 生成预览页面
   → 获得预览页面: https://domain.com/3d-pages/xyz789.html

3. 返回给用户可访问的链接

完整工作流

# 1. 上传 GLB 文件
s3_upload_file({
  fileName: "awesome-model.glb",
  fileData: "<base64_data>"
})

# 2. 生成预览页面
generate_3d_viewer({
  modelUrl: "返回的URL",
  title: "Awesome 3D Model"
})

# 3. 分享预览页面链接

🌍 支持的 S3 兼容存储

• ✅ Cloudflare R2 - 免费 10GB 存储，无流量费用
• ✅ AWS S3 - 业界标准
• ✅ MinIO - 自托管方案
• ✅ DigitalOcean Spaces - 简单易用
• ✅ Backblaze B2 - 低成本
• ✅ 阿里云 OSS - 支持 S3 兼容模式
• ✅ 腾讯云 COS - 支持 S3 兼容模式

🔐 安全配置

Cloudflare R2 自定义域名（推荐）

1. 在 R2 Bucket 设置中绑定自定义域名
2. 配置 S3_PUBLIC_URL 环境变量
3. 文件将通过自定义域名公开访问

AWS S3 公开访问

1. 配置 Bucket Policy 允许公开读取
2. 或使用预签名 URL（s3_get_presigned_url）

📚 技术栈

• Framework: Next.js 14 + App Router
• Storage: AWS SDK S3 Client (支持所有 S3 兼容存储)
• Protocol: Model Context Protocol (MCP)
• Deployment: Vercel

🐛 故障排除

上传失败：403 Forbidden

• 检查 Access Key 和 Secret Key 是否正确
• 确认 Bucket 存在且有写入权限

文件无法访问

• 配置 S3_PUBLIC_URL 环境变量
• 或使用 s3_get_presigned_url 生成临时链接

部署失败

• 确保在 Vercel 项目设置中添加了所有环境变量
• 查看 Vercel 部署日志定位问题

📖 相关文档

• Cloudflare R2 文档
• AWS S3 API 文档
• Model Context Protocol
• Vercel 部署文档

🎯 为什么选择 S3 兼容存储？

1. 灵活性: 可以随时切换存储提供商
2. 成本: Cloudflare R2 提供免费额度，无流量费用
3. 简单: 标准 S3 API，易于集成
4. 可靠: 业界标准，久经考验
5. 功能强大: 支持预签名 URL、元数据、生命周期管理等

📝 开发路线图

• [ ] 支持多文件批量上传
• [ ] 添加文件删除功能
• [ ] 支持文件夹管理
• [ ] 集成 CDN 加速
• [ ] 添加使用统计