aliyun-oss-mcp-server

一个本地（stdio）MCP 服务器，让 LLM Agent 能把本地文件批量上传到阿里云 OSS，并对上传结果进行查看、删除与获取访问 URL。

核心诉求是「批量上传」；list / delete / URL 作为配套原语，让 Agent 能自我验证与管理上传结果。

⚠️ 开发状态：早期开发阶段（v0.1.0）。核心模块（配置、路径解析、URL 生成、OSS 封装、上传工具）与服务器入口 src/index.ts 均已实现并有测试覆盖，可作为 stdio MCP 服务器直接运行；oss_list_objects / oss_delete_objects / oss_get_object_url 尚在规划中，且尚未发布到 npm。详见文末开发状态与路线图。

特性

• 📦 批量上传：一次传入「文件 / 目录 / glob 模式」的任意混合（如 dist/**/*.js），自动展开并计算远程 key。
• 🧮 智能 key 计算：目录相对自身、glob 相对其静态前缀、单文件取 basename；统一 / 分隔、去前导 /、拒绝 .. 逃逸。
• 🚦 有界并发 + 容错：默认并发 5（可配 1–20），逐文件收集成败，单个失败不中断整批。
• 🔤 文本文件自动带 charset：text/*、application/json 等文本类文件在未显式指定 Content-Type 时自动追加 ; charset=utf-8，避免浏览器直接打开时因编码猜测错误而乱码。
• 🔗 灵活 URL 策略：auto（公开 bucket 直链 / 私有 bucket 签名 URL）/ public / signed，支持自定义 CDN 域名。
• 🧪 dryRun 预览：先返回 localPath → key 规划再决定是否真正上传，降低误操作。
• 🧰 结构化输出：每个工具都返回 structuredContent（结构化数据）+ 人类可读文本摘要。

环境要求

• Node.js ≥ 18
• pnpm ≥ 10（本仓库使用 pnpm，已在 package.json 的 packageManager 字段固定版本）
• 一个阿里云 OSS Bucket 及其 AccessKey

安装

pnpm install
pnpm build

配置

本服务器完全通过环境变量读取配置，不使用 .env 文件。 代码直接从 process.env 读取（src/config.ts 用 zod 校验），缺少必填项会「快速失败」并打印清晰指引后退出。

| 变量 | 必填 | 默认 | 说明 | |---|:---:|---|---| | OSS_ACCESS_KEY_ID | ✅ | — | AccessKey ID | | OSS_ACCESS_KEY_SECRET | ✅ | — | AccessKey Secret | | OSS_REGION | ✅ | — | 如 oss-cn-hangzhou | | OSS_BUCKET | ✅ | — | 目标 Bucket 名称 | | OSS_ENDPOINT | ⬜ | — | 自定义 / 内网 endpoint（覆盖 region 推导） | | OSS_CUSTOM_DOMAIN | ⬜ | — | 绑定的 CDN / 自定义域名，用于拼公开 URL | | OSS_URL_MODE | ⬜ | auto | URL 策略：auto / public / signed | | OSS_SIGNED_URL_EXPIRES | ⬜ | 3600 | 签名 URL 默认有效期（秒） | | OSS_SECURE | ⬜ | true | 是否使用 https |

🔒 凭证仅从环境变量读取，绝不硬编码、绝不写入日志。请通过 MCP 客户端配置或 CI/CD 的密钥管理注入，切勿提交到版本库。

在 MCP 客户端中使用

MCP 服务器由客户端拉起，环境变量在客户端配置的 env 块中注入——这正是不再需要 .env 文件的原因。

以 Claude Desktop 为例，在其 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "aliyun-oss-mcp-server": {
      "command": "npx",
      "args": ["-y", "aliyun-oss-mcp-server"],
      "env": {
        "OSS_ACCESS_KEY_ID": "your-access-key-id",
        "OSS_ACCESS_KEY_SECRET": "your-access-key-secret",
        "OSS_REGION": "oss-cn-hangzhou",
        "OSS_BUCKET": "your-bucket"
      }
    }
  }
}

该配置用 npm 包名启动：npx -y aliyun-oss-mcp-server 会自动拉取并运行（package.json 已声明 bin，入口已装配完成）。该 npx 方式需本包发布到 npm 后方可生效；发布前可改用本地路径运行（见本地开发与用 MCP Inspector 调试）。

工具

所有工具均以 zod 定义 inputSchema / outputSchema；key 一律 / 分隔、去前导 /、拒绝 .. 逃逸。

oss_upload_files — 批量上传（核心）✅

把本地文件 / 目录 / glob 批量上传，逐文件返回 key 与 URL；单个失败不影响其余。

| 参数 | 类型 | 说明 | |---|---|---| | paths | string[] 必填 | 每项可为文件 / 目录 / glob（如 dist/**/*.js），可混合 | | prefix | string? | 远程 key 前缀，如 uploads/2026/ | | baseDir | string? | 计算相对 key 的基准目录，覆盖默认推导 | | concurrency | number? | 并发数，默认 5，范围 1–20 | | signedUrlExpires | number? | 给出则返回签名 URL（秒），覆盖 URL 模式 | | headers | Record<string,string>? | 透传 OSS 头，如 Cache-Control、x-oss-object-acl | | dryRun | boolean? | 仅返回 localPath → key 规划，不实际上传 |

