Nous SwapCloud Tool (stdio)

上传本地文件到交换存储（当前：Tencent COS），并返回临时下载链接（Signed URL）。
面向 MCP 客户端（Claude Code / Codex CLI / Gemini CLI / Cursor 等）的 stdio MCP server。

支持两种使用方式：

• MCP（stdio）：作为 MCP server 接入支持 MCP 的客户端，调用工具 swapcloud_upload
• Skill / CLI：直接运行 upload 子命令上传并输出 URL，适合“把大内容先上传，再把 URL 传给外部 API”

功能

• swapcloud_upload：上传本地文件并返回 signed download URL
• CLI：upload 子命令上传并输出 URL（不依赖 MCP 客户端）
• 点击兼容：自动将签名 URL 中的 ; 编码为 %3B，避免部分客户端点击时截断
• 配置零参数：自动按优先级加载 .env.*（.env.local 优先）
• 可选对象 TTL（天）：写入 object tag swapcloud_ttl_days=<days>，用于配合 COS 生命周期自动删除

依赖

• Node.js >= 20
• Tencent COS：Bucket + SecretId/SecretKey
• 权限建议：
  • 基础功能：PutObject + GetObject
  • 使用 objectTtlDays：额外需要 PutObjectTagging（tagging 失败会回滚删除已上传对象）

快速开始（npx）

1. 准备 COS 配置：环境变量或 .env.local（推荐）
2. 选择一种方式：
   • CLI：npx -y @gravtice/nous-swapcloud-tool upload --file ./path/to/file --expires 600
   • MCP：在 MCP 客户端添加本 server（见下方「MCP 客户端配置」），然后调用 swapcloud_upload

配置

配置文件优先级

.env.local > .env.production > .env.development > .env.test

默认会在「当前工作目录（process.cwd()）」和「包根目录」按上述优先级查找。

环境变量

必填：

• BACKEND=TENCENT_COS
• TENCENT_COS_REGION
• TENCENT_COS_BUCKET
• TENCENT_COS_SECRET_ID
• TENCENT_COS_SECRET_KEY

可选：

• TENCENT_COS_PREFIX：对象 Key 前缀（不带前导 /）

.env.local 示例：

BACKEND=TENCENT_COS
TENCENT_COS_REGION=ap-guangzhou
TENCENT_COS_BUCKET=swap-1250000000
TENCENT_COS_SECRET_ID=AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TENCENT_COS_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TENCENT_COS_PREFIX=swapcloud

注意：.env.local 包含密钥，已在 .gitignore 中忽略，不要提交到仓库。

运行

MCP server（stdio）：

npx -y @gravtice/nous-swapcloud-tool

CLI 上传（直接输出 URL，不依赖 MCP 客户端）：

npx -y @gravtice/nous-swapcloud-tool upload --file ./path/to/file --expires 600

如果你遇到 npm 镜像源未同步导致安装失败，可以强制使用官方 registry：

npx -y --registry=https://registry.npmjs.org/ @gravtice/nous-swapcloud-tool

Skill（nous-swapcloud-skill）

仓库内置一个 agent skill：skills/nous-swapcloud-skill/SKILL.md，基于 CLI nous-swapcloud-tool upload。

典型用途：

• 用户需要一个临时下载链接
• 需要调用外部 API 但内容太大：先把 JSON/日志/文本写成文件上传，再把 URL 传给外部 API

Claude Code

Claude Code 不需要安装 MCP 也能用（直接跑 CLI 即可）。

建议做法：

1. 把 skills/nous-swapcloud-skill/SKILL.md 放进你的工作仓库（或直接在本仓库使用）
2. 在对话里先让 Claude Code 读取该文件，然后按需上传（只返回 URL）

示例：

请先阅读 @skills/nous-swapcloud-skill/SKILL.md
然后把 ./README.md 上传，expires=600，只返回 URL

Codex CLI

1. 安装 skill（复制或软链）：

mkdir -p ~/.codex/skills
ln -s "$(pwd)/skills/nous-swapcloud-skill" ~/.codex/skills/nous-swapcloud-skill

2. 重启 Codex CLI 以加载 skill
3. 在 Codex 里直接描述需求即可（例如“把 ./out.json 上传并给我 10 分钟可下载链接”）

MCP 工具

swapcloud_upload

入参：

• filePath：本地文件路径（绝对/相对 cwd）
• expiresInSeconds：临时链接有效期（秒）
• objectTtlDays（可选）：对象 TTL（天）。Tencent COS 后端会写入 object tag：swapcloud_ttl_days=<days>

出参：临时下载链接（signed URL，纯文本）

TTL / 生命周期说明

