com.stagenth/file-relay

Official26 tools

stagenth · file-relay

Cloud file relay: chunked uploads, folders, share links, inline text reads, ZIP packing.

Cloud file transfer service with chunked uploads, sharing, and ZIP packing.

file uploadfile transfercloud storageshare linkszip compressionchunked upload

Captured live from the server via tools/list.

get_user_quota

查看当前用户的存储配额使用情况。

No parameters.

list_files

列出当前用户的文件 (默认递归遍历整个文件夹层级). 返回值同时附带 ``subfolders``(直接子文件夹列表) 与 ``has_subfolders`` 提示, 帮助 AI 感知层级结构。若用户问“目录结构 / 树”, 直接调 ``get_folder_tree`` 拿到 ASCII 树状图更直观。每个 item 都有 ``folder_path`` 字段标注它的实际归属, 同名文件不会因递归而混淆。

Parameters (6)

categoryany
按分类过滤：audio/video/image/text/code/document/archive/other
searchany
按文件名或描述搜索
folder_pathstring
目标文件夹路径, 形如 '/' 或 '/工作/项目A'。默认 '/' 列根目录。用 list_folders 探查可用路径。
recursiveboolean
True (默认) = 深度遍历, 返回该路径及所有后代文件夹下的全部文件; False = 仅列直接子文件 (类似 'ls'). 用户问“都有什么文件”时一律保持 True.
pageinteger
sizeinteger

search_files

在当前用户的所有文件中搜索。

Parameters (2)

querystringrequired
搜索关键词（文件名或描述）
limitinteger

get_file_info

查询单个文件详情。file_id 与 file_uuid 提供其一即可。

Parameters (2)

file_idany
文件 ID
file_uuidany
文件 UUID（二选一）

delete_file

删除一个文件。

Parameters (1)

file_idintegerrequired
文件 ID

upload_file

上传一个文件（base64 形式）。用 init + 单次分片 + complete 的方式复用现有服务。适合中小文件（< 20MB）。超大文件请使用 Web 端分片上传。新增 folder_path: 上传到指定文件夹, 默认根目录 "/"。

Parameters (5)

filenamestringrequired
文件名（含扩展名）
content_base64stringrequired
文件内容的 base64 编码。较大文件建议分多次调用前先咨询管理员。
mime_typestring
folder_pathstring
目标文件夹路径。'/' = 根目录 (默认); '/工作/2026' = 嵌套路径。auto_create_folders=True 时路径不存在会 mkdir -p; auto_create_folders=False 时不存在抛错。
auto_create_foldersboolean
路径不存在时是否自动 mkdir -p, 默认 True (类似 Linux mkdir -p)

upload_init

发起分片上传会话 (第 1 步 / 共 3 步)。返回: - instant=true 时, file 字段是已秒传的文件元数据, 直接用即可 - instant=false 时, 用 session_uuid + 服务端给的 chunk_size/total_chunks 逐片调 upload_chunk, 最后调 upload_complete。

Parameters (6)

filenamestringrequired
文件名（含扩展名）
total_size_bytesintegerrequired
整个文件的字节数
sha256stringrequired
整个文件的 sha256 (64 位小写十六进制); 服务端用这个做秒传命中
mime_typestring
folder_pathstring
目标文件夹路径, 默认 '/' 即根目录。auto_create_folders=True 时会按 mkdir -p 语义自动建。
auto_create_foldersboolean
路径不存在时是否自动 mkdir -p

upload_chunk

上传单个分片 (第 2 步 / 共 3 步)。可并发调用, 后端内部会记录已上传索引。网络抖动重试同一 chunk_index 安全 (服务端幂等写临时块)。

Parameters (3)

session_uuidstringrequired
upload_init 返回的会话 UUID
chunk_indexintegerrequired
分片索引 (0-based), 最后一片索引 = total_chunks-1
data_base64stringrequired
本片字节的 base64 编码。每片大小应等于 upload_init 返回的 chunk_size, 最后一片可能短。单次调用建议 <12MB base64 (约 8-9MB 原字节)。

upload_complete

合并所有分片 (第 3 步 / 共 3 步)。两种路径: - 直传 (推荐, shim 走这条): parts 带齐所有 (part_number, etag), 后端调 OSS CompleteMultipartUpload 服务端合并, 不耗 ECS 内存/带宽。 - 中转 (兼容老 shim / 网页端): 不传 parts, 从临时分片合并。返回最终 file 元数据 (id, uuid, filename, size_bytes, sha256, ...).

