weiyun

Weiyun Cloud Drive MCP Skill

Version Update Check (must be performed before first use each day)

Before using this SKILL each day, perform an update check once, following these steps:

1. Check the current version version

Read the version field in the frontmatter at the top of this file; the format is MAJOR.MINOR.PATCH。

2. Check the latest version latest

Obtain the latest version information via the command latest, with the input parameter version being the current version obtained in the previous step:

mcporter call "https://www.weiyun.com/api/v3/mcpserver" "check_skill_update" --args '{"version": "当前版本"}'

Data is returned in JSON format. Example return parameters:

Field	Type	Description
`latest`	string	Latest version number, in the format MAJOR.MINOR.PATCH
`release_note`	string	Latest version release notes
`instruction`	string	Update instructions

3. Update the version

If the current version version is lower than the latest version latest, then follow the instruction instructions to update, or prompt the user to update.

Feature Overview

Provides complete file management capabilities for the Weiyun cloud drive via the MCP protocol, including 6 MCP Tools：

Tool Name	Function	Description
`weiyun.list`	Directory listing query	View files and subdirectories by directory, with pagination and sorting support
`weiyun.download`	Batch download	Batch retrieve HTTPS download links for files
`weiyun.delete`	Batch delete	Batch delete files or directories, with support for recycle bin or permanent deletion
`weiyun.upload`	File upload	Two-phase protocol: pre-upload + chunked upload, with instant upload support
`weiyun.gen_share_link`	Generate share link	Generate a short share link for a file or directory
`check_skill_update`	Skill version check and update	Check whether the current Skill version is the latest and obtain update instructions

Core Architecture Principles: File hash calculation and block_sha_list generationmust be completed on the client side/locally. The server only receives precomputed hash values; it does not receive raw file data to compute hashes. This design is intended to prevent massive requests from overwhelming the server's storage and CPU.

Detailed Reference Documentation：

Complete MCP API reference:references/mcp_api.md(detailed explanation of request/response fields for all Tools)
Upload protocol details:references/upload_protocol.md(two-phase upload, block SHA1 algorithm, check_sha/check_data calculation)

Trigger Scenarios

