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 — ห้ามปิดถ้าเข้าผ่านอินเทอร์เน็ตสาธารณะ

ติดตั้ง

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)

python -m mcp_syncnology.server

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

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 รันจริง

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:

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

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

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 ที่ผู้ใช้ระบุเองเท่านั้น