whats-mcp 0.1.0

package/src/tools/analytics.js

@@ -0,0 +1,157 @@
+/**
+ * whats-mcp — Analytics tools (5 tools).
+ *
+ * analytics_overview, analytics_top_chats, analytics_chat_insights,
+ * analytics_timeline, analytics_search
+ */
+
+"use strict";
+
+const { phoneToJid, okResult, errResult } = require("../helpers");
+
+module.exports = [
+  {
+    definition: {
+      name: "analytics_overview",
+      description:
+        "Return a local analytics summary built from the cached WhatsApp store." +
+        " Includes totals, top chats, top tokens, top senders, and activity trends.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          top_chats: { type: "integer", description: "Number of top chats to include. Default 10." },
+          top_tokens: { type: "integer", description: "Number of top tokens to include. Default 20." },
+          top_senders: { type: "integer", description: "Number of top senders to include. Default 10." },
+          days: { type: "integer", description: "Number of daily activity buckets to include. Default 30." },
+        },
+      },
+    },
+    handler: async (args, { store }) => okResult(store.getAnalyticsOverview(args)),
+  },
+
+  {
+    definition: {
+      name: "analytics_top_chats",
+      description:
+        "Rank chats using the local analytics index." +
+        " Can sort by message count, last activity, active days, or participant count.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          limit: { type: "integer", description: "Maximum number of chats to return. Default 20." },
+          sort_by: {
+            type: "string",
+            enum: ["message_count", "last_activity", "active_days", "participants"],
+            description: "Sort criterion. Default message_count.",
+          },
+        },
+      },
+    },
+    handler: async ({ limit, sort_by }, { store }) => okResult({
+      count: Math.min(limit || 20, 200),
+      chats: store.listAnalyticsTopChats({ limit, sort_by }),
+    }),
+  },
+
+  {
+    definition: {
+      name: "analytics_chat_insights",
+      description:
+        "Return detailed local analytics for one chat, including top tokens, senders, activity, and recent messages.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          jid: { type: "string", description: "Chat JID or phone number." },
+          top_tokens: { type: "integer", description: "Maximum number of top tokens to include. Default 15." },
+          top_senders: { type: "integer", description: "Maximum number of top senders to include. Default 10." },
+          days: { type: "integer", description: "Number of daily activity buckets to include. Default 30." },
+          recent_messages: { type: "integer", description: "Number of recent messages to include. Default 5." },
+        },
+        required: ["jid"],
+      },
+    },
+    handler: async ({ jid, ...options }, { store }) => {
+      const chatJid = phoneToJid(jid);
+      const result = store.getChatAnalytics(chatJid, options)
+        || store.getChatAnalytics(jid, options);
+      if (!result) {
+        return errResult(`No analytics available for chat ${jid}.`);
+      }
+      return okResult(result);
+    },
+  },
+
+  {
+    definition: {
+      name: "analytics_timeline",
+      description:
+        "Return a daily activity timeline from the local analytics index, globally or for one chat.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          jid: { type: "string", description: "Optional chat JID or phone number." },
+          days: { type: "integer", description: "Number of days to include. Default 30." },
+        },
+      },
+    },
+    handler: async ({ jid, days }, { store }) => {
+      const result = store.getActivityTimeline({
+        jid: jid ? phoneToJid(jid) : undefined,
+        days,
+      }) || (jid ? store.getActivityTimeline({ jid, days }) : null);
+      if (!result) {
+        return errResult(`No timeline available for chat ${jid}.`);
+      }
+      return okResult(result);
+    },
+  },
+
+  {
+    definition: {
+      name: "analytics_search",
+      description:
+        "Run a ranked search over the local analytics index using token matches, phrase matches, and recency." +
+        " Supports time range and multi-JID filtering.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Search query." },
+          jid: { type: "string", description: "Optional chat JID or phone number." },
+          jids: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional: search across multiple chat JIDs. Takes precedence over jid.",
+          },
+          limit: { type: "integer", description: "Maximum number of results. Default 20." },
+          since: {
+            type: "integer",
+            description: "Unix timestamp: only include messages at or after this time.",
+          },
+          until: {
+            type: "integer",
+            description: "Unix timestamp: only include messages at or before this time.",
+          },
+        },
+        required: ["query"],
+      },
+    },
+    handler: async ({ query, jid, jids, limit, since, until }, { store }) => {
+      let chatJids = undefined;
+      if (jids && jids.length > 0) {
+        chatJids = jids.map(phoneToJid);
+      } else if (jid) {
+        chatJids = phoneToJid(jid);
+      }
+      const opts = {
+        since: since || undefined,
+        until: until || undefined,
+      };
+      const messages = store.analyticsSearch(query, chatJids, limit, opts);
+      return okResult({
+        query,
+        count: messages.length,
+        messages,
+      });
+    },
+  },
+];