• 链接 TTL：由 expiresInSeconds 控制（秒级）
• 对象 TTL：由 objectTtlDays 标记（天级），需要你在 COS 桶上配置生命周期规则才会自动删除
  • 仅想要“统一 TTL”：直接用 COS 生命周期按 TENCENT_COS_PREFIX 配一条规则即可，不必传 objectTtlDays
  • 想要“按对象 TTL”：为你需要的 swapcloud_ttl_days 值分别配置规则（COS 生命周期按天执行，可能有延迟）

生命周期规则配置要点（COS 控制台）：

• 过滤条件：对象标签 swapcloud_ttl_days=<days>
• 过期操作：删除，天数为 <days>
• 注意：如果你传了 objectTtlDays 但桶里没有对应规则，对象不会自动删除；COS 生命周期不支持秒级 TTL

常见问题

点击临时链接提示「没有权限 / AccessDenied」

Tencent COS 的签名 URL 参数里包含时间范围（形如 q-sign-time=START;END）。某些客户端会在 ; 处截断，导致签名参数不完整从而 403。

• 本项目输出会把 ; 编码为 %3B，正常情况下可直接点击
• 仍然 403：检查密钥是否具备 GetObject 权限（仅有 PutObject 也会导致下载被拒绝）

sh: nous-swapcloud-tool: command not found

通常是 npx 没有成功安装/解析该包（常见原因：本机 npm registry 指向镜像源但镜像未同步新包）。

• 临时：给 npx 增加 --registry=https://registry.npmjs.org/（见下方示例）
• 永久：在 ~/.npmrc 添加 @gravtice:registry=https://registry.npmjs.org/

MCP 客户端配置

通用 JSON（多数 MCP 客户端）

{
  "mcpServers": {
    "swapcloud": {
      "command": "npx",
      "args": ["-y", "--registry=https://registry.npmjs.org/", "@gravtice/nous-swapcloud-tool"],
      "env": {
        "BACKEND": "TENCENT_COS",
        "TENCENT_COS_REGION": "ap-guangzhou",
        "TENCENT_COS_BUCKET": "swap-1250000000",
        "TENCENT_COS_SECRET_ID": "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "TENCENT_COS_SECRET_KEY": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

如果你不需要强制使用官方 registry，可以从 args 里移除 --registry=https://registry.npmjs.org/。

如果你想用 .env.local（不在配置里写密钥），需要 MCP 客户端支持设置该 server 的 cwd，并让 cwd 指向包含 .env.local 的目录。

Claude Code CLI

claude mcp add --transport stdio \
  -e BACKEND=TENCENT_COS \
  -e TENCENT_COS_REGION=ap-guangzhou \
  -e TENCENT_COS_BUCKET=swap-1250000000 \
  -e TENCENT_COS_SECRET_ID=AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -e TENCENT_COS_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  swapcloud -- npx -y --registry=https://registry.npmjs.org/ @gravtice/nous-swapcloud-tool

如果你看到 Invalid environment variable format: swapcloud，通常表示 CLI 版本要求用 -e KEY=value 方式传环境变量，并且需要保留 -- 分隔符。

Codex CLI（~/.codex/config.toml）

[mcp_servers.swapcloud]
command = "npx"
args = ["-y", "--registry=https://registry.npmjs.org/", "@gravtice/nous-swapcloud-tool"]

[mcp_servers.swapcloud.env]
BACKEND = "TENCENT_COS"
TENCENT_COS_REGION = "ap-guangzhou"
TENCENT_COS_BUCKET = "swap-1250000000"
TENCENT_COS_SECRET_ID = "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
TENCENT_COS_SECRET_KEY = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Gemini CLI（~/.gemini/settings.json）

{
  "mcpServers": {
    "swapcloud": {
      "command": "npx",
      "args": ["-y", "--registry=https://registry.npmjs.org/", "@gravtice/nous-swapcloud-tool"],
      "env": {
        "BACKEND": "TENCENT_COS",
        "TENCENT_COS_REGION": "ap-guangzhou",
        "TENCENT_COS_BUCKET": "swap-1250000000",
        "TENCENT_COS_SECRET_ID": "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "TENCENT_COS_SECRET_KEY": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor（.cursor/mcp.json）

{
  "mcpServers": {
    "swapcloud": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "--registry=https://registry.npmjs.org/", "@gravtice/nous-swapcloud-tool"],
      "env": {
        "BACKEND": "TENCENT_COS",
        "TENCENT_COS_REGION": "ap-guangzhou",
        "TENCENT_COS_BUCKET": "swap-1250000000",
        "TENCENT_COS_SECRET_ID": "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "TENCENT_COS_SECRET_KEY": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

License

Apache-2.0（见 LICENSE）