Parameters (2)

session_uuidstringrequired
upload_init 返回的会话 UUID
partsany
【OSS 直传模式】每片对应的 (part_number, etag)。如: [{"part_number": 1, "etag": "abc..."}, ...]。shim 在 PUT 每片到 OSS 后从响应头拿到 ETag, 传回来。传了 parts 走 OSS CompleteMultipartUpload 合并 (字节不经 ECS)。不传则走老路: 从 upload_chunk 落地的临时片合并 (中转模式)。

download_file

下载一个文件, 按 MCP spec 2025-06-18 的原生 content 类型返回。根据文件 category 自动选择最合适的 MCP content block 类型: - image (jpg/png/webp/...) → content[0].type = "image" (base64 + mimeType; AI 客户端原生显示图片, 多模态 LLM 可直接看图) - audio (mp3/wav/...) → content[0].type = "audio" (base64 + mimeType; AI 客户端原生播放, 多模态模型可直接听) - text/code + as_text=true → content[0].type = "text" (UTF-8 字符串; 适合代码/文档阅读分析) - 其他所有 (video / document / archive / 大文本 / ...) → content[0].type = "resource_link" (15 分钟有效的 URL + mimeType + size; 签名自带, 无需 Authorization; AI 用 bash curl 拉字节, 或提示用户点链接在浏览器下载) 【限速】所有分支都遵守会员档位的 download_speed_bytes_per_sec 设定: - image / audio / text 分支走 astream_file(throttle=...) 读字节再 base64 - resource_link 分支: 链接指向 /api/v1/mcp-download/{token}, 目标路由也用同一套 astream_file + throttle 算法 (详见 api/v1/mcp_download.py) 【零副作用】不再使用 share_service.create_share —— MCP 下载不会在你的账号里留下任何公开分享记录, 不进分享面板, 不计分享审计。

Parameters (3)

file_idany
file_uuidany
as_textboolean
【仅文本/代码文件】直接返 UTF-8 字符串文本内容。图片/音频等非文本文件不受此参数影响(它们按 MCP 原生 content type 返回)。

create_share_link

为文件生成一个分享链接。

Parameters (4)

file_idintegerrequired
要分享的文件 ID
expires_in_secondsany
多少秒后过期；不传=永久
passwordany
可选密码
max_downloadsany
最多下载次数

download_shared_file

通过分享链接下载文件（无需是文件拥有者）。适合别人发给你一个 /s/<uuid> 链接,你想让 AI 直接读取其内容的场景。不会占用你的存储配额。下载计入分享者的月流量。

Parameters (3)

share_uuidstringrequired
分享链接的 UUID（分享 URL 最后一段，如 /s/<uuid>）
passwordany
分享密码，如有
as_textboolean
对文本/代码文件直接返回字符串，不做 base64

import_shared_file

把别人分享的文件导入到当前登录用户的文件列表。等价于「下载后再上传」,但服务端直接从源文件拷贝字节流、仍走配额/白名单/秒传检查, 所以比本地往返更快、也不消耗带宽。下载量计入分享者的月流量;存储占用计入当前用户的配额。

Parameters (2)

share_uuidstringrequired
分享链接的 UUID
passwordany
分享密码,如有

list_folders

列出文件夹 (类似 ``ls -d`` 只看目录)。路径不存在抛 folder_not_found。要列文件用 list_files。

Parameters (2)

folder_pathstring
父文件夹路径, 默认 '/' 即根目录。返回直接子文件夹列表 (不含其文件).
recursiveboolean
True 时返回整棵子树 (深度遍历)。默认 False — 只列直接子文件夹.

create_folder

创建文件夹 (类似 ``mkdir -p``)。幂等: 如果路径已经存在, 直接返回该文件夹元数据, 不抛错。

Parameters (1)

folder_pathstringrequired
要创建的完整路径, 形如 '/工作/项目A/2026'。中间路径不存在时按 mkdir -p 语义递归创建; 末端已存在时直接返回原文件夹 (幂等).

move_file

