阿里云OSS MCP服务器

🚀 为阿里云OSS (Object Storage Service) 提供的MCP (Model Context Protocol) 服务器，支持完整的云存储操作功能。

✨ 特性

• 🔌 完整的OSS功能: 支持文件上传、下载、删除、列表等全部操作
• 📡 MCP协议支持: 基于stdio协议，与AI助手无缝集成
• ⚡ 高性能: 支持分片上传、并发操作和智能缓存
• 🔧 易于配置: 环境变量配置，支持配置热重载
• 🛡️ 安全可靠: 完善的错误处理、访问控制和审计日志
• 🔍 可观测性: 健康检查、性能监控和结构化日志
• 🧩 可扩展: 插件系统和中间件架构
• 📦 开箱即用: 支持npx一键运行

🚀 快速开始

1. 安装

# 全局安装
npm install -g aigroup-aliyunoss-mcp

# 或者使用 npx 临时运行
npx aigroup-aliyunoss-mcp --help

2. 配置OSS凭据

创建 .env 文件或设置环境变量：

# 阿里云OSS配置
OSS_ACCESS_KEY_ID=your_access_key_id
OSS_ACCESS_KEY_SECRET=your_access_key_secret  
OSS_BUCKET=your_bucket_name
OSS_REGION=oss-cn-beijing

# 可选配置
OSS_SECURE=true
OSS_TIMEOUT=300
FILE_EXPIRY_HOURS=1

3. 添加到MCP配置

编辑MCP设置文件 (如 Claude Desktop):

{
  "mcpServers": {
    "aigroup-aliyunoss-mcp": {
      "command": "npx",
      "args": ["aigroup-aliyunoss-mcp", "--stdio"],
      "env": {
        "OSS_ACCESS_KEY_ID": "your_access_key_id",
        "OSS_ACCESS_KEY_SECRET": "your_access_key_secret",
        "OSS_BUCKET": "your_bucket_name", 
        "OSS_REGION": "oss-cn-beijing"
      }
    }
  }
}

4. 验证安装

# 健康检查
npx aigroup-aliyunoss-mcp --health

# 查看帮助
npx aigroup-aliyunoss-mcp --help

# 验证配置
npx aigroup-aliyunoss-mcp --validate-config

🔧 配置详解

环境变量

获取阿里云OSS凭据

1. 登录 阿里云控制台
2. 创建或选择一个OSS存储桶
3. 在 RAM访问控制 中创建用户
4. 为用户分配OSS相关权限
5. 生成访问密钥对

📋 可用工具

💡 使用示例

基础文件操作

// 上传文件
{
  "tool": "uploadFile",
  "arguments": {
    "fileName": "documents/report.pdf",
    "file": "/local/path/to/report.pdf",
    "contentType": "application/pdf"
  }
}

// 生成临时下载链接
{
  "tool": "getObjectUrl", 
  "arguments": {
    "fileName": "documents/report.pdf",
    "expires": 3600
  }
}

// 列出文件
{
  "tool": "listObjects",
  "arguments": {
    "prefix": "documents/",
    "maxKeys": 50
  }
}

批量操作

// 批量删除文件
{
  "tool": "deleteMultipleObjects",
  "arguments": {
    "fileNames": [
      "temp/file1.txt",
      "temp/file2.txt", 
      "temp/file3.txt"
    ]
  }
}

分片上传大文件

// 自动分片上传
{
  "tool": "multipartUpload",
  "arguments": {
    "fileName": "videos/large-video.mp4",
    "filePath": "/local/path/to/large-video.mp4",
    "partSize": 5242880
  }
}

🔍 监控和诊断

健康检查

# 完整健康检查
npx aigroup-aliyunoss-mcp --health

# JSON格式输出
npx aigroup-aliyunoss-mcp --health --json

健康检查包括：

• ✅ 配置验证
• ✅ OSS连接测试
• ✅ 内存使用监控
• ✅ 依赖服务状态

日志记录

服务支持结构化JSON日志，输出到stderr：

{
  "timestamp": "2025-08-18T12:00:00.000Z",
  "level": "info",
  "component": "UploadTool", 
  "message": "文件上传成功",
  "fileName": "test.jpg",
  "size": 102400,
  "duration": 1250,
  "traceId": "abc123def456"
}

性能监控

• 响应时间: 每个工具调用的耗时统计
• 吞吐量: 文件传输速率监控
• 错误率: 操作失败率统计
• 资源使用: 内存和CPU使用率

🛠️ 开发和自定义

本地开发

# 克隆项目
git clone https://github.com/your-org/aigroup-aliyunoss-mcp.git
cd aigroup-aliyunoss-mcp

# 安装依赖
npm install

# 配置环境
cp .env.example .env
# 编辑 .env 文件

# 开发模式运行
npm run dev

插件开发

创建自定义插件扩展功能：

// plugins/my-plugin/index.ts
import { Plugin, PluginContext } from 'aigroup-aliyunoss-mcp';

export default class MyPlugin implements Plugin {
  metadata = {
    name: 'my-plugin',
    version: '1.0.0',
    description: '自定义插件',
    author: 'Your Name'
  };

  async onLoad(context: PluginContext) {
    context.logger.info('插件加载成功');
  }

  getTools() {
    return [{
      name: 'myCustomTool',
      description: '自定义工具',
      inputSchema: { /* zod schema */ },
      handler: async (args, context) => {
        // 工具逻辑
        return { success: true };
      }
    }];
  }
}

中间件开发

// 自定义中间件
const customMiddleware: MiddlewareDefinition = {
  name: 'custom-middleware',
  priority: 500,
  handler: async (context, next) => {
    // 前置处理
    console.log(`调用工具: ${context.toolName}`);
    
    await next();
    
    // 后置处理
    console.log(`工具执行完成`);
  }
};

🐛 故障排除

常见问题

1. OSS连接失败

错误: OSS_CONNECTION_ERROR

解决方案:

• 检查网络连接
• 验证OSS凭据是否正确
• 确认存储桶名称和地域设置
• 检查防火墙和代理设置

2. 权限不足

错误: OSS_PERMISSION_ERROR

解决方案:

• 检查RAM用户权限设置
• 确认存储桶访问权限
• 验证访问密钥是否有效

3. 文件上传失败

错误: FILE_UPLOAD_FAILED

解决方案:

• 检查文件路径是否正确
• 验证文件大小是否超出限制
• 检查文件类型是否被允许
• 增加超时时间配置

4. 配置无效

错误: CONFIG_INVALID

解决方案:

• 运行 npx aigroup-aliyunoss-mcp --validate-config
• 检查必需的环境变量
• 验证配置文件格式

调试模式

# 启用调试日志
MCP_LOG_LEVEL=debug npx aigroup-aliyunoss-mcp --stdio

# 查看详细错误信息
npx aigroup-aliyunoss-mcp --health --verbose

获取支持

• 📖 详细文档
• 🐛 问题反馈
• 💬 讨论社区
• 📧 邮件支持

🤝 贡献

欢迎贡献代码！请阅读 贡献指南 了解详情。

开发工作流

1. Fork 项目仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'feat: 添加新功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

代码规范

• 使用 TypeScript 严格模式
• 遵循 ESLint 和 Prettier 规则
• 编写单元测试覆盖新功能
• 更新相关文档

📄 许可证

本项目使用 MIT 许可证。

🙏 致谢

• Model Context Protocol - MCP协议规范
• 阿里云OSS - 对象存储服务
• ali-oss - 阿里云OSS SDK

Made with ❤️ by the aigroup-aliyunoss-mcp team