neuron-mcp-server 1.0.0 → 1.1.0

package/src/tools/outbound-webhooks.ts

@@ -0,0 +1,181 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+const eventTypes = [
+  "message.created",
+  "message.assistant",
+  "conversation.created",
+  "conversation.escalated",
+  "conversation.closed",
+  "bot.paused",
+  "bot.resumed",
+] as const;
+
+/**
+ * Register outbound webhook tools (event-driven webhooks that fire on bot events)
+ */
+export function registerOutboundWebhookTools(server: McpServer): void {
+  // 1. Create Outbound Webhook
+  server.registerTool(
+    "neuron_create_outbound_webhook",
+    {
+      title: "Create Outbound Webhook",
+      description:
+        "Register a new outbound webhook that sends HTTP POST requests to an external URL when specified bot events occur. " +
+        "Supported events: message.created, message.assistant, conversation.created, conversation.escalated, " +
+        "conversation.closed, bot.paused, bot.resumed.",
+      inputSchema: z.object({
+        botId: z.string().describe("Unique identifier (UUID) of the bot to create the outbound webhook for"),
+        name: z.string().describe("Human-readable name for the outbound webhook"),
+        url: z.string().describe("Destination URL that will receive webhook event payloads (HTTPS recommended)"),
+        eventTypes: z
+          .array(z.enum(eventTypes))
+          .describe("Array of event types that should trigger this webhook"),
+        filterPrompt: z
+          .string()
+          .optional()
+          .describe("Optional LLM prompt to selectively filter which events are forwarded (e.g., 'only forward escalations about billing')"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const { botId, ...body } = args;
+      const response = await api("POST", `/webhooks/outbound/bot/${botId}`, body);
+
+      if (response.success) {
+        return jsonResult(response.data);
+      } else {
+        return errorResult(response.error || "Failed to create outbound webhook");
+      }
+    }
+  );
+
+  // 2. List Outbound Webhooks
+  server.registerTool(
+    "neuron_list_outbound_webhooks",
+    {
+      title: "List Outbound Webhooks",
+      description: "Retrieve all outbound webhooks configured for a specific bot, including their target URLs and subscribed event types.",
+      inputSchema: z.object({
+        botId: z.string().describe("Unique identifier (UUID) of the bot to list outbound webhooks for"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const response = await api("GET", `/webhooks/outbound/bot/${args.botId}`);
+
+      if (response.success) {
+        return jsonResult(response.data);
+      } else {
+        return errorResult(response.error || "Failed to list outbound webhooks");
+      }
+    }
+  );
+
+  // 3. Update Outbound Webhook
+  server.registerTool(
+    "neuron_update_outbound_webhook",
+    {
+      title: "Update Outbound Webhook",
+      description: "Modify an existing outbound webhook's configuration, including its destination URL, subscribed event types, or filter prompt.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the outbound webhook to update"),
+        name: z.string().optional().describe("Updated human-readable name for the webhook"),
+        url: z.string().optional().describe("Updated destination URL that will receive webhook event payloads (HTTPS recommended)"),
+        eventTypes: z
+          .array(z.enum(eventTypes))
+          .optional()
+          .describe("Updated array of event types that should trigger this webhook"),
+        filterPrompt: z.string().optional().describe("Updated LLM prompt for selectively filtering forwarded events"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const { id, ...body } = args;
+      const response = await api("PUT", `/webhooks/outbound/${id}`, body);
+
+      if (response.success) {
+        return jsonResult(response.data);
+      } else {
+        return errorResult(response.error || "Failed to update outbound webhook");
+      }
+    }
+  );
+
+  // 4. Delete Outbound Webhook
+  server.registerTool(
+    "neuron_delete_outbound_webhook",
+    {
+      title: "Delete Outbound Webhook",
+      description: "Permanently remove an outbound webhook. The external endpoint will no longer receive event notifications from this bot.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the outbound webhook to delete"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const response = await api("DELETE", `/webhooks/outbound/${args.id}`);
+
+      if (response.success) {
+        return jsonResult(response.data || { message: "Outbound webhook deleted successfully" });
+      } else {
+        return errorResult(response.error || "Failed to delete outbound webhook");
+      }
+    }
+  );
+
+  // 5. Get Outbound Webhook Logs
+  server.registerTool(
+    "neuron_get_outbound_webhook_logs",
+    {
+      title: "Get Outbound Webhook Logs",
+      description: "Retrieve delivery logs for an outbound webhook to monitor event dispatch history and debug delivery failures.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the outbound webhook to get logs for"),
+        page: z.number().optional().describe("Page number for pagination (default: 1)"),
+        limit: z.number().optional().describe("Number of log entries per page (default: 20)"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (args) => {
+      const { id, page, limit } = args;
+      const params: Record<string, string> = {};
+      if (page !== undefined) params.page = String(page);
+      if (limit !== undefined) params.limit = String(limit);
+
+      const response = await api("GET", `/webhooks/outbound/${id}/logs`, undefined, params);
+
+      if (response.success) {
+        return jsonResult(response.data);
+      } else {
+        return errorResult(response.error || "Failed to get outbound webhook logs");
+      }
+    }
+  );
+}

package/src/tools/payouts.ts

@@ -0,0 +1,133 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+export function registerPayoutTools(server: McpServer): void {
+  server.registerTool(
+    "neuron_verify_bank_account",
+    {
+      title: "Verify Bank Account",
+      description: "Verify a Nigerian bank account number via Paystack to confirm the account holder name before saving.",
+      inputSchema: z.object({
+        bankCode: z.string().describe("Nigerian bank code (e.g., '058' for GTBank, '044' for Access Bank)"),
+        accountNumber: z.string().describe("10-digit Nigerian bank account number to verify"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", "/payouts/verify-account", params);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_save_bank_account",
+    {
+      title: "Save Bank Account",
+      description: "Save a verified bank account as the organization's payout destination. Verify the account first using neuron_verify_bank_account.",
+      inputSchema: z.object({
+        bankCode: z.string().describe("Nigerian bank code (e.g., '058' for GTBank, '044' for Access Bank)"),
+        bankName: z.string().describe("Full name of the bank (e.g., 'Guaranty Trust Bank')"),
+        accountNumber: z.string().describe("10-digit Nigerian bank account number"),
+        accountName: z.string().describe("Account holder name as returned from bank verification"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", "/payouts/bank-account", params);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_get_bank_account",
+    {
+      title: "Get Bank Account",
+      description: "Retrieve the saved bank account details currently configured as the organization's payout destination.",
+      inputSchema: z.object({}),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async () => {
+      try {
+        const result = await api("GET", "/payouts/bank-account");
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_request_payout",
+    {
+      title: "Request Payout",
+      description: "Request a payout to transfer funds from the organization wallet to the linked bank account. A bank account must be saved first.",
+      inputSchema: z.object({
+        amount: z.number().int().positive().describe("Amount to transfer in the smallest currency unit — kobo for NGN (e.g., 100000 = NGN 1,000)"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", "/payouts/request", params);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "neuron_list_payouts",
+    {
+      title: "List Payouts",
+      description: "Retrieve the payout history for the organization, including amounts, statuses, and timestamps.",
+      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 payout records per page (default: 20)"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", "/payouts", undefined, params);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+}

package/src/tools/personas.ts

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+const READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+
+export function registerPersonaTools(server: McpServer): void {
+  server.registerTool(
+    "neuron_list_personas",
+    { title: "List Personas", description: "List voice personas for the org. Each persona holds a voiceProfile (tone/style/themes/dos/donts) + exemplars distilled from a Collection of mined content.", inputSchema: z.object({}), annotations: READ },
+    async () => {
+      try { return jsonResult(await api("GET", "/personas")); } catch (e) { return errorResult(e); }
+    },
+  );
+
+  server.registerTool(
+    "neuron_get_persona",
+    { title: "Get Persona", description: "Get one voice persona (full voiceProfile + exemplars).", inputSchema: z.object({ id: z.string().describe("Persona UUID") }), annotations: READ },
+    async ({ id }) => {
+      try { return jsonResult(await api("GET", `/personas/${id}`)); } catch (e) { return errorResult(e); }
+    },
+  );
+
+  server.registerTool(
+    "neuron_build_persona",
+    {
+      title: "Build Persona from Collection",
+      description:
+        "Distill a reusable voice from a Collection of mined content: analyzes the top-engagement items and reverse-engineers a voiceProfile (tone, diction, cadence, emoji/formatting habits, themes, dos/donts) + representative exemplars. Requires the collection to have >=3 usable samples. Runs an LLM call (a few seconds).",
+      inputSchema: z.object({
+        collectionId: z.string().describe("Source Collection UUID (built by the web agent / content mining)."),
+        name: z.string().optional().describe("Persona name. Defaults to '<collection name> voice'."),
+        sampleLimit: z.number().int().min(1).max(200).optional().describe("How many top-engagement items to analyze (default 40)."),
+      }),
+      annotations: WRITE,
+    },
+    async (body) => {
+      try { return jsonResult(await api("POST", "/personas/build", body)); } catch (e) { return errorResult(e); }
+    },
+  );
+
+  server.registerTool(
+    "neuron_build_persona_from_text",
+    {
+      title: "Build Persona from Text",
+      description:
+        "Distill a reusable voice from raw text — no Collection or browser extension needed. Feed it pasted posts, a chat/dialogue transcript, WhatsApp-export text, or your own well-crafted writing sample, and it reverse-engineers a voiceProfile (tone, diction, cadence, emoji/formatting habits, themes, dos/donts) + exemplars. Provide `text` (auto-split into samples) and/or `samples` (already-split). Runs an LLM call (a few seconds).",
+      inputSchema: z.object({
+        text: z.string().optional().describe("A raw blob to distill: posts, a dialogue, a chat transcript, or a writing sample. Auto-split into samples."),
+        samples: z.array(z.string()).optional().describe("Pre-split writing samples (alternative or addition to `text`)."),
+        name: z.string().optional().describe("Persona name. Defaults to '<author> voice' or 'Custom voice'."),
+        description: z.string().optional(),
+        speaker: z.string().optional().describe("If `text` is a chat transcript, keep only this speaker's lines (name match) — so a group chat yields one person's voice."),
+        platform: z.string().optional().describe("Optional metadata tag for the samples (e.g. 'whatsapp', 'x')."),
+        authorLabel: z.string().optional().describe("Who the voice belongs to, for a more grounded analysis."),
+      }),
+      annotations: WRITE,
+    },
+    async (body) => {
+      try { return jsonResult(await api("POST", "/personas/build-from-text", body)); } catch (e) { return errorResult(e); }
+    },
+  );
+
+  server.registerTool(
+    "neuron_build_persona_from_conversation",
+    {
+      title: "Build Persona from WhatsApp Chat",
+      description:
+        "Distill a reusable voice from an existing WhatsApp conversation's stored messages — no extension needed. `author` picks whose voice: 'me' (owner's own outgoing texts), 'contact' (the other party), 'bot', or 'any'. For a group chat, pass senderName/senderPhone to isolate one participant. Requires >=3 usable text messages. Runs an LLM call.",
+      inputSchema: z.object({
+        conversationId: z.string().describe("Conversation UUID (from neuron_list_conversations)."),
+        author: z.enum(["me", "contact", "bot", "any"]).optional().describe("Whose voice to capture. Default 'me'."),
+        senderName: z.string().optional().describe("For groups: match one participant by display name."),
+        senderPhone: z.string().optional().describe("For groups: match one participant by phone."),
+        name: z.string().optional(),
+        limit: z.number().int().min(1).max(500).optional().describe("How many recent messages to read (default 200)."),
+      }),
+      annotations: WRITE,
+    },
+    async (body) => {
+      try { return jsonResult(await api("POST", "/personas/build-from-conversation", body)); } catch (e) { return errorResult(e); }
+    },
+  );
+
+  server.registerTool(
+    "neuron_generate_from_persona",
+    {
+      title: "Generate Content in Voice",
+      description: "Generate content written in the persona's voice for a topic/brief. Returns N variations. Stateless — nothing is persisted.",
+      inputSchema: z.object({
+        id: z.string().describe("Persona UUID"),
+        topic: z.string().optional().describe("What to write about."),
+        platform: z.string().optional().describe("Target platform (instagram/x/tiktok/linkedin/facebook/whatsapp...)."),
+        format: z.string().optional().describe("Desired format (post, reply, caption, thread, DM...)."),
+        count: z.number().int().min(1).max(10).optional().describe("Number of variations (1-10, default 1)."),
+        extraInstructions: z.string().optional(),
+      }),
+      annotations: WRITE,
+    },
+    async ({ id, ...body }) => {
+      try { return jsonResult(await api("POST", `/personas/${id}/generate`, body)); } catch (e) { return errorResult(e); }
+    },
+  );
+
+  server.registerTool(
+    "neuron_apply_persona_to_bot",
+    {
+      title: "Apply Persona Voice to Bot",
+      description: "Give a bot this persona's voice: merges a delimited voice block into the bot's system prompt (idempotent — re-applying or swapping personas replaces it cleanly) and tags the bot's metadata with the persona id.",
+      inputSchema: z.object({ id: z.string().describe("Persona UUID"), botId: z.string().describe("Bot UUID to apply the voice to.") }),
+      annotations: WRITE,
+    },
+    async ({ id, botId }) => {
+      try { return jsonResult(await api("POST", `/personas/${id}/apply-to-bot`, { botId })); } catch (e) { return errorResult(e); }
+    },
+  );
+
+  server.registerTool(
+    "neuron_update_persona",
+    {
+      title: "Update Persona",
+      description: "Update a persona's name/description, or hand-tune its voiceProfile / exemplars.",
+      inputSchema: z.object({
+        id: z.string().describe("Persona UUID"),
+        name: z.string().optional(),
+        description: z.string().optional(),
+        voiceProfile: z.record(z.unknown()).optional(),
+        exemplars: z.array(z.record(z.unknown())).optional(),
+      }),
+      annotations: WRITE,
+    },
+    async ({ id, ...body }) => {
+      try { return jsonResult(await api("PUT", `/personas/${id}`, body)); } catch (e) { return errorResult(e); }
+    },
+  );
+
+  server.registerTool(
+    "neuron_delete_persona",
+    { title: "Delete Persona", description: "Delete a voice persona.", inputSchema: z.object({ id: z.string().describe("Persona UUID") }), annotations: WRITE },
+    async ({ id }) => {
+      try { return jsonResult(await api("DELETE", `/personas/${id}`)); } catch (e) { return errorResult(e); }
+    },
+  );
+}

package/src/tools/polls.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+export function registerPollTools(server: McpServer): void {
+  server.registerTool(
+    "neuron_send_poll",
+    {
+      title: "Send Poll",
+      description: "Send a poll message via WhatsApp. Polls support 2-12 options and optional multi-select. Only supported on Baileys channels.",
+      inputSchema: z.object({
+        channelId: z.string().describe("WhatsApp channel identifier (UUID)"),
+        to: z.string().describe("Recipient JID or phone number (individual or group)"),
+        name: z.string().min(1).describe("Poll question/title"),
+        options: z.array(z.string().min(1)).min(2).max(12).describe("Poll answer options (2-12 items)"),
+        selectableCount: z.number().int().min(0).optional().describe("Max selections allowed. 0 = unlimited (default). 1 = single-choice."),
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    },
+    async (args) => {
+      try {
+        const res = await api("POST", `/whatsapp-actions/${args.channelId}/send-poll`, {
+          to: args.to,
+          name: args.name,
+          options: args.options,
+          selectableCount: args.selectableCount,
+        });
+        return jsonResult(res);
+      } catch (error) { return errorResult(error); }
+    },
+  );
+}