ugnas-mcp

ugnas-mcp

npx -y ugnas-mcp

一款适用于运行 UGOS 的 UGREEN NAS 设备的通用 MCP（Model Context Protocol）服务，通过 SSH 与 NAS 通信（使用 SFTP 传输文件）。

与大多数现有 UGREEN NAS 集成方案不同，这里没有任何硬编码内容——没有固定 IP、子网、用户名或共享名称。所有针对特定目标的值都来自你的配置，因此同一服务适用于任何人的 NAS。

功能介绍

按 NAS 用户处理日常操作的实际方式组织：

分组	工具	是否会修改数据？
连接与系统	system.status、system.info、system.pools	只读
Docker	docker.containers.*（list/inspect/logs/start/stop/restart/remove）、docker.images.*（list/pull/remove）、docker.networks.*（list/inspect/create/remove/connect/disconnect）、docker.compose	start/stop/restart/pull/remove/create/compose 需要确认
文件与数据	files.list、files.usage、files.find、files.thumbnail、files.mkdir、files.copy、files.move、files.remove、files.upload、files.download、files.sync	thumbnail/mkdir/copy/move/remove/upload/download/sync 需要确认
备份	backup.create、backup.list、backup.verify、backup.restore、backup.schedule	create/restore/schedule 需要确认
网络	network.interfaces、network.routes、network.ports	只读

共 39 个工具。 system.pools 会报告 mdadm 阵列及降级状态、LVM 卷/逻辑卷/物理卷、btrfs 设备、块设备和文件系统。

files.find 按名称 glob 和/或扩展名搜索目录树（返回路径、大小、修改时间）。files.thumbnail 在 NAS 上使用 ffmpeg 生成图像预览或视频帧，并下载到本地——不会修改 NAS 数据（只会写入并删除 /tmp 临时文件），但将缩略图写入本地计算机需要确认：首次调用会返回试运行计划，你需要使用令牌确认后才能写入本地文件。需要 NAS 上安装 ffmpeg（UGOS 默认已安装）。

files.list 和 files.find 优先使用 GNU coreutils 标志（ls --time-style=long-iso、find -printf）；若这些命令不可用（BusyBox），则回退到 ls -1p 和 find -exec stat，以确保工具仍可运行——对于 BusyBox 的普通 ls 无法报告的大小/修改时间，则会置为零。

files.sync 与 rsync 回退方案

files.sync 使用 rsync 快速、可续传地进行 NAS↔NAS 复制，并支持 --delete 镜像和 rsync --dry-run 预检。UGOS 默认不安装 rsync，因此：

• 默认（fallback: "refuse"）——如果缺少 rsync，试运行计划仍会显示 rsync 命令，并附上说明如何安装 rsync（Entware：opkg install rsync）或如何启用回退方案的 note。在你确认之前，不会执行任何操作。
• 选择启用（fallback: "cp"）——工具会改用内置的 cp -a 复制。计划的 note 会说明这一点，而 warnings 会指出回退方案无法做到的事情：不支持 --delete 镜像、不支持 rsync --dry-run，并且会忽略 extraArgs。

因此，你可以在每次调用时传入 fallback: "cp" 来选择启用。除非你主动要求，否则不会有任何变化。

安全模型 — 先试运行，再确认

每个会修改数据的工具都分为两个阶段：

1. 不带令牌调用 → 返回一个试运行计划：将要执行的确切 shell 命令、 人类可读的摘要、任何警告，以及一个短时有效的 confirmationToken。
2. 再次调用并提供 confirmToken → 验证令牌（绑定操作、仅可使用一次，10 分钟后过期），并执行计划时记录的确切命令。

只读工具不需要令牌。这样，“复制我的数据”“拉取此镜像”或 “重启该容器”等操作都可以先审查，再执行更改。

所有用户提供的值（路径、容器名称、镜像标签）在插入远程命令前都会经过 POSIX shell 引号处理， 因此无法借此突破限制并执行任意命令。

确认时，会将确认调用的参数与令牌中记录的计划参数交叉核对：如果两者不同，工具会拒绝执行，并要求你重新运行以生成新计划 （因此，过期的令牌绝不会执行参数不同的操作）。

配置

服务会从 ~/.ugnas-mcp/config.json 读取 JSON 配置（可通过 UGNAS_MCP_CONFIG 环境变量指定其他路径）。请参阅 config.example.json。

{
  "name": "home-nas",
  "host": "192.168.1.50",
  "port": 22,
  "username": "admin",
  "auth": { "type": "key", "privateKeyPath": "~/.ssh/id_ed25519" },
  "defaultShare": "/volume1",
  "commandTimeoutMs": 60000
}

