ZSpace NAS MCP

90 个 MCP tool + 6 个 skill,让 Claude/Cursor 直接操作极空间 NAS。

你只需要其中一部分

这个仓库包含 3 个独立组件,按需取用。不需要 clone 全部:

你是	你需要	不需要
MCP 用户(想让 Claude Code 操作 NAS)	zspace/mcp_server/ + nas/ + .env(API 内置在 MCP 里)	Skill / Dashboard / RAG
Skill 用户(想用自动化工作流)	复制 skills/<name>/ 到自己项目	MCP 源码 / Dashboard / RAG
RAG 用户(想要语义搜索)	rag-server/ docker compose	Skill / Dashboard
开发者(想加新 tool/skill)	clone 整个仓库	—

MCP 用户(3 步装上)

# 1. 安装 Python 包
git clone <repo> && cd zspace-mcp-poc
pip install -e .                    # 或用 ./start.sh deps

# 2. 配置连接
cp zspace/.env.example .env && vi .env     # 填 NAS_HOST/USER/PASSWORD

# 3. 接入 Claude Code
./start.sh mcp-cfg                  # 打印配置 → 粘到 mcp.json
# 重启 Claude Code,90 tool 自动出现

首次验证: python skills/nas-setup/scripts/check.py

Skill 用户(复制到你的项目)

# 把需要的 skill 复制到你的 Claude Code 项目
cp -r skills/nas-setup ~/your-project/skills/
# 前提: 你的项目也已配置 MCP(上一步)

skill 在 skills/ 目录下,Claude Code 在该目录启动时自动发现。 当前 6 个 skill: nas-setup(前置) rag-manager(RAG管理) media-organizer ios-memo-bak label-manager file-organizer

RAG 用户(Docker 部署到 NAS)

cd rag-server
docker compose up -d                # image: coracoo/cherry:nas_rag
# 详细: rag-server/README.md

所有可选组件

组件	安装方式	用途
MCP(必须)	pip install -e .	90 tool,Claude Code 连 NAS
Skill	复制到 skills/	6 个工作流,Agent 自动触发
RAG docker	docker compose up -d	语义搜索,部署在 NAS 上
Dashboard	./start.sh dashboard	Web UI,iPhone 备忘录入口
MCP HTTP transport	./start.sh mcp-http	局域网/远程 MCP 客户端,Bearer 鉴权,端口 8765
百度网盘	zspace/scripts/netdisk_login.py	OAuth 登录后再用 28 个 znetdisk tool

用户对 Claude Code 说话                    ← 自然语言
        ↓
┌─ Skill 层(skills/) ──────────────┐
│ nas-setup / rag-manager / media-organizer│  ← LLM 触发词 → 自动加载 SKILL.md
│ ios-memo-bak / label-manager / file-org  │  ← 组合多个 MCP tool 完成复杂流程
└──────────────────┬───────────────────────┘
                   ↓ MCP 协议(stdio,JSON-RPC 2.0)
┌─ MCP 层(zspace/mcp_server/) ────────────────────┐
│ 90 个 tool(按域分文件)                    │  ← Claude Code mcp.json 配置后自动发现
│ tools/{files,storage,zvideo,notebook,    │  ← 每个 tool = 1 个 NAS API 端点封装
│        znetdisk,proxy,rag,...}           │
└──────────────────┬───────────────────────┘
                   ↓ HTTP(nas/)
┌─ 协议层(nas/,顶层共享包) ──────────────────────┐
│ auth.py  RSA 登录 + device_id 选择        │  ← Python 库,Skill 和 MCP 都复用
│ client.py NasClient(token 自动续)       │
└──────────────────┬───────────────────────┘
                   ↓ HTTP
┌─ ZSpace NAS ─────────────────────────────┐
│ :5055 主 API(文件/影视/记事本/网盘...)     │
│ :8000 RAG docker(语义搜索,可选)           │
└──────────────────────────────────────────┘

三者关系: Skill 是"做什么"(工作流) → MCP 是"怎么做"(单步操作) → nas/ 是"怎么连"(协议)。新用户只需配 MCP,skill 自动生效。

必须 & 可选

组件	必须?	说明
.env 配置	✅ 必须	NAS 连接信息(NAS_HOST/USER/PASSWORD)
zspace.mcp_server(-m 入口)	✅ 必须	MCP stdio 服务,Claude Code 连它
nas-setup skill	✅ 推荐	首次跑,验证 env + 登录 + 可选组件
rag-server/ docker	可选	RAG 语义搜索。不装也能用 86 个 tool,只是 semantic_search 不可用
dashboard/ Dashboard	可选	Web 管理界面(iPhone 备忘录入口等)
MCP HTTP transport	可选	./start.sh mcp-http,局域网/远程 MCP 客户端用,端口 8765 + Bearer
百度网盘 OAuth	可选	28 个 znetdisk tool 需要先登录

