# 🎨 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. 安装依赖
```bash
npm install
```
### 2. 配置 S3 存储
创建 `.env.local` 文件并配置 S3 凭据：
#### 使用 Cloudflare R2（推荐）
```bash
# 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
```bash
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. 本地测试
```bash
npm run dev
```
访问 http://localhost:3000 查看服务器信息
### 4. 部署到 Vercel
```bash
# 方式一：命令行部署
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 兼容存储
**参数**：
```json
{
"fileName": "model.glb",
"fileData": "base64_encoded_data",
"contentType": "model/gltf-binary",
"metadata": {
"title": "My 3D Model",
"description": "A beautiful 3D model"
}
}
```
**返回**：
```json
{
"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 存储中的所有文件
**参数**：
```json
{
"prefix": "3d-models/",
"maxKeys": 100
}
```
**返回**：
```json
{
"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（临时访问链接）
**参数**：
```json
{
"fileName": "3d-models/abc123-model.glb",
"expiresIn": 3600
}
```
**返回**：
```json
{
"success": true,
"url": "https://...presigned-url...",
"expiresIn": 3600
}
```
### 4. generate_3d_viewer
生成 3D 模型预览网页
**参数**：
```json
{
"modelUrl": "https://your-domain.com/3d-models/model.glb",
"title": "My 3D Model",
"backgroundColor": "#111",
"cameraOrbit": "45deg 75deg auto"
}
```
## 🔧 MCP 客户端配置
在 Cursor 或其他 MCP 客户端中配置：
```json
{
"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. 返回给用户可访问的链接
```
### 完整工作流
```bash
# 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 文档](https://developers.cloudflare.com/r2/)
- [AWS S3 API 文档](https://docs.aws.amazon.com/s3/)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Vercel 部署文档](https://vercel.com/docs)
## 🎯 为什么选择 S3 兼容存储？
1. **灵活性**: 可以随时切换存储提供商
2. **成本**: Cloudflare R2 提供免费额度，无流量费用
3. **简单**: 标准 S3 API，易于集成
4. **可靠**: 业界标准，久经考验
5. **功能强大**: 支持预签名 URL、元数据、生命周期管理等
## 📝 开发路线图
- [ ] 支持多文件批量上传
- [ ] 添加文件删除功能
- [ ] 支持文件夹管理
- [ ] 集成 CDN 加速
- [ ] 添加使用统计
