🎨 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 自定义域名（推荐）

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

AWS S3 公开访问

配置 Bucket Policy 允许公开读取
或使用预签名 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 部署日志定位问题

📖 相关文档

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

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

📝 开发路线图