Metadata-Version: 2.5
Name: fnos-nas-mcp
Version: 1.0.0
Summary: 飞牛 NAS (fnOS) MCP 连接器 —— 通过 WebSocket 私有协议管理 fnOS 文件、应用与 Docker，支持任意 fnOS 设备自助接入
Author: fnos-connector contributors
License-Expression: MIT
Keywords: fnnas,fnos,mcp,nas,workbuddy,飞牛
Requires-Python: >=3.10
Requires-Dist: mcp>=1.2.0
Requires-Dist: pycryptodome>=3.19.0
Requires-Dist: websocket-client>=1.6.0
Description-Content-Type: text/markdown

# 飞牛 NAS (fnOS) 通用 MCP 连接器

将任意飞牛 fnOS NAS 设备接入 WorkBuddy 的通用型 MCP 连接器。用户只需在连接时填写 **NAS 地址（IP）、端口、用户名、密码** 四项即可使用，代码中无任何硬编码设备信息。

## 功能

- **文件管理**：列目录、创建目录、上传、删除（进回收站）、重命名
- **认证**：账密登录 / 长效令牌免密复登（令牌按 NAS 地址隔离，存于 `~/.fnos-nas-mcp/`）
- **用户**：当前用户信息、用户列表（管理员）
- **应用与 Docker**：第三方应用列表、Docker 容器列表、系统入口列表
- **安全**：登录走 fnOS 原生 RSA-OAEP-SHA256 + AES-256-CBC 加密通道，请求带 HMAC-SHA256 签名，凭据仅存本机

## 连接器包结构（符合 WorkBuddy 连接器市场规范）

```
fnos-connector/
├── mcp.json               # MCP server 定义（stdio + ${ENV} 凭据注入）
├── token-schema.json      # 用户连接表单：IP / 端口 / 用户名 / 密码
├── skills/SKILL.md        # 使用说明（连接器安装后自动挂载为 skill）
├── pyproject.toml         # Python 包定义（发布 PyPI 后可 uvx 一键运行）
├── README.md
└── src/fnos_nas_mcp/      # 连接器实现
    ├── __init__.py
    ├── fnos_client.py     # fnOS WebSocket 协议客户端（通用化，无内置设备信息）
    └── server.py          # MCP server（FastMCP，stdio）
```

## 连接参数（环境变量）

| 变量 | 必填 | 说明 |
|------|------|------|
| `FNOS_HOST` | 是 | NAS 的 IP 或域名 |
| `FNOS_PORT` | 否 | Web 端口，默认 5666 |
| `FNOS_USERNAME` | 是 | fnOS 登录用户名 |
| `FNOS_PASSWORD` | 是 | fnOS 登录密码 |

首次调用任一工具时自动登录并保存长效令牌；令牌失效自动用配置账密重新登录，全程无需手动干预。

## 本地手动安装（不经过市场）

在 `~/.workbuddy/mcp.json` 中加入（python 路径按本机环境调整，需已安装 `mcp`、`websocket-client`、`pycryptodome`）：

```json
{
  "mcpServers": {
    "fnos": {
      "command": "python",
      "args": ["C:/path/to/fnos-connector/src/fnos_nas_mcp/server.py"],
      "env": {
        "FNOS_HOST": "192.168.1.10",
        "FNOS_PORT": "5666",
        "FNOS_USERNAME": "your-user",
        "FNOS_PASSWORD": "your-pass"
      }
    }
  }
}
```

保存后需在 WorkBuddy 连接器管理页面（自定义连接器入口）点击"信任"以启用。

## 上架到 WorkBuddy 连接器市场

1. **发布 Python 包**：将 `src/` 与 `pyproject.toml` 发布到 PyPI（`python -m build && twine upload dist/*`），包名 `fnos-nas-mcp`。发布后 `mcp.json` 中的 `uvx fnos-nas-mcp` 即可在任何用户机器上自动拉起，无需预装环境。
2. **提交连接器包**：向 WorkBuddy 连接器市场仓库提交 `fnos-connector/` 目录（`mcp.json` + `token-schema.json` + `skills/SKILL.md`），marketplace 侧的索引（connectors.json）中登记 id（建议 `fnos`）、名称"飞牛 NAS"、描述与图标。
3. **审核要点**：token-schema 已声明凭据仅存本机；server 无遥测、无硬编码地址；删除操作默认进回收站。

> 注意：PyPI 上架前，也可以把包发布为 Git 仓库，用户侧 mcp.json 用 `uvx --from git+https://... fnos-nas-mcp` 运行。
