一粒云 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）

安装与启动

# 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

# 使用 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：

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

Codex

编辑 ~/.codex/mcp.json：

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

Cursor

编辑 ~/.cursor/mcp.json：

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

MateClaw（内部集成）

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

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	获取文件结构摘要	快速判断文件相关性 → 避免"读了才发现无关"

开发

# 运行测试
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 部署

# 构建
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 — 内部项目