neuron-mcp-server 1.0.0 → 1.1.0

package/src/index.ts

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+/**
+ * Neuron MCP Server
+ *
+ * Exposes the full Neuron AI chatbot platform as MCP tools.
+ * Supports 120+ tools covering bots, conversations, knowledge bases,
+ * tools, webhooks, built-in tools, reflections, channels, contacts,
+ * broadcasts, billing, media, AI, marketplace, and more.
+ *
+ * Environment variables:
+ *   NEURON_API_URL   - Base URL (default: https://api.neuron.ng/api/v1)
+ *   NEURON_AUTH_TOKEN - Pre-set JWT or API key for authentication
+ *   MCP_TRANSPORT    - "http" for Streamable HTTP, "stdio" (default) for stdio
+ *   PORT             - HTTP server port (default: 3001)
+ *
+ * Transports:
+ *   stdio - For local Claude Code / IDE integration (default)
+ *   http  - For remote connections (Claude.ai custom connectors)
+ */
+
+import { config } from "dotenv";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+// Load .env from mcp-server directory (not CWD which may be the project root)
+const __dirname = dirname(fileURLToPath(import.meta.url));
+config({ path: resolve(__dirname, "../.env") });
+
+import { randomUUID } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+
+import { registerAuthTools } from "./tools/auth.js";
+import { registerBotTools } from "./tools/bots.js";
+import { registerBotApiKeyTools } from "./tools/bot-api-keys.js";
+import { registerBotApiTools } from "./tools/bot-api.js";
+import { registerConversationTools } from "./tools/conversations.js";
+import { registerKnowledgeBaseTools } from "./tools/knowledge-bases.js";
+import { registerToolsTools } from "./tools/tools.js";
+import { registerTaskTools } from "./tools/tasks.js";
+import { registerLeadTools } from "./tools/leads.js";
+import { registerPersonaTools } from "./tools/personas.js";
+import { registerWebhooksTools } from "./tools/webhooks.js";
+import { registerReflectionsTools } from "./tools/reflections.js";
+import { registerChannelsTools } from "./tools/channels.js";
+import { registerPoolTools } from "./tools/pool.js";
+import { registerOrganizationTools } from "./tools/organizations.js";
+import { registerAuditTools } from "./tools/audit.js";
+import { registerBuiltinToolsTools } from "./tools/builtin-tools.js";
+import { registerOutboundWebhookTools } from "./tools/outbound-webhooks.js";
+import { registerContactsTools } from "./tools/contacts.js";
+import { registerContactListsTools } from "./tools/contact-lists.js";
+import { registerListCampaignTools } from "./tools/list-campaigns.js";
+import { registerBroadcastsTools } from "./tools/broadcasts.js";
+import { registerBillingTools } from "./tools/billing.js";
+import { registerMediaTools } from "./tools/media.js";
+import { registerAiTools } from "./tools/ai.js";
+import { registerCampaignTools } from "./tools/campaigns.js";
+import { registerWalletTools } from "./tools/wallets.js";
+import { registerPayoutTools } from "./tools/payouts.js";
+import { registerBlogTools } from "./tools/blog.js";
+import { registerNewsletterTools } from "./tools/newsletters.js";
+import { registerListPoolTools } from "./tools/list-pool.js";
+import { registerWhatsAppActionTools } from "./tools/whatsapp-actions.js";
+import { registerGroupManagementTools } from "./tools/group-management.js";
+import { registerPollTools } from "./tools/polls.js";
+import { registerProfilePrivacyTools } from "./tools/profile-privacy.js";
+import { registerSocialChannelsTools } from "./tools/social-channels.js";
+import { registerScheduledMessageTools } from "./tools/scheduled-messages.js";
+import { registerApprovalTools } from "./tools/approvals.js";
+import { registerFlowTools } from "./tools/flows.js";
+import { registerProductsTools } from "./tools/products.js";
+
+function createServer(): McpServer {
+  const server = new McpServer({
+    name: "neuron-mcp-server",
+    version: "1.0.0",
+  });
+
+  // Register all tool groups
+  registerAuthTools(server);
+  registerBotTools(server);
+  registerBotApiKeyTools(server);
+  registerBotApiTools(server);
+  registerConversationTools(server);
+  registerKnowledgeBaseTools(server);
+  registerToolsTools(server);
+  registerTaskTools(server);
+  registerLeadTools(server);
+  registerPersonaTools(server);
+  registerWebhooksTools(server);
+  registerReflectionsTools(server);
+  registerChannelsTools(server);
+  registerPoolTools(server);
+  registerOrganizationTools(server);
+  registerAuditTools(server);
+  registerBuiltinToolsTools(server);
+  registerOutboundWebhookTools(server);
+  registerContactsTools(server);
+  registerContactListsTools(server);
+  registerListCampaignTools(server);
+  registerBroadcastsTools(server);
+  registerBillingTools(server);
+  registerMediaTools(server);
+  registerAiTools(server);
+  registerCampaignTools(server);
+  registerWalletTools(server);
+  registerPayoutTools(server);
+  registerBlogTools(server);
+  registerNewsletterTools(server);
+  registerListPoolTools(server);
+  registerWhatsAppActionTools(server);
+  registerGroupManagementTools(server);
+  registerPollTools(server);
+  registerProfilePrivacyTools(server);
+  registerSocialChannelsTools(server);
+  registerScheduledMessageTools(server);
+  registerApprovalTools(server);
+  registerFlowTools(server);
+  registerProductsTools(server);
+
+  return server;
+}
+
+async function startStdio() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Neuron MCP server running via stdio");
+}
+
+async function startHttp() {
+  const PORT = parseInt(process.env.PORT || "3001", 10);
+  const app = createMcpExpressApp({ host: "0.0.0.0" });
+
+  const transports: Record<string, StreamableHTTPServerTransport> = {};
+
+  function createTransport(): StreamableHTTPServerTransport {
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: (sid) => {
+        transports[sid] = transport;
+        console.error(`Session initialized: ${sid}`);
+      },
+    });
+
+    transport.onclose = () => {
+      const sid = transport.sessionId;
+      if (sid && transports[sid]) {
+        delete transports[sid];
+      }
+    };
+
+    return transport;
+  }
+
+  app.all("/mcp", async (req, res) => {
+    try {
+      const sessionId = req.headers["mcp-session-id"] as string | undefined;
+      let transport: StreamableHTTPServerTransport;
+
+      if (sessionId && transports[sessionId]) {
+        // Known session — reuse existing transport
+        transport = transports[sessionId];
+      } else if (req.method === "POST" && isInitializeRequest(req.body)) {
+        // New or re-initializing client — create a fresh session
+        // (handles both no session ID and stale session ID after server restart)
+        transport = createTransport();
+        const server = createServer();
+        await server.connect(transport);
+      } else if (sessionId && !transports[sessionId]) {
+        // Stale session ID with a non-initialize request — tell client to re-initialize
+        res.status(404).json({
+          jsonrpc: "2.0",
+          error: { code: -32000, message: "Session expired. Please reconnect." },
+          id: null,
+        });
+        return;
+      } else {
+        res.status(400).json({
+          jsonrpc: "2.0",
+          error: { code: -32000, message: "Bad Request: No valid session ID provided" },
+          id: null,
+        });
+        return;
+      }
+
+      await transport.handleRequest(req, res, req.body);
+    } catch (error) {
+      console.error("Error handling MCP request:", error);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: "2.0",
+          error: { code: -32603, message: "Internal server error" },
+          id: null,
+        });
+      }
+    }
+  });
+
+  const httpServer = app.listen(PORT, "0.0.0.0", () => {
+    console.error(`Neuron MCP server listening on http://0.0.0.0:${PORT}/mcp`);
+  });
+
+  let shuttingDown = false;
+
+  const shutdownMcp = async () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    console.error("Shutting down...");
+
+    const forceTimer = setTimeout(() => {
+      console.error("MCP shutdown timed out, forcing exit");
+      process.exit(1);
+    }, 10_000);
+    forceTimer.unref();
+
+    // Stop accepting new connections and drain in-flight requests
+    await new Promise<void>((resolve) => {
+      httpServer.close((err) => {
+        if (err) console.error("Error closing HTTP server:", err);
+        resolve();
+      });
+    });
+
+    // Close all MCP session transports
+    await Promise.all(
+      Object.keys(transports).map((sid) =>
+        transports[sid].close().catch(() => {}).then(() => { delete transports[sid]; }),
+      ),
+    );
+
+    clearTimeout(forceTimer);
+    process.exit(0);
+  };
+
+  process.on("SIGINT", shutdownMcp);
+  process.on("SIGTERM", shutdownMcp);
+}
+
+const mode = process.env.MCP_TRANSPORT || "stdio";
+
+if (mode === "http") {
+  startHttp().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+  });
+} else {
+  startStdio().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+  });
+}

