yifangyun-mcp-server

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

• 默认暴露只读 authority 能力

• 写操作与管理员操作按环境变量显式开启

• 默认不暴露 download_url

• 支持把原件下载到本地临时目录并计算 sha256

核心特性

Related MCP server: Yuque MCP Server

主要能力

核心能力

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

• 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_download_file_to_temp

• yfy_download_and_hash

• yfy_verify_file_current_version

• yfy_lock_current_original

扩展只读能力

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

• 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；已知 folder scope 且希望继续走官方索引时优先 yfy_search_items / yfy_search_items_advanced 并传 search_in_folder；只有在已知 root_folder_id 且需要对子树后代名称做有界递归搜索时，再使用 yfy_search_items_recursive。

可选写入与管理员能力

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

• 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 自动退避

• 本地 temp 下载与 sha256 计算

• 预签名上传地址后的本地文件投递

安全默认值

快速开始

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 能直接访问文件接口。文件访问工具默认使用 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_build_scope_snapshot(root_folder_id, max_depth=3, max_items=1000)
  -> 返回 root_folder + folders[] + files[] + stats

受控上传新版本

设置 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

详细文档

版本状态

当前包版本：0.3.0。

这次实现把仓库从“只读目录检索 + 下载链接返回”升级成了“authority 优先、OpenAPI-first、写能力显式开关”的 MCP Server。