字段	必填	说明
host	是	NAS 的 IP 地址或主机名。
port	否	SSH 端口，默认为 22。
username	是	SSH 用户名。
auth	是	{ "type": "key", "privateKeyPath": "..." }（推荐，支持 passphrase）或 { "type": "password", "password": "..." }。privateKeyPath 也可以是内联 PEM 文本。
defaultShare	否	相对工具路径的基目录，默认为 /volume1。
sftpRoot	否	SFTP 子系统的根目录。在 UGOS 上，SFTP 会被 chroot 到共享目录根目录，因此，像 /volume1/docker/x 这样的 exec 路径，在通过 SFTP 请求时必须使用 /docker/x；将此项设为 chroot 根目录（默认为 defaultShare）。如果你的 NAS 不会对 SFTP 进行 chroot，请使用 "/"。
hostKeySha256	否	设置后，会固定并强制校验 SSH 主机密钥（例如 SHA256:...）。比较时不区分填充，因此可直接使用 ssh-keygen -lf 输出的规范指纹。
commandTimeoutMs	否	每条命令的超时时间，默认为 60000。

环境变量覆盖项

适用于 CI 或注入密钥的场景。环境变量的值优先于文件中的值：

UGNAS_HOST=192.168.1.50
UGNAS_PORT=22
UGNAS_USER=admin
UGNAS_KEY_PATH=~/.ssh/id_ed25519      # or UGNAS_AUTH_TYPE=password + UGNAS_PASSWORD
UGNAS_DEFAULT_SHARE=/volume1
UGNAS_HOST_KEY_SHA256=SHA256:...

相对路径与绝对路径

文件和备份工具接受这两种路径。绝对路径按原样使用；相对路径会拼接到 defaultShare 后面：

files.list("media")  ->  /volume1/media
files.list("/mnt/x")  ->  /mnt/x

安装与运行

已发布到 npm，包名为 ugnas-mcp。可直接运行 — 无需克隆或构建：

npx ugnas-mcp
# or install it once:
npm install -g ugnas-mcp
ugnas-mcp

这会启动 stdio MCP 服务。它会从 ~/.ugnas-mcp/config.json （或 UGNAS_MCP_CONFIG / UGNAS_* 环境变量）读取配置 — 请参阅配置。

接入 MCP 客户端

将客户端指向官方包（stdio）：

{
  "mcpServers": {
    "ugnas": {
      "command": "npx",
      "args": ["-y", "ugnas-mcp"],
      "env": { "UGNAS_MCP_CONFIG": "/absolute/path/to/config.json" }
    }
  }
}

或者，如果你已全局安装，可使用 "command": "ugnas-mcp"，无需参数。

可选的 HTTP 传输

服务默认使用 stdio。设置 UGNAS_HTTP_PORT 还可启用可流式 HTTP 传输（两种传输并行运行）：

UGNAS_HTTP_HOST=127.0.0.1 UGNAS_HTTP_PORT=4110 ugnas-mcp

• POST http://127.0.0.1:4110/mcp — JSON-RPC（无状态；每个请求都会创建一个新会话，请求正文最大为 1 MiB）。
• GET http://127.0.0.1:4110/health — 存活状态与目标主机。

默认绑定到环回地址。除非同时设置 UGNAS_HTTP_ALLOW_REMOTE=1，否则会拒绝 UGNAS_HTTP_HOST=0.0.0.0（或任何非环回地址）— /mcp 端点没有身份验证，且确认令牌在整个进程范围内有效，因此只有在端口由其他方式保护时（例如带身份验证的反向代理、VPN 等）才启用此功能。

NAS 上的前置条件

• 已启用 SSH（UGOS：控制面板 → 终端与 SNMP）。
• SSH 用户可以运行 docker（属于 docker 组），并且可以使用 crontab 安排备份任务。
• UGOS 上已提供 tar、df、du、ip 和 ss——这些都是标准工具。
• backup.schedule 任务名称必须是普通单词（[A-Za-z0-9._-]）——它们会嵌入生成的 shell 脚本和 crontab 行中，因此其他名称会被提前拒绝。
• rsync 可选，仅供 files.sync 使用。如果缺少该工具，系统会提示如何安装，或如何启用内置的 cp 回退方式（files.sync { fallback: "cp" }）；其他文件工具均可在没有 rsync 的情况下运行。

许可证

MIT — 详见 LICENSE。贡献指南、架构以及开发/发布工具链请参阅 DEVELOPMENT.md。