Skip to content

Releases

NutstoreMCP v1.1.0

Choose a tag to compare

@MUMU-DADA MUMU-DADA released this 19 Oct 07:04

NutstoreMCP v1.1.0

能力开放路线(P0–P4)落地版本:工具从 36 个增加到 39 个,并附带 Windows 一键安装包(下方「下载」)。插件运行在坚果云客户端进程内,使用客户端已登录会话与它自己的实现,零第三方凭据。

下载

文件 说明
NutstoreMCP-v1.1.0-win-x64.zip Windows x64 安装包(2.3 MB):解压后运行 Install-NutstoreMCP.ps1,不需要 .NET SDK、不需要编译源码
NutstoreMCP-v1.1.0-win-x64.zip.sha256 压缩包的 SHA-256 校验和

SHA-256:934f0ff446c624ab59435a03c1c4782473f1cf97e421c3558fc5515332603044

安装(PowerShell):

# 解压后进入目录
powershell -ExecutionPolicy Bypass -File .\Install-NutstoreMCP.ps1

脚本会申请一次管理员权限(UAC):停客户端 → 装桥 → 原子修改 NutstoreClient.exe.config → 部署插件到 %LOCALAPPDATA%\NutstoreMcp\plugin-1.1.0 → 重启客户端 → 等待 MCP 端点就绪。装完把下面这段加到 MCP 客户端:

transport: streamable-http
url: http://127.0.0.1:17321/mcp

要求:Windows 10/11 x64、坚果云客户端 7.2.12.0、系统自带 PowerShell 5.1。卸载用同目录的 Uninstall-NutstoreMCP.ps1(会从安装前的备份还原客户端配置)。

新增能力

  • P0 空文件创建:contentBase64="" 走客户端空文件特殊分支(跳过内容上传,云端 hash 为 32 个零字节、块列表名为 40 个零字节),写后回读 size=0。
  • P1 任意已有目录创建(nutstore_l3_create_file 新增 directoryPath 模式):云端父目录 + 本地绑定文件夹两端预检(大小写别名即拒、父路径逐字符核对)→ 钩子在上传后、提交元数据前再复查 → 写后三重复查(父目录只多出目标且其余成员版本/哈希不变 → 目标大小/hash/版本 → 整文件分段回读 SHA-256)。沙箱根下创建同样支持。
  • P2 台账限定删除(新工具 nutstore_l3_delete_created_object):创建台账 created-objects.jsonl 记录 path/version/size/hash/来源;只删台账内、且当前状态完全匹配的文件。目录、用户已有对象、被改动过的对象、大小写别名一律拒绝。
  • P3/C4 台账限定修改(新工具 nutstore_l3_modify_file):只改台账内、自创建以来未被改动过的文件;执行必须带预演看到的 expectedVersion 作为二次确认令牌;修改产生新版本、旧版本进入历史(网页端可回退),写后核对新版本/大小/hash、整文件回读 SHA-256 与历史保留。
  • P4/E1 公开分享(新工具 nutstore_l3_publish_share):默认预演、必须 confirm;支持有效期/密码/禁下载;目标已有分享时拒绝。分享 URL 是访问凭证,默认不返回,只有显式 returnUrl=true 才返回;分享台账只存 URL 的 SHA-256。

安全模型变化

  • 禁止清单没有放松:删除对象的混淆入口仍在清单里(通用反射桥/反射工具拿不到),只有专用工具经独立契约路径调用,标记为 dedicated-only。
  • 删除/修改授权范围来自本地台账(%LOCALAPPDATA%\NutstoreMcp\created-objects.jsonl),台账被删只是失去撤销/修改授权,不影响云端对象。
  • 修改与删除都做「提交前紧邻复查 + 写后只读复查」,失败或结果未知只报告,不重试、不回滚。
  • 公开分享受账号等级限制:免费账号会被服务端拒绝(RequestException (DisabledForFreeUser),无副作用)。

