@ardennguyen/zalo-agent-cli 1.0.7

package/src/mcp/mcp-tools.js

@@ -0,0 +1,353 @@
+/**
+ * MCP tool registrations for Zalo message access and sending.
+ * Registers 7 tools: zalo_get_messages, zalo_get_history, zalo_send_message, zalo_list_threads, zalo_search_threads, zalo_mark_read, zalo_view_media.
+ */
+
+import { z } from "zod";
+import { downloadMedia, openFile } from "./media-downloader.js";
+import { extractMessageText } from "../utils/extract-message-text.js";
+
+/** Thread type constants matching zca-js ThreadType enum */
+const THREAD_USER = 0;
+
+/**
+ * Wrap a result object into MCP tool content format.
+ * @param {object} result
+ * @returns {{ content: Array }}
+ */
+function ok(result) {
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+}
+
+/**
+ * Wrap an error message into MCP tool error content format.
+ * @param {string} message
+ * @returns {{ content: Array, isError: true }}
+ */
+function err(message) {
+    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+
+/**
+ * Register all Zalo MCP tools on the server.
+ * @param {import("@modelcontextprotocol/sdk/server/mcp.js").McpServer} server
+ * @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
+ * @param {import("./thread-name-cache.js").ThreadNameCache} [nameCache] - Thread name cache
+ */
+export function registerTools(server, api, buffer, filter, config, nameCache) {
+    const maxPerPoll = config.limits?.maxMessagesPerPoll ?? 20;
+
+    // --- zalo_get_messages ---
+    server.registerTool(
+        "zalo_get_messages",
+        {
+            title: "Get Zalo Messages",
+            description:
+                "Get messages from Zalo threads (DMs and groups). Returns buffered messages since last read. Use 'since' cursor from previous response for incremental polling.",
+            inputSchema: z.object({
+                threadId: z.string().optional().describe("Thread ID to read from. Omit for all watched threads."),
+                since: z.number().int().min(0).default(0).describe("Cursor from previous read for incremental polling"),
+                limit: z.number().int().min(1).max(100).default(maxPerPoll).describe("Max messages to return"),
+            }),
+        },
+        async ({ threadId, since, limit }) => {
+            try {
+                const result = buffer.read(threadId, since, limit);
+                // Enrich messages with thread name from cache
+                if (nameCache) {
+                    for (const msg of result.messages) {
+                        const info = nameCache.get(msg.threadId);
+                        if (info) msg.threadName = info.name;
+                    }
+                }
+                return ok(result);
+            } catch (e) {
+                console.error("[mcp-tools] zalo_get_messages error:", e.message);
+                return err(e.message);
+            }
+        },
+    );
+
+    // --- zalo_send_message ---
+    server.registerTool(
+        "zalo_send_message",
+        {
+            title: "Send Zalo Message",
+            description: "Send a text message to a Zalo thread (DM or group). threadType: 0=DM(User), 1=Group.",
+            inputSchema: z.object({
+                threadId: z.string().describe("Thread ID to send message to"),
+                text: z.string().min(1).describe("Message text to send"),
+                threadType: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .max(1)
+                    .default(THREAD_USER)
+                    .describe("Thread type: 0=DM(User), 1=Group"),
+            }),
+        },
+        async ({ threadId, text, threadType }) => {
+            try {
+                const result = await api.sendMessage(text, threadId, Number(threadType));
+                const messageId = result?.message?.msgId ?? result?.msgId ?? null;
+                return ok({ success: true, messageId });
+            } catch (e) {
+                console.error("[mcp-tools] zalo_send_message error:", e.message);
+                return err(e.message);
+            }
+        },
+    );
+
+    // --- zalo_list_threads ---
+    server.registerTool(
+        "zalo_list_threads",
+        {
+            title: "List Zalo Threads",
+            description:
+                "List all Zalo threads currently buffered with unread message counts. Useful for discovering active conversations.",
+            inputSchema: z.object({
+                type: z
+                    .enum(["group", "dm", "all"])
+                    .default("all")
+                    .describe("Filter by thread type: 'dm', 'group', or 'all'"),
+            }),
+        },
+        async ({ type }) => {
+            try {
+                const stats = buffer.getStats(0);
+                // Enrich each stat entry with threadType and thread name
+                const enriched = stats.map((t) => {
+                    const threadType = buffer.getThreadType(t.threadId) ?? "unknown";
+                    const cached = nameCache?.get(t.threadId);
+                    return {
+                        ...t,
+                        threadType,
+                        name: cached?.name ?? null,
+                        ...(cached?.memberCount !== undefined && { memberCount: cached.memberCount }),
+                    };
+                });
+                const filtered = type === "all" ? enriched : enriched.filter((t) => t.threadType === type);
+                return ok({ threads: filtered, total: filtered.length });
+            } catch (e) {
+                console.error("[mcp-tools] zalo_list_threads error:", e.message);
+                return err(e.message);
+            }
+        },
+    );
+
+    // --- zalo_search_threads ---
+    server.registerTool(
+        "zalo_search_threads",
+        {
+            title: "Search Zalo Threads",
+            description:
+                "Search threads (groups/DMs) by name. Uses fuzzy Vietnamese-aware matching. Useful for finding a thread ID by name.",
+            inputSchema: z.object({
+                query: z.string().min(1).describe("Search keyword (fuzzy match, case-insensitive, accent-insensitive)"),
+                type: z
+                    .enum(["group", "dm", "all"])
+                    .default("all")
+                    .describe("Filter by thread type: 'dm', 'group', or 'all'"),
+                limit: z.number().int().min(1).max(50).default(10).describe("Max results to return"),
+            }),
+        },
+        async ({ query, type, limit }) => {
+            try {
+                if (!nameCache?.ready) {
+                    return err("Thread name cache not initialized yet. Try again shortly.");
+                }
+                const results = nameCache.search(query, type, limit);
+                return ok({ results, total: results.length });
+            } catch (e) {
+                console.error("[mcp-tools] zalo_search_threads error:", e.message);
+                return err(e.message);
+            }
+        },
+    );
+
+    // --- zalo_mark_read ---
+    server.registerTool(
+        "zalo_mark_read",
+        {
+            title: "Mark Zalo Messages Read",
+            description:
+                "Discard buffered messages up to and including the given cursor. Use the cursor returned by zalo_get_messages.",
+            inputSchema: z.object({
+                cursor: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .describe("Cursor value returned from a previous zalo_get_messages call"),
+            }),
+        },
+        async ({ cursor }) => {
+            try {
+                const discarded = buffer.markRead(cursor);
+                return ok({ success: true, discarded });
+            } catch (e) {
+                console.error("[mcp-tools] zalo_mark_read error:", e.message);
+                return err(e.message);
+            }
+        },
+    );
+
+    // --- zalo_get_history ---
+    server.registerTool(
+        "zalo_get_history",
+        {
+            title: "Get Zalo Message History",
+            description:
+                "Fetch historical messages from a Zalo DM or group conversation (up to ~2 weeks). " +
+                "Unlike zalo_get_messages (which reads from the live buffer), this fetches older messages " +
+                "from the Zalo server. Use 'lastMsgId' cursor from previous response for pagination. " +
+                "WARNING: Large limits may consume significant memory/bandwidth. Start with a small limit and paginate.",
+            inputSchema: z.object({
+                threadId: z.string().describe("Thread ID to fetch history from"),
+                threadType: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .max(1)
+                    .default(THREAD_USER)
+                    .describe("Thread type: 0=DM(User), 1=Group"),
+                limit: z.number().int().min(1).max(200).default(50).describe("Max messages to fetch"),
+                lastMsgId: z
+                    .string()
+                    .optional()
+                    .nullable()
+                    .describe("Cursor: last message ID from previous fetch for pagination"),
+            }),
+        },
+        async ({ threadId, threadType, limit, lastMsgId }) => {
+            try {
+                const allMessages = [];
+                let cursor = lastMsgId || null;
+                let done = false;
+                const maxPages = Math.ceil(limit / 20);
+                let page = 0;
+
+                while (!done && allMessages.length < limit && page < maxPages) {
+                    page++;
+                    const pageMessages = await new Promise((resolve) => {
+                        const handler = (messages) => {
+                            clearTimeout(timer);
+                            api.listener.removeListener("old_messages", handler);
+                            resolve(messages);
+                        };
+                        const timer = setTimeout(() => {
+                            api.listener.removeListener("old_messages", handler);
+                            resolve([]);
+                        }, 10000);
+
+                        api.listener.on("old_messages", handler);
+                        api.listener.requestOldMessages(threadType, cursor);
+                    });
+
+                    if (!pageMessages || pageMessages.length === 0) {
+                        done = true;
+                        break;
+                    }
+
+                    for (const msg of pageMessages) {
+                        if (allMessages.length >= limit) break;
+                        // API returns messages globally — filter to requested thread
+                        const msgThread = String(msg.threadId || "");
+                        const msgSender = String(msg.data?.uidFrom || "");
+                        const target = String(threadId);
+                        if (msgThread !== target && msgSender !== target) continue;
+                        const rawContent = msg.data?.content;
+                        const isText = typeof rawContent === "string";
+                        allMessages.push({
+                            msgId: msg.data?.msgId,
+                            threadId: msg.threadId,
+                            senderId: msg.data?.uidFrom || null,
+                            senderName: msg.data?.dName || null,
+                            text: isText ? rawContent : extractMessageText(rawContent, msg.data?.msgType),
+                            timestamp: msg.data?.ts ? Number(msg.data.ts) : null,
+                            type: isText ? "text" : msg.data?.msgType || "attachment",
+                        });
+                    }
+
+                    const lastMsg = pageMessages[pageMessages.length - 1];
+                    const nextId = lastMsg?.data?.actionId || lastMsg?.data?.msgId;
+                    if (!nextId || nextId === cursor) done = true;
+                    cursor = nextId;
+                }
+
+                // Sort oldest first
+                allMessages.sort((a, b) => (a.timestamp || 0) - (b.timestamp || 0));
+
+                // Enrich with thread name
+                if (nameCache) {
+                    const info = nameCache.get(threadId);
+                    if (info) {
+                        for (const msg of allMessages) msg.threadName = info.name;
+                    }
+                }
+
+                return ok({
+                    threadId,
+                    threadType: threadType === 0 ? "dm" : "group",
+                    count: allMessages.length,
+                    messages: allMessages,
+                    cursor: cursor,
+                    hasMore: !done,
+                });
+            } catch (e) {
+                console.error("[mcp-tools] zalo_get_history error:", e.message);
+                return err(e.message);
+            }
+        },
+    );
+
+    // --- zalo_view_media ---
+    const mediaConfig = config.media || {};
+    server.registerTool(
+        "zalo_view_media",
+        {
+            title: "View Zalo Media",
+            description:
+                "Open a Zalo media file (image, audio, video) with the system viewer. " +
+                "Media is auto-downloaded when received, organized by thread folder with date/sender metadata filenames. " +
+                "If not yet downloaded, downloads first then opens.",
+            inputSchema: z.object({
+                messageId: z.string().describe("Message ID from zalo_get_messages that has a media attachment"),
+                threadId: z.string().optional().describe("Thread ID to search in. Omit to search all threads."),
+                open: z
+                    .boolean()
+                    .default(mediaConfig.autoOpen ?? true)
+                    .describe("Open media with system viewer"),
+            }),
+        },
+        async ({ messageId, threadId, open }) => {
+            try {
+                const allMessages = buffer.read(threadId, 0, 9999).messages;
+                const message = allMessages.find((m) => m.id === messageId);
+                if (!message) return err(`Message ${messageId} not found in buffer`);
+                if (!message.attachment?.url) return err(`Message ${messageId} has no media attachment`);
+
+                // Use local file if already auto-downloaded, otherwise download now
+                let localPath = message.attachment.localPath;
+                if (!localPath) {
+                    const threadName = nameCache?.get(message.threadId)?.name || null;
+                    const result = await downloadMedia(message, {
+                        downloadDir: mediaConfig.downloadDir || undefined,
+                        autoOpen: false,
+                        threadName,
+                    });
+                    localPath = result.path;
+                }
+
+                if (open) openFile(localPath);
+
+                return ok({ success: true, path: localPath, mediaType: message.type });
+            } catch (e) {
+                console.error("[mcp-tools] zalo_view_media error:", e.message);
+                return err(e.message);
+            }
+        },
+    );
+}

package/src/mcp/media-downloader.js

@@ -0,0 +1,191 @@
+/**
+ * Download Zalo media (images, audio, video) to local filesystem, organized by thread name.
+ * Folder structure: {downloadDir}/{threadName}/{date}_{time}_{sender}_{msgId}.{ext}
+ * Cross-platform: opens media with system viewer (open/xdg-open/start).
+ */
+
+import { mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import { platform } from "os";
+import { execFile } from "child_process";
+import { CONFIG_DIR } from "../core/credentials.js";
+
+/** Default download directory when not configured */
+const DEFAULT_DIR = join(CONFIG_DIR, "media");
+
+/** Characters unsafe for filesystem paths — stripped from folder/file names */
+const UNSAFE_CHARS = /[/\\:*?"<>|]/g;
+
+/** Message types that have downloadable attachments */
+const DOWNLOADABLE_TYPES = new Set(["image", "video", "audio", "voice", "gif", "file"]);
+
+/** Extension lookup by content-type prefix */
+const CONTENT_TYPE_MAP = {
+    "image/jpeg": "jpg",
+    "image/jpg": "jpg",
+    "image/png": "png",
+    "image/gif": "gif",
+    "image/webp": "webp",
+    "image/bmp": "bmp",
+    "audio/mpeg": "mp3",
+    "audio/mp3": "mp3",
+    "audio/mp4": "m4a",
+    "audio/aac": "aac",
+    "audio/ogg": "ogg",
+    "audio/wav": "wav",
+    "audio/x-wav": "wav",
+    "video/mp4": "mp4",
+    "video/webm": "webm",
+    "video/quicktime": "mov",
+};
+
+/** Fallback extension by message type when URL and content-type give no clue */
+const TYPE_DEFAULT_EXT = {
+    image: "jpg",
+    audio: "mp3",
+    voice: "mp3",
+    video: "mp4",
+    gif: "gif",
+    file: "bin",
+};
+
+/**
+ * Sanitize a string for use as a filesystem name.
+ * @param {string} name
+ * @returns {string}
+ */
+function sanitize(name) {
+    return (name || "unknown").replace(UNSAFE_CHARS, "_").trim() || "unknown";
+}
+
+/**
+ * Guess file extension from URL, content-type, or message type.
+ * @param {string} url
+ * @param {string} [contentType]
+ * @param {string} [msgType] - Normalized message type (image, audio, video, etc.)
+ * @returns {string}
+ */
+function guessExtension(url, contentType, msgType) {
+    // Try content-type first
+    if (contentType) {
+        const ct = contentType.split(";")[0].trim().toLowerCase();
+        if (CONTENT_TYPE_MAP[ct]) return CONTENT_TYPE_MAP[ct];
+    }
+    // Try URL path extension
+    const urlMatch = url.match(/\.(jpeg|jpg|png|gif|webp|bmp|mp3|m4a|aac|ogg|wav|mp4|webm|mov)(\?|$)/i);
+    if (urlMatch) return urlMatch[1] === "jpeg" ? "jpg" : urlMatch[1].toLowerCase();
+    // Fallback by message type
+    return TYPE_DEFAULT_EXT[msgType] || "bin";
+}
+
+/**
+ * Check if a message type is downloadable media.
+ * @param {string} type - Normalized message type
+ * @returns {boolean}
+ */
+export function isDownloadableMedia(type) {
+    return DOWNLOADABLE_TYPES.has(type);
+}
+
+/**
+ * Build the folder name for a thread.
+ * Groups: thread display name. DMs: "DM_{senderName}".
+ * @param {object} message - Normalized message
+ * @param {string} [threadName] - Resolved thread name from cache
+ * @returns {string}
+ */
+function buildFolderName(message, threadName) {
+    if (message.threadType === "group") {
+        return sanitize(threadName || message.threadId);
+    }
+    return sanitize(`DM_${threadName || message.senderName || message.senderId}`);
+}
+
+/**
+ * Build a descriptive filename from message metadata.
+ * Format: {YYYY-MM-DD}_{HH-mm}_{sender}_{msgId}.{ext}
+ * @param {object} message
+ * @param {string} ext - File extension
+ * @returns {string}
+ */
+function buildFileName(message, ext) {
+    const d = new Date(message.timestamp);
+    const date = d.toISOString().slice(0, 10); // YYYY-MM-DD
+    const time = `${String(d.getHours()).padStart(2, "0")}-${String(d.getMinutes()).padStart(2, "0")}`;
+    const sender = sanitize(message.senderName || message.senderId);
+    const msgId = (message.id || "noId").slice(-8); // last 8 chars for brevity
+    return `${date}_${time}_${sender}_${msgId}.${ext}`;
+}
+
+/**
+ * Open a file with the system's default viewer (cross-platform).
+ * Exported for use by MCP tools.
+ * @param {string} filePath
+ */
+export function openFile(filePath) {
+    const isWin = platform() === "win32";
+    const cmds = { darwin: "open", win32: "start", linux: "xdg-open" };
+    const cmd = cmds[platform()] || "xdg-open";
+    // Windows "start" is a cmd.exe builtin — needs shell: true
+    execFile(cmd, isWin ? ["", filePath] : [filePath], { shell: isWin }, (err) => {
+        if (err) console.error(`[media-dl] Failed to open viewer: ${err.message}`);
+    });
+}
+
+/**
+ * Auto-download media in background when a message arrives.
+ * Non-blocking — fires and forgets. Mutates message.attachment.localPath on success.
+ * @param {object} message - Normalized message (will be mutated with localPath)
+ * @param {object} [options]
+ * @param {string} [options.downloadDir] - Base download directory
+ * @param {string} [options.threadName] - Thread display name from cache
+ */
+export function autoDownloadMedia(message, options = {}) {
+    if (!message.attachment?.url) return;
+    downloadMedia(message, { ...options, autoOpen: false }).then(
+        (result) => {
+            message.attachment.localPath = result.path;
+            console.error(`[media-dl] Saved: ${result.path}`);
+        },
+        (err) => {
+            console.error(`[media-dl] Auto-download failed: ${err.message}`);
+        },
+    );
+}
+
+/**
+ * Download media from URL and save to organized local folder.
+ * @param {object} message - Normalized message with attachment.url
+ * @param {object} [options]
+ * @param {string} [options.downloadDir] - Base download directory
+ * @param {boolean} [options.autoOpen] - Open media with system viewer after download
+ * @param {string} [options.threadName] - Thread display name from cache
+ * @returns {Promise<{ success: boolean, path: string, folder: string, fileName: string, mediaType: string }>}
+ */
+export async function downloadMedia(message, options = {}) {
+    const url = message.attachment?.url;
+    if (!url) throw new Error("Message has no attachment URL");
+
+    const baseDir = options.downloadDir || DEFAULT_DIR;
+    const folder = buildFolderName(message, options.threadName);
+    const folderPath = join(baseDir, folder);
+    mkdirSync(folderPath, { recursive: true });
+
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`Download failed: HTTP ${response.status}`);
+
+    const contentType = response.headers.get("content-type") || "";
+    const msgType = message.type || "file";
+    const ext = guessExtension(url, contentType, msgType);
+    const fileName = buildFileName(message, ext);
+    const filePath = join(folderPath, fileName);
+
+    const buffer = Buffer.from(await response.arrayBuffer());
+    writeFileSync(filePath, buffer);
+
+    if (options.autoOpen) {
+        openFile(filePath);
+    }
+
+    return { success: true, path: filePath, folder, fileName, mediaType: msgType };
+}

package/src/mcp/media-downloader.test.js

@@ -0,0 +1,45 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { isDownloadableMedia } from "./media-downloader.js";
+
+describe("isDownloadableMedia", () => {
+    it("returns true for image type", () => {
+        assert.ok(isDownloadableMedia("image"));
+    });
+
+    it("returns true for audio type", () => {
+        assert.ok(isDownloadableMedia("audio"));
+    });
+
+    it("returns true for voice type", () => {
+        assert.ok(isDownloadableMedia("voice"));
+    });
+
+    it("returns true for video type", () => {
+        assert.ok(isDownloadableMedia("video"));
+    });
+
+    it("returns true for gif type", () => {
+        assert.ok(isDownloadableMedia("gif"));
+    });
+
+    it("returns true for file type", () => {
+        assert.ok(isDownloadableMedia("file"));
+    });
+
+    it("returns false for text type", () => {
+        assert.equal(isDownloadableMedia("text"), false);
+    });
+
+    it("returns false for link type", () => {
+        assert.equal(isDownloadableMedia("link"), false);
+    });
+
+    it("returns false for sticker type", () => {
+        assert.equal(isDownloadableMedia("sticker"), false);
+    });
+
+    it("returns false for undefined type", () => {
+        assert.equal(isDownloadableMedia(undefined), false);
+    });
+});