返回：uploaded[]、failed[]、summary（total / succeeded / failed / totalBytes / conflicts / dryRun）。

oss_upload_file — 单文件精确上传 ✅

把一个本地文件上传到显式指定的远程 key。

| 参数 | 类型 | 说明 | |---|---|---| | path | string 必填 | 本地文件路径 | | key | string 必填 | 显式远程对象 key | | headers | Record<string,string>? | 透传 OSS 头 | | signedUrlExpires | number? | 给出则返回签名 URL（秒） |

返回：{ key, url, size, etag }。

规划中的工具 🚧

以下工具已在设计中确定，尚未实现：

• oss_list_objects（只读）— 按 prefix 列举对象，支持分页与 delimiter 目录视图。
• oss_delete_objects（破坏性）— 批量删除 key，支持 dryRun 预览。
• oss_get_object_url（只读）— 按 key + mode / expires 获取访问 URL。

本地开发

pnpm dev      # tsx 直接运行 src/index.ts（需先在 shell 中导出上表环境变量）
pnpm build    # tsc 编译到 dist/
pnpm test     # vitest 运行全部单元测试

本地运行时可在 shell 中导出环境变量：

export OSS_ACCESS_KEY_ID=... OSS_ACCESS_KEY_SECRET=... OSS_REGION=oss-cn-hangzhou OSS_BUCKET=...
pnpm dev

如果偏好用文件管理本地变量，可自行使用 Node 内置的 node --env-file=.env.local ...，本项目不再内置 .env 也不依赖 dotenv。

用 MCP Inspector 调试

pnpm build
npx @modelcontextprotocol/inspector node dist/index.js

Inspector 会启动一个可视化界面，可逐个工具填参手测（记得在其环境变量面板中填入 OSS 凭证）。

项目结构

src/
├── index.ts          # 入口薄壳：读配置 → 构建 ctx → 连接 stdio transport（fail-fast）
├── server.ts         # buildServer(ctx)：创建 McpServer 并注册上传工具
├── config.ts         # zod 校验环境变量，缺失即快速失败
├── oss-client.ts     # 封装 ali-oss：客户端工厂 + put/list/delete/signatureUrl + ACL 缓存
├── file-resolver.ts  # 【核心纯逻辑】paths[] → [{ localPath, key, size }]
├── url.ts            # 按 config + key + mode/expires 生成对象 URL
├── errors.ts         # 把 ali-oss / fs 错误映射成可操作的提示
└── tools/
    └── upload.ts     # oss_upload_files + oss_upload_file
test/                 # 与 src 对应的 vitest 单元测试

开发状态与路线图

• ✅ 已实现并测试：config / file-resolver / url / oss-client / errors / 上传工具（oss_upload_files、oss_upload_file）；服务器入口 src/index.ts + src/server.ts（创建 McpServer、注册工具、连接 stdio transport，配置缺失即 fail-fast）。
• 📋 待办：oss_list_objects / oss_delete_objects / oss_get_object_url 三个工具；冒烟脚本 scripts/smoke.ts（package.json 已声明 smoke 脚本但文件尚未创建）。

安全

• 凭证仅从环境变量读取，绝不硬编码、绝不日志输出。
• .gitignore 已排除 node_modules、dist、.env、*.log。
• 上传 / 删除属敏感操作：提供 dryRun 预览、破坏性标注与明细返回，降低误操作。
• key 规范化拒绝 .. 逃逸，避免意外覆盖非预期路径。

许可证

尚未指定开源许可证（建议在发布前补充，如 MIT）。