@ararahq/mcp 5.0.0 → 6.0.0

package/README.md

@@ -1,19 +1,44 @@
 # AraraHQ MCP
 
-Official Model Context Protocol server for operating AraraHQ Atendimento across support, billing and scheduling.
+Official Model Context Protocol server for AraraHQ: talk to your whole WhatsApp base, see what came back, answer who replied.
 
-Version 5 is a clean break from the legacy CPaaS-oriented server. Node.js is the only canonical implementation, OAuth is the authentication boundary, and both the npm scope and public repository are owned by AraraHQ: [`@ararahq/mcp`](https://www.npmjs.com/package/@ararahq/mcp) and [`ararahq/mcp`](https://github.com/ararahq/mcp).
+Node.js is the only implementation, OAuth is the authentication boundary, and both the npm scope and public repository are owned by AraraHQ: [`@ararahq/mcp`](https://www.npmjs.com/package/@ararahq/mcp) and [`ararahq/mcp`](https://github.com/ararahq/mcp).
 
 ## What it exposes
 
-- Atendimento: today queue, paginated conversation discovery and timeline, claim, reply and close.
-- Automations: list and inspect configured automations.
-- Campaigns: preflight and idempotent publication tied to a published Atendimento routine.
-- WhatsApp operations: single-message send, delivery lookup, templates, contacts and opt-outs.
-- Context: organization, operational health, approved templates, channels and coverage.
+Nine tools, on purpose. An agent works better with a few actions that accept what a person knows by heart (a name, a phone in any format) and resolve the rest.
+
+| Tool                | What it does                                                                                                         |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `whoami`            | Who is authenticated, which organization sends, plan and wallet balance.                                             |
+| `send_whatsapp`     | One message to one person: free text inside the 24h window, or an approved template with variables any time.         |
+| `broadcast`         | One approved template to up to 1000 people as a campaign. Dry run by default (preview and cost), A/B and scheduling. |
+| `campaign_report`   | Recent campaigns, or the full report of one: sent, delivered, read, clicked, replied, converted, blocked, cost.      |
+| `check_status`      | Did it arrive? Is the 24h window open? Was the template approved?                                                    |
+| `create_template`   | Submit a template for Meta approval, with header, footer, samples and up to 2 buttons.                               |
+| `save_contacts`     | Create or update up to 1000 contacts so you can message by name.                                                     |
+| `opt_out`           | Record that someone asked to stop. Every later send to them is blocked.                                              |
+| `read_conversation` | The raw message timeline with one person, newest first, so you can judge a reply before answering.                   |
+
+Resources (`arara://organization`, `arara://templates/approved`, `arara://campaigns/recent`, `arara://channels`) give read-only context without a tool call. Prompts `plan_broadcast`, `campaign_review` and `reply_to_responses` package the three everyday flows and always stop for approval before a write.
 
 Every tool returns both human-readable content and stable structured content. Write tools carry MCP safety annotations. Credentials never appear in tool inputs or output.
 
+Operator tools (`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`) exist for the AraraHQ team only and are gated server-side by an e-mail allowlist and an admin secret.
+
+## Panels (MCP Apps)
+
+Four tools ship an interactive panel that hosts with MCP Apps support (Claude Desktop, claude.ai, ChatGPT, VS Code) render inline. Every panel reads the same structured content the text fallback uses, so clients without panel support lose nothing.
+
+| Tool                | Panel                                                                                        |
+| ------------------- | -------------------------------------------------------------------------------------------- |
+| `campaign_report`   | Funnel with animated bars, headline numbers, block reasons, live refresh while sending.      |
+| `broadcast`         | Phone mockup of the rendered message, audience and cost, approve button, then live delivery. |
+| `check_status`      | Delivery timeline (accepted, sent, delivered, read) that polls until a final state.          |
+| `read_conversation` | Chat thread with an inline reply box that calls `send_whatsapp`.                             |
+
+Panels are single-file HTML bundles built by `scripts/build-ui.mjs` into `build/ui/` and served as `ui://arara/<panel>.html` resources with the `text/html;profile=mcp-app` MIME type. They call tools through the host (`callServerTool`) and hand follow-ups back to the chat (`sendMessage`); they never hold credentials.
+
 ## Local installation
 
 Requires Node.js 20 or newer.
@@ -67,11 +92,14 @@ Protected Resource Metadata is served at:
 
 AraraHQ currently issues installed-client OAuth tokens through its device authorization flow. Hosted clients must supply a valid AraraHQ OAuth bearer token; the MCP does not proxy credentials or mint tokens.
 
-## Tool catalog
-
-`whoami`, `get_today`, `find_conversations`, `get_conversation`, `reply_to_conversation`, `claim_conversation`, `close_conversation`, `list_automations`, `get_automation`, `prepare_campaign`, `publish_campaign`, `send_whatsapp`, `check_message`, `save_contacts`, `create_template`, `get_template_status`, `opt_out`.
+## Behavior worth knowing
 
-Campaign publication validates that the Meta template is approved and available, and that its destination routine (`support`, `billing` or `scheduling`) is published. Message acceptance is reported as queued—not delivered—and delivery is checked separately.
+- `to` accepts a phone in any spelling or a saved contact name. Brazilian numbers get `+55` and the ninth digit when missing. An ambiguous name fails with the candidates instead of guessing.
+- Free text outside the 24h window is refused by Meta. `send_whatsapp` turns that refusal into a list of your approved templates.
+- `broadcast` never drops recipients silently: names that do not resolve are returned next to the campaign id.
+- Message acceptance means queued, not delivered. Delivery is checked with `check_status`.
+- Every mutating call carries an `Idempotency-Key`, so retries are safe.
+- `broadcast` is a dry run unless `dryRun` is false. The preview resolves names, renders the template with the first contact's variables and calls the cost estimator, so approval happens with the real numbers.
 
 ## Development
 
@@ -84,7 +112,7 @@ npm pack --dry-run
 
 The server defaults to stdio. Use `MCP_TRANSPORT=http npm start` for Streamable HTTP. Override the API only for controlled environments with `ARARA_API_URL`.
 
-The former unscoped package `ararahq-mcp` is the frozen v4 distribution. New installations and every v5 release use `@ararahq/mcp`.
+The former unscoped package `ararahq-mcp` is the frozen v4 distribution. Version 5 was an Atendimento-oriented rewrite that never matched the product; version 6 is the broadcast-first server described here.
 
 ## Security
 

package/build/cli.js

@@ -4,6 +4,7 @@ import { requestDeviceCode, pollForToken, openBrowser } from "./auth/device-flow
 import { clearToken, loadToken } from "./auth/token-store.js";
 import { identitySchema } from "./lib/schemas.js";
 import { TOOL_NAMES } from "./tools/index.js";
+import { OPERATOR_TOOL_NAMES } from "./tools/operator.js";
 const log = (message) => {
     process.stdout.write(`${message}\n`);
 };
@@ -61,6 +62,7 @@ export const runCli = async (command) => {
     }
     if (command === "tools") {
         TOOL_NAMES.forEach(log);
+        OPERATOR_TOOL_NAMES.forEach(log);
         return true;
     }
     if (command === "--version" || command === "-v") {

package/build/config.js

@@ -1,8 +1,8 @@
 export const SERVER_NAME = "ararahq-mcp";
-export const SERVER_VERSION = "5.0.0";
+export const SERVER_VERSION = "6.0.0";
 export const DEFAULT_API_BASE_URL = "https://api.ararahq.com/api";
 export const OAUTH_CLIENT_ID = "ararahq-mcp";
-export const OAUTH_SCOPE = "openid profile organization:read atendimento:read atendimento:write campaigns:write";
+export const OAUTH_SCOPE = "openid profile organization:read messages:write campaigns:read campaigns:write contacts:write templates:write";
 export const API_TIMEOUT_MS = 10_000;
 export const MAX_RETRIES = 2;
 export const MAX_PAGE_SIZE = 100;

package/build/lib/admin.js

@@ -0,0 +1,23 @@
+import { apiRequest } from "./api.js";
+import { AraraError } from "./errors.js";
+const requireAdminSecret = () => {
+    const secret = process.env.ARARA_ADMIN_SECRET;
+    if (typeof secret !== "string" || secret.length === 0) {
+        throw new AraraError("ADMIN_NOT_CONFIGURED", "Admin-gated tools require ARARA_ADMIN_SECRET in the MCP server environment.", 403, false);
+    }
+    return secret;
+};
+/**
+ * Thin wrapper over apiRequest for /v1/admin/** endpoints: the session Bearer token
+ * satisfies the hasRole(ADMIN) gate in SecurityConfig, and X-Admin-Secret is the
+ * second layer checked by the controller. The secret lives only in the server
+ * process environment and is attached as a header — never in inputs, outputs or
+ * error messages. Retry/backoff and Idempotency-Key come from apiRequest.
+ */
+export const adminRequest = async (path, options) => apiRequest(path, {
+    body: options.body,
+    schema: options.schema,
+    extraHeaders: { "X-Admin-Secret": requireAdminSecret() },
+    ...(options.method === undefined ? {} : { method: options.method }),
+    ...(options.idempotencyKey === undefined ? {} : { idempotencyKey: options.idempotencyKey }),
+});

package/build/lib/api.js

@@ -23,6 +23,7 @@ export const apiRequest = async (path, options) => {
                     ...(options.idempotencyKey === undefined
                         ? {}
                         : { "Idempotency-Key": options.idempotencyKey }),
+                    ...options.extraHeaders,
                 },
             });
             const parsed = options.schema.safeParse(response.data);

package/build/lib/errors.js

@@ -13,6 +13,17 @@ export class AraraError extends Error {
         this.name = "AraraError";
     }
 }