安装

git clone <repo>
cd zspace-mcp-poc

# 1. 配置连接(必须)
cp zspace/.env.example .env
vi .env   # 填 NAS_HOST / NAS_USER / NAS_PASSWORD

# 2. 装 Python 依赖(必须)
./start.sh deps

# 3. 接入 Claude Code(必须)
./start.sh mcp-cfg   # 打印配置片段,粘到 ~/.config/claude-code/mcp.json
# 重启 Claude Code → 90 个 tool 自动出现

# 4. 首次验证
python skills/nas-setup/scripts/check.py
# 输出 ✅✅✅ 即可

# 5. (可选) RAG 语义搜索
cd rag-server && docker compose up -d    # 需要 NAS docker daemon

# 6. (可选) Web Dashboard
./start.sh dashboard   # http://localhost:15050

使用示例

用户在 Claude Code 里说: "给一年级教材打《一年级》标签"

Agent 内部执行流程:
  nas-setup skill 自动加载 → check.py 验证 .env/登录/RAG
    → semantic_search("一年级 教材") → MCP tool → POST NAS RAG daemon
    → 返回 3 个匹配 {path, snippet, distance}
    → Agent 过滤 distance < 1.0 的
    → save_file_label("一年级", "path1,path2") → MCP tool → NAS API
    → MCP 客户端弹 UI 让用户批准
    → ✅ 完成

文件路由

zspace-mcp-poc/
├── nas/                        NAS 协议层(顶层共享包,skill/dashboard/mcp 都直接依赖)
│   ├── auth.py           RSA 公钥 + device_id 自动选择
│   ├── proto.py          URL 公共参数
│   └── client.py         NasClient(token 自动续)
│
├── zspace/mcp_server/           MCP Server(入口 python -m zspace.mcp_server)
│   ├── __main__.py       -m 入口
│   ├── main.py           FastMCP 入口
│   └── tools/            按域分文件
│       ├── files.py      文件读写 + 标签
│       ├── storage.py    存储池/硬件/SMART/监控
│       ├── zvideo.py     极影视
│       ├── notebook.py   记事 (17)
│       ├── znetdisk.py   网盘
│       ├── proxy.py      远程访问
│       ├── shares.py     共享/下载
│       ├── media.py      音乐/相册
│       └── rag.py        RAG 语义搜索
│
├── dashboard/app/                  Web Dashboard(入口 python -m dashboard.app)
│   ├── __main__.py       -m 入口
│   ├── main.py           FastAPI + Session
│   └── routes/
│       ├── shortcut.py   iPhone 备忘录 → NAS 入口
│       ├── dashboard.py  WebUI
│       └── files.py,notebook.py,zvideo.py 文件/记事本/影视 CRUD
│
├── rag-server/       RAG docker 服务(在 NAS 独立部署，作为文件索引)
│   ├── app/server.py       /search /reindex /index /unindex /status
│   ├── Dockerfile + docker-compose.yml
│   └── README.md           REST 协议(端点表)
│
├── skills/       6 个自动化 skill
│   ├── nas-setup/       前置:验证 env/登录/可选组件
│   ├── rag-manager/     RAG 语义搜索索引管理(门控/重建/增量)
│   ├── ios-memo-bak/    iPhone 备忘录 → 极空间记事本
│   ├── media-organizer/ 极影视分类审计
│   ├── label-manager/   标签管理
│   └── file-organizer/  文件库诊断
│
├── pyproject.toml             包定义(pip install -e .)
├── docs/API.md                 NAS 全端点速查
├── docs/MCP.md                 90 tool 详细文档
└── start.sh                    一键启动(deps/mcp/dashboard/mcp-cfg)

MCP Tool 清单(90)

文件 & 存储池 & 监控(20)

Tool	读/写	用途
list_files	读	列目录
file_info	读	单文件元数据
recent_files	读	最近访问
file_categories	读	按类型统计
list_storage_pools	读	存储池 & 磁盘
hardware_info	读	硬件槽位
smart_report	读	SMART 磁盘健康
system_status	读	NAS 综合状态
perf_snapshot	读	SSH 实时性能
whoami	读	当前用户
mkdir	写	新建目录
rename	写	重命名
move	写	移动
copy	写	复制
remove	⚠️ 删除	不可逆,不进回收站

极影视(9)

Tool	读/写	用途
list_video_classes	读	分类列表(含 is_enable/is_system)
latest_movies / suggested_movies / random_movies	读	影片浏览
list_video_dirs	读	源目录
get_video_classification_state	读	单个分类状态
add_video_classification	写	新建分类
rename_video_classification	写	重命名分类(classification_id + new_name)
link_folder_to_classification	写	关联源目录(带 is_enable=0 拒绝)

