@ardennguyen/zalo-agent-cli 1.0.7 → 2.1.0

package/README.md

@@ -4,22 +4,32 @@
 
 # zalo-agent-cli
 
-Công cụ CLI tự động hóa Zalo — đa tài khoản, proxy, chuyển khoản ngân hàng, thanh toán QR.
+Công cụ CLI tự động hóa Zalo — đa tài khoản, proxy, chuyển khoản ngân hàng, thanh toán QR, Official Account API v3.0, và MCP server cho AI agent.
 Xây dựng trên [zca-js](https://github.com/RFS-ADRENO/zca-js).
 
+[![License: CC BY-NC-SA 4.0](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc-sa/4.0/)
+
 **[Tiếng Việt](#bắt-đầu-nhanh)** | **[English](#english)**
 
 > [!WARNING]
 > Tool này sử dụng API Zalo **không chính thức** ([zca-js](https://github.com/RFS-ADRENO/zca-js)). Zalo không hỗ trợ và **tài khoản của bạn có thể bị khóa hoặc ban**. Tự chịu trách nhiệm. Không liên kết với Zalo hay VNG. Xem [DISCLAIMER.md](DISCLAIMER.md).
 
+> [!IMPORTANT]
+> **Zalo chỉ cho phép một phiên web trên mỗi tài khoản — CLI này chiếm phiên đó.**
+> Đăng nhập Zalo Web (hoặc ứng dụng PC khác) sẽ thu hồi phiên của CLI ngay lập tức
+> ở phía máy chủ, kể cả khi không có tiến trình nào đang chạy. Ngược lại,
+> `zalo-agent login` sẽ đăng xuất Zalo Web. Ứng dụng điện thoại không bị ảnh hưởng.
+> Đo ngày 20/09/2026.
+> Lệnh `oa` là ngoại lệ — chúng dùng **API chính thức** của Zalo OA, không có rủi ro ban.
+
 > [!TIP]
 > **AI Agent Skill** — Dùng với OpenClaw, Claude Code, hoặc bất kỳ agent nào hỗ trợ SKILL.md:
 > ```bash
 > clawhub install zalo-agent          # OpenClaw (từ ClawHub registry)
 > cp -r skill/ ~/.claude/skills/zalo-agent/   # Claude Code
 > ```
-> 15+ nhóm lệnh · listen mode + webhook · 55+ ngân hàng VN · đa tài khoản + proxy
-> Xem [skill/SKILL.md](skill/SKILL.md) · [Eval scenarios](skill/evals/)
+> 16 nhóm lệnh · 190 lệnh · listen mode + webhook · 55+ ngân hàng VN · đa tài khoản + proxy
+> Xem [skill/SKILL.md](skill/SKILL.md) · [Tham chiếu lệnh đầy đủ](skill/references/command-reference.md) · [Eval scenarios](skill/evals/)
 
 > [!NOTE]
 > **Zalo Official Account (OA)** — Zalo OA API v3.0 chính thức:
@@ -30,27 +40,33 @@ Xây dựng trên [zca-js](https://github.com/RFS-ADRENO/zca-js).
 > zalo-agent oa msg text <user-id> "Xin chào"           # Gửi tin nhắn
 > zalo-agent oa listen -p 3000                           # Webhook listener
 > ```
-> OAuth login · gửi tin nhắn · quản lý follower · tag · webhook listener · VPS support
+> OAuth login · gửi tin nhắn · follower · tag · bài viết · cửa hàng · webhook listener · multi-OA · VPS support
 > Xem [docs/official-account.md](docs/official-account.md)
 
 > [!TIP]
 > **MCP Server (AI Agent Integration)** — Model Context Protocol cho Claude Code và các MCP client:
 > ```bash
-> zalo-agent mcp start              # stdio (local Claude Code)
-> zalo-agent mcp start --http 3847 --auth your-secret  # HTTP (VPS)
+> zalo-agent mcp start                                  # stdio (local Claude Code)
+> zalo-agent mcp start --http 3847 --auth your-secret   # HTTP (VPS)
 > ```
-> 4 tools: get_messages · send_message · list_threads · mark_read
-> Auto-reconnect · thread filter · noise reduction · group notifications
-> Xem [MCP Guide](skill/references/mcp-guide.md)
+> 14 tools: `zalo_get_messages` · `zalo_send_message` · `zalo_list_threads` · `zalo_search_threads` · `zalo_mark_read` · `zalo_get_history` · `zalo_view_media` · `zalo_react` · `zalo_undo` · `zalo_get_group_members` · `zalo_list_conversations` · `zalo_coverage` · `zalo_sync` · `zalo_sync_status`
+
+[Sync qua MCP và điều kiện phát hành](docs/mcp-sync.vi.md).
+> Auto-reconnect · thread filter · noise reduction · tự tải media · thông báo qua nhóm Zalo
+> Xem [MCP Guide](skill/references/mcp-guide.md) · [INSTALLATION.md](INSTALLATION.md)
 
 ---
 
 ## Cài đặt
 
+Yêu cầu **Node.js 22+**.
+
 ```bash
 npm install -g @ardennguyen/zalo-agent-cli
 ```
 
+Muốn cài kèm MCP server dạng sandbox (khuyến nghị cho AI client) → xem [INSTALLATION.md](INSTALLATION.md).
+
 ## Bắt đầu nhanh
 
 ### 1. Đăng nhập
@@ -59,7 +75,7 @@ npm install -g @ardennguyen/zalo-agent-cli
 zalo-agent login
 ```
 
-Quét QR bằng **Zalo app > Quét mã QR**. Thông tin tự động lưu.
+Quét QR bằng **Zalo app > Quét mã QR** (không dùng camera thường). QR cũng xem được trên trình duyệt tại `http://<host>:18927/qr`. Thông tin đăng nhập tự động lưu tại `~/.zalo-agent-cli/` (quyền 0600).
 
 ### 2. Tìm bạn bè
 
@@ -89,50 +105,86 @@ zalo-agent msg send <THREAD_ID> "Xin chào nhóm!" -t 1
 
 ## Danh sách lệnh
 
-Tất cả lệnh hỗ trợ `--json`. Tài liệu đầy đủ: **[Wiki](https://github.com/ardennguyen/zalo-agent-cli/wiki)**
-
-| Nhóm lệnh | Mô tả | Docs |
-|------------|--------|------|
-| `msg` | Gửi tin nhắn, hình, file, voice, video, sticker, link, thẻ chuyển khoản, QR | [Tin nhắn](https://github.com/ardennguyen/zalo-agent-cli/wiki/Tin-Nh%E1%BA%AFn) |
-| `friend` | Danh sách, tìm, thêm, xóa, chặn, biệt danh, gợi ý | [Bạn bè](https://github.com/ardennguyen/zalo-agent-cli/wiki/B%E1%BA%A1n-B%C3%A8) |
-| `group` | Tạo, đổi tên, thành viên, cài đặt, link, ghi chú, lời mời | [Nhóm & Cộng đồng](https://github.com/ardennguyen/zalo-agent-cli/wiki/Nh%C3%B3m) |
-| `conv` | Tắt thông báo, ghim, lưu trữ, ẩn hội thoại, tự xóa | [Hội thoại](https://github.com/ardennguyen/zalo-agent-cli/wiki/H%E1%BB%99i-Tho%E1%BA%A1i) |
-| `profile` | Xem/cập nhật hồ sơ, ảnh đại diện, quyền riêng tư | [Hồ sơ](https://github.com/ardennguyen/zalo-agent-cli/wiki/H%E1%BB%93-S%C6%A1) |
-| `poll` | Tạo, bỏ phiếu, đóng khảo sát | [Khảo sát](https://github.com/ardennguyen/zalo-agent-cli/wiki/Kh%E1%BA%A3o-S%C3%A1t) |
-| `reminder` | Tạo, sửa, xóa nhắc nhở | [Nhắc nhở](https://github.com/ardennguyen/zalo-agent-cli/wiki/Nh%E1%BA%AFc-Nh%E1%BB%9F) |
-| `auto-reply` | Quản lý trả lời tự động | [Trả lời tự động](https://github.com/ardennguyen/zalo-agent-cli/wiki/Tr%E1%BA%A3-L%E1%BB%9Di-T%E1%BB%B1-%C4%90%E1%BB%99ng) |
-| `quick-msg` | Tin nhắn nhanh đã lưu | [Tin nhắn nhanh](https://github.com/ardennguyen/zalo-agent-cli/wiki/Tin-Nh%E1%BA%AFn-Nhanh) |
-| `label` | Nhãn hội thoại | [Nhãn](https://github.com/ardennguyen/zalo-agent-cli/wiki/Nh%C3%A3n) |
-| `catalog` | zBusiness — danh mục sản phẩm | [zBusiness](https://github.com/ardennguyen/zalo-agent-cli/wiki/zBusiness) |
-| `listen` | Lắng nghe tin nhắn real-time, webhook, lưu JSONL | [Lắng nghe](https://github.com/ardennguyen/zalo-agent-cli/wiki/L%E1%BA%AFng-Nghe) |
-| `account` | Đa tài khoản & proxy | [Tài khoản](https://github.com/ardennguyen/zalo-agent-cli/wiki/T%C3%A0i-Kho%E1%BA%A3n) |
-| **`oa`** | **Zalo Official Account API v3.0 — OAuth, tin nhắn, follower, tag, webhook** | **[Official Account](https://github.com/ardennguyen/zalo-agent-cli/wiki/Official-Account)** |
-
-Xem thêm: [Đa tài khoản & Proxy](https://github.com/ardennguyen/zalo-agent-cli/wiki/%C4%90a-T%C3%A0i-Kho%E1%BA%A3n-&-Proxy) · [Cài đặt VPS](https://github.com/ardennguyen/zalo-agent-cli/wiki/C%C3%A0i-%C4%90%E1%BA%B7t-VPS) · [Thẻ chuyển khoản & QR](https://github.com/ardennguyen/zalo-agent-cli/wiki/Th%E1%BA%BB-Chuy%E1%BB%83n-Kho%E1%BA%A3n-&-QR) · [Official Account](https://github.com/ardennguyen/zalo-agent-cli/wiki/Official-Account)
+Tất cả lệnh hỗ trợ `--json`. Tài liệu đầy đủ: **[Wiki](https://github.com/ardennguyen/zalo-agent-cli/wiki)** · [Tham chiếu lệnh đầy đủ](skill/references/command-reference.md)
+
+| Nhóm lệnh | Số lệnh | Mô tả | Docs |
+|------------|:---:|--------|------|
+| *(top-level)* | 11 | `login`, `logout`, `status`, `whoami`, `update`, `sync`, `sync-mobile`, `sync-media`, `sync-reactions`, `sync-boards`, `sync-cloud` | [Đăng nhập & Đăng xuất](https://github.com/ardennguyen/zalo-agent-cli/wiki/%C4%90%C4%83ng-Nh%E1%BA%ADp-&-%C4%90%C4%83ng-Xu%E1%BA%A5t) |
+| `msg` | 20 | Gửi tin nhắn, hình, file, voice, video, sticker, link, thẻ chuyển khoản, QR, thu hồi, lịch sử | [Tin nhắn](https://github.com/ardennguyen/zalo-agent-cli/wiki/Tin-Nh%E1%BA%AFn) |
+| `friend` | 22 | Danh sách, tìm, thêm, xóa, chặn, biệt danh, gợi ý | [Bạn bè](https://github.com/ardennguyen/zalo-agent-cli/wiki/B%E1%BA%A1n-B%C3%A8) |
+| `group` | 33 | Tạo, đổi tên, thành viên, cài đặt, link, ghi chú, lời mời | [Nhóm & Cộng đồng](https://github.com/ardennguyen/zalo-agent-cli/wiki/Nh%C3%B3m) |
+| `conv` | 20 | Tắt thông báo, ghim, lưu trữ, ẩn hội thoại, tự xóa, xoá bộ nhớ đệm cục bộ (`forget`) | [Hội thoại](https://github.com/ardennguyen/zalo-agent-cli/wiki/H%E1%BB%99i-Tho%E1%BA%A1i) |
+| `account` | 7 | Đa tài khoản & proxy, thiết bị đã liên kết, xóa tài khoản | [Tài khoản](https://github.com/ardennguyen/zalo-agent-cli/wiki/T%C3%A0i-Kho%E1%BA%A3n) |
+| `profile` | 11 | Xem/cập nhật hồ sơ, ảnh đại diện, quyền riêng tư | [Hồ sơ](https://github.com/ardennguyen/zalo-agent-cli/wiki/H%E1%BB%93-S%C6%A1) |
+| `poll` | 7 | Tạo, bỏ phiếu, đóng khảo sát | [Khảo sát](https://github.com/ardennguyen/zalo-agent-cli/wiki/Kh%E1%BA%A3o-S%C3%A1t) |
+| `reminder` | 6 | Tạo, sửa, xóa nhắc nhở | [Nhắc nhở](https://github.com/ardennguyen/zalo-agent-cli/wiki/Nh%E1%BA%AFc-Nh%E1%BB%9F) |
+| `auto-reply` | 4 | Quản lý trả lời tự động | [Trả lời tự động](https://github.com/ardennguyen/zalo-agent-cli/wiki/Tr%E1%BA%A3-L%E1%BB%9Di-T%E1%BB%B1-%C4%90%E1%BB%99ng) |
+| `quick-msg` | 4 | Tin nhắn nhanh đã lưu | [Tin nhắn nhanh](https://github.com/ardennguyen/zalo-agent-cli/wiki/Tin-Nh%E1%BA%AFn-Nhanh) |
+| `label` | 2 | Nhãn hội thoại | [Nhãn](https://github.com/ardennguyen/zalo-agent-cli/wiki/Nh%C3%A3n) |
+| `catalog` | 9 | zBusiness — danh mục sản phẩm | [zBusiness](https://github.com/ardennguyen/zalo-agent-cli/wiki/zBusiness) |
+| `listen` | 1 | Lắng nghe real-time, webhook, JSONL, ghi vào cache cục bộ | [Lắng nghe](https://github.com/ardennguyen/zalo-agent-cli/wiki/L%E1%BA%AFng-Nghe) |
+| `mcp` | 1 | MCP server (stdio/HTTP) — 14 tools cho AI agent | [MCP Server](https://github.com/ardennguyen/zalo-agent-cli/wiki/MCP-Server-(VN)) |
+| **`oa`** | **32** | **Zalo Official Account API v3.0 — OAuth, tin nhắn, follower, tag, bài viết, cửa hàng, webhook** | **[Official Account](https://github.com/ardennguyen/zalo-agent-cli/wiki/Official-Account-(VN))** |
+
+Xem thêm: [Đa tài khoản & Proxy](https://github.com/ardennguyen/zalo-agent-cli/wiki/%C4%90a-T%C3%A0i-Kho%E1%BA%A3n-&-Proxy) · [Cài đặt VPS](https://github.com/ardennguyen/zalo-agent-cli/wiki/C%C3%A0i-%C4%90%E1%BA%B7t-VPS) · [Thẻ chuyển khoản & QR](https://github.com/ardennguyen/zalo-agent-cli/wiki/Th%E1%BA%BB-Chuy%E1%BB%83n-Kho%E1%BA%A3n-&-QR) · [Bộ nhớ đệm & Đồng bộ](https://github.com/ardennguyen/zalo-agent-cli/wiki/B%E1%BB%99-Nh%E1%BB%9B-%C4%90%E1%BB%87m-&-%C4%90%E1%BB%93ng-B%E1%BB%99) · [Bảo mật](https://github.com/ardennguyen/zalo-agent-cli/wiki/B%E1%BA%A3o-M%E1%BA%ADt)
 
 ---
 
 ## Tính năng
 
-- Đăng nhập QR qua HTTP server tự động (browser + terminal)
-- Đa tài khoản với proxy riêng biệt (1:1)
-- 90+ lệnh phủ hết tính năng Zalo
-- **Zalo Official Account (OA) API v3.0** — OAuth login, gửi tin nhắn, quản lý follower, webhook listener
+- Đăng nhập QR qua HTTP server tự động (browser + terminal), báo ngay khi bị **từ chối trên điện thoại** thay vì treo tới hết 60s
+- Đa tài khoản với proxy riêng biệt (1:1), device fingerprint riêng cho từng tài khoản
+- **190 lệnh** phủ hết tính năng Zalo cá nhân
+- **Zalo Official Account (OA) API v3.0** — OAuth login, gửi tin nhắn, follower, tag, bài viết, cửa hàng, webhook listener, multi-OA
+- **MCP server** (stdio + HTTP) — 14 tools cho Claude Code và các MCP client: đọc, gửi (kể cả vào My Documents, đánh dấu Quan trọng/Khẩn cấp), thả cảm xúc, thu hồi tin, xem thành viên nhóm, liệt kê hội thoại gần đây và kiểm tra độ đầy đủ của cache
+- **Bộ nhớ đệm cục bộ (SQLite)** — `listen` ghi mọi tin nhắn vào `zalo.db`, `msg history` đọc từ cache, `sync` (hoặc `sync-mobile`) khôi phục toàn bộ lịch sử từ điện thoại vào `zalo.db` (giải mã transfer-sync-v2; xác nhận một lần trên điện thoại), mặc định lấy **toàn bộ** lịch sử (không còn mốc chặn 2024-01-01); thêm `--days <n>` hoặc `--from <YYYY-MM-DD>` nếu chỉ cần một khoảng. Dọn dẹp: `sync-media --prune <days|all>` giải phóng dung lượng nhưng giữ nguyên nội dung tin nhắn, `--prune-orphans` nhắm vào hội thoại tài khoản không còn, và `conv forget` xoá hẳn bản sao cục bộ của một hội thoại — không cái nào gửi gì tới Zalo. Luồng đồng bộ chỉ mang **liên kết** media chứ không mang file, nên sau khi lưu tin nhắn, `sync-mobile` **tự động tải media về** (thêm `--messages-only` nếu chỉ muốn tin nhắn); `sync-media` chạy lại/tiếp tục bước tải này, không cần xác nhận trên điện thoại. Ghi chú, tin ghim, bình chọn và nhắc hẹn nằm ngoài luồng tin nhắn — dùng `sync-boards`
+- Tự động tải media (ảnh/audio/video) — một downloader duy nhất cho `listen`, `msg history`, `mcp start` và các lệnh sync, lưu vào `~/.zalo-agent-cli/accounts/<id>/media/<threadId>/` (MCP server có thể ghi đè bằng `media.downloadDir`)
 - Thẻ chuyển khoản (55+ ngân hàng VN) & QR VietQR
 - Lắng nghe real-time với webhook & lưu JSONL local
+- `logout` hủy phiên **phía server** thật sự; `logout --purge` / `account remove` xóa sạch dữ liệu cục bộ
 - Output `--json` cho mọi lệnh — scripting & AI agents
-- Credentials mã hóa tại chỗ (quyền 0600)
-- **Dual mode**: interactive (human) + non-interactive (AI agents, CI/CD)
-
----
-
-
+- Credentials lưu cục bộ với quyền 0600
+- **Dual mode**: interactive (con người) + non-interactive (AI agents, CI/CD)
+
+## Tài liệu
+
+| Tài liệu | Nội dung |
+|----------|----------|
+| [INSTALLATION.md](INSTALLATION.md) | Cài đặt `zalo-mcp` wrapper, cấu hình MCP client, thiết lập OA |
+| [docs/official-account.md](docs/official-account.md) | Tham chiếu đầy đủ lệnh OA (tiếng Việt) |
+| [skill/SKILL.md](skill/SKILL.md) | Skill cho AI agent |
+| [skill/references/command-reference.md](skill/references/command-reference.md) | Tham chiếu lệnh đầy đủ (nguồn chuẩn) |
+| [skill/references/mcp-guide.md](skill/references/mcp-guide.md) | Hướng dẫn MCP server (tiếng Việt) |
+| [skill/references/oa-command-reference.md](skill/references/oa-command-reference.md) | Tham chiếu nhanh lệnh OA cho agent |
+| [skill/references/login-flow.md](skill/references/login-flow.md) | Các cách đăng nhập (QR, proxy, credentials) |
+| [skill/references/listen-mode-guide.md](skill/references/listen-mode-guide.md) | Vận hành listener và webhook |
+| [tests/README.md](tests/README.md) | Cách chạy và viết test: bộ offline, E2E phân tầng + checklist thủ công |
+| [DISCLAIMER.md](DISCLAIMER.md) | Điều khoản đầy đủ và cảnh báo rủi ro |
+| [AGENTS.md](AGENTS.md) | Quy tắc dự án cho AI coding agent |
+| [Wiki](https://github.com/ardennguyen/zalo-agent-cli/wiki) | Tài liệu công khai, song ngữ EN + VN |
+
+## Giấy phép
+
+zalo-agent-cli © 2026 Arden Nguyen Duc Huy được cấp phép theo [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/). Xem [LICENSE](LICENSE) và [NOTICE](NOTICE). Điều khoản đầy đủ và cảnh báo rủi ro nằm trong [DISCLAIMER.md](DISCLAIMER.md).
+
+- **Miễn phí cho mục đích phi thương mại**: cá nhân, học thuật, nghiên cứu. **Không cấp phép cho mục đích thương mại** — ví dụ dùng trong sản phẩm thương mại, để cung cấp dịch vụ có thu phí, hoặc trong hoạt động kinh doanh của một công ty. Muốn xin giấy phép thương mại, hãy [mở một issue](https://github.com/ardennguyen/zalo-agent-cli/issues).
+- **Ghi công**: khi chia sẻ dự án này hoặc một phần của nó (nguyên bản hay đã sửa đổi, kể cả bên trong dự án khác), hãy ghi công theo mẫu trong [NOTICE](NOTICE), nêu rõ bạn có sửa đổi hay không, và dẫn link giấy phép.
+- **Chia sẻ tương tự (ShareAlike)**: bản sửa đổi được chia sẻ phải dùng CC BY-NC-SA 4.0 (hoặc phiên bản mới hơn, hoặc giấy phép tương thích do Creative Commons liệt kê).
+- Các phần dẫn xuất từ phần mềm MIT — [zalo-agent-cli của PhucMPham](https://github.com/PhucMPham/zalo-agent-cli) và bản vá của [zca-js](https://github.com/RFS-ADRENO/zca-js) được đóng gói kèm — vẫn thuộc giấy phép MIT; xem [NOTICE](NOTICE).
+- Các phiên bản phát hành trước thay đổi này (2.0.0 trở về trước) được phát hành theo giấy phép MIT và giữ nguyên các điều khoản đó.
 
 ---
 
 ## English
 
-CLI tool for Zalo automation — multi-account, proxy support, bank transfers, QR payments.
+CLI tool for Zalo automation — multi-account, proxy support, bank transfers, QR payments, Official Account API v3.0, and an MCP server for AI agents.
+
+> [!IMPORTANT]
+> **Zalo allows one web session per account — this CLI occupies it.**
+> Signing into Zalo Web (or another PC client) revokes the CLI's session
+> server-side, instantly, even with nothing running. The reverse is also true:
+> `zalo-agent login` signs Zalo Web out. Your phone app is unaffected.
+> Measured 2026-09-20.
 
 > [!TIP]
 > **AI Agent Skill** — Use with OpenClaw, Claude Code, or any SKILL.md-compatible agent:
@@ -140,8 +192,8 @@ CLI tool for Zalo automation — multi-account, proxy support, bank transfers, Q
 > clawhub install zalo-agent                    # OpenClaw (from ClawHub registry)
 > cp -r skill/ ~/.claude/skills/zalo-agent/     # Claude Code
 > ```
-> 15+ command groups · listen mode + webhook · 55+ VN banks · multi-account + proxy
-> See [skill/SKILL.md](skill/SKILL.md) · [Eval scenarios](skill/evals/)
+> 16 command groups · 190 commands · listen mode + webhook · 55+ VN banks · multi-account + proxy
+> See [skill/SKILL.md](skill/SKILL.md) · [Full command reference](skill/references/command-reference.md) · [Eval scenarios](skill/evals/)
 
 > [!NOTE]
 > **Zalo Official Account (OA)** — Official Zalo OA API v3.0:
@@ -152,21 +204,25 @@ CLI tool for Zalo automation — multi-account, proxy support, bank transfers, Q
 > zalo-agent oa msg text <user-id> "Hello"              # Send message
 > zalo-agent oa listen -p 3000                           # Webhook listener
 > ```
-> OAuth login · messaging · follower management · tags · webhook listener · VPS support
+> OAuth login · messaging · followers · tags · articles · store · webhook listener · multi-OA · VPS support
 > See [docs/official-account.md](docs/official-account.md)
 
 > [!TIP]
 > **MCP Server (AI Agent Integration)** — Model Context Protocol support for Claude Code and MCP clients:
 > ```bash
-> zalo-agent mcp start              # stdio (local Claude Code)
-> zalo-agent mcp start --http 3847 --auth your-secret  # HTTP (VPS)
+> zalo-agent mcp start                                  # stdio (local Claude Code)
+> zalo-agent mcp start --http 3847 --auth your-secret   # HTTP (VPS)
 > ```
-> 4 tools: get_messages · send_message · list_threads · mark_read
-> Auto-reconnect · thread filter · noise reduction · group notifications
-> See [MCP Guide](skill/references/mcp-guide.md)
+> 14 tools: `zalo_get_messages` · `zalo_send_message` · `zalo_list_threads` · `zalo_search_threads` · `zalo_mark_read` · `zalo_get_history` · `zalo_view_media` · `zalo_react` · `zalo_undo` · `zalo_get_group_members` · `zalo_list_conversations` · `zalo_coverage` · `zalo_sync` · `zalo_sync_status`
+
+[MCP sync and release prerequisites](docs/mcp-sync.md).
+> Auto-reconnect · thread filter · noise reduction · media auto-download · Zalo-group notifications
+> See [MCP Guide](skill/references/mcp-guide.md) · [INSTALLATION.md](INSTALLATION.md)
 
 ### Quick Start
 
+Requires **Node.js 22+**.
+
 ```bash
 npm install -g @ardennguyen/zalo-agent-cli
 zalo-agent login                           # 1. Login via QR
@@ -175,31 +231,74 @@ zalo-agent listen                          # 3. Listen for threadId
 zalo-agent msg send <THREAD_ID> "Hello!"   # 4. Send a message
 ```
 
-### Commands
-
-Full docs: **[Wiki](https://github.com/ardennguyen/zalo-agent-cli/wiki)**
-
-| Group | Description | Docs |
-|-------|-------------|------|
-| `msg` | Text, images, files, voice, video, stickers, links, bank cards, QR | [Messages](https://github.com/ardennguyen/zalo-agent-cli/wiki/Messages) |
-| `friend` | List, find, add, remove, block, alias, recommendations | [Friends](https://github.com/ardennguyen/zalo-agent-cli/wiki/Friends) |
-| `group` | Create, rename, members, settings, links, notes, invites | [Groups](https://github.com/ardennguyen/zalo-agent-cli/wiki/Groups) |
-| `conv` | Mute, pin, archive, hidden, auto-delete | [Conversations](https://github.com/ardennguyen/zalo-agent-cli/wiki/Conversations) |
-| `profile` | Profile, avatar gallery, privacy | [Profile](https://github.com/ardennguyen/zalo-agent-cli/wiki/Profile) |
-| `poll` | Create, vote, lock polls | [Polls](https://github.com/ardennguyen/zalo-agent-cli/wiki/Polls) |
-| `reminder` | Create, edit, remove reminders | [Reminders](https://github.com/ardennguyen/zalo-agent-cli/wiki/Reminders) |
-| `auto-reply` | Auto-reply rules | [Auto-Reply](https://github.com/ardennguyen/zalo-agent-cli/wiki/Auto-Reply) |
-| `quick-msg` | Saved quick messages | [Quick Messages](https://github.com/ardennguyen/zalo-agent-cli/wiki/Quick-Messages) |
-| `label` | Conversation labels | [Labels](https://github.com/ardennguyen/zalo-agent-cli/wiki/Labels) |
-| `catalog` | zBusiness catalogs & products | [Catalog](https://github.com/ardennguyen/zalo-agent-cli/wiki/Catalog) |
-| `listen` | Real-time listener, webhook, JSONL | [Listener](https://github.com/ardennguyen/zalo-agent-cli/wiki/Listener) |
-| `account` | Multi-account & proxy | [Accounts](https://github.com/ardennguyen/zalo-agent-cli/wiki/Accounts) |
-| **`oa`** | **Zalo Official Account API v3.0 — OAuth, messaging, followers, webhook** | **[Official Account](https://github.com/ardennguyen/zalo-agent-cli/wiki/Official-Account)** |
+For the sandboxed MCP-server install (recommended for AI clients), see [INSTALLATION.md](INSTALLATION.md).
 
+### Commands
 
+Full docs: **[Wiki](https://github.com/ardennguyen/zalo-agent-cli/wiki)** · [Full command reference](skill/references/command-reference.md)
+
+| Group | Commands | Description | Docs |
+|-------|:---:|-------------|------|
+| *(top-level)* | 11 | `login`, `logout`, `status`, `whoami`, `update`, `sync`, `sync-mobile`, `sync-media`, `sync-reactions`, `sync-boards`, `sync-cloud` | [Login & Logout](https://github.com/ardennguyen/zalo-agent-cli/wiki/Login-&-Logout) |
+| `msg` | 20 | Text, images, files, voice, video, stickers, links, bank cards, QR, recall, history | [Messages](https://github.com/ardennguyen/zalo-agent-cli/wiki/Messages) |
+| `friend` | 22 | List, find, add, remove, block, alias, recommendations | [Friends](https://github.com/ardennguyen/zalo-agent-cli/wiki/Friends) |
+| `group` | 33 | Create, rename, members, settings, links, notes, invites | [Groups](https://github.com/ardennguyen/zalo-agent-cli/wiki/Groups) |
+| `conv` | 20 | Mute, pin, archive, hidden, auto-delete, forget local cache | [Conversations](https://github.com/ardennguyen/zalo-agent-cli/wiki/Conversations) |
+| `account` | 7 | Multi-account & proxy, linked devices, account removal | [Accounts](https://github.com/ardennguyen/zalo-agent-cli/wiki/Accounts) |
+| `profile` | 11 | Profile, avatar gallery, privacy | [Profile](https://github.com/ardennguyen/zalo-agent-cli/wiki/Profile) |
+| `poll` | 7 | Create, vote, lock polls | [Polls](https://github.com/ardennguyen/zalo-agent-cli/wiki/Polls) |
+| `reminder` | 6 | Create, edit, remove reminders | [Reminders](https://github.com/ardennguyen/zalo-agent-cli/wiki/Reminders) |
+| `auto-reply` | 4 | Auto-reply rules | [Auto-Reply](https://github.com/ardennguyen/zalo-agent-cli/wiki/Auto-Reply) |
+| `quick-msg` | 4 | Saved quick messages | [Quick Messages](https://github.com/ardennguyen/zalo-agent-cli/wiki/Quick-Messages) |
+| `label` | 2 | Conversation labels | [Labels](https://github.com/ardennguyen/zalo-agent-cli/wiki/Labels) |
+| `catalog` | 9 | zBusiness catalogs & products | [Catalog](https://github.com/ardennguyen/zalo-agent-cli/wiki/Catalog) |
+| `listen` | 1 | Real-time listener, webhook, JSONL, local cache writes | [Listener](https://github.com/ardennguyen/zalo-agent-cli/wiki/Listener) |
+| `mcp` | 1 | MCP server (stdio/HTTP) — 14 tools for AI agents | [MCP Server](https://github.com/ardennguyen/zalo-agent-cli/wiki/MCP-Server) |
+| **`oa`** | **32** | **Zalo Official Account API v3.0 — OAuth, messaging, followers, tags, articles, store, webhook** | **[Official Account](https://github.com/ardennguyen/zalo-agent-cli/wiki/Official-Account)** |
+
+See also: [Multi-Account & Proxy](https://github.com/ardennguyen/zalo-agent-cli/wiki/Multi-Account-&-Proxy) · [VPS Setup](https://github.com/ardennguyen/zalo-agent-cli/wiki/VPS-Setup) · [Bank Card & QR Payments](https://github.com/ardennguyen/zalo-agent-cli/wiki/Bank-Card-&-QR-Payments) · [Local Cache & Sync](https://github.com/ardennguyen/zalo-agent-cli/wiki/Local-Cache-&-Sync) · [Security](https://github.com/ardennguyen/zalo-agent-cli/wiki/Security)
+
+### Features
+
+- QR login over an auto-started HTTP server (browser + terminal), reporting a **decline on the phone** immediately instead of hanging until the 60s timeout
+- Multi-account with a dedicated proxy (1:1) and a per-account device fingerprint
+- **190 commands** covering the personal-account Zalo surface
+- **Zalo Official Account (OA) API v3.0** — OAuth login, messaging, followers, tags, articles, store, webhook listener, multi-OA
+- **MCP server** (stdio + HTTP) — 14 tools for Claude Code and other MCP clients: read, send (to My Documents too, marked Important/Urgent), react, recall, list a group's members, list recent conversations, and check how complete the cache is
+- **Local SQLite cache** — `listen` writes every message to `zalo.db`, `msg history` reads from it, and `sync` (or `sync-mobile`) restores full history from the phone into `zalo.db` (transfer-sync-v2 decrypt; one confirmation on the phone), defaulting to **all** history (the old 2024-01-01 floor is gone), with `--days <n>` or `--from <YYYY-MM-DD>` to narrow it. Housekeeping: `sync-media --prune <days|all>` reclaims disk while keeping message text, `--prune-orphans` targets conversations the account no longer has, and `conv forget` removes a conversation's local copy entirely — none of which contact Zalo. The sync stream carries media **links**, not files, so a `sync-mobile` run **downloads its attachments automatically** once the messages are stored (`--messages-only` skips it); `sync-media` re-runs or resumes that fetch on its own, with no phone confirmation. Notes, pinned messages, polls and reminders live outside the message stream — `sync-boards` fetches those
+- Automatic media download — one downloader shared by `listen`, `msg history`, `mcp start` and the sync commands, saving to `~/.zalo-agent-cli/accounts/<id>/media/<threadId>/` (the MCP server can override the root with `media.downloadDir`)
+- Bank cards (55+ VN banks) and VietQR payment images
+- Real-time listener with webhook forwarding and local JSONL archival
+- `logout` performs a real **server-side** session invalidation; `logout --purge` / `account remove` wipe all local data
+- `--json` output on every command — scripting and AI agents
+- Credentials stored locally with 0600 permissions
+- **Dual mode**: interactive (human) and non-interactive (AI agents, CI/CD)
+
+### Documentation
+
+| Document | Contents |
+|----------|----------|
+| [INSTALLATION.md](INSTALLATION.md) | `zalo-mcp` wrapper install, MCP client config, OA setup |
+| [docs/official-account.md](docs/official-account.md) | Full OA command reference (Vietnamese) |
+| [skill/SKILL.md](skill/SKILL.md) | AI agent skill |
+| [skill/references/command-reference.md](skill/references/command-reference.md) | Exhaustive command reference (source of truth) |
+| [skill/references/mcp-guide.md](skill/references/mcp-guide.md) | MCP server guide (Vietnamese) |
+| [skill/references/oa-command-reference.md](skill/references/oa-command-reference.md) | OA quick reference for agents |
+| [skill/references/login-flow.md](skill/references/login-flow.md) | Login methods (QR, proxy, credentials file) |
+| [skill/references/listen-mode-guide.md](skill/references/listen-mode-guide.md) | Listener and webhook operation |
+| [tests/README.md](tests/README.md) | How to run and write the tests: offline suite, tiered live E2E, manual checklist |
+| [DISCLAIMER.md](DISCLAIMER.md) | Full terms and risk warning |
+| [AGENTS.md](AGENTS.md) | Project rules for AI coding agents |
+| [Wiki](https://github.com/ardennguyen/zalo-agent-cli/wiki) | Public docs, bilingual EN + VN |
 
 ---
 
 ## License
 
-[MIT](LICENSE) · See [DISCLAIMER.md](DISCLAIMER.md) for full terms.
+zalo-agent-cli © 2026 Arden Nguyen Duc Huy is licensed under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/). See [LICENSE](LICENSE) and [NOTICE](NOTICE). See [DISCLAIMER.md](DISCLAIMER.md) for full terms and risk warnings.
+
+- **Free for non-commercial use** (personal, academic, research). **Commercial use is not licensed** — for example in a commercial product, to provide paid services, or in a company's business operations. To request a commercial license, [open an issue](https://github.com/ardennguyen/zalo-agent-cli/issues).
+- **Credit required:** if you share this project or any part of it, as-is or modified (including inside another project), credit it as shown in [NOTICE](NOTICE), say whether you made changes, and link to the license.
+- **ShareAlike:** shared modifications must be released under CC BY-NC-SA 4.0 (or a later version, or a compatible license listed by Creative Commons).
+- Portions derived from MIT-licensed software — [zalo-agent-cli by PhucMPham](https://github.com/PhucMPham/zalo-agent-cli) and the patched [zca-js](https://github.com/RFS-ADRENO/zca-js) shipped inside the package — remain under the MIT License; see [NOTICE](NOTICE).
+- Versions published before this change (2.0.0 and earlier) were released under the MIT License and keep those terms.

package/node_modules/asynckit/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Alex Indigo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/asynckit/README.md

@@ -0,0 +1,233 @@
+# asynckit [![NPM Module](https://img.shields.io/npm/v/asynckit.svg?style=flat)](https://www.npmjs.com/package/asynckit)
+
+Minimal async jobs utility library, with streams support.
+
+[![PhantomJS Build](https://img.shields.io/travis/alexindigo/asynckit/v0.4.0.svg?label=browser&style=flat)](https://travis-ci.org/alexindigo/asynckit)
+[![Linux Build](https://img.shields.io/travis/alexindigo/asynckit/v0.4.0.svg?label=linux:0.12-6.x&style=flat)](https://travis-ci.org/alexindigo/asynckit)
+[![Windows Build](https://img.shields.io/appveyor/ci/alexindigo/asynckit/v0.4.0.svg?label=windows:0.12-6.x&style=flat)](https://ci.appveyor.com/project/alexindigo/asynckit)
+
+[![Coverage Status](https://img.shields.io/coveralls/alexindigo/asynckit/v0.4.0.svg?label=code+coverage&style=flat)](https://coveralls.io/github/alexindigo/asynckit?branch=master)
+[![Dependency Status](https://img.shields.io/david/alexindigo/asynckit/v0.4.0.svg?style=flat)](https://david-dm.org/alexindigo/asynckit)
+[![bitHound Overall Score](https://www.bithound.io/github/alexindigo/asynckit/badges/score.svg)](https://www.bithound.io/github/alexindigo/asynckit)
+
+<!-- [![Readme](https://img.shields.io/badge/readme-tested-brightgreen.svg?style=flat)](https://www.npmjs.com/package/reamde) -->
+
+AsyncKit provides harness for `parallel` and `serial` iterators over list of items represented by arrays or objects.
+Optionally it accepts abort function (should be synchronously return by iterator for each item), and terminates left over jobs upon an error event. For specific iteration order built-in (`ascending` and `descending`) and custom sort helpers also supported, via `asynckit.serialOrdered` method.
+
+It ensures async operations to keep behavior more stable and prevent `Maximum call stack size exceeded` errors, from sync iterators.
+
+| compression        |     size |
+| :----------------- | -------: |
+| asynckit.js        | 12.34 kB |
+| asynckit.min.js    |  4.11 kB |
+| asynckit.min.js.gz |  1.47 kB |
+
+
+## Install
+
+```sh
+$ npm install --save asynckit
+```
+
+## Examples
+
+### Parallel Jobs
+
+Runs iterator over provided array in parallel. Stores output in the `result` array,
+on the matching positions. In unlikely event of an error from one of the jobs,
+will terminate rest of the active jobs (if abort function is provided)
+and return error along with salvaged data to the main callback function.
+
+#### Input Array
+
+```javascript
+var parallel = require('asynckit').parallel
+  , assert   = require('assert')
+  ;
+
+var source         = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
+  , expectedResult = [ 2, 2, 8, 32, 128, 64, 16, 4 ]
+  , expectedTarget = [ 1, 1, 2, 4, 8, 16, 32, 64 ]
+  , target         = []
+  ;
+
+parallel(source, asyncJob, function(err, result)
+{
+  assert.deepEqual(result, expectedResult);
+  assert.deepEqual(target, expectedTarget);
+});
+
+// async job accepts one element from the array
+// and a callback function
+function asyncJob(item, cb)
+{
+  // different delays (in ms) per item
+  var delay = item * 25;
+
+  // pretend different jobs take different time to finish
+  // and not in consequential order
+  var timeoutId = setTimeout(function() {
+    target.push(item);
+    cb(null, item * 2);
+  }, delay);
+
+  // allow to cancel "leftover" jobs upon error
+  // return function, invoking of which will abort this job
+  return clearTimeout.bind(null, timeoutId);
+}
+```
+
+More examples could be found in [test/test-parallel-array.js](test/test-parallel-array.js).
+
+#### Input Object
+
+Also it supports named jobs, listed via object.
+
+```javascript
+var parallel = require('asynckit/parallel')
+  , assert   = require('assert')
+  ;
+
+var source         = { first: 1, one: 1, four: 4, sixteen: 16, sixtyFour: 64, thirtyTwo: 32, eight: 8, two: 2 }
+  , expectedResult = { first: 2, one: 2, four: 8, sixteen: 32, sixtyFour: 128, thirtyTwo: 64, eight: 16, two: 4 }
+  , expectedTarget = [ 1, 1, 2, 4, 8, 16, 32, 64 ]
+  , expectedKeys   = [ 'first', 'one', 'two', 'four', 'eight', 'sixteen', 'thirtyTwo', 'sixtyFour' ]
+  , target         = []
+  , keys           = []
+  ;
+
+parallel(source, asyncJob, function(err, result)
+{
+  assert.deepEqual(result, expectedResult);
+  assert.deepEqual(target, expectedTarget);
+  assert.deepEqual(keys, expectedKeys);
+});
+
+// supports full value, key, callback (shortcut) interface
+function asyncJob(item, key, cb)
+{
+  // different delays (in ms) per item
+  var delay = item * 25;
+
+  // pretend different jobs take different time to finish
+  // and not in consequential order
+  var timeoutId = setTimeout(function() {
+    keys.push(key);
+    target.push(item);
+    cb(null, item * 2);
+  }, delay);
+
+  // allow to cancel "leftover" jobs upon error
+  // return function, invoking of which will abort this job
+  return clearTimeout.bind(null, timeoutId);
+}
+```
+
+More examples could be found in [test/test-parallel-object.js](test/test-parallel-object.js).
+
+### Serial Jobs
+
+Runs iterator over provided array sequentially. Stores output in the `result` array,
+on the matching positions. In unlikely event of an error from one of the jobs,
+will not proceed to the rest of the items in the list
+and return error along with salvaged data to the main callback function.
+
+#### Input Array
+
+```javascript
+var serial = require('asynckit/serial')
+  , assert = require('assert')
+  ;
+
+var source         = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
+  , expectedResult = [ 2, 2, 8, 32, 128, 64, 16, 4 ]
+  , expectedTarget = [ 0, 1, 2, 3, 4, 5, 6, 7 ]
+  , target         = []
+  ;
+
+serial(source, asyncJob, function(err, result)
+{
+  assert.deepEqual(result, expectedResult);
+  assert.deepEqual(target, expectedTarget);
+});
+
+// extended interface (item, key, callback)
+// also supported for arrays
+function asyncJob(item, key, cb)
+{
+  target.push(key);
+
+  // it will be automatically made async
+  // even it iterator "returns" in the same event loop
+  cb(null, item * 2);
+}
+```
+
+More examples could be found in [test/test-serial-array.js](test/test-serial-array.js).
+
+#### Input Object
+
+Also it supports named jobs, listed via object.
+
+```javascript
+var serial = require('asynckit').serial
+  , assert = require('assert')
+  ;
+
+var source         = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
+  , expectedResult = [ 2, 2, 8, 32, 128, 64, 16, 4 ]
+  , expectedTarget = [ 0, 1, 2, 3, 4, 5, 6, 7 ]
+  , target         = []
+  ;
+
+var source         = { first: 1, one: 1, four: 4, sixteen: 16, sixtyFour: 64, thirtyTwo: 32, eight: 8, two: 2 }
+  , expectedResult = { first: 2, one: 2, four: 8, sixteen: 32, sixtyFour: 128, thirtyTwo: 64, eight: 16, two: 4 }
+  , expectedTarget = [ 1, 1, 4, 16, 64, 32, 8, 2 ]
+  , target         = []
+  ;
+
+
+serial(source, asyncJob, function(err, result)
+{
+  assert.deepEqual(result, expectedResult);
+  assert.deepEqual(target, expectedTarget);
+});
+
+// shortcut interface (item, callback)
+// works for object as well as for the arrays
+function asyncJob(item, cb)
+{
+  target.push(item);
+
+  // it will be automatically made async
+  // even it iterator "returns" in the same event loop
+  cb(null, item * 2);
+}
+```
+
+More examples could be found in [test/test-serial-object.js](test/test-serial-object.js).
+
+_Note: Since _object_ is an _unordered_ collection of properties,
+it may produce unexpected results with sequential iterations.
+Whenever order of the jobs' execution is important please use `serialOrdered` method._
+
+### Ordered Serial Iterations
+
+TBD
+
+For example [compare-property](compare-property) package.
+
+### Streaming interface
+
+TBD
+
+## Want to Know More?
+
+More examples can be found in [test folder](test/).
+
+Or open an [issue](https://github.com/alexindigo/asynckit/issues) with questions and/or suggestions.
+
+## License
+
+AsyncKit is licensed under the MIT license.