@ararahq/mcp 5.0.0 → 6.0.0

package/build/tools/operator.js

@@ -0,0 +1,229 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { adminRequest } from "../lib/admin.js";
+import { apiRequest } from "../lib/api.js";
+import { assertOperatorAllowed } from "../lib/operator-access.js";
+import { jsonValueSchema, pagedTemplatesSchema } from "../lib/schemas.js";
+import { execute } from "../mcp/result.js";
+import { destructive, idempotentWrite, readOnly, register as registerSharedTool, write, } from "./register.js";
+const idSchema = z.string().uuid();
+const amountSchema = z.number().positive().max(1_000_000);
+/**
+ * Listing never exposes key material: only fields on this allowlist survive,
+ * regardless of what the backend returns.
+ */
+export const safeApiKeySchema = z
+    .object({
+    id: z.string(),
+    name: z.string().optional(),
+    prefix: z.string().optional(),
+    last4: z.string().optional(),
+    maskedKey: z.string().optional(),
+    scope: z.string().optional(),
+    mode: z.string().optional(),
+    createdAt: z.string().optional(),
+    expiresAt: z.string().nullable().optional(),
+})
+    .strip();
+const walletMutationSchema = z
+    .object({ status: z.string(), organizationId: z.string(), amount: z.string() })
+    .passthrough();
+const balanceSchema = z
+    .object({ organizationId: z.string(), balance: z.union([z.number(), z.string()]) })
+    .passthrough();
+const failureBreakdownSchema = z
+    .object({
+    windowHours: z.number(),
+    totalMessages: z.number(),
+    totalFailures: z.number(),
+    byReason: z.record(z.number()),
+    byTemplate: z.record(z.number()),
+    topCodes: z.record(z.number()),
+})
+    .passthrough();
+const anyRecordSchema = z.record(jsonValueSchema);
+export const filterTemplates = (templates, filter) => {
+    if (filter === undefined || filter.length === 0)
+        return templates;
+    const needle = filter.toLowerCase();
+    return templates.filter((template) => template.name.toLowerCase().includes(needle) ||
+        template.providerStatus.toLowerCase().includes(needle) ||
+        template.category.toLowerCase().includes(needle));
+};
+/** Every operator tool runs behind the e-mail allowlist gate (fail closed). */
+const register = (server, name, description, inputSchema, annotations, handler) => {
+    registerSharedTool(server, name, description, inputSchema, annotations, handler, {
+        gate: () => assertOperatorAllowed(),
+    });
+};
+export const OPERATOR_TOOL_NAMES = [
+    "create_api_key",
+    "list_api_keys",
+    "revoke_api_key",
+    "configure_webhook_route",
+    "list_templates",
+    "delete_template",
+    "template_health",
+    "list_failures",
+    "get_balance",
+    "add_credit",
+    "remove_credit",
+    "list_transactions",
+];
+export const registerOperatorTools = (server) => {
+    register(server, "create_api_key", "Create an API key. The key value is returned ONCE in this response and can never be listed again.", {
+        name: z.string().trim().min(1).max(255),
+        mode: z.enum(["LIVE", "TEST"]).default("LIVE"),
+        scope: z.enum(["ADMIN", "SEND_ONLY"]).default("ADMIN"),
+    }, write, async (input) => execute(async () => ({
+        data: await apiRequest("/v1/api-keys", {
+            method: "POST",
+            body: { name: input.name, mode: input.mode, scope: input.scope },
+            schema: anyRecordSchema,
+            retry: false,
+        }),
+        message: "API key created. Store the key value now: it will never be shown again.",
+    })));
+    register(server, "list_api_keys", "List API keys (prefix, last4 and scope only — never the key value).", {}, readOnly, async () => execute(async () => {
+        const keys = await apiRequest("/v1/api-keys", { schema: z.array(safeApiKeySchema) });
+        return { data: keys, message: `${keys.length} API key(s) loaded.` };
+    }));
+    register(server, "revoke_api_key", "Revoke an API key permanently.", { apiKeyId: idSchema }, destructive, async (input) => execute(async () => {
+        const apiKeyId = idSchema.parse(input.apiKeyId);
+        await apiRequest(`/v1/api-keys/${apiKeyId}`, {
+            method: "DELETE",
+            schema: z.unknown(),
+        });
+        return { data: { apiKeyId, revoked: true }, message: "API key revoked." };
+    }));
+    register(server, "configure_webhook_route", "Configure the A/B template pool for an API key's webhook send route.", {
+        apiKeyId: idSchema,
+        senderNumberId: idSchema,
+        templateIds: z.array(idSchema).min(1).max(20),
+        secondarySenderNumberId: idSchema.optional(),
+    }, idempotentWrite, async (input) => execute(async () => {
+        const apiKeyId = idSchema.parse(input.apiKeyId);
+        return {
+            data: await apiRequest(`/v1/api-keys/${apiKeyId}/webhook-route`, {
+                method: "PUT",
+                body: {
+                    senderNumberId: input.senderNumberId,
+                    templateIds: input.templateIds,
+                    ...(input.secondarySenderNumberId === undefined
+                        ? {}
+                        : { secondarySenderNumberId: input.secondarySenderNumberId }),
+                },
+                schema: anyRecordSchema,
+            }),
+            message: "Webhook route configured.",
+        };
+    }));
+    register(server, "list_templates", "List templates with name, status, category and availability. Optional filter matches name, status or category.", { filter: z.string().max(100).optional() }, readOnly, async (input) => execute(async () => {
+        const templates = await apiRequest("/v1/templates?size=100", {
+            schema: pagedTemplatesSchema,
+        });
+        const filter = typeof input.filter === "string" ? input.filter : undefined;
+        const data = filterTemplates(templates, filter);
+        return { data, message: `${data.length} template(s) loaded.` };
+    }));
+    register(server, "delete_template", "Delete a template.", { templateId: idSchema }, destructive, async (input) => execute(async () => {
+        const templateId = idSchema.parse(input.templateId);
+        await apiRequest(`/v1/templates/${templateId}`, {
+            method: "DELETE",
+            schema: z.unknown(),
+        });
+        return { data: { templateId, deleted: true }, message: "Template deleted." };
+    }));
+    register(server, "template_health", "Delivery, read and failure analytics for one template.", { templateId: idSchema }, readOnly, async (input) => execute(async () => {
+        const templateId = idSchema.parse(input.templateId);
+        return {
+            data: await apiRequest(`/v1/templates/${templateId}/analytics`, {
+                schema: anyRecordSchema,
+            }),
+            message: "Template health loaded.",
+        };
+    }));
+    register(server, "list_failures", "Admin: breakdown of send failures by reason (paused / recipient / media / other) in a time window.", { organizationId: idSchema, hours: z.number().int().min(1).max(720).default(24) }, readOnly, async (input) => execute(async () => {
+        const organizationId = idSchema.parse(input.organizationId);
+        const hours = z
+            .number()
+            .int()
+            .min(1)
+            .max(720)
+            .parse(input.hours ?? 24);
+        const data = await adminRequest(`/v1/admin/diagnostics/failures?organizationId=${organizationId}&hours=${hours}`, { schema: failureBreakdownSchema });
+        return {
+            data,
+            message: `${data.totalFailures} failure(s) in the last ${data.windowHours}h.`,
+        };
+    }));
+    register(server, "get_balance", "Admin: wallet balance for an organization.", { organizationId: idSchema }, readOnly, async (input) => execute(async () => {
+        const organizationId = idSchema.parse(input.organizationId);
+        const data = await adminRequest(`/v1/admin/wallet/${organizationId}/balance`, {
+            schema: balanceSchema,
+        });
+        return { data, message: `Balance: R$ ${String(data.balance)}.` };
+    }));
+    register(server, "add_credit", "Admin: add wallet credit through the ledger. Idempotent per externalId.", {
+        organizationId: idSchema,
+        amount: amountSchema,
+        description: z.string().trim().min(1).max(255),
+        externalId: z.string().trim().min(1).max(100).optional(),
+    }, idempotentWrite, async (input) => execute(async () => {
+        const externalId = typeof input.externalId === "string" ? input.externalId : `mcp-credit-${randomUUID()}`;
+        const data = await adminRequest("/v1/admin/wallet/credit", {
+            method: "POST",
+            body: {
+                organizationId: input.organizationId,
+                amount: input.amount,
+                description: input.description,
+                externalId,
+            },
+            schema: walletMutationSchema,
+            idempotencyKey: externalId,
+        });
+        return { data: { ...data, externalId }, message: "Credit applied through the ledger." };
+    }));
+    register(server, "remove_credit", "Admin: debit wallet credit through the ledger, with a mandatory reason. Idempotent per externalId. Never leaves a negative balance unless allowNegative is explicitly true.", {
+        organizationId: idSchema,
+        amount: amountSchema,
+        reason: z.string().trim().min(1).max(255),
+        externalId: z.string().trim().min(1).max(100).optional(),
+        allowNegative: z.boolean().default(false),
+    }, idempotentWrite, async (input) => execute(async () => {
+        const externalId = typeof input.externalId === "string" ? input.externalId : `mcp-debit-${randomUUID()}`;
+        const data = await adminRequest("/v1/admin/wallet/debit", {
+            method: "POST",
+            body: {
+                organizationId: input.organizationId,
+                amount: input.amount,
+                reason: input.reason,
+                externalId,
+                allowNegative: input.allowNegative === true,
+            },
+            schema: walletMutationSchema,
+            idempotencyKey: externalId,
+        });
+        return { data: { ...data, externalId }, message: "Debit applied through the ledger." };
+    }));
+    register(server, "list_transactions", "Wallet ledger entries for the authenticated organization, newest first.", {
+        page: z.number().int().nonnegative().default(0),
+        size: z.number().int().min(1).max(100).default(50),
+    }, readOnly, async (input) => execute(async () => {
+        const page = z
+            .number()
+            .int()
+            .nonnegative()
+            .parse(input.page ?? 0);
+        const size = z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .parse(input.size ?? 50);
+        const data = await apiRequest(`/v1/wallet/transactions?page=${page}&size=${size}`, {
+            schema: anyRecordSchema,
+        });
+        return { data, message: "Wallet transactions loaded." };
+    }));
+};

