abs-zalo-bot 0.2.0

package/mcp/server.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+/**
+ * Zalo Personal MCP — thin MCP facade over hermes-zalo-personal-bridge.
+ *
+ * Design learned from minhkhoa0502/zalo-personal-mcp:
+ * - Own the MCP layer (tool surface + policy)
+ * - Reuse zca-js only inside the long-lived bridge/daemon
+ * - History via daemon capture, not REST getGroupChatHistory (often 404)
+ * - Never log to stdout (MCP stdio protocol)
+ *
+ * Our difference: Policy Guard + READ_ONLY_SOURCE + destination-only send.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const BRIDGE_URL = (process.env.ZALO_BRIDGE_URL || "http://127.0.0.1:3871").replace(/\/$/, "");
+const TOKEN = process.env.DASHBOARD_TOKEN || process.env.ZALO_BRIDGE_TOKEN || "";
+
+function log(...args) {
+  console.error("[zalo-personal-mcp]", ...args);
+}
+
+async function bridge(path, { method = "GET", body = null } = {}) {
+  const headers = { "content-type": "application/json" };
+  if (TOKEN && TOKEN !== "change-me") headers["x-bridge-token"] = TOKEN;
+  const res = await fetch(`${BRIDGE_URL}${path}`, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = { raw: text.slice(0, 2000) };
+  }
+  if (!res.ok) {
+    const err = data?.error || data?.message || res.statusText;
+    throw new Error(`bridge ${method} ${path} → ${res.status}: ${err}`);
+  }
+  return data;
+}
+
+function ok(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+  };
+}
+
+function fail(err) {
+  return {
+    content: [{ type: "text", text: JSON.stringify({ error: String(err?.message || err) }, null, 2) }],
+    isError: true,
+  };
+}
+
+const server = new McpServer({
+  name: "zalo-personal-mcp",
+  version: "0.1.0",
+});
+
+// --- read tools ---
+server.tool(
+  "zalo_status",
+  "Bridge/account safety status: connected?, READ_ONLY_SOURCE, destination, corpus counts.",
+  {},
+  async () => {
+    try {
+      const [status, corpus] = await Promise.all([
+        bridge("/api/status"),
+        bridge("/api/corpus/summary").catch(() => null),
+      ]);
+      return ok({
+        accounts: status.accounts,
+        owner_user_id: status.owner_user_id,
+        phone_label: status.phone_label,
+        destination: status.destination,
+        safety: status.safety,
+        corpus,
+      });
+    } catch (e) {
+      return fail(e);
+    }
+  },
+);
+
+server.tool(
+  "zalo_list_groups",
+  "List known groups (source_id + name + mode). From bridge catalog / discovery.",
+  {
+    account_id: z.string().optional().describe("Account id, default bridge default"),
+  },
+  async ({ account_id }) => {
+    try {
+      const q = account_id ? `?account_id=${encodeURIComponent(account_id)}` : "";
+      const data = await bridge(`/api/sources${q}`);
+      return ok({
+        destination: data.destination,
+        sources: (data.sources || []).map((s) => ({
+          source_id: s.source_id,
+          source_name: s.source_name,
+          mode: s.mode,
+          is_allowed: s.is_allowed,
+          muted: s.muted,
+        })),
+      });
+    } catch (e) {
+      return fail(e);
+    }
+  },
+);
+
+server.tool(
+  "zalo_list_users",
+  "List known user ids / display names from corpus (members + senders).",
+  {
+    limit: z.number().int().min(1).max(1000).optional(),
+    account_id: z.string().optional(),
+  },
+  async ({ limit = 100, account_id }) => {
+    try {
+      const qs = new URLSearchParams();
+      if (account_id) qs.set("account_id", account_id);
+      qs.set("limit", String(limit));
+      const data = await bridge(`/api/users?${qs}`);
+      return ok(data);
+    } catch (e) {
+      return fail(e);
+    }
+  },
+);
+
+server.tool(
+  "zalo_group_members",
+  "List members of a group source_id (user_id, role, display_name).",
+  {
+    source_id: z.string().describe("Zalo group id"),
+    account_id: z.string().optional(),
+    limit: z.number().int().min(1).max(2000).optional(),
+  },
+  async ({ source_id, account_id, limit = 500 }) => {
+    try {
+      const qs = new URLSearchParams();
+      if (account_id) qs.set("account_id", account_id);
+      qs.set("limit", String(limit));
+      const data = await bridge(`/api/sources/${encodeURIComponent(source_id)}/members?${qs}`);
+      return ok(data);
+    } catch (e) {
+      return fail(e);
+    }
+  },
+);
+
+server.tool(
+  "zalo_recent_messages",
+  "Read recently captured/stored messages from the bridge corpus (daemon/listener). Prefer this over history API.",
+  {
+    limit: z.number().int().min(1).max(200).optional(),
+    account_id: z.string().optional(),
+    source_id: z.string().optional().describe("Filter by group id"),
+  },
+  async ({ limit = 50, account_id, source_id }) => {
+    try {
+      const qs = new URLSearchParams();
+      if (account_id) qs.set("account_id", account_id);
+      if (source_id) qs.set("source_id", source_id);
+      qs.set("limit", String(limit));
+      // bridge /api/events currently supports account_id+limit; filter client-side if source_id
+      const data = await bridge(`/api/events?${qs}`);
+      let events = data.events || [];
+      if (source_id) events = events.filter((e) => String(e.source_id) === String(source_id));
+      return ok({ count: events.length, events });
+    } catch (e) {
+      return fail(e);
+    }
+  },
+);
+
+server.tool(
+  "zalo_corpus_summary",
+  "Corpus inventory: groups, users, member links, messages, last backfill.",
+  {
+    account_id: z.string().optional(),
+  },
+  async ({ account_id }) => {
+    try {
+      const q = account_id ? `?account_id=${encodeURIComponent(account_id)}` : "";
+      return ok(await bridge(`/api/corpus/summary${q}`));
+    } catch (e) {
+      return fail(e);
+    }
+  },
+);
+
+server.tool(
+  "zalo_backfill",
+  "READ_ONLY backfill: groups/users/members + best-effort old messages. May take minutes. Does not send messages.",
+  {
+    history_count: z.number().int().min(1).max(200).optional(),
+    max_groups: z.number().int().min(1).max(500).optional(),
+    account_id: z.string().optional(),
+  },
+  async ({ history_count = 50, max_groups = 200, account_id }) => {
+    try {
+      const data = await bridge("/api/corpus/backfill", {
+        method: "POST",
+        body: { history_count, max_groups, account_id },
+      });
+      return ok(data);
+    } catch (e) {
+      return fail(e);
+    }
+  },
+);
+
+server.tool(
+  "zalo_refresh_discovery",
+  "Re-scan groups after connect: resolve the configured destination + account owner.",
+  {
+    account_id: z.string().optional(),
+  },
+  async ({ account_id }) => {
+    try {
+      return ok(
+        await bridge("/api/discovery/refresh", {
+          method: "POST",
+          body: { account_id },
+        }),
+      );
+    } catch (e) {
+      return fail(e);
+    }
+  },
+);
+
+// Explicitly NOT exposing: free-form send to arbitrary threads, friend mutations, group admin.
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  log(`running · bridge=${BRIDGE_URL}`);
+  try {
+    const h = await bridge("/healthz");
+    log("bridge health", h);
+  } catch (e) {
+    log("bridge not reachable yet:", String(e.message || e));
+  }
+}
+
+main().catch((err) => {
+  log("fatal", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "abs-zalo-bot",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Zalo channel adapter for AI agents. Official OA and personal QR kept separate, fail-closed by default.",
+  "author": "teddiesloco",
+  "license": "MIT",
+  "keywords": [
+    "zalo",
+    "zalo-bot",
+    "zca-js",
+    "chatbot",
+    "messaging",
+    "ai-agent",
+    "mcp",
+    "vietnam",
+    "official-account",
+    "personal-qr"
+  ],
+  "homepage": "https://github.com/teddiesloco/abs-zalo-bot#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/teddiesloco/abs-zalo-bot.git"
+  },
+  "bugs": {
+    "url": "https://github.com/teddiesloco/abs-zalo-bot/issues"
+  },
+  "files": [
+    "src/",
+    "mcp/",
+    "scripts/",
+    "config/bots.example.json",
+    "config.toml",
+    ".env.example",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "zalo-personal-mcp": "./mcp/server.js"
+  },
+  "scripts": {
+    "start": "node src/cli.js serve",
+    "dev": "node --watch src/cli.js serve",
+    "self-check": "node src/cli.js self-check",
+    "status": "node src/cli.js status",
+    "qr": "node src/cli.js qr",
+    "onboarding": "node src/cli.js onboarding",
+    "digest": "node src/cli.js digest",
+    "backfill": "node src/cli.js backfill",
+    "mcp": "node mcp/server.js",
+    "setup": "node scripts/setup.js setup",
+    "install:locked": "npm ci",
+    "doctor": "node scripts/setup.js doctor",
+    "dashboard-info": "node scripts/setup.js dashboard-info",
+    "smoke": "node scripts/battle-smoke.js",
+    "battle": "node scripts/battle-smoke.js",
+    "validate-config": "node scripts/public-gate.js validate-config",
+    "secret-scan": "node scripts/public-gate.js secret-scan",
+    "syntax-check": "node scripts/public-gate.js syntax-check",
+    "test": "node --test test/*.test.js",
+    "cold": "npm test && npm run validate-config && npm run secret-scan && npm run syntax-check && npm run self-check && npm run smoke"
+  },
+  "engines": {
+    "node": ">=22.5"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "express": "^4.21.2",
+    "zca-js": "2.1.2",
+    "zod": "3.25.76"
+  },
+  "overrides": {
+    "@hono/node-server": "2.1.0"
+  }
+}

package/scripts/battle-smoke.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * Cold battle smoke — proves bridge + MCP surface can do real work.
+ * READ_ONLY defaults. Does not spam source groups.
+ */
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const BRIDGE = process.env.ZALO_BRIDGE_URL || "http://127.0.0.1:3871";
+
+async function j(url, opts) {
+  const res = await fetch(url, opts);
+  const text = await res.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = { raw: text.slice(0, 500) };
+  }
+  return { status: res.status, ok: res.ok, data };
+}
+
+function pass(name, detail = "") {
+  console.log(`PASS  ${name}${detail ? " · " + detail : ""}`);
+}
+function fail(name, detail = "") {
+  console.error(`FAIL  ${name}${detail ? " · " + detail : ""}`);
+  process.exitCode = 1;
+}
+
+async function main() {
+  console.log("=== Zalo Personal MCP battle smoke ===");
+  console.log("bridge", BRIDGE);
+
+  // 1 health
+  let r = await j(`${BRIDGE}/healthz`);
+  if (r.ok) pass("healthz");
+  else return fail("healthz", String(r.status));
+
+  // 2 battle-ready
+  r = await j(`${BRIDGE}/api/battle-ready`);
+  if (!r.ok) return fail("battle-ready endpoint", r.status);
+  const br = r.data;
+  console.log(JSON.stringify({ battle_ready: br.battle_ready, account: br.account, destination: br.destination, corpus: br.corpus, safety: br.safety }, null, 2));
+  if (br.battle_ready) pass("battle_ready");
+  else fail("battle_ready", "not connected or destination/safety incomplete");
+
+  // 3 reconnect session if needed
+  if (br.account?.status !== "connected") {
+    r = await j(`${BRIDGE}/api/accounts/default/connect`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: "{}",
+    });
+    if (r.ok && r.data?.status?.status === "connected") pass("reconnect session");
+    else fail("reconnect session", JSON.stringify(r.data).slice(0, 200));
+  } else pass("already connected");
+
+  // 4 corpus
+  r = await j(`${BRIDGE}/api/corpus/summary`);
+  if (r.ok) pass("corpus_summary", `msgs=${r.data.messages} users=${r.data.users} groups=${r.data.sources}`);
+  else fail("corpus_summary");
+
+  // 5 sources list
+  r = await j(`${BRIDGE}/api/sources`);
+  if (r.ok && Array.isArray(r.data.sources) && r.data.sources.length > 0) {
+    pass("list_groups", String(r.data.sources.length));
+  } else fail("list_groups");
+
+  // 6 policy: wrong outbound blocked via ask with empty dest would fail; use status safety
+  r = await j(`${BRIDGE}/api/status`);
+  const safety = r.data?.safety || {};
+  if (safety.READ_ONLY_SOURCE && safety.auto_reply_disabled && safety.dm_reply_disabled) {
+    pass("READ_ONLY_SOURCE safety flags");
+  } else fail("safety flags", JSON.stringify(safety));
+
+  // 7 dry ask path (may send to configured destination if explicitly enabled)
+  // Use a soft question; Policy Guard still destination-only.
+  const doSend = process.env.BATTLE_SEND === "true";
+  if (doSend) {
+    r = await j(`${BRIDGE}/api/ask`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ question: "tóm tắt nhanh corpus hiện có?", hours: 24 }),
+    });
+    if (r.ok) pass("ask_destination", r.data?.reason || r.data?.ok);
+    else fail("ask_destination", JSON.stringify(r.data).slice(0, 300));
+  } else {
+    pass("ask_destination skipped (set BATTLE_SEND=true to send real report)");
+  }
+
+  // 8 MCP server boots
+  await new Promise((resolve) => {
+    const child = spawn("node", [path.join(root, "mcp/server.js")], {
+      env: { ...process.env, ZALO_BRIDGE_URL: BRIDGE },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let err = "";
+    child.stderr.on("data", (d) => {
+      err += d.toString();
+    });
+    setTimeout(() => {
+      child.kill("SIGTERM");
+      if (err.includes("running") || err.includes("bridge health")) pass("mcp_server_boot", err.trim().split("\n").slice(-2).join(" | "));
+      else fail("mcp_server_boot", err.slice(0, 300) || "no stderr");
+      resolve();
+    }, 1500);
+  });
+
+  console.log(process.exitCode ? "=== SMOKE FAILED ===" : "=== SMOKE OK — battle surface ready ===");
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/scripts/corpus-stats.js

@@ -0,0 +1,23 @@
+import { DatabaseSync } from "node:sqlite";
+const db = new DatabaseSync("./data/bridge.sqlite3");
+const q = (s) => db.prepare(s).get();
+const out = {
+  messages: q("SELECT COUNT(*) AS c FROM zalo_messages").c,
+  users: q("SELECT COUNT(*) AS c FROM zalo_users").c,
+  members: q("SELECT COUNT(*) AS c FROM zalo_source_members").c,
+  sources: q("SELECT COUNT(*) AS c FROM zalo_sources").c,
+  sample_users: db
+    .prepare(
+      "SELECT user_id, display_name FROM zalo_users WHERE display_name != '' LIMIT 5",
+    )
+    .all(),
+  sample_groups: db
+    .prepare("SELECT source_id, source_name FROM zalo_sources LIMIT 8")
+    .all(),
+  sample_msgs: db
+    .prepare(
+      "SELECT source_name, sender_display_name, substr(text_redacted,1,100) AS t FROM zalo_messages LIMIT 5",
+    )
+    .all(),
+};
+console.log(JSON.stringify(out, null, 2));

package/scripts/probe-history.js

@@ -0,0 +1,76 @@
+import { Store } from "../src/store.js";
+import { BridgeHub } from "../src/zalo_runtime.js";
+import { PolicyGuard } from "../src/policy.js";
+import { loadConfig } from "../src/config.js";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const config = loadConfig(path.join(root, "config.toml"));
+const store = new Store(path.join(root, "data"));
+const policy = new PolicyGuard({ config, store });
+const hub = new BridgeHub({ config, store, policy });
+const rt = hub.getRuntime("default");
+await rt.connect({ forceQr: false });
+const api = rt.api;
+const gid = process.env.ZALO_GROUP_ID || process.argv[2] || "";
+if (!gid) {
+  console.error("Missing group id. Pass ZALO_GROUP_ID or the group id as the first argument.");
+  process.exit(2);
+}
+
+const info = await api.getGroupInfo(gid);
+const g = info.gridInfoMap[gid];
+console.log(
+  JSON.stringify(
+    {
+      name: g?.name,
+      totalMember: g?.totalMember,
+      memberIds_len: g?.memberIds?.length ?? null,
+      memVerList_len: g?.memVerList?.length ?? null,
+      memVerList_sample: (g?.memVerList || []).slice(0, 5),
+      currentMems_sample: (g?.currentMems || []).slice(0, 2),
+      adminIds: g?.adminIds || [],
+      creatorId: g?.creatorId || "",
+      keys: Object.keys(g || {}),
+    },
+    null,
+    2,
+  ),
+);
+
+try {
+  const h = await api.getGroupChatHistory(gid, 5);
+  console.log(
+    "history",
+    JSON.stringify({
+      keys: Object.keys(h || {}),
+      msgs: h?.groupMsgs?.length,
+      sample: h?.groupMsgs?.[0]
+        ? {
+            threadId: h.groupMsgs[0].threadId,
+            isSelf: h.groupMsgs[0].isSelf,
+            dataKeys: Object.keys(h.groupMsgs[0].data || {}),
+            msgId: h.groupMsgs[0].data?.msgId,
+            contentType: typeof h.groupMsgs[0].data?.content,
+          }
+        : null,
+    }),
+  );
+} catch (e) {
+  console.log("history_err", e?.message || e);
+}
+
+// try getGroupMembersInfo with memVerList if present
+const ids = (g?.memVerList || g?.memberIds || []).slice(0, 5).map(String);
+if (ids.length) {
+  try {
+    const mi = await api.getGroupMembersInfo(ids);
+    console.log("members_info_count", Object.keys(mi?.profiles || {}).length);
+  } catch (e) {
+    console.log("members_err", e?.message || e);
+  }
+}
+
+await rt.pause();
+store.close();