Use Weiyun MCP tools for file management (query, download, delete, upload, share)
Upload files to Weiyun: Prefer to use scripts/upload_to_weiyun.py to complete in one step, with no need to manually calculate parameters or call MCP
Implement or debug Weiyun MCP file upload (weiyun.upload Tool）
calculate block_sha_list、check_sha、check_data and other upload parameters
Understand the Weiyun two-phase upload protocol (pre-upload → chunked upload)
Check skill version updates (check_skill_update）
Debug FTN upload errors or SHA1 checksum mismatch issues

Interface Overview

1. weiyun.list — Directory listing query

Query the contents of a Weiyun drive directory, returning a list of subdirectories and files.

Request parameters：

Field	Type	Required	Description
get_type	uint32	No	Retrieval type: 0-all, 1-directories only, 2-files only
offset	uint32	No	Pagination start offset, starting from 0
limit	uint32	Yes	Number returned per page, maximum 50
order_by	uint32	No	Sort field: 0-no sorting, 1-by name, 2-by modification time
asc	bool	No	true-ascending, false-descending (default)
dir_key	string	No	The directory key to query (hex encoded); if empty, the dirkey bound to the token is used
pdir_key	string	No	The parent directory key to query (hex encoded); if empty, the pdirkey bound to the token is used

Response: returns pdir_key(parent directory key),dir_list(directory list),file_list(file list),finish_flag(whether retrieval is complete).

Note: Tencent Docs files are automatically filtered out and do not appear in the returned results.

2. weiyun.download — Batch download

Batch obtain HTTPS download links for Weiyun files.

Notes：

This feature cannot download files from Weiyun shared links; it can only download files in the user's Weiyun drive.

Request parameters：

Field	Type	Required	Description
items	McpDownloadFileItem[]	Yes	List of files to download

Each McpDownloadFileItem contains file_id(file ID) and pdir_key(directory key where it is located), both required.

Response: for each file returns file_id、https_download_url(download link),file_size(file size),cookie(cookie that must be included when downloading).

Permission verification: only files owned by the current user can be downloaded (directory ownership is determined via pdir_key ).

3. weiyun.delete — Batch delete

Batch delete files or directories in the Weiyun drive.

Request parameters：

Field	Type	Required	Description
file_list	McpDeleteFileItem[]	No	List of files to delete (`file_id` + `pdir_key`）
dir_list	McpDeleteDirItem[]	No	List of directories to delete (`dir_key` + `pdir_key`）
delete_completely	bool	No	false-move to recycle bin (default), true-permanently delete

Note：file_list and dir_list at least one must be filled in.

Response: returns freed_space(number of bytes of space freed) and freed_index_cnt(total number of files/directories deleted).

4. weiyun.gen_share_link — Generate share link

Generate a short share link for a Weiyun file or directory.

Request parameters：

Field	Type	Required	Description
file_list	McpShareFileItem[]	No	List of files to share (`file_id` + `pdir_key`）
dir_list	McpShareDirItem[]	No	List of directories to share (`dir_key` + `pdir_key`）
share_name	string	No	Share name; if not filled in, the first file or directory name will be used

Note：

file_list and dir_list At least one must be filled in.

Share links cannot be downloaded using this skill; the user must be prompted to open a webpage to download

⚠️ Key: pdir_key cannot be empty!

pdir_key must use weiyun.list The top-levelin the response pdir_key, not the file's own pdir_key field (which may be an empty string)
If an empty pdir_keyis passed, it may cause an abnormal share link,It is strongly recommendedthat the caller explicitly passes in the correct pdir_key
Incorrect example: directly use file_list[i].pdir_key(may be empty)
Correct example: use weiyun.list The top-level pdir_key field value of the response

Response: returns short_url(share short link) and share_name(share name).

5. weiyun.upload — file upload

Weiyun file upload usesa two-phase protocol：

Phase 1: pre-upload

Send file metadata and the chunk SHA1 list, check whether instant upload is possible, or obtain an upload channel.

Required fields：filename、file_size、file_sha、block_sha_list、check_sha Optional fields：file_md5、check_data、pdir_key

Key behavior：file_sha must equal block_sha_list the last value of , otherwise validation will fail.

Response judgment：

file_exist=true → instant upload successful, upload completed
file_exist=false → use the returned upload_key、channel_list、ex for multipart upload

Phase 2: multipart upload

According to the channel list returned by pre-upload, upload file data chunk by chunk.

Required fields：upload_key、channel_list、channel_id、ex、file_data、filename

Upload status：

1 = continue uploading the next chunk
2 = upload completed
3 = wait for other channels to complete

6. check_skill_update — skill version check update

Check whether the current Skill version is the latest; if there is a new version, return update instructions.

Request parameters：

Field	Type	Required	Description
version	string	Yes	Current Skill version number, format MAJOR.MINOR.PATCH

Response：

Field	Type	Description
latest	string	Latest version number, format MAJOR.MINOR.PATCH
release_note	string	Latest version release notes
instruction	string	Update instructions (follow these instructions when an update is needed)

Note: Before using this Skill for the first time each day, a version check must be performed once (see the "Version Update Check" section at the top of the document for details).

Chunk SHA1 calculation algorithm

This is the most core part of the upload feature. Weiyundoes not usethe standard independent chunk SHA1, but instead usesstreaming SHA1 internal state。

Algorithm steps (chunk size = 512KB = 524288 bytes)

Createashared SHA1 hash object
For each block except the last one:
- Read 524288 bytes and update() to the SHA1 object
- Extract the SHA1 internal registers (h0, h1, h2, h3, h4) tolittle-endianoutput
- Output as a 40-character hex string → the sha value of that block
For the last block (may be less than 524288 bytes):
- Continue updating the remaining data with the same SHA1 object
- sha value isthe standard SHA1 hexdigest of the entire file(big-endian, including finalization)

check_sha and check_data computation

Used for server-side tamper-proof verification:

lastBlockSize = file_size % 524288（若为 0 则取 524288）
checkBlockSize = lastBlockSize % 128（若为 0 则取 128）

check_sha：处理完所有非最后块后，继续 update 最后块中前 (lastBlockSize - checkBlockSize) 字节，
           然后取 SHA1 内部寄存器 h0-h4 小端序输出为 hex
check_data：文件末尾 checkBlockSize 字节的 Base64 编码

Usage Scripts

One-click Upload Script (Recommended)

Directly upload a local file to Weiyun, integrating the complete process of parameter computation + pre-upload + chunked upload:

# 基本用法
python3 scripts/upload_to_weiyun.py /path/to/file --token <mcp_token> --env_id <env_id>

# 指定上传目录
python3 scripts/upload_to_weiyun.py /path/to/file --token <mcp_token> --pdir_key <dir_key>

# 使用环境变量
export WEIYUN_MCP_TOKEN=<mcp_token>
export WEIYUN_ENV_ID=<env_id>
python3 scripts/upload_to_weiyun.py /path/to/file

Script parameters:

Parameter	Required	Description
`file_path`	Yes	Local file path (positional parameter)
`--token`	Yes	MCP token (or set the `WEIYUN_MCP_TOKEN` environment variable)
`--env_id`	No	Environment identifier (e.g. `sit-0cd15bb3`, or set `WEIYUN_ENV_ID`）
`--pdir_key`	No	Upload target directory key (if not provided, uses the directory bound to the token)
`--mcp_url`	No	MCP service address (default `https://www.weiyun.com/api/v3/mcpserver`）
`--max_rounds`	No	Maximum number of upload rounds (default 50)

Upload strategy: loop "pre-upload to obtain channel → upload one chunk → re-pre-upload" until complete. Each pre-upload automatically skips already successful chunks (offset increments with progress), supporting instant upload.

When used by an AI Agent: you only need to execute_command run this script, without manually computing block_sha_list or calling MCP.

Parameter Computation Script

Only computes upload parameters (does not perform upload), used for debugging or manually calling MCP:

python3 scripts/gen_block_info_list.py /path/to/file

Output includes:block_sha_list、file_sha、file_md5、check_sha、check_data、block_size、block_count。

Both scripts include a pure Python SHA1 implementation, supporting extraction of the internal state without finalization — this is something the Python standard library hashlib.sha1 cannot do.

Error Code Description

The MCP interface returns the following error codes when exceptions occur; callers can handle them accordingly based on the error code:

Error Code	Name	Description
117401	ERR_RATE_LIMIT	Daily call quota exhausted, please try again tomorrow
117402	ERR_MCP_TOKEN_INVALID	MCP token is invalid or expired, please regenerate the token
117403	ERR_MCP_PARAM_EMPTY	Required request parameters are empty (e.g. both file_list and dir_list are empty for the delete interface)
117404	ERR_MCP_PARAM_INVALID	Invalid request parameters (e.g. incorrect format of file_id or pdir_key)
117405	ERR_MCP_PERMISSION_DENIED	No permission to operate on files not in your own directory
117406	ERR_MCP_BACKEND_FAIL	Backend service call failed, please try again later

Handling Suggestions：

117401: Wait for the quota to reset automatically at midnight the next day, or subscribe to Weiyun membership to increase the quota
117402: Regenerate the token
117403/117404: Check whether the request parameters are complete and correctly formatted
117405: Confirm that the file/directory being operated on belongs to the current user
117406: This is a temporary server-side exception and can be retried

Common operation workflows

Workflow 1: Find and download a file

When you need to find a file in Weiyun and download it locally, follow these steps:

Step 1: Query the root directory

调用 weiyun.list，参数：limit=50, get_type=0

In the response, file_list contains files,dir_list contains subdirectories
Remember the top-level pdir_keyin the response (needed for subsequent downloads)
If the file is in the root directory → proceed to Step 3
If the file is not in the root directory → you need to traverse subdirectories (Step 2)

Step 2: Traverse subdirectories to find the file

调用 weiyun.list，参数：
  dir_key = <子目录的 dir_key>（从 dir_list 中获取）
  pdir_key = <子目录所在父目录的 pdir_key>（即上一次 list 响应顶层的 pdir_key，或子目录所在目录的 dir_key）
  limit = 50

⚠️ Key: When querying subdirectories, the meanings of dir_key and pdir_key are:

dir_key: the key of the target subdirectory to query (obtained from the dir_list in dir_key field)
pdir_key: the parent directory key where the subdirectory is located (obtained from the previous level's weiyun.list top-level pdir_key in the response)

If there are further nested subdirectories, repeat this step recursively.

Step 3: Obtain the download link

调用 weiyun.download，参数：
  items = [{"file_id": "<文件的 file_id>", "pdir_key": "<文件所在目录的 pdir_key>"}]

file_id: obtained from file_list obtained from
pdir_key: use weiyun.list in the responsetop-level pdir_key(not the file's own pdir_key field)

Step 4: Download the file locally

curl -s -L -o <本地文件名> -b "<cookie>" "<https_download_url>"

-L: follow redirects (required)
-b: carry cookies (obtained from the download response, in a format such as FTN5K=08bfd4be）
After the download is complete, verify that the file size matches file_size consistent

Workflow 2: Upload a file to Weiyun

Recommended method(one-click script):

# 1. 先查根目录获取 pdir_key
# 调用 weiyun.list limit=50 → 记住响应中的 pdir_key

# 2. 上传
python3 scripts/upload_to_weiyun.py /path/to/file --pdir_key <pdir_key>

Manual method: see the "5. weiyun.upload — File Upload" section above.

Workflow 3: Generate a share link

# 1. 先查目录获取文件信息和 pdir_key
调用 weiyun.list → 找到目标文件的 file_id，记住响应**顶层** pdir_key

# 2. 生成分享链接（pdir_key 必须非空！）
调用 weiyun.gen_share_link，参数：
  file_list = [{"file_id": "<file_id>", "pdir_key": "<响应顶层的 pdir_key>"}]
  share_name = "<文件名>"

⚠️ Key：pdir_key must use weiyun.list in the responsetop-level pdir_key, and you must never pass an empty string! The pdir_key field in a file item may be empty and must not be used.

Workflow 4: Delete a file

# 1. 先查目录获取文件信息
调用 weiyun.list → 找到目标文件的 file_id，记住响应顶层 pdir_key

# 2. 删除
调用 weiyun.delete，参数：
  file_list = [{"file_id": "<file_id>", "pdir_key": "<pdir_key>"}]
  delete_completely = false  （移到回收站，更安全）

Authentication mechanism

All MCP tools need to pass WyHeader via the HTTP header mcp_token：

WyHeader: mcp_token=<token>

Common questions

How should files be uploaded: directly use python3 scripts/upload_to_weiyun.py <文件路径> --pdir_key <目录key>, with no need to manually calculate parameters or call MCP
What should pdir_key be set to when downloading: use weiyun.list in the responsetop-level pdir_key, not the file's own pdir_key field (this field may be an empty string)
pdir_key cannot be empty when generating a share link: you must first call weiyun.list, and use the response'stop-level pdir_key(not file_list[i].pdir_key, which is usually empty).pdir_key being empty will cause the share link to open abnormally
What should pdir_key be set to when querying subdirectories: enter the key of the parent directory where the subdirectory is located. For a subdirectory under the root directory, this is the root directory's weiyun.list top-level pdir_key
Cookies need to be included when downloading：weiyun.download The returned download link needs to be used with curl -b "<cookie>" carrying the cookie value, and at the same time -L follow redirects
Upload reports "Cannot upload to a directory that you do not own": must specify the --pdir_key parameter. First call weiyun.list to obtain the top-level pdir_key
sharded upload channel len=0: after each round of uploading one shard, the returned channel list may all be len=0, and you need to re-pre-upload to obtain the next batch of channels.upload_to_weiyun.py has automatically handled this issue
SHA1 mismatch: ensure the chunk SHA value uses the streaming SHA1 internal state (little-endian), rather than an independent chunk SHA1
file_sha is overwritten: the server overwrites file_sha with the SHA of the last block — the two must be equal
Base64 double encoding: the MCP framework automatically converts the base64 string to bytes and passes it to the file_data field, and the server will perform Base64 decoding again
Channel ID mismatch: when uploading a shard, channel_id must match some entry in channel_list an entry in matches
Environment identifier: the SIT environment needs to carry in the Cookie env_id=sit-xxxxx
Permission verification: download, delete, and share operations will verify directory ownership; files not in your own directory will be skipped
Tencent Docs filtering: list queries will automatically filter out files of the Tencent Docs type
pip install requests: the upload script depends on the requests library; if it reports missing, please install it first:pip install requests
All operations that require pdir_key(download, delete, share, upload), should use the weiyun.list responsetop-level's pdir_key, rather than the file/directory entry's own pdir_key field

About this skill

Version Update Check (must be performed before first use each day)

1. Check the current version version

2. Check the latest version latest

3. Update the version

Feature Overview

Trigger Scenarios

Interface Overview

1. weiyun.list — Directory listing query

2. weiyun.download — Batch download

3. weiyun.delete — Batch delete

4. weiyun.gen_share_link — Generate share link

5. weiyun.upload — file upload

Phase 1: pre-upload

Phase 2: multipart upload

6. check_skill_update — skill version check update

Chunk SHA1 calculation algorithm

Algorithm steps (chunk size = 512KB = 524288 bytes)

check_sha and check_data computation

Usage Scripts

One-click Upload Script (Recommended)

Parameter Computation Script

Error Code Description

Common operation workflows

Workflow 1: Find and download a file

Workflow 2: Upload a file to Weiyun

Workflow 3: Generate a share link

Workflow 4: Delete a file

Authentication mechanism

Common questions