+const DEFAULT_CODES = {
+    401: "UNAUTHENTICATED",
+    403: "FORBIDDEN",
+    404: "NOT_FOUND",
+    429: "RATE_LIMITED",
+};
+const DEFAULT_MESSAGES = {
+    401: "OAuth authentication is required or has expired.",
+    403: "This account is not allowed to do that.",
+    404: "The requested resource does not exist in this organization.",
+};
 const parseRetryAfter = (value) => {
     if (typeof value !== "string" || value.length === 0)
         return undefined;
@@ -34,16 +45,10 @@ export const toAraraError = (error) => {
     const nested = typeof candidate.error === "object" && candidate.error !== null
         ? candidate.error
         : candidate;
-    const code = typeof nested.code === "string"
-        ? nested.code
-        : status === 429
-            ? "RATE_LIMITED"
-            : "UPSTREAM_ERROR";
+    const code = typeof nested.code === "string" ? nested.code : (DEFAULT_CODES[status] ?? "UPSTREAM_ERROR");
     const message = typeof nested.message === "string"
         ? nested.message
-        : status === 401
-            ? "OAuth authentication is required or has expired."
-            : "AraraHQ API request failed.";
+        : (DEFAULT_MESSAGES[status] ?? "AraraHQ API request failed.");
     const retryAfterSeconds = parseRetryAfter(error.response?.headers["retry-after"]);
     return new AraraError(code, message, status, status === 429 || status >= 500, retryAfterSeconds);
 };

package/build/lib/operator-access.js

@@ -0,0 +1,26 @@
+import { apiRequest } from "./api.js";
+import { AraraError } from "./errors.js";
+import { identitySchema } from "./schemas.js";
+/**
+ * Operator tools are gated by an e-mail allowlist held only in the server process
+ * environment (ARARA_OPERATOR_EMAILS, comma-separated). Fail closed: with the
+ * variable unset or empty, every operator tool is refused.
+ *
+ * The identity is fetched per call, never cached at module level: the HTTP
+ * transport serves concurrent requests from different accounts in one process,
+ * so a process-wide cache would let one caller ride another caller's identity.
+ */
+export const getAllowedOperatorEmails = (raw = process.env.ARARA_OPERATOR_EMAILS) => (raw ?? "")
+    .split(",")
+    .map((email) => email.trim().toLowerCase())
+    .filter((email) => email.length > 0);
+export const assertOperatorAllowed = async () => {
+    const allowed = getAllowedOperatorEmails();
+    if (allowed.length === 0) {
+        throw new AraraError("OPERATOR_NOT_CONFIGURED", "Operator tools require ARARA_OPERATOR_EMAILS in the MCP server environment.", 403, false);
+    }
+    const identity = await apiRequest("/auth/me", { schema: identitySchema });
+    if (!allowed.includes(identity.email.toLowerCase())) {
+        throw new AraraError("OPERATOR_NOT_ALLOWED", "The authenticated account is not allowed to use operator tools.", 403, false);
+    }
+};

package/build/lib/recipients.js

@@ -0,0 +1,67 @@
+import { apiRequest } from "./api.js";
+import { AraraError } from "./errors.js";
+import { contactsListSchema } from "./schemas.js";
+const BRAZIL_COUNTRY_CODE = "55";
+const BRAZIL_LANDLINE_LENGTH = 10;
+const BRAZIL_MOBILE_LENGTH = 11;
+const BRAZIL_MOBILE_PREFIX = "9";
+const CONTACT_LOOKUP_SIZE = 5;
+const PHONE_PATTERN = /^[+(\d][\d\s().-]{7,}$/;
+export const E164_PATTERN = /^\+[1-9]\d{6,14}$/;
+export const looksLikePhone = (value) => PHONE_PATTERN.test(value.trim());
+/**
+ * Normalizes any human phone spelling into E.164. Brazilian numbers without the
+ * country code get +55, and 10-digit Brazilian mobiles get the ninth digit.
+ */
+export const normalizePhone = (raw) => {
+    const digits = raw.replace(/\D/g, "");
+    const hasCountryCode = raw.trim().startsWith("+") || digits.length >= 12;
+    if (hasCountryCode)
+        return withBrazilianNinthDigit(digits);
+    if (digits.length === BRAZIL_LANDLINE_LENGTH || digits.length === BRAZIL_MOBILE_LENGTH) {
+        return `+${BRAZIL_COUNTRY_CODE}${digits}`;
+    }
+    return `+${digits}`;
+};
+const withBrazilianNinthDigit = (digits) => {
+    if (!digits.startsWith(BRAZIL_COUNTRY_CODE))
+        return `+${digits}`;
+    const local = digits.slice(BRAZIL_COUNTRY_CODE.length);
+    if (local.length !== BRAZIL_LANDLINE_LENGTH)
+        return `+${digits}`;
+    const areaCode = local.slice(0, 2);
+    const rest = local.slice(2);
+    return `+${BRAZIL_COUNTRY_CODE}${areaCode}${BRAZIL_MOBILE_PREFIX}${rest}`;
+};
+export const recipientLabel = (recipient) => recipient.name === undefined ? recipient.phone : `${recipient.phone} (${recipient.name})`;
+/**
+ * Resolves a phone in any format or a saved contact name into one E.164 recipient.
+ * Ambiguous names fail loudly with the candidates instead of guessing.
+ */
+export const resolveRecipient = async (to) => {
+    const trimmed = to.trim();
+    if (looksLikePhone(trimmed)) {
+        const phone = normalizePhone(trimmed);
+        if (!E164_PATTERN.test(phone)) {
+            throw new AraraError("INVALID_PHONE", `'${trimmed}' is not a valid phone number.`, 400, false);
+        }
+        return { phone };
+    }
+    const params = new URLSearchParams({ q: trimmed, page: "0", size: String(CONTACT_LOOKUP_SIZE) });
+    const result = await apiRequest(`/v1/contacts?${params.toString()}`, {
+        schema: contactsListSchema,
+    });
+    const matches = result.contacts.filter((contact) => contact.phone.length > 0);
+    if (matches.length === 0) {
+        throw new AraraError("CONTACT_NOT_FOUND", `No saved contact named '${trimmed}'. Pass the phone number or save the contact first.`, 404, false);
+    }
+    if (matches.length > 1) {
+        const options = matches.map((contact) => `${contact.name} (${contact.phone})`).join(", ");
+        throw new AraraError("CONTACT_AMBIGUOUS", `'${trimmed}' matches more than one contact: ${options}. Use the phone number.`, 409, false);
+    }
+    const [match] = matches;
+    if (match === undefined) {
+        throw new AraraError("CONTACT_NOT_FOUND", `No saved contact named '${trimmed}'.`, 404, false);
+    }
+    return { phone: normalizePhone(match.phone), name: match.name };
+};

package/build/lib/schemas.js

@@ -11,109 +11,142 @@ export const identitySchema = z
     .object({ name: z.string(), email: z.string().email() })
     .passthrough();
 export const planSchema = z.record(jsonValueSchema);
+export const balanceSchema = z.record(jsonValueSchema);
+export const mutationSchema = z.record(jsonValueSchema);
 export const paginationSchema = z.object({
     page: z.number().int().nonnegative(),
     size: z.number().int().positive(),
     totalElements: z.number().int().nonnegative(),
     totalPages: z.number().int().nonnegative(),
 });
-export const inboxRowSchema = z
+export const templateSchema = z
     .object({
     id: z.string(),
-    customerPhone: z.string(),
-    customerName: z.string().nullable().optional(),
+    name: z.string(),
+    formattedName: z.string().optional(),
+    category: z.string(),
+    language: z.string(),
+    providerStatus: z.string(),
+    rejectionReason: z.string().nullable().optional(),
+    availableForSending: z.boolean(),
+    bodyPreview: z.string().nullable().optional(),
+    structureJson: jsonValueSchema.optional(),
+})
+    .passthrough();
+export const templatesSchema = z.array(templateSchema);
+export const pagedTemplatesSchema = z
+    .object({ data: templatesSchema, pagination: paginationSchema })
+    .transform(({ data }) => data);
+export const templateStatusSchema = z
+    .object({
     status: z.string(),
-    lastInteractionAt: z.string().nullable().optional(),
-    windowExpiresAt: z.string().nullable().optional(),
-    isWindowOpen: z.boolean(),
-    leadSummary: z.string().nullable().optional(),
-    originatingCampaignId: z.string().nullable().optional(),
-    routineKey: z.string(),
-    stage: z.string().nullable().optional(),
-    nextStep: z.string().nullable().optional(),
-    slaDueAt: z.string().nullable().optional(),
-    overdue: z.boolean(),
-    ownerId: z.string().nullable().optional(),
-    ownerName: z.string().nullable().optional(),
-    claimedAt: z.string().nullable().optional(),
-    lastMessagePreview: z.string().nullable().optional(),
-    lastMessageDirection: z.string().nullable().optional(),
+    rejectionReason: z.string().nullable().optional(),
+    category: z.string().nullable().optional(),
 })
     .passthrough();
-export const pagedInboxSchema = z
+export const messageSchema = z
     .object({
-    content: z.array(inboxRowSchema),
-    page: z.number().int().nonnegative(),
-    size: z.number().int().positive(),
-    totalElements: z.number().int().nonnegative(),
-    totalPages: z.number().int().nonnegative(),
-    waiting: z.number().int().nonnegative(),
-    attention: z.number().int().nonnegative(),
-    unassigned: z.number().int().nonnegative(),
+    id: z.string().nullable(),
+    status: z.string(),
+    receiver: z.string(),
+    cost: z.number().nullable().optional(),
+    reason: z.string().nullable().optional(),
 })
-    .transform(({ content, page, size, totalElements, totalPages, waiting, attention, unassigned }) => ({
-    data: content,
-    pagination: { page, size, totalElements, totalPages },
-    summary: { waiting, attention, unassigned },
-}));
-export const todaySchema = z.record(jsonValueSchema);
-export const coverageSchema = z.record(jsonValueSchema);
-export const routineSchema = z
-    .object({ key: z.string(), name: z.string().optional(), published: z.boolean() })
     .passthrough();
-export const routinesSchema = z.array(routineSchema);
-export const messageSchema = z.object({ id: z.string().nullable() }).passthrough();
-export const pagedMessagesSchema = z
+export const windowStatusSchema = z.object({
+    results: z.array(z
+        .object({
+        phone: z.string(),
+        isWindowOpen: z.boolean(),
+        hoursRemaining: z.number().nullable().optional(),
+    })
+        .passthrough()),
+});
+export const contactSchema = z.object({ name: z.string(), phone: z.string() }).passthrough();
+export const contactsListSchema = z
+    .object({ contacts: z.array(contactSchema), total: z.number().int().nonnegative() })
+    .passthrough();
+export const contactsBatchSchema = z
     .object({
-    content: z.array(messageSchema),
-    page: z.number().int().nonnegative(),
-    size: z.number().int().positive(),
-    totalElements: z.number().int().nonnegative(),
-    totalPages: z.number().int().nonnegative(),
+    created: z.number().int().nonnegative(),
+    updated: z.number().int().nonnegative(),
+    skipped: z.number().int().nonnegative(),
+    errors: z
+        .array(z
+        .object({
+        index: z.number().int(),
+        phone: z.string().nullable().optional(),
+        reason: z.string(),
+    })
+        .passthrough())
+        .default([]),
 })
-    .transform(({ content, page, size, totalElements, totalPages }) => ({
-    data: content,
-    pagination: { page, size, totalElements, totalPages },
-}));
-export const mutationSchema = z.record(jsonValueSchema);
-export const automationSchema = z
+    .passthrough();
+export const conversationMessageSchema = z
     .object({
-    id: z.string(),
-    name: z.string(),
-    trigger: z.string(),
-    triggerConfig: jsonValueSchema,
-    active: z.boolean(),
-    steps: z.array(z.object({ type: z.string(), config: jsonValueSchema }).passthrough()),
-    costPerRunBrl: z.number(),
-    stats: jsonValueSchema.optional(),
-    webhookUrl: z.string().nullable().optional(),
+    direction: z.string(),
+    status: z.string(),
+    templateName: z.string().nullable().optional(),
+    body: z.string().nullable().optional(),
+    createdAt: z.string(),
 })
     .passthrough();
-export const automationsSchema = z.array(automationSchema);
-export const templateSchema = z
+export const conversationSchema = z
+    .object({
+    phone: z.string(),
+    total: z.number().int().nonnegative(),
+    messages: z.array(conversationMessageSchema),
+})
+    .passthrough();
+export const campaignSchema = z
     .object({
     id: z.string(),
     name: z.string(),
-    formattedName: z.string().optional(),
-    category: z.string(),
-    language: z.string(),
-    providerStatus: z.string(),
-    availableForSending: z.boolean(),
+    status: z.string(),
+    totalMessages: z.number().int().nonnegative(),
+    totalCost: z.number(),
+    scheduledAt: z.string().nullable().optional(),
 })
     .passthrough();
-export const templatesSchema = z.array(templateSchema);
+export const campaignListItemSchema = campaignSchema.extend({
+    templateName: z.string(),
+    sentCount: z.number().int().nonnegative(),
+    deliveredCount: z.number().int().nonnegative(),
+    readCount: z.number().int().nonnegative(),
+    failedCount: z.number().int().nonnegative(),
+    createdAt: z.string().nullable().optional(),
+});
+export const campaignListSchema = z
+    .object({
+    content: z.array(campaignListItemSchema),
+    totalPages: z.number().int().nonnegative(),
+    totalElements: z.number().int().nonnegative(),
+})
+    .transform(({ content, totalPages, totalElements }) => ({
+    data: content,
+    pagination: { totalPages, totalElements },
+}));
+export const campaignDetailSchema = campaignListItemSchema.extend({
+    clickedCount: z.number().int().nonnegative(),
+    replyCount: z.number().int().nonnegative().default(0),
+    convertedCount: z.number().int().nonnegative(),
+    convertedValue: z.number(),
+    holdoutCount: z.number().int().nonnegative().default(0),
+    blockedCount: z.number().int().nonnegative().default(0),
+    blockReasons: z.array(z.object({ motivo: z.string(), quantidade: z.number() })).default([]),
+    refundCount: z.number().int().nonnegative().default(0),
+    refundValue: z.number().default(0),
+});
 export const numberSchema = z.record(jsonValueSchema);
 export const numbersSchema = z.object({
     numbers: z.array(numberSchema),
     slot: jsonValueSchema.nullable().optional(),
 });
-export const campaignSchema = z
+export const campaignEstimateSchema = z
     .object({
-    id: z.string(),
-    name: z.string(),
-    status: z.string(),
-    totalMessages: z.number().int().nonnegative(),
+    templateCategory: z.string(),
+    recipientCount: z.number().int().nonnegative(),
+    unitPrice: z.number(),
     totalCost: z.number(),
-    scheduledAt: z.string().nullable().optional(),
 })
     .passthrough();

package/build/lib/templates.js

@@ -0,0 +1,27 @@
+const URL_ACTION = "URL";
+const isRecord = (value) => typeof value === "object" && value !== null;
+const firstTypeContent = (structure) => {
+    if (!isRecord(structure) || !isRecord(structure.types))
+        return undefined;
+    const first = Object.values(structure.types)[0];
+    return isRecord(first) ? first : undefined;
+};
+/** Button labels of a template, in order, read from the provider structure JSON. */
+export const templateButtonLabels = (structure) => {
+    const content = firstTypeContent(structure);
+    const actions = content?.actions;
+    if (!Array.isArray(actions))
+        return [];
+    return actions.flatMap((action) => isRecord(action) && typeof action.title === "string" ? [action.title] : []);
+};
+/** True when at least one button carries a dynamic URL that needs a variable. */
+export const hasDynamicUrlButton = (structure) => {
+    const content = firstTypeContent(structure);
+    const actions = content?.actions;
+    if (!Array.isArray(actions))
+        return false;
+    return actions.some((action) => isRecord(action) &&
+        action.type === URL_ACTION &&
+        typeof action.url === "string" &&
+        /\{\{\d+\}\}/.test(action.url));
+};

package/build/prompts/index.js

@@ -2,8 +2,7 @@ const prompt = (text) => ({
     messages: [{ role: "user", content: { type: "text", text } }],
 });
 export const registerAllPrompts = (server) => {
-    server.registerPrompt("triage_today", { description: "Prioritize today's Atendimento queue without taking write actions." }, () => prompt("Read arara://operation/health, call get_today, and propose a prioritized queue. Show overdue items, unowned conversations, stage, owner, next step and SLA. Do not claim, reply or close anything without explicit confirmation."));
-    server.registerPrompt("draft_reply", { description: "Draft a grounded reply for one conversation." }, () => prompt("Use find_conversations and get_conversation to understand the selected case. Draft a concise reply consistent with the current stage and next step. Do not call reply_to_conversation until the user explicitly approves the exact text."));
-    server.registerPrompt("campaign_preflight", { description: "Review a campaign before publication." }, () => prompt("Call prepare_campaign. Verify the approved template, published Atendimento routine, coverage, audience, variables and schedule. Present the final payload and risks. Do not call publish_campaign without explicit confirmation."));
-    server.registerPrompt("close_case_review", { description: "Check whether a conversation is ready to close." }, () => prompt("Load the conversation timeline and its metadata. Confirm owner, outcome, next step and any promised follow-up. Recommend closure only when no unresolved obligation remains. Do not call close_conversation without explicit confirmation."));
+    server.registerPrompt("plan_broadcast", { description: "Prepare a broadcast and ask for approval before sending." }, () => prompt("Call whoami to confirm the organization and balance. Read arara://templates/approved and pick the template that fits the goal, or propose one with create_template if none fits. Call broadcast in its default dry-run mode to render the message, resolve the audience and estimate the cost, and show that preview. Only call broadcast with dryRun=false after the user explicitly approves."));
+    server.registerPrompt("campaign_review", { description: "Read the results of a campaign and say what to do next." }, () => prompt("Call campaign_report without an id to find the campaign, then with its id for the full report. Summarize delivery, reads, clicks, replies and conversions as percentages of the audience, explain blocked and refunded rows, and recommend one next action: reply to responders, re-send to the unread with another template, or stop."));
+    server.registerPrompt("reply_to_responses", { description: "Answer people who replied to a broadcast." }, () => prompt("Use read_conversation to read what the person wrote. Draft a short reply consistent with the campaign and the conversation so far. If they asked to stop, call opt_out instead of replying. Do not call send_whatsapp until the user approves the exact text."));
 };

package/build/resources/index.js

@@ -1,8 +1,8 @@
 import { apiRequest } from "../lib/api.js";
-import { coverageSchema, identitySchema, numbersSchema, planSchema, routineSchema, templatesSchema, todaySchema, } from "../lib/schemas.js";
-import { z } from "zod";
+import { balanceSchema, campaignListSchema, identitySchema, numbersSchema, pagedTemplatesSchema, planSchema, } from "../lib/schemas.js";
+const RECENT_CAMPAIGNS_SIZE = 10;
+const APPROVED_STATUS = "APPROVED";
 const json = (value) => JSON.stringify(value, null, 2);
-const routinesResponseSchema = z.object({ data: z.array(routineSchema) });
 const registerJsonResource = (server, name, uri, title, description, loader) => {
     server.registerResource(name, uri, { title, description, mimeType: "application/json" }, async (resourceUri) => {
         try {
@@ -32,29 +32,27 @@ const registerJsonResource = (server, name, uri, title, description, loader) =>
     });
 };
 export const registerAllResources = (server) => {
-    registerJsonResource(server, "organization", "arara://organization", "Organization", "Authenticated identity and current AraraHQ plan.", async () => {
-        const [identity, plan] = await Promise.all([
+    registerJsonResource(server, "organization", "arara://organization", "Organization", "Authenticated identity, current plan and wallet balance.", async () => {
+        const [identity, plan, balance] = await Promise.all([
             apiRequest("/auth/me", { schema: identitySchema }),
             apiRequest("/v1/organizations/me/plan", { schema: planSchema }),
+            apiRequest("/dashboard/wallet/balance", { schema: balanceSchema }),
         ]);
-        return { identity, plan };
+        return { identity, plan, balance };
     });
-    registerJsonResource(server, "operation_health", "arara://operation/health", "Operation health", "Today, channel health and published Atendimento routines.", async () => {
-        const [today, numbers, routines] = await Promise.all([
-            apiRequest("/v1/operation/today", { schema: todaySchema }),
-            apiRequest("/v1/organizations/me/numbers", { schema: numbersSchema }),
-            apiRequest("/v1/operation/routines", { schema: routinesResponseSchema }),
-        ]);
-        return {
-            today,
-            channels: numbers,
-            publishedRoutines: routines.data.filter((routine) => routine.published),
-        };
+    registerJsonResource(server, "approved_templates", "arara://templates/approved", "Approved templates", "Templates Meta currently allows for sending. Use their names in broadcast and send_whatsapp.", 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);
     });
-    registerJsonResource(server, "approved_templates", "arara://templates/approved", "Approved templates", "Templates that Meta currently allows for sending.", async () => {
-        const templates = await apiRequest("/v1/templates", { schema: templatesSchema });
-        return templates.filter((template) => template.providerStatus === "APPROVED" && template.availableForSending);
+    registerJsonResource(server, "recent_campaigns", "arara://campaigns/recent", "Recent campaigns", "Latest broadcasts with status, counts and cost.", async () => {
+        const params = new URLSearchParams({ page: "0", size: String(RECENT_CAMPAIGNS_SIZE) });
+        const result = await apiRequest(`/v1/campaigns?${params.toString()}`, {
+            schema: campaignListSchema,
+        });
+        return result.data;
     });
-    registerJsonResource(server, "channels", "arara://channels", "WhatsApp channels", "Configured numbers and slot state for this organization.", () => apiRequest("/v1/organizations/me/numbers", { schema: numbersSchema }));
-    registerJsonResource(server, "coverage", "arara://coverage", "Service coverage", "Working hours and after-hours policy for Atendimento.", () => apiRequest("/v1/operation/coverage", { schema: coverageSchema }));
+    registerJsonResource(server, "channels", "arara://channels", "WhatsApp numbers", "Configured sending numbers and slot state for this organization.", () => apiRequest("/v1/organizations/me/numbers", { schema: numbersSchema }));
 };

package/build/server/create.js

@@ -3,10 +3,14 @@ import { SERVER_NAME, SERVER_VERSION } from "../config.js";
 import { registerAllPrompts } from "../prompts/index.js";
 import { registerAllResources } from "../resources/index.js";
 import { registerAllTools } from "../tools/index.js";
+import { registerOperatorTools } from "../tools/operator.js";
+import { registerUiResources } from "../ui/resources.js";
 export const createServer = () => {
     const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
     registerAllTools(server);
+    registerOperatorTools(server);
     registerAllResources(server);
+    registerUiResources(server);
     registerAllPrompts(server);
     return server;
 };