yifangyun-mcp-server

亿方云 OpenAPI 的 MCP Server。当前版本 1.1.0-beta.3。

默认能力：网盘浏览、检索、元数据读取、受控下载。可选启用 Workspace（业务范围约束）和 Inventory（完整目录清单与缺失审计）。

能力边界（必读）

Related MCP server: Yuque MCP Server

核心工具

按需 toolset：organization、collaboration、mutation、admin、transfer。 写操作与 Provider transfer URL 默认均不注册。

术语速查（文档中常见难词）

推荐下载流程

已知精确路径：

1. yfy_resolve({ path, from })

2. yfy_get({ ref })

3. yfy_download({ file })

4. Host 打开 download.local_path，或带认证 GET download.fetch_url

5. （可选）yfy_download_release({ download_id })

限制在 Workspace 内下载：

1. yfy_workspace_validate({ workspace })

2. 在同一 Workspace 内 resolve / browse 得到目标文件

3. yfy_download({ workspace, file, version?, expected? })

传入 workspace 后，服务会在下载前、后各做一次 membership 校验。结果为 outside 或 unavailable 时不会返回可用文件。

历史版本： 必须原样复制 yfy_versions 返回的 VersionRef。当前版请省略 version，不要自行构造“当前版”引用。

批量 ZIP： yfy_download_batch({ items, workspace?, expected? }) 接受 1-20 个同一非外协访问身份下的 FileRef/FolderRef。20 是本服务的请求放大保护上限，不是 Provider OpenAPI 上限。它只打包当前内容，不接受 VersionRef；服务校验 ZIP 中央目录、成员路径和本地文件头，并返回成员数、展开总大小及整个归档的哈希。该校验不证明 Provider 已包含每个文件夹的全部语义内容，调用方应避免同时传入文件夹及其子项。

stdio 与 HTTP

• stdio 不启动 HTTP staged 服务，因此必须 YFY_DOWNLOAD_EXPOSE_LOCAL_PATH=enabled。

• HTTP 可同时开启 path 与 staged URL；远程部署通常只开放 fetch_url。

staged 路由：

GET /staged/v1/{download_id}/{optional_file_name}

与 /mcp 共用 Bearer、Host、Origin 防护。URL 过期、显式 release、完整性校验失败，或抓取次数用尽后均不可用。 每个 staged GET 还受 YFY_DOWNLOAD_WALL_TIMEOUT_MS 限制；慢客户端不能无限占用读租约或阻塞关闭。

最小配置

YFY_CLIENT_ID=your-client-id
YFY_CLIENT_SECRET=your-client-secret
YFY_ENTERPRISE_ID=115
YFY_DEFAULT_USER_ID=530
YFY_TOOLSETS=drive
YFY_TRANSPORT=stdio

招投标（Tender）工作流：

YFY_TOOLSETS=drive,workspace,inventory
YFY_WORKFLOW_PROFILES=tender
YFY_WORKSPACES_JSON=[{"id":"tender_public","root_folder_id":"501000000000","access_context":"default","tags":["tender"]}]

远程 HTTP 示例：

YFY_TRANSPORT=http
YFY_HTTP_HOST=0.0.0.0
YFY_HTTP_PORT=3000
YFY_HTTP_BEARER_TOKEN=replace-with-a-long-random-token
YFY_HTTP_ALLOWED_HOSTS=mcp.example.com
YFY_HTTP_ALLOWED_ORIGINS=https://agent.example.com
YFY_DOWNLOAD_EXPOSE_LOCAL_PATH=disabled
YFY_DOWNLOAD_STAGED_HTTP=enabled
YFY_DOWNLOAD_STAGED_MAX_CONCURRENT_READS=20
YFY_DOWNLOAD_STAGED_PUBLIC_BASE_URL=https://mcp.example.com

非回环监听，或 staged 对外 base URL 指向远程主机时：必须配置 Bearer、允许的 Host 与 Origin。 staged 响应从受保护本地文件句柄单遍流式输出；默认并发读 20，硬上限 40。生产建议由反向代理终止 TLS。

Provider 请求默认：同一访问身份并发 20，全局并发 40。预签名文件下载按身份单独限流，避免单身份占满全局容量。

Inventory 的 SQLite 在专用 Worker 线程中运行。Worker 异常退出后，新的 Inventory 请求会立即失败；服务关闭不会等待已失效的 RPC。

临时存储

下载中与已登记下载共用 YFY_MAX_TEMP_BYTES。服务不会为腾出空间而删除尚未过期的旧下载；空间不足返回 YFY_LOCAL_STORAGE_INSUFFICIENT。

YFY_TEMP_DIR 下由服务独占管理：

启动时：先清理已过期或无效的 download，再对仍有效文件做配额校验。 release 仅在物理删除成功后才成功并扣减配额；删除失败会返回错误，不会假成功。

不要把 YFY_STATE_DB 或其他业务文件放进 artifacts/、downloads/。

运行与验证

npm ci
npm run build
npm test
npm run test:perf
npm pack --dry-run

启动（需 Node.js >=24）：

# 本地构建产物 + 项目根 .env
node --env-file=.env dist/index.js

HTTP 模式（npx，跨平台）

需检出本仓库（脚本不随全局 npm 包分发）。无需本地 npm install 业务依赖、无需 build，通过 npx 拉发布包启动：

# 1) 准备脚本同目录环境文件
cp scripts/http.env.example scripts/.env   # Windows: Copy-Item scripts\http.env.example scripts\.env
# 编辑 scripts/.env，填写 Client ID/Secret 等，并保持 YFY_TRANSPORT=http

# 2) 启动（默认读 scripts/.env）
node scripts/start-npx.mjs
# 或: npm run start:http:npx

# 指定其它 env 文件（优先级更高）
node scripts/start-npx.mjs --env-file ./http.prod.env

本机验证：curl http://127.0.0.1:3000/health（若 YFY_HTTP_HOST=0.0.0.0，仍用 127.0.0.1 探测）。完整说明见 部署指南 · HTTP 模式启动。

文档索引