neuron-mcp-server 1.0.0 → 1.1.0

package/src/tools/contacts.ts

@@ -0,0 +1,395 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult, getAuthToken, getBaseUrl } from "../client.js";
+
+export function registerContactsTools(server: McpServer): void {
+  // List contacts
+  server.registerTool(
+    "neuron_list_contacts",
+    {
+      title: "List Contacts",
+      description: "Retrieve all contacts for the current organization with optional filtering by search term, tag, and pagination.",
+      inputSchema: z.object({
+        search: z.string().optional().describe("Search term to filter contacts by name, phone number, or email address"),
+        tag: z.string().optional().describe("Tag name to filter contacts by category"),
+        doNotBroadcast: z.boolean().optional().describe("Filter to contacts that are (true) or are not (false) excluded from broadcasts"),
+        doNotAutoRespond: z.boolean().optional().describe("Filter to contacts the bot will never (true) / may (false) auto-respond to"),
+        page: z.number().int().positive().optional().describe("Page number for pagination (default: 1)"),
+        limit: z.number().int().positive().optional().describe("Number of contacts per page (default: 20)"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", "/contacts", undefined, {
+          search: params.search,
+          tag: params.tag,
+          doNotBroadcast: params.doNotBroadcast === undefined ? undefined : String(params.doNotBroadcast),
+          doNotAutoRespond: params.doNotAutoRespond === undefined ? undefined : String(params.doNotAutoRespond),
+          page: params.page,
+          limit: params.limit,
+        });
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Search contacts
+  server.registerTool(
+    "neuron_search_contacts",
+    {
+      title: "Search Contacts",
+      description: "Search contacts by a query string across name, phone number, and email fields. Returns matching contacts ranked by relevance.",
+      inputSchema: z.object({
+        q: z.string().describe("Search query string to match against contact name, phone, or email"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", "/contacts/search", undefined, { q: params.q });
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Get contact
+  server.registerTool(
+    "neuron_get_contact",
+    {
+      title: "Get Contact",
+      description: "Retrieve detailed information about a specific contact including their tags, notes, and associated lists.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the contact"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", `/contacts/${params.id}`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Create contact
+  server.registerTool(
+    "neuron_create_contact",
+    {
+      title: "Create Contact",
+      description: "Create a new contact in the organization's address book. If notes are provided, they are saved as a structured note entry with source tracking.",
+      inputSchema: z.object({
+        name: z.string().describe("Full name of the contact"),
+        phone: z.string().describe("Contact phone number in E.164 format (e.g., +2348012345678)"),
+        email: z.string().optional().describe("Email address of the contact"),
+        tags: z.array(z.string()).optional().describe("Tags to categorize the contact (e.g., ['vendor', 'lagos'])"),
+        notes: z.string().optional().describe("Additional notes about the contact, saved as a structured entry"),
+        doNotBroadcast: z.boolean().optional().describe("If true, this contact is permanently excluded from all broadcasts"),
+        doNotAutoRespond: z.boolean().optional().describe("If true, the bot will never auto-respond to this contact (manual/API and human sends still work)"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", "/contacts", params);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Update contact
+  server.registerTool(
+    "neuron_update_contact",
+    {
+      title: "Update Contact",
+      description: "Update an existing contact's details. If notes are provided, they are appended as a new structured note entry without overwriting existing notes.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the contact to update"),
+        name: z.string().optional().describe("Updated full name for the contact"),
+        phone: z.string().optional().describe("Updated phone number in E.164 format (e.g., +2348012345678)"),
+        email: z.string().optional().describe("Updated email address for the contact"),
+        tags: z.array(z.string()).optional().describe("Updated tags for the contact (replaces existing tags)"),
+        notes: z.string().optional().describe("New note to append to the contact's existing notes"),
+        doNotBroadcast: z.boolean().optional().describe("Set true to exclude this contact from all broadcasts, false to allow"),
+        doNotAutoRespond: z.boolean().optional().describe("Set true so the bot never auto-responds to this contact, false to allow (manual/API and human sends are unaffected either way)"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const { id, ...body } = params;
+        const result = await api("PUT", `/contacts/${id}`, body);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Delete contact
+  server.registerTool(
+    "neuron_delete_contact",
+    {
+      title: "Delete Contact",
+      description: "Permanently delete a contact and remove them from all contact lists. This action cannot be undone.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the contact to delete"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("DELETE", `/contacts/${params.id}`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Export contacts
+  server.registerTool(
+    "neuron_export_contacts",
+    {
+      title: "Export Contacts",
+      description: "Export all contacts as a downloadable dataset for the current organization.",
+      inputSchema: z.object({}),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async () => {
+      try {
+        const result = await api("GET", "/contacts/export");
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Import contacts
+  server.registerTool(
+    "neuron_import_contacts",
+    {
+      title: "Import Contacts",
+      description: "Bulk import multiple contacts into the organization's address book. Accepts an array of contact objects with name, phone, and optional fields.",
+      inputSchema: z.object({
+        contacts: z.array(z.object({
+          name: z.string().describe("Full name of the contact"),
+          phone: z.string().describe("Contact phone number in E.164 format (e.g., +2348012345678)"),
+          email: z.string().optional().describe("Email address of the contact"),
+          tags: z.array(z.string()).optional().describe("Tags to categorize the contact"),
+          notes: z.string().optional().describe("Additional notes about the contact"),
+        })).describe("Array of contact objects to import into the organization"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", "/contacts/import", { contacts: params.contacts });
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Populate contacts
+  server.registerTool(
+    "neuron_populate_contacts",
+    {
+      title: "Populate Contacts",
+      description: "Enrich existing contacts with additional data from connected messaging channels. Syncs profile information from linked platforms.",
+      inputSchema: z.object({}),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async () => {
+      try {
+        const result = await api("POST", "/contacts/populate");
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Sync WhatsApp contacts
+  server.registerTool(
+    "neuron_sync_whatsapp_contacts",
+    {
+      title: "Sync WhatsApp Contacts",
+      description: "Synchronize contacts from all connected WhatsApp channels into the organization's contact database. Creates new contacts for unseen numbers.",
+      inputSchema: z.object({}),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async () => {
+      try {
+        const result = await api("POST", "/contacts/sync-whatsapp");
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Semantic search contacts
+  server.registerTool(
+    "neuron_semantic_search_contacts",
+    {
+      title: "Semantic Search Contacts",
+      description:
+        "Search contacts using natural language AI-powered semantic search. Finds contacts based on the meaning of their notes — skills, services, schedules, preferences, etc. Returns ranked results with relevance scores and AI-generated match reasons.",
+      inputSchema: z.object({
+        query: z.string().describe("Natural language search query (e.g., 'who can deliver to Lagos on Monday?')"),
+        limit: z.number().int().positive().max(20).optional().describe("Maximum number of results to return (default: 10, max: 20)"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const queryParams: Record<string, string | number> = { q: params.query };
+        if (params.limit) queryParams.limit = params.limit;
+        const result = await api("GET", "/contacts/semantic-search", undefined, queryParams);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Audio-to-contact extraction
+  server.registerTool(
+    "neuron_audio_contact",
+    {
+      title: "Extract Contact from Audio",
+      description:
+        "Transcribe an audio recording and extract contact information (name, phone, email, notes, tags). " +
+        "Automatically saves the extracted contact to the organization's address book.",
+      inputSchema: z.object({
+        audioBase64: z.string().describe("Base64-encoded audio data containing spoken contact information"),
+        audioFormat: z
+          .string()
+          .optional()
+          .default("webm")
+          .describe("Audio format hint for decoding (default: 'webm')"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        // Decode base64 to buffer and create a File-like object for the API
+        const buffer = Buffer.from(params.audioBase64, "base64");
+        const blob = new Blob([buffer], { type: `audio/${params.audioFormat || "webm"}` });
+
+        // Create FormData and send to extract-audio endpoint
+        const formData = new FormData();
+        formData.append("audio", blob, `recording.${params.audioFormat || "webm"}`);
+
+        // Use raw fetch since api() doesn't handle FormData
+        const response = await fetch(`${getBaseUrl()}/contacts/extract-audio`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${getAuthToken()}`,
+          },
+          body: formData,
+        });
+
+        const extractResult: any = await response.json();
+        if (!extractResult.success || extractResult.data?.extracted?.error) {
+          return errorResult(
+            new Error(extractResult.data?.extracted?.error || extractResult.error?.message || "Extraction failed"),
+          );
+        }
+
+        const { extracted, transcript } = extractResult.data;
+
+        // Auto-save the contact
+        const saveResult = await api("POST", "/contacts", {
+          name: extracted.name,
+          phone: extracted.phone,
+          email: extracted.email,
+          tags: extracted.tags || [],
+          notes: extracted.notes,
+        });
+
+        return jsonResult({
+          success: true,
+          data: {
+            transcript,
+            extracted,
+            contact: (saveResult as any).data,
+          },
+        });
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+}