package/build/tools/register.js

@@ -0,0 +1,46 @@
+import { failure, toolOutputSchema } from "../mcp/result.js";
+export const readOnly = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+export const write = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+export const idempotentWrite = { ...write, idempotentHint: true };
+export const destructive = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+/**
+ * Registers a tool with the shared output envelope. An optional [gate] runs before
+ * the handler and refuses the call through the same structured failure envelope. An
+ * optional [ui] resource URI links the tool to an MCP Apps panel.
+ */
+export const register = (server, name, description, inputSchema, annotations, handler, options = {}) => {
+    const { gate, ui } = options;
+    const wrapped = gate === undefined
+        ? handler
+        : async (input) => {
+            try {
+                await gate();
+            }
+            catch (error) {
+                return failure(error);
+            }
+            return handler(input);
+        };
+    server.registerTool(name, {
+        description,
+        inputSchema,
+        outputSchema: toolOutputSchema,
+        annotations,
+        ...(ui === undefined ? {} : { _meta: { ui: { resourceUri: ui } } }),
+    }, wrapped);
+};

package/build/tools/send.js

@@ -0,0 +1,150 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { apiRequest } from "../lib/api.js";
+import { AraraError, toAraraError } from "../lib/errors.js";
+import { E164_PATTERN, recipientLabel, resolveRecipient } from "../lib/recipients.js";
+import { messageSchema, pagedTemplatesSchema, templateStatusSchema } from "../lib/schemas.js";
+import { windowStatusSchema } from "../lib/schemas.js";
+import { execute } from "../mcp/result.js";
+import { uiResourceUri } from "../ui/resources.js";
+import { readOnly, register, write } from "./register.js";
+const WINDOW_CLOSED_CODE = "CONVERSATION_WINDOW_CLOSED";
+const APPROVED_STATUS = "APPROVED";
+const MAX_MESSAGE_LENGTH = 4096;
+const MAX_VARIABLES = 20;
+const MAX_VARIABLE_LENGTH = 1024;
+const MAX_TEMPLATE_SUGGESTIONS = 10;
+export const e164Schema = z.string().regex(E164_PATTERN, "Use E.164, for example +5511999999999.");
+export const recipientInputSchema = z.string().trim().min(1).max(255);
+export const variablesSchema = z.array(z.string().max(MAX_VARIABLE_LENGTH)).max(MAX_VARIABLES);
+const idSchema = z.string().uuid();
+export const loadApprovedTemplateNames = async () => {
+    const params = new URLSearchParams({ status: APPROVED_STATUS, size: "100" });
+    const templates = await apiRequest(`/v1/templates?${params.toString()}`, {
+        schema: pagedTemplatesSchema,
+    });
+    return templates
+        .filter((template) => template.availableForSending)
+        .map((template) => template.name);
+};
+const windowClosedError = async (label) => {
+    const approved = await loadApprovedTemplateNames().catch(() => []);
+    const hint = approved.length === 0
+        ? "There is no approved template yet. Create one with create_template."
+        : `Approved templates: ${approved.slice(0, MAX_TEMPLATE_SUGGESTIONS).join(", ")}. Send one with send_whatsapp using templateName.`;
+    return new AraraError(WINDOW_CLOSED_CODE, `The 24h window with ${label} is closed, so free text is not allowed. ${hint}`, 422, false);
+};
+const buildSendBody = (input) => {
+    const base = input.from === undefined ? {} : { sender: input.from };
+    if (input.templateName !== undefined) {
+        return {
+            ...base,
+            receiver: input.phone,
+            type: "template",
+            templateName: input.templateName,
+            variables: input.variables,
+        };
+    }
+    return { ...base, receiver: input.phone, type: "text", body: input.message };
+};
+const sendOne = async (input, label) => {
+    try {
+        return await apiRequest("/v1/messages", {
+            method: "POST",
+            body: buildSendBody(input),
+            schema: messageSchema,
+            idempotencyKey: input.idempotencyKey,
+        });
+    }
+    catch (error) {
+        const normalized = toAraraError(error);
+        if (normalized.code === WINDOW_CLOSED_CODE && input.templateName === undefined) {
+            throw await windowClosedError(label);
+        }
+        throw normalized;
+    }
+};
+const registerSendWhatsapp = (server) => {
+    register(server, "send_whatsapp", "Send one WhatsApp message to one person. Pass 'to' as a phone in any format or a saved contact name. Pass 'message' for free text (only works inside the 24h window) or 'templateName' + 'variables' for an approved template (works any time). If the window is closed the error lists your approved templates. For many people use broadcast.", {
+        to: recipientInputSchema,
+        message: z.string().trim().min(1).max(MAX_MESSAGE_LENGTH).optional(),
+        templateName: z.string().trim().min(1).optional(),
+        variables: variablesSchema.default([]),
+        from: e164Schema.optional(),
+        idempotencyKey: z.string().uuid().optional(),
+    }, write, async (input) => execute(async () => {
+        const message = typeof input.message === "string" ? input.message : undefined;
+        const templateName = typeof input.templateName === "string" ? input.templateName : undefined;
+        if ((message === undefined) === (templateName === undefined)) {
+            throw new AraraError("INVALID_INPUT", "Pass exactly one of 'message' (free text) or 'templateName' (approved template).", 400, false);
+        }
+        const recipient = await resolveRecipient(recipientInputSchema.parse(input.to));
+        const label = recipientLabel(recipient);
+        const idempotencyKey = typeof input.idempotencyKey === "string" ? input.idempotencyKey : randomUUID();
+        const data = await sendOne({
+            phone: recipient.phone,
+            variables: variablesSchema.parse(input.variables),
+            idempotencyKey,
+            ...(message === undefined ? {} : { message }),
+            ...(templateName === undefined ? {} : { templateName }),
+            ...(typeof input.from === "string" ? { from: input.from } : {}),
+        }, label);
+        return {
+            data: { ...data, recipient, idempotencyKey },
+            message: `Message to ${label} accepted (${data.status}). Check delivery with check_status.`,
+        };
+    }));
+};
+const checkMessage = async (messageId) => {
+    const data = await apiRequest(`/v1/messages/${encodeURIComponent(messageId)}`, {
+        schema: messageSchema,
+    });
+    return { data, message: `Message ${messageId}: ${data.status}.` };
+};
+const checkTemplate = async (templateId) => {
+    const data = await apiRequest(`/v1/templates/${templateId}/status`, {
+        schema: templateStatusSchema,
+    });
+    const reason = typeof data.rejectionReason === "string" && data.rejectionReason.length > 0
+        ? ` Reason: ${data.rejectionReason}`
+        : "";
+    return { data, message: `Template ${templateId}: ${data.status}.${reason}` };
+};
+const checkWindow = async (to) => {
+    const recipient = await resolveRecipient(to);
+    const result = await apiRequest("/v1/conversations/window-status", {
+        method: "POST",
+        body: { phones: [recipient.phone] },
+        schema: windowStatusSchema,
+        retry: false,
+    });
+    const [status] = result.results;
+    const isWindowOpen = status?.isWindowOpen === true;
+    const hours = typeof status?.hoursRemaining === "number" ? `${status.hoursRemaining.toFixed(1)}h left` : "";
+    const label = recipientLabel(recipient);
+    const message = isWindowOpen
+        ? `${label}: window OPEN (${hours}). Free text is allowed.`
+        : `${label}: window CLOSED. Only an approved template can be sent.`;
+    return { data: { recipient, isWindowOpen, ...status }, message };
+};
+const registerCheckStatus = (server) => {
+    register(server, "check_status", "Answer 'did it arrive?', 'can I text them now?' and 'was my template approved?'. Pass exactly one of: 'to' (phone or contact name, returns whether the 24h window is open), 'messageId' (the id returned by send_whatsapp; delivery status and cost) or 'templateId' (Meta approval status with the rejection reason).", {
+        to: recipientInputSchema.optional(),
+        messageId: z.string().trim().min(1).optional(),
+        templateId: idSchema.optional(),
+    }, readOnly, async (input) => execute(async () => {
+        const provided = ["to", "messageId", "templateId"].filter((key) => typeof input[key] === "string");
+        if (provided.length !== 1) {
+            throw new AraraError("INVALID_INPUT", "Pass exactly one of 'to', 'messageId' or 'templateId'.", 400, false);
+        }
+        if (typeof input.messageId === "string")
+            return checkMessage(input.messageId);
+        if (typeof input.templateId === "string")
+            return checkTemplate(idSchema.parse(input.templateId));
+        return checkWindow(recipientInputSchema.parse(input.to));
+    }), { ui: uiResourceUri("status") });
+};
+export const registerSendTools = (server) => {
+    registerSendWhatsapp(server);
+    registerCheckStatus(server);
+};

