neuron-mcp-server 1.0.0 → 1.1.0

package/src/tools/newsletters.ts

@@ -0,0 +1,271 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+export function registerNewsletterTools(server: McpServer): void {
+  // 1. List newsletters
+  server.registerTool(
+    "neuron_list_newsletters",
+    {
+      title: "List Newsletters",
+      description: "Retrieve a paginated list of all WhatsApp Channel newsletters for the organization, with optional filtering by WhatsApp session channel.",
+      inputSchema: z.object({
+        channelId: z.string().optional().describe("Filter newsletters by WhatsApp session channel identifier (UUID)"),
+        page: z.number().int().positive().optional().describe("Page number for pagination (default: 1)"),
+        limit: z.number().int().positive().optional().describe("Number of items per page (default: 20)"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (args) => {
+      try {
+        const response = await api("GET", "/newsletters", undefined, {
+          channelId: args.channelId,
+          page: args.page,
+          limit: args.limit,
+        });
+        return jsonResult(response);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // 2. Create newsletter
+  server.registerTool(
+    "neuron_create_newsletter",
+    {
+      title: "Create Newsletter",
+      description: "Create a new WhatsApp Channel newsletter for one-way broadcast updates. Requires a connected Baileys session on the specified channel.",
+      inputSchema: z.object({
+        channelId: z.string().describe("Identifier (UUID) of the WhatsApp session channel to create the newsletter on"),
+        name: z.string().describe("Display name of the newsletter visible to subscribers"),
+        description: z.string().optional().describe("Description of the newsletter's purpose and content"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (args) => {
+      try {
+        const response = await api("POST", "/newsletters", args);
+        return jsonResult(response);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // 3. Get newsletter
+  server.registerTool(
+    "neuron_get_newsletter",
+    {
+      title: "Get Newsletter",
+      description: "Retrieve detailed information about a specific WhatsApp Channel newsletter, including subscriber count and metadata.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the newsletter to retrieve"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (args) => {
+      try {
+        const response = await api("GET", `/newsletters/${args.id}`);
+        return jsonResult(response);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // 4. Update newsletter
+  server.registerTool(
+    "neuron_update_newsletter",
+    {
+      title: "Update Newsletter",
+      description: "Update the name or description of an existing WhatsApp Channel newsletter. Only provided fields are changed.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the newsletter to update"),
+        name: z.string().optional().describe("New display name for the newsletter"),
+        description: z.string().optional().describe("New description for the newsletter"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (args) => {
+      try {
+        const { id, ...updateData } = args;
+        const response = await api("PUT", `/newsletters/${id}`, updateData);
+        return jsonResult(response);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // 5. Delete newsletter
+  server.registerTool(
+    "neuron_delete_newsletter",
+    {
+      title: "Delete Newsletter",
+      description: "Permanently delete a WhatsApp Channel newsletter and remove it from WhatsApp. This action cannot be undone.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the newsletter to delete"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (args) => {
+      try {
+        const response = await api("DELETE", `/newsletters/${args.id}`);
+        return jsonResult(response);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // 6. Post to newsletter
+  server.registerTool(
+    "neuron_post_to_newsletter",
+    {
+      title: "Post to Newsletter",
+      description: "Post a message to a WhatsApp Channel newsletter. All subscribers receive the message. Provide at least one of text or mediaUrl. This triggers delivery and cannot be undone.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the newsletter to post to"),
+        text: z.string().optional().describe("Message text or caption to post to the newsletter"),
+        messageType: z.enum(["text", "image", "video", "document"]).default("text").describe("Type of message to send (default: 'text')"),
+        mediaUrl: z.string().optional().describe("URL of the media file to attach (required for image, video, or document types)"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (args) => {
+      try {
+        const body: Record<string, string | undefined> = {
+          text: args.text,
+          messageType: args.messageType,
+          mediaUrl: args.mediaUrl,
+        };
+        const response = await api("POST", `/newsletters/${args.id}/post`, body);
+        return jsonResult(response);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // 6b. Post to WhatsApp Status / Story
+  server.registerTool(
+    "neuron_post_to_status",
+    {
+      title: "Post to WhatsApp Status",
+      description:
+        "Post a WhatsApp Status / Story from a connected direct (Baileys) WhatsApp number. Visible to the account's synced contacts for 24 hours — you do NOT specify recipients (the contact list is built automatically; pass statusJidList only to target a subset). Provide at least one of text or mediaUrl. channelId is optional and auto-resolves to the default connected number. This triggers delivery and cannot be undone.",
+      inputSchema: z.object({
+        text: z.string().optional().describe("Status text (for a text story) or caption (for media)"),
+        messageType: z.enum(["text", "image", "video", "audio"]).default("text").describe("Type of status (default: 'text')"),
+        mediaUrl: z.string().optional().describe("URL of the image/video/audio to post (required for non-text statuses)"),
+        channelId: z.string().optional().describe("WhatsApp session channel UUID to post from. Omit to auto-resolve."),
+        backgroundColor: z.string().optional().describe("Text-status background colour as hex, e.g. '#315575'"),
+        font: z.number().int().min(0).max(9).optional().describe("Text-status font index (0–9)"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (args) => {
+      try {
+        const response = await api("POST", "/conversations/compose-story", {
+          text: args.text,
+          messageType: args.messageType,
+          mediaUrl: args.mediaUrl,
+          channelId: args.channelId,
+          backgroundColor: args.backgroundColor,
+          font: args.font,
+        });
+        return jsonResult(response);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // 7. Refresh newsletter metadata
+  server.registerTool(
+    "neuron_refresh_newsletter",
+    {
+      title: "Refresh Newsletter",
+      description: "Re-fetch metadata (name, description, subscriber count) for a WhatsApp Channel newsletter from WhatsApp to synchronize local data.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the newsletter to refresh"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (args) => {
+      try {
+        const response = await api("POST", `/newsletters/${args.id}/refresh`);
+        return jsonResult(response);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // 8. Sync newsletters from WhatsApp
+  server.registerTool(
+    "neuron_sync_newsletters",
+    {
+      title: "Sync Newsletters",
+      description: "Synchronize and import WhatsApp Channels from a connected WhatsApp session into Neuron. Discovers channels created outside Neuron.",
+      inputSchema: z.object({
+        channelId: z.string().describe("Identifier (UUID) of the WhatsApp session channel to sync newsletters from"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (args) => {
+      try {
+        const response = await api("POST", "/newsletters/sync", { channelId: args.channelId });
+        return jsonResult(response);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+}

package/src/tools/organizations.ts

@@ -0,0 +1,287 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+export function registerOrganizationTools(server: McpServer): void {
+  // Get Organization
+  server.registerTool(
+    "neuron_get_organization",
+    {
+      title: "Get Organization",
+      description: "Retrieve detailed information about a specific organization, including its name, settings, and configuration.",
+      inputSchema: z.object({
+        orgId: z.string().describe("Unique identifier (UUID) of the organization to retrieve"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", `/organizations/${params.orgId}`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Update Organization
+  server.registerTool(
+    "neuron_update_organization",
+    {
+      title: "Update Organization",
+      description: "Update organization settings such as name, description, or configuration preferences. Only provided fields are changed.",
+      inputSchema: z.object({
+        orgId: z.string().describe("Unique identifier (UUID) of the organization to update"),
+        name: z.string().optional().describe("New display name for the organization"),
+        autoOptOutBroadcast: z.boolean().optional().describe("Auto-exclude a contact from broadcasts when they send a broadcast opt-out message (e.g. 'stop messaging me'). Off by default."),
+        autoSuppressHostile: z.boolean().optional().describe("Auto-exclude a contact from broadcasts when they are hostile about being contacted (e.g. cursing us out for messaging them). Off by default."),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const { orgId, ...body } = params;
+        const result = await api("PUT", `/organizations/${orgId}`, body);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Update WhatsApp Credentials
+  server.registerTool(
+    "neuron_update_whatsapp_credentials",
+    {
+      title: "Update WhatsApp Credentials",
+      description: "Update WhatsApp Business API credentials for the organization. These credentials are required for sending messages via the WhatsApp Cloud API.",
+      inputSchema: z.object({
+        orgId: z.string().describe("Unique identifier (UUID) of the organization"),
+        whatsappPhoneNumberId: z.string().describe("WhatsApp phone number ID from the Meta Business dashboard"),
+        whatsappBusinessAccountId: z.string().describe("WhatsApp Business Account ID from the Meta Business dashboard"),
+        whatsappAccessToken: z.string().describe("WhatsApp access token for API authentication (keep confidential)"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const { orgId, ...body } = params;
+        const result = await api("PUT", `/organizations/${orgId}/whatsapp`, body);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Set Default Channel
+  server.registerTool(
+    "neuron_set_default_channel",
+    {
+      title: "Set Default WhatsApp Channel",
+      description:
+        "Set or clear the default WhatsApp channel for the organization. The default channel is used by neuron_send_whatsapp for auto-resolving which channel to send through.",
+      inputSchema: z.object({
+        orgId: z.string().describe("Unique identifier (UUID) of the organization"),
+        channelId: z.string().nullable().describe("Identifier (UUID) of the channel to set as default, or null to clear the default"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("PUT", `/organizations/${params.orgId}/default-channel`, {
+          channelId: params.channelId,
+        });
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // List Members
+  server.registerTool(
+    "neuron_list_members",
+    {
+      title: "List Organization Members",
+      description: "Retrieve a list of all members in the organization, including their roles and permissions.",
+      inputSchema: z.object({
+        orgId: z.string().describe("Unique identifier (UUID) of the organization"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", `/organizations/${params.orgId}/members`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Invite Member
+  server.registerTool(
+    "neuron_invite_member",
+    {
+      title: "Invite Organization Member",
+      description: "Send an invitation to a new member to join the organization. The invitee receives an email with a link to accept.",
+      inputSchema: z.object({
+        orgId: z.string().describe("Unique identifier (UUID) of the organization"),
+        email: z.string().email().describe("Email address of the person to invite"),
+        name: z.string().describe("Full name of the person being invited"),
+        role: z.string().optional().describe("Role to assign to the member (e.g., 'admin', 'agent', 'viewer')"),
+        canViewConversations: z.boolean().optional().describe("Whether the invited member can view conversations (default: true)"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const { orgId, ...body } = params;
+        const result = await api("POST", `/organizations/${orgId}/members`, body);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // List Invitations
+  server.registerTool(
+    "neuron_list_invitations",
+    {
+      title: "List Invitations",
+      description: "Retrieve a list of all pending invitations for the organization that have not yet been accepted or revoked.",
+      inputSchema: z.object({
+        orgId: z.string().describe("Unique identifier (UUID) of the organization"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", `/organizations/${params.orgId}/invitations`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Revoke Invitation
+  server.registerTool(
+    "neuron_revoke_invitation",
+    {
+      title: "Revoke Invitation",
+      description: "Revoke a pending organization invitation so it can no longer be accepted. This action cannot be undone.",
+      inputSchema: z.object({
+        orgId: z.string().describe("Unique identifier (UUID) of the organization"),
+        invitationId: z.string().describe("Unique identifier (UUID) of the invitation to revoke"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("DELETE", `/organizations/${params.orgId}/invitations/${params.invitationId}`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Update Member Permissions
+  server.registerTool(
+    "neuron_update_member",
+    {
+      title: "Update Member Permissions",
+      description: "Update a member's permissions within the organization, such as conversation access. Only provided fields are changed.",
+      inputSchema: z.object({
+        orgId: z.string().describe("Unique identifier (UUID) of the organization"),
+        userId: z.string().describe("Unique identifier (UUID) of the member to update"),
+        canViewConversations: z.boolean().describe("Whether the member can view conversations"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const { orgId, userId, ...body } = params;
+        const result = await api("PATCH", `/organizations/${orgId}/members/${userId}`, body);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Remove Member
+  server.registerTool(
+    "neuron_remove_member",
+    {
+      title: "Remove Organization Member",
+      description: "Permanently remove a member from the organization. The member loses all access immediately. This action cannot be undone.",
+      inputSchema: z.object({
+        orgId: z.string().describe("Unique identifier (UUID) of the organization"),
+        userId: z.string().describe("Unique identifier (UUID) of the member to remove"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("DELETE", `/organizations/${params.orgId}/members/${params.userId}`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+}