# 一粒云 MCP Server (V1)

> 标准化 MCP 协议暴露云盘文件搜索、读写、分享、标签等能力。
> 支持 Claude Desktop、Codex、Cursor、MateClaw 等所有 MCP 兼容 AI 客户端。
>
> **V1 策略**：全用现有云盘 API，云盘侧 zero-change。MCP Server 侧做文本提取和格式转换。
> V2 将新增专用 API（text-content / write-content / search 等）替代降级方案。

## 快速开始

### 前提条件

- Node.js ≥ 22
- pnpm ≥ 9
- 一粒云云盘服务运行中（默认 `http://localhost:8080`）

### 安装与启动

```bash
# 1. 安装依赖
pnpm install

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env，至少配置：
#   YLIYUN_API_BASE_URL=http://localhost:8080
#   MCP_API_KEYS=your-secret-key-here

# 3. 启动开发服务器（热重载）
pnpm dev
```

服务器启动后：
- MCP 端点：`http://localhost:18100/mcp`
- 健康检查：`http://localhost:18100/health`

### 验证 MCP Server

```bash
# 使用 MCP Inspector 测试
npx @modelcontextprotocol/inspector \
  --transport streamable-http \
  --url http://localhost:18100/mcp \
  --headers '{"Authorization": "Bearer your-api-key"}'
```

## 配置 AI 客户端

### Claude Desktop

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "yliyun": {
      "type": "streamable-http",
      "url": "https://ai.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <你的API Key>"
      }
    }
  }
}
```

### Codex

编辑 `~/.codex/mcp.json`：

```json
{
  "mcpServers": {
    "yliyun": {
      "transport": "streamable-http",
      "url": "https://ai.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <你的API Key>"
      }
    }
  }
}
```

### Cursor

编辑 `~/.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "yliyun": {
      "transport": "streamable-http",
      "url": "https://ai.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <你的API Key>"
      }
    }
  }
}
```

### MateClaw（内部集成）

在 MateClaw Admin → MCP Server 管理中添加：

```yaml
name: 一粒云云盘
transport: streamable_http
url: http://yliyun-mcp:18100/mcp
headers:
  X-Internal-Service: mateclaw
  X-Forward-User-Id: ${currentUserId}
  X-Forward-Tenant-Id: ${currentTenantId}
disclosureTier: full
```

## MCP Tools 列表（V1 — 14 个）

### 核心工具（12 个）

| Tool | 说明 | V1 云盘 API |
|---|---|---|
| `file.search` | 搜索文件 | `GET /cloud-drive/file/list?keyword=&recursive=true` ✅ |
| `file.read` | 读取文件内容 | `GET /cloud-drive/file/download` + MCP Server 本地提取文本 |
| `file.list` | 浏览目录 | `GET /cloud-drive/file/list` ✅ |
| `file.create` | 创建文件/目录 | `POST /cloud-drive/file/upload` + `/folder` ✅ |
| `file.save` | 保存更新 | `POST /cloud-drive/file-version/upload` ✅ |
| `file.move` | 移动/重命名 | `PUT /cloud-drive/file/move` + `/rename` ✅ |
| `file.delete` | 删除（回收站） | `DELETE /cloud-drive/file/delete` ✅ |
| `file.tag` | 标签管理 | `PUT /cloud-drive/file-tag/rel/save` ✅ |
| `file.share_link` | 创建分享 | `POST /cloud-drive/share-link/create` ✅ |
| `file.versions` | 版本历史 | `GET /cloud-drive/file-version/list` ✅ |
| `space.context` | 空间上下文 | `GET /cloud-drive/space/dept-list`（降级） |
| `user.profile` | 用户信息 | 认证上下文（降级） |

### 上下文窗口辅助工具（2 个）

| Tool | 说明 | 解决什么问题 |
|---|---|---|
| `file.grep` | 搜索文件内容（不加载全文） | 大文件内搜索关键词 → 只返回匹配行，省窗口 |
| `file.summarize` | 获取文件结构摘要 | 快速判断文件相关性 → 避免"读了才发现无关" |

## 开发

```bash
# 运行测试
pnpm test

# 类型检查
pnpm typecheck

# 代码检查
pnpm lint

# MCP Inspector 手动测试
pnpm inspect
```

## 项目结构

```
src/
├── index.ts           # 服务入口
├── server.ts          # FastMCP Server 配置
├── config.ts          # 环境变量配置
├── auth/              # 认证模块（Ticket/API Key/内部服务）
├── cloud-api/         # 云盘 HTTP API 客户端
├── tools/             # MCP Tool 实现（12个）
├── schemas/           # Zod Schema 定义
├── errors.ts          # 结构化错误定义
└── middleware/         # 速率限制、幂等控制、审计日志
```

## Docker 部署

```bash
# 构建
docker build -t yliyun-mcp-server:latest .

# 运行
docker run -d --name yliyun-mcp \
  -p 18100:18100 \
  -e YLIYUN_API_BASE_URL=http://yliyun-cloud:8080 \
  -e MCP_API_KEYS=your-production-key \
  yliyun-mcp-server:latest
```

## 云盘依赖（V1）

V1 全用现有 API，云盘 zero-change。需确认以下 API 可用：

| 确认项 | API | 用途 |
|---|---|---|
| Token 生成 | `POST /extends/user-token/get` | Ticket → OAuth2 Token |
| Token 校验 | `POST /system/oauth2/check-token` | 每次请求验权 |
| 文件列表 | `GET /cloud-drive/file/list` | 浏览 + 搜索 |
| 文件预览 | `GET /cloud-drive/file/preview` | 元数据 |
| 文件下载 | `GET /cloud-drive/file/download` | 下载文件（MCP Server 提取文本） |
| 文件上传 | `POST /cloud-drive/file/upload` | 创建文件 |
| 文件夹 | `POST /cloud-drive/file/folder` | 创建目录 |
| 重命名 | `PUT /cloud-drive/file/rename` | 重命名 |
| 删除 | `DELETE /cloud-drive/file/delete` | 移到回收站 |
| 移动 | `PUT /cloud-drive/file/move` | 移动文件 |
| 外链 | `POST /cloud-drive/share-link/create` | 创建分享 |
| 标签 | `PUT /cloud-drive/file-tag/rel/save` | 文件标签 |
| 版本 | `GET /cloud-drive/file-version/list` | 版本历史 |
| 版本上传 | `POST /cloud-drive/file-version/upload` | 文件更新 |
| 空间 | `GET /cloud-drive/space/dept-list` | 空间列表 |

## V2 云盘 API 补全计划

V1 稳定后，云盘侧新增以下 API 来提升 MCP Server 性能：

| API | 说明 |
|---|---|
| `GET /cloud-drive/file/text-content` | 云盘侧文本提取，MCP Server 不再需要下载文件 |
| `POST /cloud-drive/file/write-content` | 文本直写，MCP Server 不再需要构造 multipart |
| `GET /cloud-drive/file/search` | 全局全文搜索 |
| `GET /cloud-drive/space/context` | 空间统计和上下文 |
| `GET /extends/user/profile` | 用户信息和存储统计 |

## License

UNLICENSED — 内部项目