zalo-agent-cli 1.1.0 → 1.3.0

package/README.md

@@ -30,6 +30,28 @@ Xây dựng trên [zca-js](https://github.com/RFS-ADRENO/zca-js).
 > 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/)
 
+> [!NOTE]
+> **Zalo Official Account (OA)** — v1.1.0 hỗ trợ Zalo OA API v3.0 chính thức:
+> ```bash
+> zalo-agent oa init                                    # Setup wizard (interactive)
+> zalo-agent oa init --app-id <ID> --secret <KEY> --skip-webhook  # Non-interactive (AI agent)
+> zalo-agent oa whoami                                  # Xem thông tin OA
+> 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
+> Xem [docs/official-account.md](docs/official-account.md)
+
+> [!TIP]
+> **MCP Server (AI Agent Integration)** — v1.2.0 hỗ trợ 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)
+> ```
+> 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)
+
 ---
 
 ## Cài đặt
@@ -138,6 +160,28 @@ CLI tool for Zalo automation — multi-account, proxy support, bank transfers, Q
 > 15+ command groups · listen mode + webhook · 55+ VN banks · multi-account + proxy
 > See [skill/SKILL.md](skill/SKILL.md) · [Eval scenarios](skill/evals/)
 
+> [!NOTE]
+> **Zalo Official Account (OA)** — v1.1.0 adds official Zalo OA API v3.0:
+> ```bash
+> zalo-agent oa init                                    # Setup wizard (interactive)
+> zalo-agent oa init --app-id <ID> --secret <KEY> --skip-webhook  # Non-interactive (AI agent)
+> zalo-agent oa whoami                                  # OA profile
+> 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
+> See [docs/official-account.md](docs/official-account.md)
+
+> [!TIP]
+> **MCP Server (AI Agent Integration)** — v1.2.0 adds 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)
+> ```
+> 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)
+
 ### Quick Start
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zalo-agent-cli",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "CLI tool for Zalo automation — multi-account, proxy, bank transfers, QR payments, Official Account API v3.0",
   "type": "module",
   "bin": {
@@ -42,11 +42,14 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "chalk": "^5.3.0",
     "commander": "^14.0.3",
+    "express": "^5.2.1",
     "https-proxy-agent": "^8.0.0",
     "node-fetch": "^3.3.0",
-    "zca-js": "^2.1.1"
+    "zca-js": "^2.1.1",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "eslint": "^10.0.3",

package/src/cli.test.js

@@ -83,6 +83,7 @@ describe("CLI interface", () => {
         assert.match(out, /--proxy/);
         assert.match(out, /--credentials/);
         assert.match(out, /--qr-url/);
+        assert.match(out, /--qr-port/);
     });
 
     it("logout --help shows --purge", () => {

package/src/commands/listen.js

@@ -108,7 +108,21 @@ export function registerListenCommand(program) {
                         if (opts.filter === "group" && msg.type !== THREAD_GROUP) return;
                         if (!opts.self && msg.isSelf) return;
 
-                        const content = typeof msg.data.content === "string" ? msg.data.content : "[non-text]";
+                        const rawContent = msg.data.content;
+                        const isText = typeof rawContent === "string";
+                        const msgType = msg.data.msgType || null;
+                        // Build readable display: show type + title/href for non-text
+                        let displayContent;
+                        if (isText) {
+                            displayContent = rawContent;
+                        } else if (rawContent && typeof rawContent === "object") {
+                            const parts = [msgType || "attachment"];
+                            if (rawContent.title) parts.push(`"${rawContent.title}"`);
+                            if (rawContent.href) parts.push(rawContent.href);
+                            displayContent = `[${parts.join(" | ")}]`;
+                        } else {
+                            displayContent = `[${msgType || "non-text"}]`;
+                        }
                         const data = {
                             event: "message",
                             msgId: msg.data.msgId,
@@ -116,13 +130,16 @@ export function registerListenCommand(program) {
                             threadId: msg.threadId,
                             type: msg.type,
                             isSelf: msg.isSelf,
-                            content,
+                            uidFrom: msg.data.uidFrom || null,
+                            dName: msg.data.dName || null,
+                            msgType,
+                            content: rawContent,
                         };
                         const dir = msg.isSelf ? "→" : "←";
                         const typeLabel = msg.type === THREAD_USER ? "DM" : "GR";
                         emitEvent(
                             data,
-                            `${dir} [${typeLabel}] [${msg.threadId}] ${content}  (msgId: ${msg.data.msgId})`,
+                            `${dir} [${typeLabel}] [${msg.threadId}] ${displayContent}  (msgId: ${msg.data.msgId})`,
                         );
                     });
                 }

package/src/commands/login.js

@@ -26,6 +26,7 @@ export function registerLoginCommands(program) {
         .option("-p, --proxy <url>", "Proxy URL (http/https/socks5://[user:pass@]host:port)")
         .option("-n, --name <label>", "Friendly name for this account", "")
         .option("--qr-url", "Start local HTTP server to view QR in browser (for VPS/headless)")
+        .option("-q, --qr-port <port>", "Port for QR HTTP server (default: 18927)", parseInt)
         .option("--credentials <path>", "Login from exported credentials file (skip QR)")
         .action(async (opts) => {
             // Credential-based login (headless/CI)
@@ -55,8 +56,9 @@ export function registerLoginCommands(program) {
             }
 
             // QR-based login
+            const jsonMode = program.opts().json;
             if (opts.proxy) info(`Using proxy: ${maskProxy(opts.proxy)}`);
-            info("Generating QR code... Scan with Zalo mobile app.");
+            if (!jsonMode) info("Generating QR code... Scan with Zalo mobile app.");
 
             let qrServer = null;
             try {
@@ -65,7 +67,7 @@ export function registerLoginCommands(program) {
 
                     // Always start HTTP server for QR scanning (no flag needed)
                     if (!qrServer) {
-                        qrServer = startQrServer(getQRPath());
+                        qrServer = startQrServer(getQRPath(), opts.qrPort || 18927);
                     }
                 });
 
@@ -79,9 +81,18 @@ export function registerLoginCommands(program) {
                 const creds = extractCredentials();
                 saveCredentials(ownId, creds);
                 addAccount(ownId, displayName, opts.proxy);
-                success(`Logged in as ${displayName} (${ownId})`);
+
+                if (jsonMode) {
+                    console.log(JSON.stringify({ event: "login_success", ownId, name: displayName }));
+                } else {
+                    success(`Logged in as ${displayName} (${ownId})`);
+                }
             } catch (e) {
-                error(`Login failed: ${e.message}`);
+                if (jsonMode) {
+                    console.log(JSON.stringify({ event: "login_error", message: e.message }));
+                } else {
+                    error(`Login failed: ${e.message}`);
+                }
                 process.exit(1);
             } finally {
                 if (qrServer) qrServer.close();

package/src/commands/mcp.js

@@ -0,0 +1,186 @@
+/**
+ * MCP server command — starts a Model Context Protocol server over stdio transport.
+ * Allows Claude Code and other MCP clients to read/send Zalo messages via tool calls.
+ *
+ * IMPORTANT: All diagnostic output uses console.error() — stdout is the MCP transport channel.
+ */
+
+import { getApi, autoLogin, clearSession } from "../core/zalo-client.js";
+import { MessageBuffer } from "../mcp/message-buffer.js";
+import { ThreadFilter } from "../mcp/thread-filter.js";
+import { loadMCPConfig, parseDuration } from "../mcp/mcp-config.js";
+import { createMCPServer } from "../mcp/mcp-server.js";
+import { registerTools } from "../mcp/mcp-tools.js";
+import { createHTTPServer } from "../mcp/mcp-http-transport.js";
+import { ZaloNotifier } from "../mcp/notifier.js";
+
+/** Zalo close code for duplicate web session — fatal, do not retry */
+const CLOSE_DUPLICATE = 3000;
+
+/**
+ * Normalize a raw zca-js message event into the buffer's message shape.
+ * @param {object} msg - Raw zca-js message event
+ * @returns {object} Normalized message
+ */
+function normalizeMessage(msg) {
+    const rawContent = msg.data.content;
+    const isText = typeof rawContent === "string";
+    return {
+        id: msg.data.msgId,
+        threadId: msg.threadId,
+        threadType: msg.type === 0 ? "dm" : "group",
+        senderId: msg.data.uidFrom || null,
+        senderName: msg.data.dName || null,
+        text: isText
+            ? rawContent
+            : rawContent?.title || rawContent?.href || `[${msg.data.msgType || "attachment"}]`,
+        timestamp: Date.now(),
+        type: isText ? "text" : msg.data.msgType || "attachment",
+        attachment:
+            !isText && rawContent
+                ? {
+                      type: msg.data.msgType,
+                      url: rawContent.href || null,
+                      description: rawContent.title || null,
+                  }
+                : null,
+        replyTo: null,
+    };
+}
+
+export function registerMCPCommands(program) {
+    const mcp = program.command("mcp").description("MCP server for AI agent integration");
+
+    mcp.command("start")
+        .description("Start MCP server (stdio or HTTP transport)")
+        .option("--config <path>", "Config file path (default: ~/.zalo-agent-cli/mcp-config.json)")
+        .option("--http <port>", "Use HTTP transport on specified port (default: stdio)")
+        .option("--auth <token>", "Bearer token for HTTP auth (only with --http)")
+        .action(async (opts) => {
+            // Perform login explicitly here — preAction hook skips "mcp"
+            try {
+                await autoLogin(false);
+            } catch (e) {
+                console.error("[mcp] Auto-login failed:", e.message);
+                process.exit(1);
+            }
+
+            // Load MCP config (config path option reserved for future use)
+            const config = loadMCPConfig();
+            console.error("[mcp] Config loaded:", JSON.stringify(config.limits));
+
+            // Build buffer + filter from config
+            const maxAge = parseDuration(config.limits?.bufferMaxAge ?? "2h");
+            const maxSize = config.limits?.bufferMaxSize ?? 500;
+            const buffer = new MessageBuffer(maxSize, maxAge);
+            const filter = new ThreadFilter(config);
+
+            // Start MCP server — stdio (default) or HTTP
+            try {
+                if (opts.http) {
+                    const port = Number(opts.http);
+                    const deps = { api: getApi(), buffer, filter, config };
+                    createHTTPServer(registerTools, deps, port, opts.auth || null);
+                    console.error(`[mcp] HTTP server started on port ${port}`);
+                } else {
+                    await createMCPServer(getApi(), buffer, filter, config);
+                }
+            } catch (e) {
+                console.error("[mcp] Failed to start MCP server:", e.message);
+                process.exit(1);
+            }
+
+            // Setup notifier (sends to Zalo group when agent is offline)
+            const notifier = new ZaloNotifier(getApi(), config);
+
+            let reconnectCount = 0;
+
+            /**
+             * Attach Zalo listener handlers to the current API instance.
+             * Must be called again after each re-login with the new API instance.
+             * @param {object} api - zca-js API instance
+             */
+            function attachListenerHandlers(api) {
+                api.listener.on("message", (msg) => {
+                    // Skip self-sent messages
+                    if (msg.isSelf) return;
+
+                    const normalized = normalizeMessage(msg);
+
+                    // Apply thread watch filter
+                    if (!filter.shouldWatch(normalized.threadId, normalized.threadType)) return;
+
+                    // Apply noise filter (stickers, system msgs, short emoji)
+                    if (!filter.shouldKeep(normalized)) return;
+
+                    buffer.push(normalized.threadId, normalized);
+                    notifier.onMessage(normalized);
+                    console.error(
+                        `[mcp] Buffered ${normalized.threadType} msg from ${normalized.threadId}`,
+                    );
+                });
+
+                api.listener.on("connected", () => {
+                    if (reconnectCount > 0) {
+                        console.error(`[mcp] Reconnected (#${reconnectCount})`);
+                    }
+                });
+
+                api.listener.on("disconnected", (code) => {
+                    console.error(`[mcp] Disconnected (code: ${code}). Auto-retrying...`);
+                });
+
+                api.listener.on("closed", async (code) => {
+                    if (code === CLOSE_DUPLICATE) {
+                        console.error("[mcp] Duplicate Zalo Web session detected. Exiting.");
+                        process.exit(1);
+                    }
+                    reconnectCount++;
+                    console.error(
+                        `[mcp] Connection closed (code: ${code}). Re-login in 5s... (reconnect #${reconnectCount})`,
+                    );
+                    await new Promise((r) => setTimeout(r, 5000));
+                    try {
+                        clearSession();
+                        await autoLogin(false);
+                        console.error("[mcp] Re-login successful. Restarting listener...");
+                        const newApi = getApi();
+                        attachListenerHandlers(newApi);
+                        newApi.listener.start({ retryOnClose: true });
+                    } catch (e) {
+                        console.error(`[mcp] Re-login failed: ${e.message}. Retrying in 30s...`);
+                        await new Promise((r) => setTimeout(r, 30000));
+                        try {
+                            clearSession();
+                            await autoLogin(false);
+                            const retryApi = getApi();
+                            attachListenerHandlers(retryApi);
+                            retryApi.listener.start({ retryOnClose: true });
+                            console.error("[mcp] Re-login successful on retry.");
+                        } catch (e2) {
+                            console.error(`[mcp] Re-login retry failed: ${e2.message}. Exiting.`);
+                            process.exit(1);
+                        }
+                    }
+                });
+
+                api.listener.on("error", () => {
+                    // WS errors are followed by close/disconnect — suppress to avoid noise
+                });
+            }
+
+            // Wire listener and start
+            try {
+                const api = getApi();
+                attachListenerHandlers(api);
+                api.listener.start({ retryOnClose: true });
+                console.error("[mcp] Zalo listener started. MCP server ready.");
+            } catch (e) {
+                console.error("[mcp] Failed to start listener:", e.message);
+                process.exit(1);
+            }
+
+            // Keep process alive (MCP server runs on stdio — process must not exit)
+            await new Promise(() => {});
+        });
+}

package/src/index.js

@@ -27,6 +27,7 @@ import { registerLabelCommands } from "./commands/label.js";
 import { registerCatalogCommands } from "./commands/catalog.js";
 import { registerListenCommand } from "./commands/listen.js";
 import { registerOACommands } from "./commands/oa.js";
+import { registerMCPCommands } from "./commands/mcp.js";
 import { autoLogin } from "./core/zalo-client.js";
 import { checkForUpdates, selfUpdate } from "./utils/update-check.js";
 import { success, error, warning } from "./utils/output.js";
@@ -44,7 +45,8 @@ program
     .hook("preAction", async (thisCommand) => {
         const cmdName = thisCommand.args?.[0] || thisCommand.name();
         // Suppress zca-js internal logs in JSON mode to keep stdout clean for piping
-        if (program.opts().json) {
+        if (program.opts().json || cmdName === "mcp") {
+            // Suppress zca-js stdout logs: JSON mode needs clean output, MCP uses stdout as transport
             process.env.ZALO_JSON_MODE = "1";
         } else if (cmdName !== "oa") {
             // OA commands use official Zalo API — no disclaimer needed
@@ -52,7 +54,7 @@ program
             console.log();
         }
         // Auto-login before any command that needs it (skip for login/account/oa commands)
-        const skipAutoLogin = ["login", "account", "help", "version", "update", "oa"].includes(cmdName);
+        const skipAutoLogin = ["login", "account", "help", "version", "update", "oa", "mcp"].includes(cmdName);
         if (!skipAutoLogin) {
             await autoLogin(program.opts().json);
         }
@@ -88,5 +90,6 @@ registerLabelCommands(program);
 registerCatalogCommands(program);
 registerListenCommand(program);
 registerOACommands(program);
+registerMCPCommands(program);
 
 program.parse();

package/src/mcp/mcp-config.js

@@ -0,0 +1,76 @@
+/**
+ * Load/save MCP-specific config from ~/.zalo-agent-cli/mcp-config.json.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { CONFIG_DIR } from "../core/credentials.js";
+
+const MCP_CONFIG_FILE = join(CONFIG_DIR, "mcp-config.json");
+
+/** Default MCP config — sensible defaults for local development */
+export function getDefaultConfig() {
+    return {
+        watchThreads: ["dm:*", "group:*"],
+        mode: "manual",
+        triggerKeywords: ["@bot"],
+        notify: {
+            enabled: false,
+            thread: null,
+            on: ["dm"],
+            cooldown: "5m",
+        },
+        limits: {
+            maxMessagesPerPoll: 20,
+            autoDigestThreshold: 50,
+            bufferMaxAge: "2h",
+            bufferMaxSize: 500,
+        },
+    };
+}
+
+/**
+ * Load MCP config from disk, merged with defaults.
+ * @returns {object} MCP config
+ */
+export function loadMCPConfig() {
+    const defaults = getDefaultConfig();
+    try {
+        const raw = readFileSync(MCP_CONFIG_FILE, "utf-8");
+        const saved = JSON.parse(raw);
+        // Shallow merge: saved values override defaults
+        return {
+            ...defaults,
+            ...saved,
+            notify: { ...defaults.notify, ...saved.notify },
+            limits: { ...defaults.limits, ...saved.limits },
+        };
+    } catch {
+        // File doesn't exist or invalid JSON — use defaults
+        return defaults;
+    }
+}
+
+/**
+ * Save MCP config to disk.
+ * @param {object} config
+ */
+export function saveMCPConfig(config) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(MCP_CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
+}
+
+/**
+ * Parse duration string (e.g. "2h", "5m", "30s") to milliseconds.
+ * @param {string|number} duration
+ * @returns {number} Milliseconds
+ */
+export function parseDuration(duration) {
+    if (typeof duration === "number") return duration;
+    const match = String(duration).match(/^(\d+)\s*(h|m|s|ms)?$/i);
+    if (!match) return 0;
+    const value = parseInt(match[1], 10);
+    const unit = (match[2] || "ms").toLowerCase();
+    const multipliers = { h: 3600000, m: 60000, s: 1000, ms: 1 };
+    return value * (multipliers[unit] || 1);
+}

package/src/mcp/mcp-http-transport.js

@@ -0,0 +1,75 @@
+/**
+ * Express server wrapping MCP StreamableHTTP transport with bearer token auth.
+ * Uses stateless mode — each POST /mcp request creates a fresh server+transport.
+ */
+
+import express from "express";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+
+/**
+ * Create HTTP MCP server with optional bearer token auth.
+ * @param {Function} registerToolsFn - Registers tools on a McpServer instance
+ * @param {object} deps - { api, buffer, filter, config }
+ * @param {number} port
+ * @param {string|null} authToken - Bearer token (null = no auth)
+ * @returns {import("http").Server}
+ */
+export function createHTTPServer(registerToolsFn, deps, port, authToken) {
+    const app = express();
+    app.use(express.json());
+
+    // Auth middleware — skips /health
+    if (authToken) {
+        app.use((req, res, next) => {
+            if (req.path === "/health") return next();
+            const token = req.headers.authorization?.slice(7); // strip "Bearer "
+            if (token !== authToken) {
+                return res.status(401).json({ error: "Unauthorized" });
+            }
+            next();
+        });
+    }
+
+    // MCP endpoint — stateless, fresh server+transport per request
+    app.post("/mcp", async (req, res) => {
+        try {
+            const server = new McpServer({ name: "zalo-agent", version: "1.0.0" });
+            registerToolsFn(server, deps.api, deps.buffer, deps.filter, deps.config);
+
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined, // stateless mode
+            });
+
+            res.on("close", () => {
+                transport.close();
+                server.close();
+            });
+
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        } catch (err) {
+            console.error("MCP HTTP error:", err);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                });
+            }
+        }
+    });
+
+    // Health check — no auth required
+    app.get("/health", (req, res) => {
+        res.json({
+            status: "ok",
+            uptime: Math.floor(process.uptime()),
+            threads: deps.buffer.getStats().length,
+        });
+    });
+
+    return app.listen(port, "0.0.0.0", () => {
+        console.error(`MCP HTTP server listening on port ${port}`);
+    });
+}

package/src/mcp/mcp-server.js

@@ -0,0 +1,33 @@
+/**
+ * MCP server setup with stdio transport.
+ * Creates and connects the McpServer instance for Claude Code integration.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./mcp-tools.js";
+
+/**
+ * Create and start MCP server with stdio transport.
+ * All logs MUST use console.error() — stdout is reserved for MCP protocol.
+ * @param {object} api - zca-js API instance
+ * @param {import("./message-buffer.js").MessageBuffer} buffer
+ * @param {import("./thread-filter.js").ThreadFilter} filter
+ * @param {object} config - MCP config
+ * @returns {Promise<McpServer>}
+ */
+export async function createMCPServer(api, buffer, filter, config) {
+    const server = new McpServer({
+        name: "zalo-agent",
+        version: "1.0.0",
+    });
+
+    registerTools(server, api, buffer, filter, config);
+
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+
+    console.error("[mcp-server] MCP server connected via stdio transport");
+
+    return server;
+}