neuron-mcp-server 1.0.1 → 1.1.0

package/src/tools/group-management.ts

@@ -0,0 +1,265 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+/** Shared "where do the members come from" schema for create / add / remove. */
+const memberSources = {
+  fromGroupIds: z.array(z.string()).optional().describe("Copy/combine members live from these WhatsApp group JIDs"),
+  listIds: z.array(z.string()).optional().describe("Contact list ids or slugs — pulls every member"),
+  contactIds: z.array(z.string()).optional().describe("Existing contact ids"),
+  phones: z.array(z.string()).optional().describe("Raw phone numbers, e.g. pasted from a CSV"),
+  allContacts: z.boolean().optional().describe("Union the org's entire address book"),
+  tags: z.array(z.string()).optional().describe("Keep only contacts carrying one of these tags"),
+  excludeListIds: z.array(z.string()).optional().describe("Subtract every member of these lists"),
+};
+
+export function registerGroupManagementTools(server: McpServer): void {
+  // 0. Create Group
+  server.registerTool(
+    "neuron_create_group",
+    {
+      title: "Create WhatsApp Group",
+      description:
+        "Create a new WhatsApp group and seed its members from any combination of sources: other groups (combine/copy), contact lists, individual contacts, pasted phone numbers, or the whole address book. Optionally pass a unique `slug` to address the group later without its JID. Members blocked by privacy come back in the failed list. Uses the org's default connected session unless `channelId` is given.",
+      inputSchema: z.object({
+        subject: z.string().min(1).max(100).describe("Group name"),
+        channelId: z.string().optional().describe("Session (connected WhatsApp number) UUID. Omit to use the default."),
+        slug: z.string().optional().describe("Optional org-unique handle (lowercase letters, numbers, hyphens)"),
+        description: z.string().optional().describe("Optional group description"),
+        ifExists: z.enum(["return", "error"]).optional().describe("When the slug is already taken: 'error' (default) fails, 'return' returns the existing group and adds any given members to it (idempotent create)."),
+        ...memberSources,
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    },
+    async ({ subject, channelId, slug, description, ifExists, ...sources }) => {
+      try {
+        const res = await api("POST", `/groups`, { subject, channelId, slug, description, ifExists, sources });
+        return jsonResult(res);
+      } catch (error) { return errorResult(error); }
+    },
+  );
+
+  // 0b. Add Group Members (from sources)
+  server.registerTool(
+    "neuron_add_group_members",
+    {
+      title: "Add Members to Group",
+      description:
+        "Add members to an existing group, resolved from any combination of sources (other groups, contact lists, contacts, pasted phones, all contacts). Address the group by its id, slug, or JID.",
+      inputSchema: z.object({
+        group: z.string().describe("Group id, slug, or JID (ending in @g.us)"),
+        ...memberSources,
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    },
+    async ({ group, ...sources }) => {
+      try {
+        const res = await api("POST", `/groups/${encodeURIComponent(group)}/members`, { sources });
+        return jsonResult(res);
+      } catch (error) { return errorResult(error); }
+    },
+  );
+
+  // 0c. Remove Group Members (from sources)
+  server.registerTool(
+    "neuron_remove_group_members",
+    {
+      title: "Remove Members from Group",
+      description:
+        "Remove members from a group, resolved from any combination of sources — e.g. remove everyone on a contact list. Address the group by its id, slug, or JID.",
+      inputSchema: z.object({
+        group: z.string().describe("Group id, slug, or JID (ending in @g.us)"),
+        ...memberSources,
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    },
+    async ({ group, ...sources }) => {
+      try {
+        const res = await api("DELETE", `/groups/${encodeURIComponent(group)}/members`, { sources });
+        return jsonResult(res);
+      } catch (error) { return errorResult(error); }
+    },
+  );
+
+  // 1. Update Group Subject
+  server.registerTool(
+    "neuron_update_group_subject",
+    {
+      title: "Update Group Subject",
+      description: "Update the name/subject of a WhatsApp group. Requires the bot to be a group admin.",
+      inputSchema: z.object({
+        channelId: z.string().describe("WhatsApp channel identifier (UUID)"),
+        groupJid: z.string().describe("Group JID (ending in @g.us)"),
+        subject: z.string().min(1).describe("New group name/subject"),
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    async (args) => {
+      try {
+        const res = await api("PUT", `/whatsapp-actions/${args.channelId}/groups/${args.groupJid}/subject`, {
+          subject: args.subject,
+        });
+        return jsonResult(res);
+      } catch (error) { return errorResult(error); }
+    },
+  );
+
+  // 2. Update Group Description
+  server.registerTool(
+    "neuron_update_group_description",
+    {
+      title: "Update Group Description",
+      description: "Update the description of a WhatsApp group. Requires the bot to be a group admin.",
+      inputSchema: z.object({
+        channelId: z.string().describe("WhatsApp channel identifier (UUID)"),
+        groupJid: z.string().describe("Group JID (ending in @g.us)"),
+        description: z.string().describe("New group description (can be empty string to clear)"),
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    async (args) => {
+      try {
+        const res = await api("PUT", `/whatsapp-actions/${args.channelId}/groups/${args.groupJid}/description`, {
+          description: args.description,
+        });
+        return jsonResult(res);
+      } catch (error) { return errorResult(error); }
+    },
+  );
+
+  // 3. Update Group Settings
+  server.registerTool(
+    "neuron_update_group_settings",
+    {
+      title: "Update Group Settings",
+      description: "Change WhatsApp group settings: 'announcement' (only admins send), 'not_announcement' (everyone sends), 'locked' (only admins edit info), 'unlocked' (everyone edits info). Requires admin.",
+      inputSchema: z.object({
+        channelId: z.string().describe("WhatsApp channel identifier (UUID)"),
+        groupJid: z.string().describe("Group JID (ending in @g.us)"),
+        setting: z.enum(["announcement", "not_announcement", "locked", "unlocked"]).describe("Group setting to apply"),
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    async (args) => {
+      try {
+        const res = await api("PUT", `/whatsapp-actions/${args.channelId}/groups/${args.groupJid}/settings`, {
+          setting: args.setting,
+        });
+        return jsonResult(res);
+      } catch (error) { return errorResult(error); }
+    },
+  );
+
+  // 4. Update Group Members
+  server.registerTool(
+    "neuron_update_group_members",
+    {
+      title: "Update Group Members",
+      description: "Add, remove, promote, or demote members in a WhatsApp group. Provide phone numbers or JIDs. Requires admin privileges.",
+      inputSchema: z.object({
+        channelId: z.string().describe("WhatsApp channel identifier (UUID)"),
+        groupJid: z.string().describe("Group JID (ending in @g.us)"),
+        participants: z.array(z.string()).min(1).describe("Array of phone numbers or JIDs (e.g. ['2348012345678'] or ['2348012345678@s.whatsapp.net'])"),
+        action: z.enum(["add", "remove", "promote", "demote"]).describe("Action to perform on the participants"),
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    },
+    async (args) => {
+      try {
+        const res = await api("POST", `/whatsapp-actions/${args.channelId}/groups/${args.groupJid}/members`, {
+          participants: args.participants,
+          action: args.action,
+        });
+        return jsonResult(res);
+      } catch (error) { return errorResult(error); }
+    },
+  );
+
+  // 5. Set Group Join Approval
+  server.registerTool(
+    "neuron_set_group_join_approval",
+    {
+      title: "Set Group Join Approval",
+      description: "Enable or disable join approval mode for a WhatsApp group. When enabled, join requests must be manually approved by admins. Requires admin.",
+      inputSchema: z.object({
+        channelId: z.string().describe("WhatsApp channel identifier (UUID)"),
+        groupJid: z.string().describe("Group JID (ending in @g.us)"),
+        enabled: z.boolean().describe("true to require admin approval for joins, false to allow direct joins"),
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    async (args) => {
+      try {
+        const res = await api("PUT", `/whatsapp-actions/${args.channelId}/groups/${args.groupJid}/join-approval`, {
+          enabled: args.enabled,
+        });
+        return jsonResult(res);
+      } catch (error) { return errorResult(error); }
+    },
+  );
+
+  // 6. Handle Join Requests
+  server.registerTool(
+    "neuron_handle_join_requests",
+    {
+      title: "Handle Join Requests",
+      description: "Approve or reject pending join requests for a WhatsApp group. Requires admin privileges.",
+      inputSchema: z.object({
+        channelId: z.string().describe("WhatsApp channel identifier (UUID)"),
+        groupJid: z.string().describe("Group JID (ending in @g.us)"),
+        participants: z.array(z.string()).min(1).describe("Array of phone numbers or JIDs of requesters"),
+        action: z.enum(["approve", "reject"]).describe("Whether to approve or reject the join requests"),
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    },
+    async (args) => {
+      try {
+        const res = await api("POST", `/whatsapp-actions/${args.channelId}/groups/${args.groupJid}/join-requests`, {
+          participants: args.participants,
+          action: args.action,
+        });
+        return jsonResult(res);
+      } catch (error) { return errorResult(error); }
+    },
+  );
+
+  // 7. Revoke Group Invite
+  server.registerTool(
+    "neuron_revoke_group_invite",
+    {
+      title: "Revoke Group Invite",
+      description: "Revoke the current group invite link and generate a new one. The old link will stop working. Requires admin.",
+      inputSchema: z.object({
+        channelId: z.string().describe("WhatsApp channel identifier (UUID)"),
+        groupJid: z.string().describe("Group JID (ending in @g.us)"),
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    },
+    async (args) => {
+      try {
+        const res = await api("POST", `/whatsapp-actions/${args.channelId}/groups/${args.groupJid}/revoke-invite`);
+        return jsonResult(res);
+      } catch (error) { return errorResult(error); }
+    },
+  );
+
+  // 8. Leave Group
+  server.registerTool(
+    "neuron_leave_group",
+    {
+      title: "Leave Group",
+      description: "Make the bot leave a WhatsApp group. This action is irreversible — the bot will need to be re-added by an admin.",
+      inputSchema: z.object({
+        channelId: z.string().describe("WhatsApp channel identifier (UUID)"),
+        groupJid: z.string().describe("Group JID (ending in @g.us)"),
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    },
+    async (args) => {
+      try {
+        const res = await api("POST", `/whatsapp-actions/${args.channelId}/groups/${args.groupJid}/leave`);
+        return jsonResult(res);
+      } catch (error) { return errorResult(error); }
+    },
+  );
+}