package/src/tools/channels.js

@@ -0,0 +1,215 @@
+/**
+ * whats-mcp — Newsletter / Channel tools (5 tools).
+ *
+ * create_channel, get_channel_info, manage_channel,
+ * update_channel, delete_channel
+ */
+
+"use strict";
+
+const {
+  newsletterJid, resolveMedia, okResult, errResult,
+} = require("../helpers");
+
+function _fmtChannel(meta) {
+  return {
+    jid: meta.id,
+    name: meta.name || meta.subject || null,
+    description: meta.description || meta.desc || null,
+    subscriber_count: meta.subscribers || meta.subscriberCount || null,
+    creation_time: meta.creation ? Number(meta.creation) : null,
+    picture_url: meta.picture || meta.pictureUrl || null,
+    invite_link: meta.inviteLink || null,
+    state: meta.state || null,
+    verification: meta.verification || null,
+    mute: meta.mute || null,
+  };
+}
+
+module.exports = [
+  // 1. create_channel
+  {
+    definition: {
+      name: "create_channel",
+      description:
+        "Create a new WhatsApp Channel (Newsletter)." +
+        " Returns the channel metadata including JID.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name:        { type: "string", description: "Channel name." },
+          description: { type: "string", description: "Optional channel description." },
+          picture:     { type: "string", description: "Optional profile picture: URL, base64, or file path." },
+        },
+        required: ["name"],
+      },
+    },
+    handler: async ({ name, description, picture }, { sock }) => {
+      const opts = { name };
+      if (description) opts.description = description;
+      if (picture) {
+        const media = resolveMedia(picture);
+        if (Buffer.isBuffer(media)) {
+          opts.picture = media;
+        } else if (media.url) {
+          const resp = await fetch(media.url);
+          opts.picture = Buffer.from(await resp.arrayBuffer());
+        }
+      }
+      const result = await sock.newsletterCreate(name, opts);
+      return okResult({
+        status: "created",
+        channel: _fmtChannel(result),
+      });
+    },
+  },
+
+  // 2. get_channel_info
+  {
+    definition: {
+      name: "get_channel_info",
+      description:
+        "Get metadata for a WhatsApp Channel (Newsletter)." +
+        " You can fetch by JID or invite link.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          jid: {
+            type: "string",
+            description: "Channel JID (e.g. 120363xxx@newsletter) or invite link.",
+          },
+        },
+        required: ["jid"],
+      },
+    },
+    handler: async ({ jid }, { sock }) => {
+      let meta;
+      if (jid.startsWith("https://") || jid.startsWith("http://")) {
+        // Invite link -> extract code
+        const code = jid.split("/").pop();
+        meta = await sock.newsletterMetadata("invite", code);
+      } else {
+        const channelJid = newsletterJid(jid);
+        meta = await sock.newsletterMetadata("jid", channelJid);
+      }
+      return okResult({ channel: _fmtChannel(meta) });
+    },
+  },
+
+  // 3. manage_channel
+  {
+    definition: {
+      name: "manage_channel",
+      description:
+        "Follow (subscribe), unfollow, mute, or unmute a WhatsApp Channel.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          jid: { type: "string", description: "Channel JID." },
+          action: {
+            type: "string",
+            enum: ["follow", "unfollow", "mute", "unmute"],
+            description: "Action to perform.",
+          },
+        },
+        required: ["jid", "action"],
+      },
+    },
+    handler: async ({ jid, action }, { sock }) => {
+      const channelJid = newsletterJid(jid);
+
+      if (action === "follow") {
+        await sock.newsletterFollow(channelJid);
+        return okResult({ status: "followed", jid: channelJid });
+      }
+      if (action === "unfollow") {
+        await sock.newsletterUnfollow(channelJid);
+        return okResult({ status: "unfollowed", jid: channelJid });
+      }
+      if (action === "mute") {
+        await sock.newsletterMute(channelJid);
+        return okResult({ status: "muted", jid: channelJid });
+      }
+      if (action === "unmute") {
+        await sock.newsletterUnmute(channelJid);
+        return okResult({ status: "unmuted", jid: channelJid });
+      }
+      return errResult(`Unknown action: ${action}`);
+    },
+  },
+
+  // 4. update_channel
+  {
+    definition: {
+      name: "update_channel",
+      description: "Update a channel's name, description, or picture.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          jid:         { type: "string", description: "Channel JID." },
+          name:        { type: "string", description: "New channel name." },
+          description: { type: "string", description: "New channel description." },
+          picture:     { type: "string", description: "New picture: URL, base64, or file path. Use 'remove' to delete." },
+        },
+        required: ["jid"],
+      },
+    },
+    handler: async ({ jid, name, description, picture }, { sock }) => {
+      const channelJid = newsletterJid(jid);
+      const updates = [];
+
+      if (name) {
+        await sock.newsletterUpdateName(channelJid, name);
+        updates.push("name");
+      }
+      if (description !== undefined) {
+        await sock.newsletterUpdateDescription(channelJid, description);
+        updates.push("description");
+      }
+      if (picture) {
+        if (picture === "remove") {
+          await sock.newsletterRemovePicture(channelJid);
+          updates.push("picture (removed)");
+        } else {
+          const media = resolveMedia(picture);
+          let imgBuf;
+          if (Buffer.isBuffer(media)) {
+            imgBuf = media;
+          } else if (media.url) {
+            const resp = await fetch(media.url);
+            imgBuf = Buffer.from(await resp.arrayBuffer());
+          } else {
+            imgBuf = media;
+          }
+          await sock.newsletterUpdatePicture(channelJid, imgBuf);
+          updates.push("picture");
+        }
+      }
+
+      if (updates.length === 0) {
+        return errResult("No updates provided. Specify name, description, or picture.");
+      }
+      return okResult({ status: "updated", jid: channelJid, updated: updates });
+    },
+  },
+
+  // 5. delete_channel
+  {
+    definition: {
+      name: "delete_channel",
+      description: "Delete a WhatsApp Channel that you own. This action is irreversible.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          jid: { type: "string", description: "Channel JID to delete." },
+        },
+        required: ["jid"],
+      },
+    },
+    handler: async ({ jid }, { sock }) => {
+      const channelJid = newsletterJid(jid);
+      await sock.newsletterDelete(channelJid);
+      return okResult({ status: "deleted", jid: channelJid });
+    },
+  },
+];