验证

  • 375 项主测试、17 项 WPF 探针、11 项配置补丁、108 项客户端绑定 / 3 个程序集全部通过(.\verify.ps1)。
  • 在线验证(坚果云 7.2.12.0,tools/list 39 项):
    • 空文件创建、已有目录创建(子目录与沙箱根,含 28 个既有成员快照)成功并回读一致;
    • 台账限定删除成功(重复删除/非台账对象/大小写别名被拒),客户端同步移除本地文件;
    • 台账限定修改 v1→v2 成功,file_versions 保留 v1「创建」与 v2「编辑」,read_file 读到新内容且完整性校验通过;
    • E1 分享预演正常;执行因免费账号被服务端拒绝(DisabledForFreeUser),无分享产生,工具如实报告失败。
  • 发布包实机验收:从本 Release 的 zip 解压实装成功(39 工具、UI 钩子已接入);卸载脚本实机验证能移除桥 DLL、从备份还原客户端配置并重启客户端;再装一次恢复 39 工具。

升级注意

  • 客户端契约新增了 3 个钩子方法(DeleteCloudObject / ModifyCloudFile / PublishCloudObject)。从 v1.0.0 升级必须重新运行 Install-NutstoreMCP.ps1(需要一次 UAC,客户端会先被关闭)然后重启客户端;只覆盖插件目录不够。
  • 程序集版本号本轮保持 1.0.0.0(未 bump),发布版本号以仓库 tag v1.1.0 为准。

说明

  • 仅供个人数据与授权账号上的自动化使用
  • 安装脚本会备份 NutstoreClient.exe.config;出问题用 Uninstall-NutstoreMCP.ps1 还原

完整文档:README · MCP-API · ARCHITECTURE · 开发计划

NutstoreMCP v1.0.0

Choose a tag to compare

@MUMU-DADA MUMU-DADA released this 18 Oct 18:57

NutstoreMCP v1.0.0

首个公开版本:把坚果云桌面客户端的查询与管理能力做成 MCP 插件。插件运行在客户端进程内,使用客户端已登录的会话和它自己的实现,不需要 WebDAV 或任何第三方凭据。

能力

  • 36 个 MCP 工具:同步文件夹、云端目录/详情/历史版本/分享状态、联系人、账号与流量、路径 ACL、事件游标与单页事件、文件内容只读(≤256 KiB,可分段)
  • 文件操作:下载到新路径、同沙箱移动/重命名、单层目录创建、新建文件(内联 ≤256 KiB / 本地文件 ≤16 MiB;>393216 字节走客户端 4 MiB 分块上传)
  • 管理:云端新建同步文件夹、绑定本地空目录、读取/修改白名单设置
  • 诊断:插件状态/热重载、客户端类型搜索/反射、通用反射桥、WPF 控件树探针

安全

  • 写工具默认只预演,需令牌 + confirm=true + dryRun=false;系统级设置另需第二把锁
  • 创建文件只允许在本次新建且确认为空的目录里进行,从结构上避免大小写别名触发客户端改名
  • 不覆盖、不删除;删除/解绑/迁移同步根/ACL 写/分享写等入口不开放
  • 不导出分享链接、密码、会话凭据

验证

  • 283 项主测试、17 项 WPF 探针、11 项配置补丁、84 项客户端绑定 / 3 个程序集全部通过
  • 在线验证:建目录、建文件(300 KiB / 400 KiB / 4.3 MiB)、移动、绑定、读取
  • 验证客户端:坚果云 7.2.12.0;MCP 端点 http://127.0.0.1:17321/mcp,tools/list 36 项

说明

  • 需要 Windows 与已安装的坚果云客户端;安装/卸载见 deploy/README.md
  • 早期 L1 WebDAV / L2 本地只读独立服务器已退役,代码与测试已删除
  • 仅供个人数据与授权账号上的自动化使用

完整文档:README · MCP-API · ARCHITECTURE