# mcp-syncnology

MCP server ที่เปิดให้ Hermes agent (หรือ MCP client อื่น ๆ) ควบคุม/ดูข้อมูล **Synology NAS** ผ่าน DSM Web API — ไม่ใช่ web scraping, เป็น API ทางการของ Synology ที่ล็อกอินด้วย username/password แล้วได้ session token (`_sid`) มาใช้เรียก endpoint อื่น ๆ ต่อ

## โครงสร้าง

```
src/mcp_syncnology/
  config.py   # อ่าน env: SYNOLOGY_BASE_URL, SYNOLOGY_USERNAME, SYNOLOGY_PASSWORD, ...
  client.py   # SynologyClient: login/session + wrapper รอบ DSM API แต่ละตัว
  server.py   # FastMCP server + tool definitions
```

`client.py` มี `call(api, method, version, **params)` กลางที่ resolve path/version จริงของแต่ละ API ผ่าน `SYNO.API.Info` เอง (ไม่ hardcode path) และ auto re-login ถ้า session หมดอายุ — เพิ่ม DSM API ตัวใหม่ได้ง่าย ๆ โดยเรียก `self.call("SYNO.xxx", "method", ...)`

## ความปลอดภัย

- **ห้ามใส่รหัสผ่านจริงในโค้ดหรือแชทเด็ดขาด** — เก็บไว้ใน `.env` (ไฟล์นี้อยู่ใน `.gitignore` แล้ว) เท่านั้น
- ถ้า DSM account เปิด 2FA ไว้ ต้องใส่ `SYNOLOGY_OTP_CODE` ต่อการ login หนึ่งครั้ง (code หมดอายุเร็ว) — แนะนำให้สร้าง local DSM account แยกสำหรับ automation นี้แล้วปิด 2FA เฉพาะ account นั้น หรือใช้ Application Password ถ้า DSM version รองรับ
- Tool `syncnology_delete_path` เป็น irreversible action ต้องเรียกด้วย `confirm=True` เท่านั้น และควรให้ agent ยืนยันกับผู้ใช้ก่อนเรียกทุกครั้ง
- ถ้า NAS ใช้ self-signed cert ในเครือข่ายภายใน ให้ตั้ง `SYNOLOGY_VERIFY_SSL=false` ใน `.env` — ห้ามปิดถ้าเข้าผ่านอินเทอร์เน็ตสาธารณะ

## ติดตั้ง

```bash
cd D:/MCP/mcp-syncnology
pip install -e .
copy .env.example .env
```

แก้ `.env` ให้เป็น IP/พอร์ต NAS จริง (เช่น `https://192.168.1.10:5001`) และ username/password ของ DSM

## รันทดสอบ (stdio)

```bash
python -m mcp_syncnology.server
```

หรือทดสอบผ่าน MCP Inspector:

```bash
mcp dev src/mcp_syncnology/server.py
```

## Tools ที่มีให้แล้ว

| Tool | ทำอะไร |
|---|---|
| `syncnology_list_shared_folders` | list shared folder บน NAS |
| `syncnology_list_files` | list ไฟล์/โฟลเดอร์ในพาธที่กำหนด |
| `syncnology_get_file_info` | ดู metadata ของไฟล์/โฟลเดอร์ |
| `syncnology_create_folder` | สร้างโฟลเดอร์ใหม่ |
| `syncnology_delete_path` | ลบไฟล์/โฟลเดอร์ (ต้อง `confirm=True`) |
| `syncnology_system_info` | ข้อมูลรุ่น/DSM version/uptime |
| `syncnology_utilization` | CPU/RAM/network usage ปัจจุบัน |
| `syncnology_storage_info` | สถานะ storage pool/volume/disk |
| `syncnology_list_backup_tasks` | list Active Backup for Business task |
| `syncnology_backup_task_status` | สถานะ backup task ตาม task_id (filter จาก list, ไม่มี method status แยก) |
| `syncnology_list_download_tasks` | list Download Station task |
| `syncnology_create_download_task` | เพิ่ม download task ใหม่ (URL/magnet) |
| `syncnology_delete_download_task` | ลบ download task |
| `syncnology_list_cameras` | list กล้องใน Surveillance Station |
| `syncnology_system_logs` | ดู system log ล่าสุด |

เพิ่ม tool ใหม่: เพิ่มเมธอดใน `client.py` ที่เรียก `self.call("SYNO.xxx", "method", ...)` แล้วห่อด้วย `@mcp.tool()` ใน `server.py`

## ต่อกับ Hermes agent

Hermes เก็บ MCP server config ไว้ที่ `~/.hermes/config.yaml` (Linux/DGX Spark) หรือ `%LOCALAPPDATA%\hermes\config.yaml` (Windows) ใต้ key `mcp_servers:` ค่า secret (`SYNOLOGY_USERNAME`/`SYNOLOGY_PASSWORD`) อ่านจาก `.env` ในโฟลเดอร์นี้โดยตรงเสมอ ไม่ต้องใส่ใน config ของ Hermes

### Deploy บน DGX Spark (Linux) — ที่ Hermes รันจริง

```bash
git clone https://github.com/humyai99/mcp-syncnology.git
cd mcp-syncnology
python3 -m venv .venv
.venv/bin/python -m pip install -e .
cp .env.example .env   # แก้ SYNOLOGY_BASE_URL/USERNAME/PASSWORD ให้เป็นค่าจริง
chmod +x run-hermes.sh
```

แล้วเพิ่มใน `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  mcp-syncnology:
    command: bash
    args:
      - /path/to/mcp-syncnology/run-hermes.sh
    enabled: true
```

### Windows (ถ้ามี Hermes instance แยกบนเครื่องนี้ด้วย)

```yaml
mcp_servers:
  mcp-syncnology:
    command: powershell.exe
    args:
      - -NoProfile
      - -ExecutionPolicy
      - Bypass
      - -File
      - D:\MCP\mcp-syncnology\run-hermes.ps1
    enabled: true
```

หลังแก้ config ต้อง restart Hermes เพื่อโหลด MCP server ตัวใหม่

## ทดสอบแล้วกับ NAS จริง

- ผ่าน: login, system_info, utilization, storage_info, list_shared_folders, list_files, get_file_info, create_folder, delete_path, system_logs, list_backup_tasks, backup_task_status
- `syncnology_list_download_tasks` / `syncnology_list_cameras` ยังไม่ได้ทดสอบจริง เพราะ NAS ที่ใช้ทดสอบไม่ได้ติดตั้งแพ็กเกจ Download Station / Surveillance Station — โค้ดเรียก API ตามเอกสารทั่วไป แต่ยังไม่ยืนยันกับ NAS ที่มีแพ็กเกจเหล่านี้จริง
- รันด้วย `python scripts/smoke_test.py` (read-only) หรือ `--with-write` (รวม create/delete โฟลเดอร์ทดสอบ) เพื่อตรวจสอบกับ NAS ของคุณเองอีกครั้ง เพราะพฤติกรรม DSM API บางอย่าง (เช่น version ของ method ที่ใช้ได้) ต่างกันไปตาม DSM version

## ยังไม่ได้ทำ / ข้อจำกัดที่ควรรู้

- ยังไม่รองรับ Application Password / OAuth ของ DSM 7+ (ถ้ามีจะปลอดภัยกว่า username/password ตรง ๆ)
- `syncnology_create_download_task` ให้ NAS ไปดึงไฟล์จาก URL ใดก็ได้ — ควรจำกัดว่า agent เรียกได้จาก URL ที่ผู้ใช้ระบุเองเท่านั้น