Yifangyun Mcp Server

亿方云 OpenAPI 的 MCP Server。当前版本定位为 OpenAPI-first 的 Cloud Authority Server：

• 默认暴露只读 authority 能力
• 写操作与管理员操作按环境变量显式开启
• 默认不暴露 download_url
• 支持把原件下载到本地临时目录并计算 sha256
• 支持可恢复、可取消、带 checkpoint 和 page receipt 的大目录扫描
• 支持本地 stdio 和受保护的 Streamable HTTP transport

核心特性

特性	说明
企业 JWT 默认认证	使用 grant_type=jwt_simple 换取企业 token 和用户 token
OpenAPI-first	以亿方云官方 OpenAPI 路径为主，不做脱离官方能力面的私有协议
分层能力面	只读 authority + 受控 mutation/admin
Authority 工具	folder/file info、versions、ancestors、scope assert、snapshot、download+hash
本地下载落地	按 access identity 下载文件到 temp，返回 temp_path + sha1 + sha256 + size_bytes
安全默认值	download_url 默认不注册，mutation/admin 默认不注册
私有化部署适配	支持 https://host/openapi 和 https://host/openapi/api 两类地址配置
统一响应	所有工具统一返回 ok/data/meta/warnings/raw? 结构
限流元数据	返回 request_id、source_api_version、X-Rate-Limit-* 摘要
Durable scan	start / advance / status / search / cancel，进程重启后可恢复
完整性边界	明确返回 pagination_complete、safe_to_claim_absence、incomplete_reasons

主要能力

核心能力

这部分默认开启，适合做文件定位、范围校验、版本核对和原件锁定：

• yfy_get_folder_info
• yfy_get_file_info
• yfy_get_file_info_full
• yfy_get_file_versions
• yfy_get_file_version_info
• yfy_get_folder_ancestors
• yfy_get_file_ancestors
• yfy_assert_file_in_scope
• yfy_get_file_scope_membership
• yfy_validate_authority_root
• yfy_download_file_to_temp
• yfy_download_and_hash
• yfy_verify_file_current_version
• yfy_lock_current_original

扩展只读能力

这部分默认也会开启，适合做目录快照、批量回源、路径解析、协作与组织信息查询：

• yfy_start_scope_scan
• yfy_advance_scope_scan
• yfy_get_scope_scan
• yfy_cancel_scope_scan
• yfy_search_scope_snapshot
• yfy_list_scope_scan_matches
• yfy_list_scope_snapshot_items
• yfy_build_scope_snapshot
• yfy_list_folder_tree
• yfy_search_items_recursive
• yfy_batch_get_file_info
• yfy_resolve_path
• yfy_search_items
• yfy_search_items_advanced
• yfy_get_share_links
• yfy_get_comments
• yfy_list_collab_items
• yfy_get_folder_collabs
• yfy_list_groups
• yfy_get_group_users
• yfy_get_user_by_query

搜索定位建议：精确路径优先 yfy_resolve_path；官方索引搜索使用 yfy_search_items_advanced，但其结果仅用于候选发现；需要大目录遍历、恢复或缺失结论时使用 durable scope scan。yfy_search_items_recursive、yfy_build_scope_snapshot 和 yfy_list_folder_tree 保留为小目录兼容工具。

可选写入与管理员能力

这部分默认关闭。只有在显式开启对应环境变量后，才会注册：

• yfy_create_folder
• yfy_update_file
• yfy_update_folder
• yfy_move_item
• yfy_copy_item
• yfy_delete_item
• yfy_restore_item
• yfy_upload_file
• yfy_upload_file_by_path
• yfy_upload_new_version
• yfy_manage_collab
• yfy_admin_departments
• yfy_admin_groups
• yfy_admin_users
• yfy_admin_logs
• yfy_admin_sync

底层能力说明

为了支撑上面的工具，服务内部已经实现：

