概述
部署在 MCPHub 后面的 stdio MCP 服务器运行在容器内。当工具接收本地路径时,该路径在 hub 上解析,而不是在发起请求的客户端机器上。文件暂存只解决其中一个窄场景:客户端需要把文件交给工具处理,再把结果取回。- 客户端把文件副本上传到 hub;
- 调用时在声明过的输入参数里传入
mcpfile://引用,而不是路径; - hub 把引用改写成该用户暂存目录中的真实路径;
- 工具处理副本。反方向同样成立:客户端预留一个目标路径,工具写入后,hub 通过一次性下载链接把结果提供出去。
启用文件暂存
文件暂存默认关闭,本阶段没有 Dashboard 界面。需要同时具备三部分:全局总开关、服务器的staging 声明,以及按工具的启用项。
1. 全局总开关
管理员通过 system-config API 打开总开关。请求会把传入的键合并到已保存的设置上,其他设置保持不变。PUT /api/system-config 对非管理员调用返回 403。如果 hub 部署在子路径下,请在路径前加上 BASE_PATH。
2. 服务器暂存声明
在服务器上声明适配器。服务器所有者可以为自己的私有服务器设置适配器;添加或移除shared 信任只有管理员可以操作:
{"shared":true}(仅管理员),并配置带按用户槽位的 credentialTemplate。
3. 按工具启用
file-staging 路由允许所有者或管理员调用。tool 是不带服务器前缀的工具名;省略 inputParams/outputParams 时会保留已保存的值,因此禁用工具不会丢失声明。两个 PATCH 路由都会对结果做整体校验:启用中的工具仍然要求 staging.adapter 和 stdio 服务器。
本阶段没有用于暂存的 Dashboard 界面。仍可使用整服务器 PUT /api/servers/:name({"config": ...})做批量编辑,但它一旦收到 tools 就会替换整个工具对象,因此暂存变更应优先使用 PATCH 路由。
前提条件
- 服务器必须是 stdio 类型,HTTP/SSE 和 OpenAPI 服务器无法使用暂存。
- 服务器声明
staging.adapter: "ssh",每个需要暂存的工具单独开启fileStaging。 - 目前只验证了固定版本
@fangjunjie/ssh-mcp-server@1.11.0这一种适配器配置。启动命令必须是npx(或node),且该精确版本说明必须是第一个位置参数;连接后的服务器必须报告版本1.11.0。其他包、版本或启动方式都会保持关闭。 - 解析后的命令行会按每个用户检查 SSH 参数白名单。会扩大子进程本地根目录的参数——
--allowed-local-paths、--config-file,以及携带同一设置的--ssh/--ssh-config-file连接对象——会使该服务器的暂存被关闭。 - 共享、分组或公开服务器还需要
"staging": { "adapter": "ssh", "shared": true }和带按用户槽位的credentialTemplate;两者缺一,服务器暂存都会被拒绝。 - 需要下载链接时,必须配置
install.baseUrl(或INSTALL_BASE_URL),因为远程客户端无法解析 hub 的localhost。
配置
文件模式下,同样的配置在mcp_settings.json 中如下。通过 API 时,PATCH /api/servers/:name/staging 设置 staging 对象,PATCH /api/servers/:name/file-staging 设置单个工具的 fileStaging 对象。
inputParams 列出可以携带“hub 已持有的文件”引用的参数;outputParams 列出工具会写出、由 hub 登记的目标参数。方向用反、写在未声明的参数里,或在一次调用中重复使用同一个引用,都会在工具执行前被拒绝。同一个参数不能同时出现在两个列表中。
只有 ready 引用能作为输入,只有 reserved 引用能作为输出。能拿到工具 schema 时,声明过的参数必须存在于该 schema 中,且类型必须是字符串。hiddenParams 不能与 inputParams/outputParams 重叠。启用了 fileStaging 却没有任何参数,会在保存时被拒绝。
配置模板和分组模板不会导出服务器的 staging 声明或按工具的 fileStaging;导入模板本身不会启用暂存。
方向
引用的方向取决于数据流的方向,而不只是工具名称。两次 SSH 调用中的remotePath 都是普通的远端参数,永远不是暂存参数。
输入:把上传的文件交给工具
remotePath 仍是普通的远端路径,不会被改写,也不应写进 inputParams。
输出:让工具写出文件并由 hub 提供下载
ssh 下是 ssh-upload);tools 的键是不带前缀的工具名(upload、download)。
内置工具
当调用者能解析到真实用户时,对于至少暴露一个已启用暂存服务器的路由,hub 会注入三个虚拟工具:filename只用于展示,永远不是路径。目录部分、NUL、CR、LF、引号和反斜杠会被去掉,名称截断到 255 个 UTF-8 字节。content_base64是内联上传。要预留输出目标,请完全省略该字段;空字符串会被拒绝。- 只有当路由暴露多个已启用暂存的服务器时才需要
server,且必须是其中之一。 allow_zero_byte(默认false)允许零字节的工具输出变成就绪。它只对输出引用生效。status和download只能看到调用者拥有的引用;他人的或缺失的引用返回相同的未找到错误。download要求引用处于ready状态;reserved、failed或已过期的引用会被拒绝。返回的链接一次性且短期有效;重试需要重新调用mcphub_file_download。- 这些工具只在存在暂存目标的路由中列出,也不会通过
$smart路由暴露。
保留命名空间
任何以mcphub_file_ 开头的工具名都归 hub 保留,配置中的 tools 条目也不允许使用该前缀。如果上游服务器仍然暴露了同前缀的工具,hub 的定义优先:上游工具不会出现在列表中,同名调用由 hub 处理或拒绝,永远不会转发给上游服务器。
下载
mcphub_file_download 使用 install.baseUrl 加上配置的 basePath 生成链接:
BASE_PATH 默认为空时,路径是 /staging/download/:token。该路由直接注册在 app 上,位于 /api 的 Dashboard 认证中间件之外:持有 token 即代表拥有该能力,因此客户端不需要 Dashboard 会话即可取文件。如果 hub 部署在子路径下,请在路径前加上 BASE_PATH。
该路由只接受 GET(HEAD 返回 405)。token 随机生成、按哈希存储,在 downloadTtlSeconds 后过期,并在第一次请求时原子消费;未知、已使用或已过期的 token 都返回相同的 404。响应始终为附件下载,文件名经过清理,并带有 Content-Type: application/octet-stream、X-Content-Type-Options: nosniff、Cache-Control: private, no-store,不会内联渲染。
如果 install.baseUrl 缺失,或仍指向内置的 http://localhost:3000 默认值,mcphub_file_download 会拒绝生成链接,因为远程 MCP 客户端无法解析该地址。请在设置中配置公网地址,或使用 INSTALL_BASE_URL。
引用生命周期与重启
引用会经过reserved、ready、failed 和 expired 四种状态:
reserved:不带内容调用mcphub_file_upload时创建的零字节目标,不能作为输入。ready:已登记内容,带有大小和 SHA-256,只读,可作为输入或下载。failed:终态。调用失败、抛错、超时,或产出的文件缺失、超限、(未设置allow_zero_byte时)为空。expired:超过引用 TTL。
- 停止 hub 时仍持有租约的
reserved引用会在启动时变为failed,租约和配额预留被清除,其 UUID 永远不会被复用。被崩溃调用租用的引用不会再次出租、覆盖或提供下载,即使残留的子进程已经写入了字节。 - 从未被租用的
reserved引用会跨重启保留,并在 TTL 到期前继续作为输出目标可用。 ready内容及其 TTL 会跨重启保留。读钉不会:启动时会被清除,因为没有任何读取者能活过进程重启。
MCPHUB_REPLICA_MODE=true)会关闭暂存,第二个 hub 进程也不得共享同一个暂存目录。
配置项
设置位于systemConfig.fileStaging,通过 PUT /api/system-config(仅管理员)写入;文件模式也可以在 mcp_settings.json 中设置同一个对象。部分更新会合并到已保存的值上。默认值:
暂存内容位于
data/uploads/staging(可用 MCPHUB_STAGING_ROOT 覆盖);文件模式账本和进程锁位于 data/staging-state(MCPHUB_STAGING_STATE_DIR)。两者都应放在持久卷上。账本是权威数据;引用目录里的 meta.json 只是缓存。
在 DB_SYNCHRONIZE=false 的部署中,数据库模式启用暂存前需先执行 docs/migrations/0006-file-staging.sql。数据库模式把引用和 token 保存在 file_staging_refs 和 file_staging_tokens 中,内容仍然位于本地暂存根目录。
认证
暂存调用必须解析到真实用户账号。以下调用者会在创建或改写引用之前被拒绝:- system bearer key,即使该 key 指定了 owner;
- 匿名调用者和
skipAuth的guest用户; - 标记为
credentialEligible: false的用户,以及已不存在的用户; - 副本模式下的请求。
安全边界
暂存让 hub 复制文件,而不是把 hub 的文件系统访问权授予客户端。边界由 hub 侧的所有权检查和受信任 SSH 适配器自身的按用户根目录检查共同保证。- 工具子进程与 hub 以同一操作系统用户运行在同一容器中。用户之间没有操作系统级隔离。
- 按用户的工作目录和暂存根目录是正确性边界,不是安全边界。它们保证引用及其相对路径绑定到正确的用户,并阻止受信任适配器解析到该根目录之外;但无法阻止能直接读取文件系统的工具。
- 因此,共享或公开服务器不是其用户之间的隔离边界。整个 hub 容器也不是:同一部署中另一个具备 shell 或文件系统访问权限的 stdio 服务器可以读取暂存目录和账本。请限制这类服务器的使用范围,或接受该风险。
- 引用是绑定到单个用户和单个服务器的能力,下载链接是一次性能力。两者都应视为机密。
- 暂存不是透明访问:只有声明过的参数会被改写。客户端在其他参数中直接传入的原始路径仍然在容器内解析,hub 不会扫描或改写工具响应。
尚未包含
暂存目前不提供浏览器上传页面、S3/MinIO 或多节点存储、响应路径自动识别或自动注入downloadUrl、虚拟工具的 $smart 暴露、MCP Apps 文件 API、已签发引用的撤销路径、非 SSH 适配器,以及操作系统级隔离。直接调用、嵌套调用与错误记录都会把引用排除在活动记录之外;经 hub 不检查的通道(例如资源读取)传到上游工具的内容不在该保证范围内。本阶段也没有用于暂存的 Dashboard 编辑器;配置通过上述 PATCH 路由完成。