package/src/tools/chats.js

@@ -0,0 +1,291 @@
+/**
+ * whats-mcp — Chat management tools (5 tools).
+ *
+ * list_chats, get_messages, manage_chat, star_message, set_disappearing
+ */
+
+"use strict";
+
+const {
+  phoneToJid, isGroupJid, okResult, errResult, formatChat, formatMessage,
+} = require("../helpers");
+const { fetchAdditionalHistory } = require("./history-support");
+
+module.exports = [
+  // 1. list_chats
+  {
+    definition: {
+      name: "list_chats",
+      description:
+        "List recent chats from the in-memory store." +
+        " Returns chat JIDs, names, timestamps, unread counts, and other metadata." +
+        " Results are sorted by most recent activity.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          limit:  { type: "integer", description: "Max number of chats to return (default 50, max 500)." },
+          offset: { type: "integer", description: "Offset for pagination (default 0)." },
+          filter: {
+            type: "string",
+            enum: ["all", "groups", "contacts", "unread"],
+            description: "Filter chats: all (default), groups, contacts, unread.",
+          },
+        },
+      },
+    },
+    handler: async ({ limit, offset, filter }, { store }) => {
+      let chats = store.listChats(10000);
+
+      // Apply filter
+      const f = filter || "all";
+      if (f === "groups")   chats = chats.filter((c) => isGroupJid(c.id));
+      if (f === "contacts") chats = chats.filter((c) => !isGroupJid(c.id));
+      if (f === "unread")   chats = chats.filter((c) => (c.unreadCount || 0) > 0);
+
+      const total = chats.length;
+      const off = offset || 0;
+      const lim = Math.min(limit || 50, 500);
+      const page = chats.slice(off, off + lim);
+
+      return okResult({
+        total,
+        offset: off,
+        count: page.length,
+        chats: page.map(formatChat),
+      });
+    },
+  },
+
+  // 2. get_messages
+  {
+    definition: {
+      name: "get_messages",
+      description:
+        "Get recent messages from a specific chat." +
+        " Messages come from the local store and can trigger an on-demand history fetch for older messages." +
+        " Use before_id for pagination toward older messages.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          jid:       { type: "string", description: "Chat JID or phone number." },
+          limit:     { type: "integer", description: "Max number of messages to return (default 50, max 200)." },
+          before_id: { type: "string", description: "Message ID cursor: return messages older than this. For pagination." },
+          fetch_history: {
+            type: "boolean",
+            description: "If true (default), request additional older history from WhatsApp when the local cache is insufficient.",
+          },
+          history_count: {
+            type: "integer",
+            description: "How many older messages to request from WhatsApp during on-demand history sync (default: max(limit, 50), max 200).",
+          },
+          history_wait_ms: {
+            type: "integer",
+            description: "How long to wait for history sync events after requesting older messages (default 3500ms, max 15000ms).",
+          },
+          since: {
+            type: "integer",
+            description: "Unix timestamp: only include messages sent at or after this time.",
+          },
+          until: {
+            type: "integer",
+            description: "Unix timestamp: only include messages sent at or before this time.",
+          },
+          include_types: {
+            type: "array",
+            items: { type: "string" },
+            description: "If set, only include messages of these types (e.g. text, image, video, audio, document, voice_note, sticker, location, contact, poll).",
+          },
+          exclude_types: {
+            type: "array",
+            items: { type: "string" },
+            description: "Exclude messages of these types (e.g. reaction, protocol, senderKeyDistribution, unknown).",
+          },
+        },
+        required: ["jid"],
+      },
+    },
+    handler: async ({ jid, limit, before_id, fetch_history, history_count, history_wait_ms, since, until, include_types, exclude_types }, { sock, store }) => {
+      const chatJid = phoneToJid(jid);
+      const lim = Math.min(limit || 50, 200);
+      const filterOpts = {
+        since: since || undefined,
+        until: until || undefined,
+        types: include_types || undefined,
+        excludeTypes: exclude_types || undefined,
+      };
+      let historySync = {
+        enabled: fetch_history !== false,
+        requested: false,
+        received: false,
+        reason: "cache_sufficient",
+        before_count: store.countMessages(chatJid),
+        after_count: store.countMessages(chatJid),
+      };
+
+      let messages = store.getMessages(chatJid, lim, before_id, filterOpts);
+      const shouldFetchHistory = fetch_history !== false && (before_id || messages.length < lim);
+      if (shouldFetchHistory) {
+        historySync = await fetchAdditionalHistory({
+          sock,
+          store,
+          jid: chatJid,
+          beforeId: before_id,
+          limit: lim,
+          historyCount: history_count,
+          waitMs: history_wait_ms,
+          enabled: fetch_history !== false,
+        });
+        messages = store.getMessages(chatJid, lim, before_id, filterOpts);
+      }
+
+      return okResult({
+        jid: chatJid,
+        count: messages.length,
+        messages: messages.map(formatMessage),
+        history_sync: historySync,
+      });
+    },
+  },
+
+  // 3. manage_chat
+  {
+    definition: {
+      name: "manage_chat",
+      description:
+        "Perform a chat management action: archive, unarchive, pin, unpin," +
+        " mute, unmute, mark_read, mark_unread, delete, or clear.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          jid:    { type: "string", description: "Chat JID or phone number." },
+          action: {
+            type: "string",
+            enum: [
+              "archive", "unarchive",
+              "pin", "unpin",
+              "mute", "unmute",
+              "mark_read", "mark_unread",
+              "delete", "clear",
+            ],
+            description: "Action to perform.",
+          },
+          mute_duration: {
+            type: "integer",
+            description: "For 'mute' action: duration in seconds. 0 = 8 hours, -1 = forever. Default 8 hours.",
+          },
+        },
+        required: ["jid", "action"],
+      },
+    },
+    handler: async ({ jid, action, mute_duration }, { sock, store }) => {
+      const chatJid = phoneToJid(jid);
+      const now = Date.now();
+
+      // Get last messages for read/unread operations
+      let lastMessages;
+      if (action === "mark_read" || action === "mark_unread") {
+        const msgs = store.getMessages(chatJid, 1);
+        if (msgs.length > 0) {
+          lastMessages = [{ id: msgs[0].key.id, remoteJid: chatJid, fromMe: msgs[0].key.fromMe }];
+        }
+      }
+
+      const modMap = {
+        archive:      { archive: true, lastMessages: undefined },
+        unarchive:    { archive: false, lastMessages: undefined },
+        pin:          { pin: true },
+        unpin:        { pin: false },
+        mute:         {
+          mute: mute_duration === -1
+            ? undefined // Will be handled below
+            : (mute_duration || 8 * 3600) * 1000 + now,
+        },
+        unmute:       { mute: null },
+        mark_read:    { markRead: true, lastMessages },
+        mark_unread:  { markRead: false, lastMessages },
+        delete:       { delete: true, lastMessages },
+        clear:        { clear: { messages: [] } }, // clears all messages flag
+      };
+
+      if (action === "mute" && mute_duration === -1) {
+        modMap.mute.mute = 0; // 0 = mute forever in Baileys
+      }
+
+      const mod = modMap[action];
+      if (!mod) return errResult(`Unknown action: ${action}`);
+
+      // Baileys chatModify takes (modification, jid)
+      await sock.chatModify(mod, chatJid);
+
+      return okResult({ status: action, jid: chatJid });
+    },
+  },
+
+  // 4. star_message
+  {
+    definition: {
+      name: "star_message",
+      description: "Star or unstar a message.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          jid:        { type: "string", description: "Chat JID." },
+          message_id: { type: "string", description: "Message ID to star/unstar." },
+          star:       { type: "boolean", description: "true to star, false to unstar. Default true." },
+          from_me:    { type: "boolean", description: "Whether the message was sent by you. Default false." },
+        },
+        required: ["jid", "message_id"],
+      },
+    },
+    handler: async ({ jid, message_id, star, from_me }, { sock }) => {
+      const chatJid = phoneToJid(jid);
+      const shouldStar = star !== false;
+      await sock.chatModify(
+        {
+          star: {
+            messages: [{ id: message_id, fromMe: from_me ?? false }],
+            star: shouldStar,
+          },
+        },
+        chatJid,
+      );
+      return okResult({
+        status: shouldStar ? "starred" : "unstarred",
+        jid: chatJid,
+        message_id,
+      });
+    },
+  },
+
+  // 5. set_disappearing
+  {
+    definition: {
+      name: "set_disappearing",
+      description:
+        "Set disappearing messages timer for a chat." +
+        " Available durations: 0 (off), 86400 (24h), 604800 (7 days), 7776000 (90 days).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          jid:      { type: "string", description: "Chat JID." },
+          duration: {
+            type: "integer",
+            enum: [0, 86400, 604800, 7776000],
+            description: "Disappearing timer in seconds: 0=off, 86400=24h, 604800=7d, 7776000=90d.",
+          },
+        },
+        required: ["jid", "duration"],
+      },
+    },
+    handler: async ({ jid, duration }, { sock }) => {
+      const chatJid = phoneToJid(jid);
+      await sock.sendMessage(chatJid, { disappearingMessagesInChat: duration });
+      const labels = { 0: "off", 86400: "24 hours", 604800: "7 days", 7776000: "90 days" };
+      return okResult({
+        status: "set",
+        jid: chatJid,
+        disappearing: labels[duration] || `${duration}s`,
+      });
+    },
+  },
+];