记事本(17)

Tool	读/写	用途
notebook_list/info/search	读	浏览 & 搜索
notebook_allclassify/classifylist	读	分类树
notebook_totalsize/getconfig	读	统计 & 配置
notebook_historyinfo/historylist	读	历史版本
notebook_new/modify/delete	写	CRUD
notebook_pin/updatelabel/movenotepad	写	置顶/标签/移动
notebook_newclassify/deleteclassify/updateclassify	写	分类管理

百度网盘(28)— 需要 OAuth 登录

分组	Tool	用途
auth	znetdisk_auth_check/token/userinfo/logout	OAuth oob 登录
file	znetdisk_file_list/download/upload/newdir	云盘文件管理
task	znetdisk_task_list/action	传输任务
sync	znetdisk_sync_add/list/open/close/delete/home	NAS ↔ 云盘双向同步
autobackup	znetdisk_autobackup_* (7)	自动备份
share	znetdisk_share_verify/filelist/transfer/transfer_result	⭐ 分享链接转存
fail	znetdisk_fail_list	失败列表

共享 & 下载 & 远程访问(11)

Tool	用途
samba_status / webdav_status / ftp_status / dlna_status	共享服务状态
list_downloads / list_shares / list_nshares	下载 & 分享
proxy_login / proxy_url_for_port / proxy_fetch / proxy_list_whitelist	zos 云代理

音乐 & 相册(3)

Tool	用途
list_songs	歌曲列表
list_albums	相册列表
list_album_feeds	相册内容

RAG 语义搜索(3)— 需要 rag-server docker

Tool	用途
semantic_search	自然语言搜文件内容
reindex	重建索引
index_status	索引概况

Skill 清单(6)

Skill	触发词	用途
nas-setup	首次配置、验证连接	前置:验证 env/登录/可选组件(RAG)
rag-manager	RAG 索引、reindex	RAG 语义搜索索引生命周期管理
ios-memo-bak	iPhone 备忘录同步	一键配置 iPhone Shortcut → NAS 记事本
media-organizer	极影视整理、frds 拆分	只读审计分类/源目录/影片抽样
label-manager	打标签、按标签找	标签 CRUD + 反向查询
file-organizer	重复文件、孤儿文件	文件库只读诊断

接入标准

MCP Client(mcp.json)

{
  "mcpServers": {
    "zspace-nas": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "zspace.mcp_server"],
      "cwd": "/path/to/zspace-mcp-poc",
      "env": {
        "NAS_HOST": "192.168.x.x",
        "NAS_USER": "<phone>",
        "NAS_PASSWORD": "<password>",
        "NAS_DEVICE_ID": "<32 hex>"
      }
    },
    "zspace-nas-http": {
      "url": "http://192.168.x.x:8765/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_HTTP_TOKEN from NAS .env>"
      }
    }
  }
}

(本地 Claude Code 用 zspace-nas stdio 条目;局域网/远程 MCP 客户端用 zspace-nas-http HTTP 条目,两个互不干扰,NAS 端跑 ./start.sh mcp-http 后启用)

环境变量

变量	必填	说明
NAS_HOST	✅	NAS IP
NAS_USER	✅	手机号
NAS_PASSWORD	✅	密码
NAS_DEVICE_ID	推荐	32 字符,复用已登记设备绕短信验证
KEY_SSH	可选	perf_snapshot 需要
NAS_SSH_PORT	可选	默认 57922
NAS_RAG_URL	可选	RAG daemon 地址,默认 http://nas:8000

写操作安全规则

1. destroy 类(remove/notebook_delete) 不进回收站,MCP 客户端弹 UI 让用户批准
2. 状态校验(link_folder_to_classification) 目标分类 is_enable=0 时直接拒绝
3. 标签覆盖(save_file_label) 覆盖式,打新标签前先 file_info 看现有标签

RAG docker 部署(可选)

cd rag-server
docker compose up -d    # image: coracoo/cherry:nas_rag
# 首次跑 reindex
curl -X POST http://nas:8000/reindex -H 'Content-Type: application/json' \
  -d '{"scope":"files","full":true}'

REST API 详见 rag-server/README.md(端点表)。

文档

文档	内容
docs/API.md	NAS 全端点速查(12 域,~900 行)
docs/MCP.md	90 tool 参数/返回/端点映射
rag-server/README.md	RAG REST 协议(端点表)
docs/iphone-shortcut.md	iPhone Shortcut 配置图解

License

MIT — 详见 LICENSE。欢迎 PR/Issue/Star。

CONTRIBUTING.md