package/src/tools/ai.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+export function registerAiTools(server: McpServer): void {
+  // Rewrite text
+  server.registerTool(
+    "neuron_rewrite_text",
+    {
+      title: "Rewrite Text",
+      description: "Rewrite or rephrase text using AI with specified tone, style, or instructions (e.g., make it more formal, translate, summarize).",
+      inputSchema: z.object({
+        text: z.string().describe("The original text to rewrite or transform"),
+        instruction: z.string().optional().describe("Instructions for how to rewrite the text (e.g., 'make it more professional', 'translate to Spanish', 'summarize in 2 sentences')"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", "/ai/rewrite", {
+          text: params.text,
+          instruction: params.instruction,
+        });
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+}

package/src/tools/approvals.ts

@@ -0,0 +1,231 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+const callbackShape = z
+  .object({
+    response: z
+      .object({
+        schemes: z
+          .array(z.enum(["interactive", "keyword", "code", "llm"]))
+          .optional()
+          .describe("Ordered fallback for turning a reply into a decision (default: ['keyword'])"),
+        code: z.string().optional().describe("One-time confirmation code — enables the 'code' scheme"),
+      })
+      .optional(),
+    delivery: z
+      .object({
+        scheme: z
+          .enum(["webhook_signed", "webhook_simple", "neuron_message", "neuron_tool", "none"])
+          .describe("How the decision reaches the caller"),
+        config: z
+          .record(z.any())
+          .optional()
+          .describe("Scheme config: {url,secret} or {webhookId}; {targetJid,channelId}; {toolId}; {method}"),
+      })
+      .optional(),
+    await: z.boolean().optional().describe("Hold the request until resolved (long-poll)"),
+    awaitTimeoutSec: z.number().int().min(1).max(60).optional(),
+  })
+  .optional()
+  .describe("Callback config. Omit for a poll-only flow (delivery scheme 'none').");
+
+export function registerApprovalTools(server: McpServer): void {
+  // Request an approval
+  server.registerTool(
+    "neuron_request_approval",
+    {
+      title: "Request Approval",
+      description:
+        "Ask a human to approve or reject an action over WhatsApp and get the decision back. " +
+        "The recipient replies approve/reject (optionally with a reason) or quotes the message. " +
+        "Use this to gate any action needing human sign-off (refunds, deploys, spend, publishing). " +
+        "Returns an approvalId; poll neuron_get_approval / neuron_list_approvals for the outcome, or supply a " +
+        "webhook in `callback` to be notified. Requires a bot API key ('nrn_' prefix).",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+      inputSchema: z.object({
+        apiKey: z.string().describe("Bot API key with 'nrn_' prefix for authentication"),
+        to: z.string().describe("Recipient phone number (E.164/digits) or WhatsApp group JID"),
+        prompt: z.string().describe("The approval question shown to the human"),
+        context: z.string().optional().describe("Optional long-form details — stored in a shareable Neuron Note and linked from the WhatsApp message"),
+        channelId: z.string().optional().describe("Optional WhatsApp channel override (UUID)"),
+        expiresInSeconds: z.number().int().positive().optional().describe("Time to live before auto-expiry (default 86400, 60–604800)"),
+        metadata: z.record(z.any()).optional().describe("Opaque data echoed back verbatim in the result/callback"),
+        idempotencyKey: z.string().optional().describe("Dedupe key — returns the existing approval on repeat"),
+        callback: callbackShape,
+      }),
+    },
+    async (params) => {
+      try {
+        const { apiKey, callback, ...rest } = params;
+        const body = {
+          ...rest,
+          callback: callback ?? { response: { schemes: ["keyword"] }, delivery: { scheme: "none" } },
+        };
+        const result = await api("POST", "approvals", body, undefined, { Authorization: `Bearer ${apiKey}` });
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  // Get an approval (optionally long-poll)
+  server.registerTool(
+    "neuron_get_approval",
+    {
+      title: "Get Approval",
+      description:
+        "Fetch a single approval request by id, including its decision once resolved. " +
+        "Set waitSeconds (1–60) to long-poll until it resolves. Requires a bot API key.",
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      inputSchema: z.object({
+        apiKey: z.string().describe("Bot API key with 'nrn_' prefix for authentication"),
+        approvalId: z.string().describe("The approval request id (UUID)"),
+        waitSeconds: z.number().int().min(1).max(60).optional().describe("Long-poll up to N seconds for resolution"),
+      }),
+    },
+    async (params) => {
+      try {
+        const { apiKey, approvalId, waitSeconds } = params;
+        const result = await api(
+          "GET",
+          `approvals/${approvalId}`,
+          undefined,
+          waitSeconds ? { wait: waitSeconds } : undefined,
+          { Authorization: `Bearer ${apiKey}` },
+        );
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  // List approvals
+  server.registerTool(
+    "neuron_list_approvals",
+    {
+      title: "List Approvals",
+      description:
+        "List approval requests for the organization, newest first. Filter by status " +
+        "(pending/approved/rejected/expired/cancelled). Requires a bot API key.",
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      inputSchema: z.object({
+        apiKey: z.string().describe("Bot API key with 'nrn_' prefix for authentication"),
+        status: z.string().optional().describe("Filter: pending | approved | rejected | expired | cancelled"),
+        channelId: z.string().optional().describe("Filter by WhatsApp channel (UUID)"),
+        page: z.number().int().positive().optional().describe("Page number (default 1)"),
+        limit: z.number().int().positive().optional().describe("Items per page (default 25, max 100)"),
+      }),
+    },
+    async (params) => {
+      try {
+        const { apiKey, status, channelId, page, limit } = params;
+        const result = await api(
+          "GET",
+          "approvals",
+          undefined,
+          { status, channelId, page, limit },
+          { Authorization: `Bearer ${apiKey}` },
+        );
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  // Respond to (approve/reject) a pending approval
+  server.registerTool(
+    "neuron_respond_approval",
+    {
+      title: "Respond to Approval",
+      description:
+        "Approve or reject a pending approval programmatically — the decision surface for an authorized operator " +
+        "acting via MCP instead of replying on WhatsApp. Fires the configured callback and posts the outcome to the " +
+        "WhatsApp chat. Exactly-once: the first responder (here or on WhatsApp) wins; later responses return 410. " +
+        "Requires a bot API key.",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+      inputSchema: z.object({
+        apiKey: z.string().describe("Bot API key with 'nrn_' prefix for authentication"),
+        approvalId: z.string().describe("The approval request id (UUID)"),
+        decision: z.enum(["approve", "reject"]).describe("The decision to record"),
+        reason: z.string().optional().describe("Optional reason (recommended for rejections)"),
+        responderName: z.string().optional().describe("Optional display name of the operator making the decision"),
+      }),
+    },
+    async (params) => {
+      try {
+        const { apiKey, approvalId, decision, reason, responderName } = params;
+        const result = await api(
+          "POST",
+          `approvals/${approvalId}/respond`,
+          { decision, reason, responderName },
+          undefined,
+          { Authorization: `Bearer ${apiKey}` },
+        );
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  // Cancel a pending approval
+  server.registerTool(
+    "neuron_cancel_approval",
+    {
+      title: "Cancel Approval",
+      description:
+        "Cancel a still-pending approval (e.g. the upstream action was aborted). " +
+        "Fires the approval.cancelled callback. Requires a bot API key.",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      inputSchema: z.object({
+        apiKey: z.string().describe("Bot API key with 'nrn_' prefix for authentication"),
+        approvalId: z.string().describe("The approval request id (UUID) to cancel"),
+        reason: z.string().optional().describe("Optional cancellation reason"),
+      }),
+    },
+    async (params) => {
+      try {
+        const { apiKey, approvalId, reason } = params;
+        const result = await api(
+          "POST",
+          `approvals/${approvalId}/cancel`,
+          { reason },
+          undefined,
+          { Authorization: `Bearer ${apiKey}` },
+        );
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+}

package/src/tools/audit.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+export function registerAuditTools(server: McpServer): void {
+  // List Audit Logs
+  server.registerTool(
+    "neuron_list_audit_logs",
+    {
+      title: "List Audit Logs",
+      description: "Retrieve audit logs for the organization, showing a chronological record of actions performed by members. Supports filtering by action type and resource.",
+      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 log entries per page (default: 20)"),
+        action: z.string().optional().describe("Filter by action type (e.g., 'CREATE', 'UPDATE', 'DELETE')"),
+        resourceType: z.string().optional().describe("Filter by resource type (e.g., 'USER', 'ORGANIZATION', 'BOT', 'CAMPAIGN')"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const queryParams: Record<string, string | number> = {};
+
+        if (params.page !== undefined) {
+          queryParams.page = params.page;
+        }
+        if (params.limit !== undefined) {
+          queryParams.limit = params.limit;
+        }
+        if (params.action !== undefined) {
+          queryParams.action = params.action;
+        }
+        if (params.resourceType !== undefined) {
+          queryParams.resourceType = params.resourceType;
+        }
+
+        const result = await api("GET", "/audit", undefined, queryParams);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+}