• 统一 GET/POST JSON 请求内核
• token 缓存和提前刷新
• 429/5xx 自动退避
• 非幂等 POST 不自动重试
• Provider 并发上限、带 jitter 的退避和 token singleflight
• 本地 temp 下载与 sha256 计算
• 预签名上传地址后的本地文件投递

安全默认值

环境变量	默认值	说明
YFY_ALLOW_DOWNLOAD_URL	disabled	关闭后不注册 yfy_get_download_url
YFY_ENABLE_MUTATION_TOOLS	disabled	关闭后不注册任何写工具
YFY_ENABLE_ADMIN_TOOLS	disabled	关闭后不注册任何 admin 工具
YFY_ENABLE_RAW_RESPONSE	disabled	关闭后工具不回传原始响应体
YFY_MAX_DOWNLOAD_BYTES	268435456	默认最大下载 256 MiB

快速开始

npm install
npm run build

最小公有云配置：

YFY_CLIENT_ID=your-client-id
YFY_CLIENT_SECRET=your-client-secret
YFY_ENTERPRISE_ID=115
YFY_DEFAULT_USER_ID=530

私有化部署再覆盖地址：

YFY_OPENAPI_BASE_URL=https://qiyeyun.example.com/openapi
YFY_OAUTH_BASE_URL=https://qiyeyun.example.com/openoauth

# 如果部署直接暴露 /openapi/api，可改用：
# YFY_API_BASE_URL=https://qiyeyun.example.com/openapi/api

启动 stdio MCP：

npm start

MCP 客户端配置示例

{
  "mcpServers": {
    "yifangyun": {
      "command": "node",
      "args": ["/path/to/yifangyun-mcp/dist/index.js"],
      "env": {
        "YFY_CLIENT_ID": "your-client-id",
        "YFY_CLIENT_SECRET": "your-client-secret",
        "YFY_ENTERPRISE_ID": "115",
        "YFY_DEFAULT_USER_ID": "530"
      }
    }
  }
}

权限模型

亿方云 OpenAPI 仍然有两个权限平面：

权限平面	Token	适用接口
企业管理	企业 token	部门、管理员、同步、日志
云盘访问	用户 token	文件夹、文件、搜索、版本、下载、协作

即使某个账号是云盘管理员，也不要假设企业 token 能直接访问文件接口。文件访问工具默认使用 YFY_DEFAULT_USER_ID，或根据 YFY_FILE_ACCESS_USER_STRATEGY 走 admin/explicit 策略。

典型调用链

锁定当前原件

yfy_assert_file_in_scope(file_id, root_folder_id)
  -> 证明文件属于授权根目录
yfy_lock_current_original(file_id, root_folder_id)
  -> 返回 metadata + temp_path + sha256

构建目录快照

yfy_start_scope_scan(root_folder_id, queries=[...])
  -> scan_id + revision=0
  -> 重复调用直到 complete 或 partial
  -> 基于本地 page artifacts 搜索，不重复遍历 Provider

受控上传新版本

设置 YFY_ENABLE_MUTATION_TOOLS=enabled
yfy_upload_new_version(file_id, local_path="/path/to/file")
  -> OpenAPI 申请 presign_url
  -> 本地字节上传
  -> 返回 current_file

开发命令

npm run build
npm test
npm run dev

详细文档

文档	内容
配置说明	环境变量、能力开关、私有化部署地址、运行保护参数
工具参考	当前工具分组、推荐使用方式、默认暴露策略
OpenAPI 覆盖矩阵	当前 MCP 对官方 OpenAPI 的覆盖范围、部分覆盖项与明确不在范围内的域
部署指南	本地运行、MCP 客户端接入、GitHub 安装建议
架构与安全	架构分层、认证流程、安全默认值、下载与写操作边界
v0.4 迁移说明	durable scan、scope assert、projection 和弃用策略

版本状态

当前包版本：0.4.0。

当前版本增加 durable scan、完整性语义、字段投影、下载漂移复核、统一错误码、可观测性和 Streamable HTTP。