neuron-mcp-server 1.0.0 → 1.1.0

package/src/tools/campaigns.ts

@@ -0,0 +1,429 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+export function registerCampaignTools(server: McpServer): void {
+  server.registerTool(
+    "neuron_list_campaigns",
+    {
+      title: "List Campaigns",
+      description: "Retrieve all campaigns for the current organization with optional status filtering and pagination.",
+      inputSchema: z.object({
+        status: z.string().optional().describe("Filter by campaign status: 'draft', 'active', 'paused', 'completed', 'stopped', or 'rejected'"),
+        page: z.number().int().positive().optional().describe("Page number for pagination (default: 1)"),
+        limit: z.number().int().positive().optional().describe("Number of campaigns per page (default: 20)"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", "/campaigns", undefined, params);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_get_campaign",
+    {
+      title: "Get Campaign",
+      description: "Retrieve detailed information about a specific campaign including its status, budget, participants, and delivery metrics.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the campaign"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", `/campaigns/${params.id}`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_campaign_marketplace",
+    {
+      title: "Browse Campaign Marketplace",
+      description: "Browse available campaigns in the marketplace that your organization can join to earn rewards by sending messages.",
+      inputSchema: z.object({
+        page: z.number().int().positive().optional().describe("Page number for pagination (default: 1)"),
+        limit: z.number().int().positive().optional().describe("Number of campaigns per page (default: 20)"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", "/campaigns/marketplace", undefined, params);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_create_campaign",
+    {
+      title: "Create Campaign",
+      description: "Create a new outreach campaign with target audience, messaging template, and schedule configuration. Requires a Pro or Business plan.",
+      inputSchema: z.object({
+        title: z.string().describe("Campaign title displayed in marketplace and dashboard"),
+        message: z.string().describe("The WhatsApp message template to send to contacts"),
+        rewardPerDelivery: z.number().describe("Reward per successful delivery in kobo (e.g., 5000 = NGN 50)"),
+        totalBudget: z.number().describe("Total campaign budget in kobo (e.g., 500000 = NGN 5,000)"),
+        deadline: z.string().describe("Campaign deadline in ISO 8601 date format (e.g., '2025-12-31')"),
+        description: z.string().optional().describe("Campaign description shown in the marketplace listing"),
+        guidelines: z.string().optional().describe("Instructions and guidelines for campaign participants"),
+        requireMutualContact: z.boolean().optional().describe("Only allow sends to contacts who have previously responded (default: false)"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", "/campaigns", params);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_update_campaign",
+    {
+      title: "Update Campaign",
+      description: "Update a campaign that is in 'draft' or 'rejected' status. Active or completed campaigns cannot be modified.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the campaign to update"),
+        title: z.string().optional().describe("Updated campaign title"),
+        message: z.string().optional().describe("Updated WhatsApp message template"),
+        rewardPerDelivery: z.number().optional().describe("Updated reward per delivery in kobo (e.g., 5000 = NGN 50)"),
+        totalBudget: z.number().optional().describe("Updated total campaign budget in kobo"),
+        deadline: z.string().optional().describe("Updated campaign deadline in ISO 8601 date format"),
+        description: z.string().optional().describe("Updated marketplace description"),
+        guidelines: z.string().optional().describe("Updated participant guidelines"),
+        requireMutualContact: z.boolean().optional().describe("Updated mutual contact requirement setting"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const { id, ...data } = params;
+        const result = await api("PUT", `/campaigns/${id}`, data);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_delete_campaign",
+    {
+      title: "Delete Campaign",
+      description: "Permanently delete a campaign that is in 'draft' status. Active or funded campaigns cannot be deleted.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the draft campaign to delete"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("DELETE", `/campaigns/${params.id}`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_submit_campaign",
+    {
+      title: "Submit Campaign for Review",
+      description: "Submit a draft campaign for admin review and approval. The campaign must be in 'draft' status.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the draft campaign to submit for review"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", `/campaigns/${params.id}/submit`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_fund_campaign",
+    {
+      title: "Fund Campaign",
+      description: "Fund an approved campaign by deducting the total budget from the organization's wallet balance. Requires sufficient wallet funds.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the approved campaign to fund"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", `/campaigns/${params.id}/fund`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_join_campaign",
+    {
+      title: "Join Campaign",
+      description: "Join a marketplace campaign as a participant to earn rewards by sending messages through your WhatsApp channel.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the campaign to join"),
+        channelId: z.string().describe("Unique identifier (UUID) of your WhatsApp channel to send messages from"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const { id, ...data } = params;
+        const result = await api("POST", `/campaigns/${id}/join`, data);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_get_eligible_contacts",
+    {
+      title: "Get Eligible Contacts",
+      description: "Retrieve contacts eligible to receive a campaign message. Respects deduplication rules and mutual contact requirements.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the campaign to check eligibility for"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", `/campaigns/${params.id}/eligible-contacts`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_send_campaign_message",
+    {
+      title: "Send Campaign Messages",
+      description: "Send a campaign message to selected eligible contacts via WhatsApp. Requires the campaign to be in 'active' status and contacts to be eligible.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the active campaign"),
+        contactIds: z.array(z.string()).describe("Array of contact UUIDs to send the campaign message to"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const { id, contactIds } = params;
+        const result = await api("POST", `/campaigns/${id}/send`, { contactIds });
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_my_participations",
+    {
+      title: "My Campaign Participations",
+      description: "Retrieve all campaigns the current organization has joined as a participant, including earnings and delivery stats.",
+      inputSchema: z.object({
+        page: z.number().int().positive().optional().describe("Page number for pagination (default: 1)"),
+        limit: z.number().int().positive().optional().describe("Number of participations per page (default: 20)"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", "/campaigns/my-participations", undefined, params);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_campaign_participants",
+    {
+      title: "List Campaign Participants",
+      description: "Retrieve all participants who have joined a campaign you own, including their delivery counts and earned rewards.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the campaign you own"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", `/campaigns/${params.id}/participants`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_pause_campaign",
+    {
+      title: "Pause Campaign",
+      description: "Pause an active campaign to temporarily stop message delivery. Can be resumed later with the resume action.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the active campaign to pause"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", `/campaigns/${params.id}/pause`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_resume_campaign",
+    {
+      title: "Resume Campaign",
+      description: "Resume a previously paused campaign to restart message delivery.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the paused campaign to resume"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", `/campaigns/${params.id}/resume`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_stop_campaign",
+    {
+      title: "Stop Campaign",
+      description: "Permanently stop an active campaign and refund the remaining unspent budget to the organization's wallet. This action cannot be undone.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the active campaign to stop"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", `/campaigns/${params.id}/stop`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+}