package/build/tools/templates.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { apiRequest } from "../lib/api.js";
+import { templateSchema } from "../lib/schemas.js";
+import { execute } from "../mcp/result.js";
+import { register, write } from "./register.js";
+import { e164Schema } from "./send.js";
+const MAX_TEMPLATE_NAME = 512;
+const MAX_TEMPLATE_BODY = 4096;
+const MAX_FOOTER = 60;
+const MAX_BUTTONS = 2;
+const DEFAULT_LANGUAGE = "pt_BR";
+const DEFAULT_HEADER_TYPE = "text";
+const buttonSchema = z.object({
+    type: z.enum(["QUICK_REPLY", "URL", "PHONE_NUMBER", "SMART_LINK", "COPY_CODE"]),
+    text: z.string().trim().min(1),
+    url: z.string().url().optional(),
+    phone: e164Schema.optional(),
+});
+const registerCreateTemplate = (server) => {
+    register(server, "create_template", "Submit a WhatsApp template for Meta approval. Needed for broadcasts and for messaging outside the 24h window. Body uses positional placeholders like 'Oi {{1}}, seu pedido {{2}} saiu'; Meta rejects bodies that are only variables. Up to 2 buttons; a SMART_LINK button gets its clicks counted in campaign_report. Track approval with check_status(templateId).", {
+        name: z
+            .string()
+            .regex(/^[a-z0-9_]+$/, "Lowercase letters, digits and underscores only.")
+            .max(MAX_TEMPLATE_NAME),
+        category: z.enum(["MARKETING", "UTILITY", "AUTHENTICATION"]),
+        body: z.string().trim().min(1).max(MAX_TEMPLATE_BODY),
+        language: z.string().default(DEFAULT_LANGUAGE),
+        header: z.string().trim().min(1).optional(),
+        headerType: z.enum(["text", "media", "document"]).optional(),
+        footer: z.string().trim().min(1).max(MAX_FOOTER).optional(),
+        samples: z.record(z.string()).optional(),
+        buttons: z.array(buttonSchema).max(MAX_BUTTONS).optional(),
+    }, write, async (input) => execute(async () => {
+        const header = typeof input.header === "string"
+            ? {
+                header: input.header,
+                headerType: typeof input.headerType === "string" ? input.headerType : DEFAULT_HEADER_TYPE,
+            }
+            : {};
+        const data = await apiRequest("/v1/templates", {
+            method: "POST",
+            body: {
+                name: input.name,
+                category: input.category,
+                body: input.body,
+                language: input.language,
+                ...header,
+                ...(typeof input.footer === "string" ? { footer: input.footer } : {}),
+                ...(input.samples === undefined ? {} : { samples: input.samples }),
+                ...(input.buttons === undefined ? {} : { buttons: input.buttons }),
+            },
+            schema: templateSchema,
+            retry: false,
+        });
+        return {
+            data,
+            message: `Template '${data.name}' submitted (${data.providerStatus}). Approval usually takes minutes; check with check_status(templateId: "${data.id}").`,
+        };
+    }));
+};
+export const registerTemplateTools = (server) => {
+    registerCreateTemplate(server);
+};