neuron-mcp-server 1.0.0 → 1.1.0

package/src/tools/contact-lists.ts

@@ -0,0 +1,320 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+export function registerContactListsTools(server: McpServer): void {
+  server.registerTool(
+    "neuron_list_contact_lists",
+    {
+      title: "List Contact Lists",
+      description: "Retrieve all contact lists for the current organization with optional filtering by search term, type, and pagination.",
+      inputSchema: z.object({
+        search: z.string().optional().describe("Search term to filter lists by name or slug"),
+        type: z.string().optional().describe("Filter by list type: 'static', 'dynamic', or 'merged'"),
+        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 (params) => {
+      try {
+        const result = await api("GET", "/contact-lists", undefined, {
+          search: params.search,
+          type: params.type,
+          page: params.page,
+          limit: params.limit,
+        });
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_get_contact_list",
+    {
+      title: "Get Contact List",
+      description: "Retrieve detailed information about a specific contact list, including member count and configuration.",
+      inputSchema: z.object({
+        idOrSlug: z.string().describe("Unique identifier (UUID) or URL-friendly slug of the contact list"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", `/contact-lists/${params.idOrSlug}`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_create_contact_list",
+    {
+      title: "Create Contact List",
+      description: "Create a new contact list. Slug is auto-generated from name if not provided. For dynamic lists, provide criteria with rules and/or an AI prompt.",
+      inputSchema: z.object({
+        name: z.string().describe("Display name for the contact list"),
+        slug: z.string().optional().describe("URL-friendly identifier (auto-generated from name if omitted)"),
+        description: z.string().optional().describe("Human-readable description of the list's purpose"),
+        type: z.enum(["static", "dynamic", "merged"]).optional().describe("List type (default: 'static')"),
+        criteria: z.record(z.unknown()).optional().describe("Dynamic list criteria object: { rules?: { operator, conditions }, aiPrompt?, aiMaxResults? }"),
+        refreshSchedule: z.enum(["manual", "daily", "weekly", "on_access"]).optional().describe("Refresh schedule for dynamic lists (default: 'manual')"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", "/contact-lists", params);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_update_contact_list",
+    {
+      title: "Update Contact List",
+      description: "Update an existing contact list's name, slug, description, criteria, or refresh schedule.",
+      inputSchema: z.object({
+        idOrSlug: z.string().describe("Unique identifier (UUID) or URL-friendly slug of the contact list to update"),
+        name: z.string().optional().describe("Updated display name for the list"),
+        slug: z.string().optional().describe("Updated URL-friendly slug for the list"),
+        description: z.string().optional().describe("Updated description of the list's purpose"),
+        criteria: z.record(z.unknown()).optional().nullable().describe("Updated dynamic list criteria. Set to null to clear existing criteria."),
+        refreshSchedule: z.enum(["manual", "daily", "weekly", "on_access"]).optional().describe("Updated refresh schedule for dynamic lists"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const { idOrSlug, ...body } = params;
+        const result = await api("PUT", `/contact-lists/${idOrSlug}`, body);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_delete_contact_list",
+    {
+      title: "Delete Contact List",
+      description: "Permanently delete a contact list. System-protected lists (e.g., 'Do Not Contact') cannot be deleted.",
+      inputSchema: z.object({
+        idOrSlug: z.string().describe("Unique identifier (UUID) or URL-friendly slug of the contact list to delete"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("DELETE", `/contact-lists/${params.idOrSlug}`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_get_contact_list_members",
+    {
+      title: "Get Contact List Members",
+      description: "Retrieve the members of a specific contact list with optional search filtering and pagination.",
+      inputSchema: z.object({
+        idOrSlug: z.string().describe("Unique identifier (UUID) or URL-friendly slug of the contact list"),
+        search: z.string().optional().describe("Search term to filter members by name or phone number"),
+        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 (params) => {
+      try {
+        const result = await api("GET", `/contact-lists/${params.idOrSlug}/members`, undefined, {
+          search: params.search,
+          page: params.page,
+          limit: params.limit,
+        });
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_add_to_contact_list",
+    {
+      title: "Add to Contact List",
+      description: "Add one or more contacts to a list by contact ID or phone number. Phone numbers without existing contacts are auto-created as minimal contact records.",
+      inputSchema: z.object({
+        idOrSlug: z.string().describe("Unique identifier (UUID) or URL-friendly slug of the target contact list"),
+        entries: z.array(
+          z.object({
+            contactId: z.string().optional().describe("Unique identifier (UUID) of an existing contact"),
+            phone: z.string().optional().describe("Phone number in E.164 format (e.g., +2348012345678). Creates a new contact if no match exists."),
+          }),
+        ).describe("Array of contacts to add, each identified by contactId or phone number"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", `/contact-lists/${params.idOrSlug}/members`, {
+          entries: params.entries,
+        });
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_remove_from_contact_list",
+    {
+      title: "Remove from Contact List",
+      description: "Remove one or more contacts from a list by their contact IDs. Does not delete the contacts themselves.",
+      inputSchema: z.object({
+        idOrSlug: z.string().describe("Unique identifier (UUID) or URL-friendly slug of the contact list"),
+        contactIds: z.array(z.string()).describe("Array of contact UUIDs to remove from the list"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("DELETE", `/contact-lists/${params.idOrSlug}/members`, {
+          contactIds: params.contactIds,
+        });
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_merge_contact_lists",
+    {
+      title: "Merge Contact Lists",
+      description: "Merge two or more contact lists into a single unified list, deduplicating entries. Window merge creates a virtual union; materialized merge creates a static copy.",
+      inputSchema: z.object({
+        name: z.string().describe("Display name for the resulting merged list"),
+        sourceListIds: z.array(z.string()).min(2).describe("UUIDs or slugs of the source lists to merge (minimum 2)"),
+        mergeType: z.enum(["window", "materialized"]).describe("Merge strategy: 'window' (virtual union, stays in sync) or 'materialized' (static copy at merge time)"),
+        slug: z.string().optional().describe("URL-friendly slug for the merged list (auto-generated if omitted)"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", "/contact-lists/merge", params);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_find_contact_lists_for_contact",
+    {
+      title: "Find Contact Lists for Contact",
+      description: "Retrieve all contact lists that a specific contact belongs to.",
+      inputSchema: z.object({
+        contactId: z.string().describe("Unique identifier (UUID) of the contact to look up"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", `/contact-lists/by-contact/${params.contactId}`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_refresh_contact_list",
+    {
+      title: "Refresh Contact List",
+      description: "Trigger a refresh of a dynamic contact list. Re-evaluates criteria rules and/or AI prompt and materializes updated members.",
+      inputSchema: z.object({
+        idOrSlug: z.string().describe("Unique identifier (UUID) or URL-friendly slug of the dynamic list to refresh"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", `/contact-lists/${params.idOrSlug}/refresh`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+}