把文件挪到指定文件夹 (类似 ``mv file /target/dir/``)。 OSS 字节不动, 只改逻辑路径, 操作几毫秒完成。

Parameters (3)

file_idintegerrequired
要移动的文件 ID
target_folder_pathstringrequired
目标文件夹路径, 形如 '/归档/2026'。'/' 即移到根目录.
auto_create_foldersboolean
目标路径不存在时是否 mkdir -p

move_folder

移动整个文件夹 (类似 ``mv /工作/项目A /归档/``)。会递归更新所有后代的逻辑路径。OSS 字节不动。

Parameters (3)

folder_pathstringrequired
要移动的文件夹完整路径, 如 '/工作/项目A'
target_parent_pathstringrequired
新父文件夹路径。'/' 即移到根目录。若也想改名, 用 rename_folder 工具 (不在此工具中合并).
auto_create_foldersboolean
目标父路径不存在时是否 mkdir -p

rename_folder

改名 (不动 parent)。

Parameters (2)

folder_pathstringrequired
要改名的文件夹完整路径
new_namestringrequired
新名字 (不含 / )。同 parent 下不能重名.

delete_folder

删除文件夹 (类似 ``rmdir`` 或 ``rm -r``)。内部 ready/locked 文件按"软删进回收站"处理, 30 天后才物删 OSS 字节; 用户可在该窗口期内通过回收站恢复。

Parameters (2)

folder_pathstringrequired
要删除的文件夹完整路径
recursiveboolean
False (默认): 文件夹必须为空 (无子文件夹 + 无文件), 否则报 folder_not_empty。True: 递归删除整棵子树, 内部所有文件软删进回收站 (类似 rm -rf).

get_folder_tree

以 ASCII 树状图返回用户的文件夹/文件层级 (推荐: 用户问“目录结构”时用这个). 返回: { "root_path": "/", "tree": "ASCII 字符串", "stats": {"folders": N, "files": M, "truncated": bool} }

Parameters (4)

folder_pathstring
起始路径, 默认 '/' 即整个用户文件树。
max_depthinteger
最大渲染深度, 默认 10. 超出深度的节点显示为 '...'.
max_nodesinteger
最大渲染节点数 (文件+文件夹合计). 超出后用 'N more...' 截断.
include_filesboolean
True 时把文件也画进树, False 只画目录。

scrape_url

抓取一个公开网页，返回干净的 Markdown（供 AI 阅读/总结/提取）。只抓公开网页，禁止内网/保留地址；不生成任何内容，只做抓取与格式转换。

Parameters (3)

urlstringrequired
要抓取的网页 URL（http/https，仅限公开网页）
only_main_contentboolean
只提取正文主体，去掉导航/广告/页脚
formatsany
输出格式子集：markdown / html / text，默认 markdown

list_supported_sites

列出当前支持下载的媒体站点（安全白名单）。

No parameters.

get_media_info

探测媒体信息（标题/时长/可选清晰度），不下载、不扣 credit。

Parameters (1)

urlstringrequired
媒体链接或 BV 号（仅白名单站点）

download_media

下载媒体（异步）。立即返回 job_id，用 get_download_status 轮询。按次扣固定 credit（调用即扣，失败全退）。save_to=file_relay 存进你的文件中转站；save_to=local 完成后给一个带签名的临时下载链接。高清晰度需先在网页端 https://stagenth.com 绑定 B站账号。

Parameters (3)

urlstringrequired
媒体链接或 BV 号（仅白名单站点）
save_tostring
file_relay=存到文件中转站 / local=临时下载链接
qualityany
清晰度 qn 或标签(如 80/1080P)；缺省按登录态。高清需在网页端绑定 B站账号

get_download_status

查询媒体下载任务状态/结果。成功后 file_relay 返回 file_id；local 返回临时下载链接。

Parameters (1)

job_idintegerrequired
download_media 返回的 job_id

get_media_comments

查询视频评论（免费，不下载）。返回热门/最新评论 + 游标分页 next_offset。

Parameters (3)

urlstringrequired
媒体链接或 BV 号（仅白名单站点）
sortinteger
3=热门(默认) 2=最新
next_offsetstring
翻页游标：上次返回的 next_offset，首页留空

Install

claude_desktop_config.json

{
  "mcpServers": {
    "file-relay": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://stagenth.com/mcp/file-relay/"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.