README.md•10.8 kB
# 腾讯云 COS MCP 服务器
一个基于 Node.js 的 Model Context Protocol (MCP)服务器,为 Claude Desktop、Cursor 和 Windsurf 等 IDE 提供腾讯云对象存储(COS)功能。
## 功能特性
- 🚀 **文件上传** - 支持单文件和批量文件上传到腾讯云 COS
- 📦 **大文件上传** - 自动分片上传,支持断点续传和进度监控
- 🔄 **并发控制** - 智能重试机制和可配置并发限制
- 🧹 **资源清理** - 自动清理临时文件,防止磁盘空间泄漏
- 📁 **文件管理** - 复制、移动、重命名文件操作
- 🗂️ **文件夹操作** - 创建、删除文件夹,支持递归操作
- 🔗 **临时 URL** - 生成带签名的临时访问链接,支持自定义过期时间
- 📋 **对象管理** - 列出存储桶中的对象,支持前缀过滤和文件夹视图
- 🗑️ **批量删除** - 支持单个和批量删除 COS 中的对象
- 📊 **统计分析** - 文件夹统计信息,包括大小、数量、类型分布
- 🔧 **MCP 兼容** - 完全兼容 Model Context Protocol 规范
## 快速开始
📖 **快速上手**: 查看 [快速参考指南](./QUICK_REFERENCE.md) 了解所有工具的基本用法
📚 **详细文档**: 查看 [工具使用说明](./TOOLS_USAGE.md) 获取完整的API文档和示例
### 本地调试
```bash
# 克隆项目
git clone https://github.com/156554395/tx-cos-mcp.git
cd tx-cos-mcp
# 安装依赖
pnpm install
# 配置环境变量
export COS_SECRET_ID=your-secret-id
export COS_SECRET_KEY=your-secret-key
export COS_REGION=your-region
export COS_BUCKET=your-bucket
export COS_DOMAIN=your-custom-domain.com
# 启动调试服务器
pnpm inspector
```
## 环境配置
服务器通过环境变量读取腾讯云 COS 配置:
### 作为 MCP 服务器使用(推荐)
在 MCP 兼容编辑器中配置:
```json
{
"command": "npx",
"args": ["-y", "tx-cos-mcp@latest"],
"env": {
"COS_SECRET_ID": "your-secret-id",
"COS_SECRET_KEY": "your-secret-key",
"COS_REGION": "your-region",
"COS_BUCKET": "your-bucket",
"COS_DOMAIN": "your-custom-domain.com"
},
"transportType": "stdio"
}
```
### 环境变量说明
| 变量名 | 必需 | 说明 | 示例 |
| ---------------- | ---- | ----------------- | --------------------------- |
| `COS_SECRET_ID` | ✅ | 腾讯云 Secret ID | `AKIDxxx...` |
| `COS_SECRET_KEY` | ✅ | 腾讯云 Secret Key | `xxx...` |
| `COS_REGION` | ✅ | COS 地域 | `ap-beijing`, `ap-shanghai` |
| `COS_BUCKET` | ✅ | 存储桶名称 | `my-bucket-1234567890` |
| `COS_DOMAIN` | ❌ | 自定义域名 | `cdn.example.com` |
## MCP 工具列表
### 1. upload_file - 单文件上传
```javascript
{
"file_path": "/path/to/local/file.jpg", // 必需:本地文件路径
"object_key": "images/file.jpg", // 可选:COS中的对象键
"custom_domain": "cdn.example.com" // 可选:自定义域名
}
```
### 2. upload_multiple - 批量文件上传
```javascript
{
"files": [
{
"file_path": "/path/to/file1.jpg",
"object_key": "images/file1.jpg" // 可选
},
{
"file_path": "/path/to/file2.png" // 使用文件名作为对象键
}
]
}
```
### 3. get_signed_url - 获取临时访问 URL
```javascript
{
"object_key": "images/file.jpg", // 必需:COS对象键
"expire_time": 3600 // 可选:过期时间(秒),默认1小时
}
```
### 4. list_objects - 列出存储桶对象
```javascript
{
"prefix": "images/" // 可选:对象键前缀过滤
}
```
### 5. delete_object - 删除对象
```javascript
{
"object_key": "images/file.jpg" // 必需:要删除的对象键
}
```
### 6. copy_object - 复制对象
```javascript
{
"source_key": "images/file.jpg", // 必需:源对象键
"target_key": "backup/file.jpg", // 必需:目标对象键
"target_bucket": "other-bucket" // 可选:目标存储桶
}
```
### 7. move_object - 移动对象
```javascript
{
"source_key": "temp/file.jpg", // 必需:源对象键
"target_key": "images/file.jpg", // 必需:目标对象键
"target_bucket": "other-bucket" // 可选:目标存储桶
}
```
### 8. rename_object - 重命名对象
```javascript
{
"old_key": "images/old_name.jpg", // 必需:原对象键
"new_key": "images/new_name.jpg" // 必需:新对象键
}
```
### 9. delete_multiple - 批量删除对象
```javascript
{
"object_keys": [ // 必需:对象键数组
"images/file1.jpg",
"images/file2.jpg",
"temp/file3.png"
]
}
```
### 10. create_folder - 创建文件夹
```javascript
{
"folder_path": "images/thumbnails" // 必需:文件夹路径
}
```
### 11. delete_folder - 删除文件夹
```javascript
{
"folder_path": "temp/", // 必需:文件夹路径
"recursive": true // 可选:是否递归删除,默认false
}
```
### 12. list_folders - 列出文件夹和文件
```javascript
{
"prefix": "images/" // 可选:路径前缀,默认根目录
}
```
### 13. get_folder_stats - 获取文件夹统计
```javascript
{
"folder_path": "images/" // 可选:文件夹路径,为空则统计整个存储桶
}
```
### 14. upload_large_file - 大文件分片上传
```javascript
{
"file_path": "/path/to/large/video.mp4", // 必需:本地大文件路径
"object_key": "videos/video.mp4", // 可选:COS中的对象键
"custom_domain": "cdn.example.com", // 可选:自定义域名
"chunk_size": 2097152, // 可选:分片大小(字节),默认1MB
"concurrency": 5, // 可选:并发上传数,默认3,最大10
"force_slice": true // 可选:强制使用分片上传
}
```
### 15. get_upload_progress - 获取上传进度
```javascript
{
"session_id": "abc123def456" // 可选:特定会话ID,不提供则返回所有
}
```
### 16. clear_upload_progress - 清理上传进度
```javascript
{
"session_id": "abc123def456" // 必需:要清理的会话ID
}
```
### 17. manage_temp_files - 管理临时文件
```javascript
{
"action": "cleanup", // 必需:'stats'(统计) 或 'cleanup'(清理)
"type": "progress", // 可选:'progress'/'cache'/'uploads'/'all'
"older_than_days": 7 // 可选:清理多少天前的文件,默认7天
}
```
## IDE 集成配置
### 使用本地运行集成
```json
{
"mcpServers": {
"tx-cos-mcp": {
"command": "node",
"args": ["your-absolute-path/tx-cos-mcp/index.js"],
"env": {
"COS_SECRET_ID": "your-secret-id",
"COS_SECRET_KEY": "your-secret-key",
"COS_REGION": "your-region",
"COS_BUCKET": "your-bucket",
"COS_DOMAIN": "your-custom-domain.com"
}
}
}
}
```
### 已发布到 npm 集成
```json
{
"mcpServers": {
"tx-cos-mcp": {
"command": "npx",
"args": ["y", "tx-cos-mcp@latest"],
"env": {
"COS_SECRET_ID": "your-secret-id",
"COS_SECRET_KEY": "your-secret-key",
"COS_REGION": "your-region",
"COS_BUCKET": "your-bucket",
"COS_DOMAIN": "your-custom-domain.com"
},
"transportType": "stdio"
}
}
}
```
#### Claude code 中集成
在配置中添加 MCP 服务器配置,使用相同的 JSON 格式。
#### Cursor IDE
在设置中添加 MCP 服务器配置,使用相同的 JSON 格式。
#### Windsurf IDE
参考官方文档配置 MCP 服务器,使用上述配置参数。
## 常用命令
```bash
# 查看版本
npx tx-cos-mcp --version
# 测试配置
COS_SECRET_ID=xxx COS_SECRET_KEY=xxx COS_REGION=your-region COS_BUCKET=test npx tx-cos-mcp
# 开发模式
npm run dev
# 运行测试
npm run test # 基础功能测试
npm run test:mcp # MCP协议合规性测试
npm run test:temp # 临时目录管理测试
npm run test:cleanup # 临时文件清理测试
npm run test:path # 文件路径验证测试
# 发布到npm (维护者)
npm run publish:npm
```
## 测试
项目包含完整的测试套件,确保功能的可靠性:
### 测试文件
- `test/test.js` - 基础功能测试
- `test/test-mcp.js` - MCP协议合规性测试
- `test/test-temp.js` - 临时目录管理测试
- `test/test-cleanup.js` - 临时文件清理测试
- `test/test-path-validation.js` - 文件路径验证测试
### 运行测试
```bash
# 运行所有测试
npm test
# 单独测试
npm run test:mcp # 测试MCP协议功能
npm run test:temp # 测试临时目录管理
npm run test:cleanup # 测试临时文件清理
npm run test:path # 测试文件路径验证
```
### 测试覆盖
- ✅ COS服务基础功能验证
- ✅ MCP协议标准输出合规性
- ✅ 临时目录结构和管理
- ✅ 上传完成后资源清理
- ✅ 断点续传进度管理
- ✅ 异常情况资源回收
- ✅ 文件路径清理和中文支持
## 开发指南
### 项目结构
```
tx-cos-mcp/
├── index.js # MCP服务器主入口
├── src/
│ ├── cosService.js # COS SDK封装服务
│ ├── config.js # 配置管理
│ ├── uploadProgress.js # 上传进度管理
│ └── tempManager.js # 临时文件管理
├── test/ # 测试文件目录
│ ├── test.js # 基础功能测试
│ ├── test-mcp.js # MCP协议合规性测试
│ ├── test-temp.js # 临时目录管理测试
│ └── test-cleanup.js # 临时文件清理测试
├── config-examples/ # 配置示例
├── package.json # 项目配置
└── README.md # 项目文档
```
### 核心依赖
- `@modelcontextprotocol/sdk` - MCP 协议实现
- `cos-nodejs-sdk-v5` - 腾讯云 COS 官方 SDK
### 贡献指南
1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/new-feature`)
3. 提交更改 (`git commit -am 'Add new feature'`)
4. 推送分支 (`git push origin feature/new-feature`)
5. 创建 Pull Request
## 许可证
MIT License - 查看[LICENSE](LICENSE)文件了解详情。
## 支持与反馈
- 🐛 **问题反馈**: [GitHub Issues](https://github.com/156554395/tx-cos-mcp/issues)
- 💡 **功能建议**: [GitHub Discussions](https://github.com/156554395/tx-cos-mcp/discussions)
- 📧 **联系作者**: 156554395@qq.com