# 360 AI 云盘 MCP Server & CLI

360 AI 云盘的 MCP Server + CLI 工具，为 AI Agent 和开发者提供云盘文件管理能力。基于 TypeScript / Node.js 构建，包含两个产物：

- **360 AI 云盘 CLI** — 面向终端用户和 AI Agent（通过 Shell）的命令行工具，命令名 **`360disk`**，结构化 JSON 输出。
- **360 AI 云盘 MCP Server** — 面向支持 Model Context Protocol (MCP) 的 AI Agent（如 Claude Desktop、Cursor）的服务端，支持 Stdio / Streamable HTTP / SSE 三种传输方式。

## 快速开始

```bash
npm install          # 安装依赖
npm run build        # 构建
```

## MCP Server

在 MCP Client 配置文件中添加（适用于 Cursor、Claude Desktop 等）：

```json
{
  "mcpServers": {
    "360-ai-cloud-disk-mcp": {
      "command": "node",
      "args": ["build/index.js", "--stdio"],
      "env": {
        "API_KEY": "yunpan_xxxxxxxxxx"
      }
    }
  }
}
```

其他传输方式：

```bash
node build/index.js --stdio     # stdio 模式
node build/index.js --sse       # SSE 模式
node build/index.js --http      # Streamable HTTP 模式
```

### MCP 工具

| 工具 | 说明 |
|------|------|
| `file-list` | 获取目录文件列表 |
| `file-search` | 搜索文件 |
| `file-save` | 保存文件到云盘（URL / 文本内容） |
| `file-share` | 生成分享链接 |
| `file-move` | 移动文件或文件夹 |
| `file-rename` | 重命名文件或文件夹 |
| `make-dir` | 创建目录 |
| `get-download-url` | 获取下载链接 |
| `user-info` | 获取用户信息 |
| `file-upload-stdio` | 上传本地文件（仅 Stdio 模式） |
| `file-download-stdio` | 下载云盘文件（仅 Stdio 模式） |

## CLI

```bash
node build/cli.js --help

# 登录
node build/cli.js auth login --api-key yunpan_xxxxxxxxxx

# 常用操作
node build/cli.js dir ls /                       # 列出目录
node build/cli.js file search "报告"             # 搜索文件
node build/cli.js file upload ./report.pdf --dest /文档/   # 上传文件
node build/cli.js file download <nid> --dir ./   # 下载文件
node build/cli.js file share /文档/报告.pdf       # 分享文件
```

### CLI 命令

| 命令组 | 子命令 | 说明 |
|--------|--------|------|
| `auth` | `login` / `whoami` / `logout` | 鉴权管理 |
| `user` | `info` | 用户信息 |
| `dir` | `ls` / `mkdir` | 目录操作 |
| `file` | `mv` / `trans-copy` / `rename` / `rm` / `search` / `share` / `url` / `node-info` / `origin-size` / `clear-dir` / `config` / `save` / `append` / `exists` / `upload` / `download` | 文件操作 |
| `completion` | `install` / `uninstall` / `script` | Shell 补全 |

### CLI 特性

- **结构化输出**：默认 JSON，支持 `--format text` 和 `--quiet` 模式
- **统一错误码**：语义化错误码，进程退出码对应
- **管道集成**：stdin 输入、批量操作，可与 `jq` 等工具组合
- **超时/重试**：`--timeout` 和 `--retries` 全局选项
- **Shell 补全**：bash / zsh 自动补全

## 认证

使用前需要 360 AI 云盘 API 密钥（`yunpan_` 开头）。

鉴权优先级：`--api-key` 参数 > `API_KEY` 环境变量 > `~/.360disk/config.json`

## 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `API_KEY` | 云盘 API 密钥 | — |
| `ECS_ENV` | 环境 | `prod` |
| `SUB_CHANNEL` | 子渠道 | `open` |
| `LOG_LEVEL` | 日志级别 | `info` |

## 许可证

Apache-2.0