@ararahq/mcp 5.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Arara Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# AraraHQ MCP
+
+Official Model Context Protocol server for operating AraraHQ Atendimento across support, billing and scheduling.
+
+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).
+
+## 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.
+
+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.
+
+## Local installation
+
+Requires Node.js 20 or newer.
+
+```bash
+npx -y @ararahq/mcp login
+npx -y @ararahq/mcp status
+```
+
+The device authorization flow opens AraraHQ in the browser. Access and refresh tokens are stored in the operating-system keychain, never in a project file or client configuration.
+
+Configure an MCP client with stdio:
+
+```json
+{
+  "mcpServers": {
+    "ararahq": {
+      "command": "npx",
+      "args": ["-y", "@ararahq/mcp", "--stdio"]
+    }
+  }
+}
+```
+
+Useful diagnostics:
+
+```bash
+npx -y @ararahq/mcp doctor
+npx -y @ararahq/mcp tools
+npx -y @ararahq/mcp logout
+```
+
+## Hosted transport
+
+The hosted server uses stateless MCP Streamable HTTP at `POST /mcp`. It accepts OAuth bearer tokens only in the `Authorization` header. Query-string credentials, API-key tool arguments, legacy SSE endpoints, permissive CORS and debug endpoints do not exist.
+
+```bash
+MCP_TRANSPORT=http \
+PORT=3333 \
+MCP_PUBLIC_URL=https://mcp.ararahq.com/mcp \
+MCP_ALLOWED_HOSTS=mcp.ararahq.com \
+MCP_ALLOWED_ORIGINS=https://chatgpt.com,https://claude.ai \
+ARARA_OAUTH_ISSUER=https://api.ararahq.com/api \
+npm start
+```
+
+Protected Resource Metadata is served at:
+
+- `/.well-known/oauth-protected-resource`
+- `/.well-known/oauth-protected-resource/mcp`
+
+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`.
+
+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.
+
+## Development
+
+```bash
+npm ci
+npm run check
+npm audit --omit=dev
+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`.
+
+## Security
+
+- OAuth tokens remain server-side and are redacted by design.
+- External HTTP requests have explicit timeouts.
+- Retries are limited to safe methods or requests carrying an idempotency key and honor `Retry-After`.
+- All consumed API payloads are validated before fields are used.
+- Hosted requests are rate-limited and checked against explicit host and origin allowlists.
+- No telemetry is collected by this package.
+
+Report vulnerabilities privately to `security@ararahq.com`.
+
+## License
+
+MIT © AraraHQ

package/build/auth/context.js

@@ -0,0 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+export const runWithAccessToken = (accessToken, task) => storage.run({ accessToken }, task);
+export const getRequestAccessToken = () => storage.getStore()?.accessToken;

package/build/auth/device-flow.js

@@ -0,0 +1,75 @@
+import axios from "axios";
+import { spawn } from "node:child_process";
+import { z } from "zod";
+import { API_TIMEOUT_MS, getApiBaseUrl, OAUTH_CLIENT_ID, OAUTH_SCOPE } from "../config.js";
+import { saveToken } from "./token-store.js";
+const deviceCodeSchema = z.object({
+    deviceCode: z.string(),
+    userCode: z.string(),
+    verificationUri: z.string().url(),
+    verificationUriComplete: z.string().url().optional(),
+    expiresIn: z.number().positive(),
+    interval: z.number().positive(),
+});
+const tokenSchema = z.object({
+    accessToken: z.string(),
+    refreshToken: z.string().optional(),
+    expiresIn: z.number().positive().optional(),
+});
+const wait = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+export const requestDeviceCode = async () => {
+    const response = await axios.post(`${getApiBaseUrl()}/oauth/device/code`, { clientId: OAUTH_CLIENT_ID, scope: OAUTH_SCOPE }, { timeout: API_TIMEOUT_MS });
+    return deviceCodeSchema.parse(response.data);
+};
+export const pollForToken = async (code) => {
+    const deadline = Date.now() + code.expiresIn * 1_000;
+    let interval = Math.max(2_000, code.interval * 1_000);
+    while (Date.now() < deadline) {
+        await wait(interval);
+        try {
+            const response = await axios.post(`${getApiBaseUrl()}/oauth/device/token`, { clientId: OAUTH_CLIENT_ID, deviceCode: code.deviceCode }, { timeout: API_TIMEOUT_MS });
+            const token = tokenSchema.parse(response.data);
+            await saveToken({
+                accessToken: token.accessToken,
+                ...(token.refreshToken === undefined ? {} : { refreshToken: token.refreshToken }),
+                ...(token.expiresIn === undefined
+                    ? {}
+                    : { expiresAt: Date.now() + token.expiresIn * 1_000 }),
+            });
+            return;
+        }
+        catch (error) {
+            if (!axios.isAxiosError(error))
+                throw error;
+            const payload = error.response?.data;
+            const record = typeof payload === "object" && payload !== null ? payload : {};
+            const nested = typeof record.error === "object" && record.error !== null
+                ? record.error
+                : record;
+            const codeValue = typeof nested.code === "string"
+                ? nested.code
+                : typeof record.error === "string"
+                    ? record.error
+                    : "";
+            if (codeValue === "authorization_pending")
+                continue;
+            if (codeValue === "slow_down") {
+                interval += 2_000;
+                continue;
+            }
+            if (codeValue === "access_denied")
+                throw new Error("OAuth login was denied.");
+            if (codeValue === "expired_token")
+                throw new Error("OAuth login expired. Run login again.");
+            throw new Error("OAuth token polling failed.");
+        }
+    }
+    throw new Error("OAuth login timed out. Run login again.");
+};
+export const openBrowser = (url) => {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.on("error", () => undefined);
+    child.unref();
+};

package/build/auth/token-store.js

@@ -0,0 +1,28 @@
+import keytar from "keytar";
+const SERVICE = "ararahq-mcp";
+const ACCESS = "oauth-access-token";
+const REFRESH = "oauth-refresh-token";
+const EXPIRES = "oauth-expires-at";
+export const saveToken = async (token) => {
+    await keytar.setPassword(SERVICE, ACCESS, token.accessToken);
+    if (token.refreshToken)
+        await keytar.setPassword(SERVICE, REFRESH, token.refreshToken);
+    if (token.expiresAt !== undefined)
+        await keytar.setPassword(SERVICE, EXPIRES, String(token.expiresAt));
+};
+export const loadToken = async () => {
+    const accessToken = await keytar.getPassword(SERVICE, ACCESS);
+    if (!accessToken)
+        return null;
+    const refreshToken = await keytar.getPassword(SERVICE, REFRESH);
+    const expiresRaw = await keytar.getPassword(SERVICE, EXPIRES);
+    const expiresAt = expiresRaw === null ? undefined : Number(expiresRaw);
+    return {
+        accessToken,
+        ...(refreshToken === null ? {} : { refreshToken }),
+        ...(expiresAt === undefined || !Number.isFinite(expiresAt) ? {} : { expiresAt }),
+    };
+};
+export const clearToken = async () => {
+    await Promise.all([ACCESS, REFRESH, EXPIRES].map((account) => keytar.deletePassword(SERVICE, account)));
+};

package/build/auth/tokens.js

@@ -0,0 +1,39 @@
+import axios from "axios";
+import { getApiBaseUrl, API_TIMEOUT_MS, OAUTH_CLIENT_ID } from "../config.js";
+import { getRequestAccessToken } from "./context.js";
+import { loadToken, saveToken } from "./token-store.js";
+const isRefreshResponse = (value) => {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return (typeof record.accessToken === "string" &&
+        (record.refreshToken === undefined || typeof record.refreshToken === "string") &&
+        (record.expiresIn === undefined || typeof record.expiresIn === "number"));
+};
+export const getAccessToken = async () => {
+    const contextual = getRequestAccessToken();
+    if (contextual)
+        return contextual;
+    const stored = await loadToken();
+    if (!stored)
+        throw new Error("OAuth login required. Run `ararahq-mcp login`.");
+    if (stored.expiresAt === undefined || stored.expiresAt > Date.now() + 30_000)
+        return stored.accessToken;
+    if (!stored.refreshToken)
+        throw new Error("OAuth session expired. Run `ararahq-mcp login` again.");
+    const response = await axios.post(`${getApiBaseUrl()}/oauth/token/refresh`, {
+        clientId: OAUTH_CLIENT_ID,
+        refreshToken: stored.refreshToken,
+    }, { timeout: API_TIMEOUT_MS });
+    if (!isRefreshResponse(response.data))
+        throw new Error("OAuth server returned an invalid refresh response.");
+    const refreshed = response.data;
+    await saveToken({
+        accessToken: refreshed.accessToken,
+        refreshToken: refreshed.refreshToken ?? stored.refreshToken,
+        ...(refreshed.expiresIn === undefined
+            ? {}
+            : { expiresAt: Date.now() + refreshed.expiresIn * 1_000 }),
+    });
+    return refreshed.accessToken;
+};

package/build/cli.js

@@ -0,0 +1,71 @@
+import axios from "axios";
+import { API_TIMEOUT_MS, getApiBaseUrl, SERVER_VERSION } from "./config.js";
+import { requestDeviceCode, pollForToken, openBrowser } from "./auth/device-flow.js";
+import { clearToken, loadToken } from "./auth/token-store.js";
+import { identitySchema } from "./lib/schemas.js";
+import { TOOL_NAMES } from "./tools/index.js";
+const log = (message) => {
+    process.stdout.write(`${message}\n`);
+};
+const login = async () => {
+    const code = await requestDeviceCode();
+    const url = code.verificationUriComplete ??
+        `${code.verificationUri}?code=${encodeURIComponent(code.userCode)}`;
+    log(`Authorize AraraHQ MCP at:\n${url}\nCode: ${code.userCode}`);
+    openBrowser(url);
+    await pollForToken(code);
+    log("OAuth login complete. Tokens are stored in the operating-system keychain.");
+};
+const status = async () => {
+    const token = await loadToken();
+    if (!token) {
+        log("Not authenticated. Run `ararahq-mcp login`.");
+        return;
+    }
+    try {
+        const response = await axios.get(`${getApiBaseUrl()}/auth/me`, {
+            headers: { Authorization: `Bearer ${token.accessToken}` },
+            timeout: API_TIMEOUT_MS,
+        });
+        const identity = identitySchema.parse(response.data);
+        log(`Authenticated as ${identity.name} (${identity.email}).`);
+    }
+    catch {
+        log("A token exists, but the OAuth session could not be validated. Run `ararahq-mcp login` again.");
+        process.exitCode = 1;
+    }
+};
+const doctor = async () => {
+    log(`AraraHQ MCP ${SERVER_VERSION}`);
+    log(`Node ${process.versions.node}: ${Number(process.versions.node.split(".")[0]) >= 20 ? "ok" : "requires >=20"}`);
+    log(`API: ${getApiBaseUrl()}`);
+    await status();
+};
+export const runCli = async (command) => {
+    if (command === "login") {
+        await login();
+        return true;
+    }
+    if (command === "logout") {
+        await clearToken();
+        log("OAuth tokens removed from the system keychain.");
+        return true;
+    }
+    if (command === "status") {
+        await status();
+        return true;
+    }
+    if (command === "doctor") {
+        await doctor();
+        return true;
+    }
+    if (command === "tools") {
+        TOOL_NAMES.forEach(log);
+        return true;
+    }
+    if (command === "--version" || command === "-v") {
+        log(SERVER_VERSION);
+        return true;
+    }
+    return false;
+};

package/build/config.js

@@ -0,0 +1,17 @@
+export const SERVER_NAME = "ararahq-mcp";
+export const SERVER_VERSION = "5.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 API_TIMEOUT_MS = 10_000;
+export const MAX_RETRIES = 2;
+export const MAX_PAGE_SIZE = 100;
+export const getApiBaseUrl = () => (process.env.ARARA_API_URL ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
+export const getHttpPort = () => {
+    const raw = process.env.PORT ?? "3333";
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65_535) {
+        throw new Error("PORT must be an integer between 1 and 65535.");
+    }
+    return parsed;
+};

package/build/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { runCli } from "./cli.js";
+import { runHttp } from "./transports/http.js";
+import { runStdio } from "./transports/stdio.js";
+const main = async () => {
+    const command = process.argv[2];
+    if (command && (await runCli(command)))
+        return;
+    const useHttp = process.env.MCP_TRANSPORT === "http" ||
+        (process.env.PORT !== undefined && !process.argv.includes("--stdio"));
+    if (useHttp)
+        await runHttp();
+    else
+        await runStdio();
+};
+if (process.env.NODE_ENV !== "test") {
+    main().catch((error) => {
+        const message = error instanceof Error ? error.message : "Unknown startup error";
+        process.stderr.write(`AraraHQ MCP failed: ${message}\n`);
+        process.exitCode = 1;
+    });
+}

package/build/lib/api.js

@@ -0,0 +1,45 @@
+import axios from "axios";
+import { API_TIMEOUT_MS, getApiBaseUrl, MAX_RETRIES } from "../config.js";
+import { getAccessToken } from "../auth/tokens.js";
+import { AraraError, toAraraError } from "./errors.js";
+const wait = async (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+const canRetry = (method, idempotencyKey) => ["GET", "HEAD", "PUT", "DELETE", "OPTIONS"].includes(method.toUpperCase()) ||
+    idempotencyKey !== undefined;
+export const apiRequest = async (path, options) => {
+    const token = await getAccessToken();
+    const method = options.method ?? "GET";
+    const retryAllowed = (options.retry ?? true) && canRetry(method, options.idempotencyKey);
+    let attempt = 0;
+    while (true) {
+        try {
+            const response = await axios.request({
+                baseURL: getApiBaseUrl(),
+                url: path,
+                method,
+                data: options.body,
+                timeout: API_TIMEOUT_MS,
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    ...(options.idempotencyKey === undefined
+                        ? {}
+                        : { "Idempotency-Key": options.idempotencyKey }),
+                },
+            });
+            const parsed = options.schema.safeParse(response.data);
+            if (!parsed.success) {
+                throw new AraraError("INVALID_API_RESPONSE", "AraraHQ API returned an unexpected response.", 502, false);
+            }
+            return parsed.data;
+        }
+        catch (error) {
+            const normalized = toAraraError(error);
+            if (!retryAllowed || !normalized.retryable || attempt >= MAX_RETRIES)
+                throw normalized;
+            const delay = normalized.retryAfterSeconds !== undefined
+                ? normalized.retryAfterSeconds * 1_000
+                : 250 * 2 ** attempt + Math.floor(Math.random() * 100);
+            attempt += 1;
+            await wait(Math.min(delay, 10_000));
+        }
+    }
+};

package/build/lib/errors.js

@@ -0,0 +1,49 @@
+import axios from "axios";
+export class AraraError extends Error {
+    code;
+    status;
+    retryable;
+    retryAfterSeconds;
+    constructor(code, message, status, retryable, retryAfterSeconds) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.retryable = retryable;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "AraraError";
+    }
+}
+const parseRetryAfter = (value) => {
+    if (typeof value !== "string" || value.length === 0)
+        return undefined;
+    const seconds = Number.parseInt(value, 10);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds);
+    const date = Date.parse(value);
+    return Number.isNaN(date) ? undefined : Math.max(0, Math.ceil((date - Date.now()) / 1_000));
+};
+export const toAraraError = (error) => {
+    if (error instanceof AraraError)
+        return error;
+    if (!axios.isAxiosError(error)) {
+        return new AraraError("INTERNAL_ERROR", "The MCP server could not complete the request.", 500, false);
+    }
+    const status = error.response?.status ?? 503;
+    const payload = error.response?.data;
+    const candidate = typeof payload === "object" && payload !== null ? payload : {};
+    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 message = typeof nested.message === "string"
+        ? nested.message
+        : status === 401
+            ? "OAuth authentication is required or has expired."
+            : "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/schemas.js

@@ -0,0 +1,119 @@
+import { z } from "zod";
+export const jsonValueSchema = z.lazy(() => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema),
+    z.record(jsonValueSchema),
+]));
+export const identitySchema = z
+    .object({ name: z.string(), email: z.string().email() })
+    .passthrough();
+export const planSchema = 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
+    .object({
+    id: z.string(),
+    customerPhone: z.string(),
+    customerName: z.string().nullable().optional(),
+    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(),
+})
+    .passthrough();
+export const pagedInboxSchema = 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(),
+})
+    .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
+    .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(),
+})
+    .transform(({ content, page, size, totalElements, totalPages }) => ({
+    data: content,
+    pagination: { page, size, totalElements, totalPages },
+}));
+export const mutationSchema = z.record(jsonValueSchema);
+export const automationSchema = 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(),
+})
+    .passthrough();
+export const automationsSchema = z.array(automationSchema);
+export const templateSchema = z
+    .object({
+    id: z.string(),
+    name: z.string(),
+    formattedName: z.string().optional(),
+    category: z.string(),
+    language: z.string(),
+    providerStatus: z.string(),
+    availableForSending: z.boolean(),
+})
+    .passthrough();
+export const templatesSchema = z.array(templateSchema);
+export const numberSchema = z.record(jsonValueSchema);
+export const numbersSchema = z.object({
+    numbers: z.array(numberSchema),
+    slot: jsonValueSchema.nullable().optional(),
+});
+export const campaignSchema = z
+    .object({
+    id: z.string(),
+    name: z.string(),
+    status: z.string(),
+    totalMessages: z.number().int().nonnegative(),
+    totalCost: z.number(),
+    scheduledAt: z.string().nullable().optional(),
+})
+    .passthrough();

package/build/mcp/result.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { toAraraError } from "../lib/errors.js";
+export const toolOutputSchema = {
+    ok: z.boolean(),
+    data: z.unknown().optional(),
+    error: z
+        .object({
+        code: z.string(),
+        message: z.string(),
+        retryable: z.boolean(),
+        retryAfterSeconds: z.number().optional(),
+    })
+        .optional(),
+};
+export const success = (data, message) => ({
+    content: [{ type: "text", text: message }],
+    structuredContent: { ok: true, data },
+});
+export const failure = (error) => {
+    const normalized = toAraraError(error);
+    const details = {
+        code: normalized.code,
+        message: normalized.message,
+        retryable: normalized.retryable,
+        ...(normalized.retryAfterSeconds === undefined
+            ? {}
+            : { retryAfterSeconds: normalized.retryAfterSeconds }),
+    };
+    return {
+        isError: true,
+        content: [{ type: "text", text: `${details.code}: ${details.message}` }],
+        structuredContent: { ok: false, error: details },
+    };
+};
+export const execute = async (task) => {
+    try {
+        const result = await task();
+        return success(result.data, result.message);
+    }
+    catch (error) {
+        return failure(error);
+    }
+};

package/build/prompts/index.js

@@ -0,0 +1,9 @@
+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."));
+};

package/build/resources/index.js

@@ -0,0 +1,60 @@
+import { apiRequest } from "../lib/api.js";
+import { coverageSchema, identitySchema, numbersSchema, planSchema, routineSchema, templatesSchema, todaySchema, } from "../lib/schemas.js";
+import { z } from "zod";
+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 {
+            return {
+                contents: [
+                    {
+                        uri: resourceUri.toString(),
+                        mimeType: "application/json",
+                        text: json(await loader()),
+                    },
+                ],
+            };
+        }
+        catch {
+            return {
+                contents: [
+                    {
+                        uri: resourceUri.toString(),
+                        mimeType: "application/json",
+                        text: json({
+                            error: { code: "RESOURCE_UNAVAILABLE", message: "Resource could not be loaded." },
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+};
+export const registerAllResources = (server) => {
+    registerJsonResource(server, "organization", "arara://organization", "Organization", "Authenticated identity and current AraraHQ plan.", async () => {
+        const [identity, plan] = await Promise.all([
+            apiRequest("/auth/me", { schema: identitySchema }),
+            apiRequest("/v1/organizations/me/plan", { schema: planSchema }),
+        ]);
+        return { identity, plan };
+    });
+    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 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, "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 }));
+};

package/build/server/create.js

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+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";
+export const createServer = () => {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    registerAllTools(server);
+    registerAllResources(server);
+    registerAllPrompts(server);
+    return server;
+};

package/build/tools/index.js

@@ -0,0 +1,284 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { MAX_PAGE_SIZE } from "../config.js";
+import { apiRequest } from "../lib/api.js";
+import { AraraError } from "../lib/errors.js";
+import { automationSchema, automationsSchema, campaignSchema, coverageSchema, identitySchema, jsonValueSchema, messageSchema, mutationSchema, pagedInboxSchema, pagedMessagesSchema, planSchema, routineSchema, templateSchema, templatesSchema, todaySchema, } from "../lib/schemas.js";
+import { execute, toolOutputSchema } from "../mcp/result.js";
+const readOnly = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+const write = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+const idempotentWrite = { ...write, idempotentHint: true };
+const destructive = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+const idSchema = z.string().uuid();
+const e164Schema = z.string().regex(/^\+[1-9]\d{6,14}$/, "Use E.164, for example +5511999999999.");
+const routineKeySchema = z.enum(["support", "billing", "scheduling"]);
+const routinesResponseSchema = z.object({ data: z.array(routineSchema) });
+const register = (server, name, description, inputSchema, annotations, handler) => {
+    server.registerTool(name, { description, inputSchema, outputSchema: toolOutputSchema, annotations }, handler);
+};
+export const TOOL_NAMES = [
+    "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",
+];
+export const registerAllTools = (server) => {
+    register(server, "whoami", "Return the authenticated AraraHQ identity and organization plan.", {}, readOnly, async () => execute(async () => {
+        const [identity, plan] = await Promise.all([
+            apiRequest("/auth/me", { schema: identitySchema }),
+            apiRequest("/v1/organizations/me/plan", { schema: planSchema }),
+        ]);
+        return {
+            data: { identity, plan },
+            message: `Authenticated as ${identity.name} (${identity.email}).`,
+        };
+    }));
+    register(server, "get_today", "Return today's Atendimento queue across support, billing and scheduling.", {}, readOnly, async () => execute(async () => ({
+        data: await apiRequest("/v1/operation/today", { schema: todaySchema }),
+        message: "Today's operation loaded.",
+    })));
+    register(server, "find_conversations", "Find Atendimento conversations with stable pagination. Use this before selecting a conversation.", {
+        filter: z.string().max(100).optional(),
+        page: z.number().int().nonnegative().default(0),
+        size: z.number().int().min(1).max(MAX_PAGE_SIZE).default(50),
+    }, readOnly, async (input) => execute(async () => {
+        const params = new URLSearchParams({ page: String(input.page), size: String(input.size) });
+        if (typeof input.filter === "string" && input.filter.length > 0)
+            params.set("filter", input.filter);
+        const data = await apiRequest(`/v1/operation/inbox?${params.toString()}`, {
+            schema: pagedInboxSchema,
+        });
+        return { data, message: `${data.data.length} conversation(s) loaded.` };
+    }));
+    register(server, "get_conversation", "Load a paginated message timeline. Conversation metadata comes from find_conversations.", {
+        conversationId: idSchema,
+        page: z.number().int().nonnegative().default(0),
+        size: z.number().int().min(1).max(MAX_PAGE_SIZE).default(50),
+    }, readOnly, async (input) => execute(async () => {
+        const conversationId = idSchema.parse(input.conversationId);
+        const page = z.number().int().nonnegative().parse(input.page);
+        const size = z.number().int().min(1).max(MAX_PAGE_SIZE).parse(input.size);
+        const data = await apiRequest(`/v1/conversations/${conversationId}/messages?page=${page}&size=${size}`, { schema: pagedMessagesSchema });
+        return {
+            data: { conversationId, ...data },
+            message: `${data.data.length} message(s) loaded.`,
+        };
+    }));
+    register(server, "reply_to_conversation", "Reply inside an Atendimento conversation. Accepted means queued, not delivered.", {
+        conversationId: idSchema,
+        body: z.string().trim().min(1).max(4096),
+    }, write, async (input) => execute(async () => ({
+        data: await apiRequest("/v1/conversations/reply", {
+            method: "POST",
+            body: input,
+            schema: mutationSchema,
+            retry: false,
+        }),
+        message: "Reply accepted and queued for delivery.",
+    })));
+    register(server, "claim_conversation", "Assign an unowned conversation to the authenticated operator.", { conversationId: idSchema }, idempotentWrite, async (input) => execute(async () => {
+        const conversationId = idSchema.parse(input.conversationId);
+        return {
+            data: await apiRequest(`/v1/operation/inbox/${conversationId}/claim`, {
+                method: "POST",
+                body: {},
+                schema: mutationSchema,
+                retry: false,
+            }),
+            message: "Conversation claimed.",
+        };
+    }));
+    register(server, "close_conversation", "Close a conversation after its outcome and next step are resolved.", { conversationId: idSchema }, destructive, async (input) => execute(async () => {
+        const conversationId = idSchema.parse(input.conversationId);
+        return {
+            data: await apiRequest(`/v1/conversations/${conversationId}/status`, {
+                method: "PATCH",
+                body: { status: "CLOSED" },
+                schema: mutationSchema,
+            }),
+            message: "Conversation closed.",
+        };
+    }));
+    register(server, "list_automations", "List configured automations.", {}, readOnly, async () => execute(async () => {
+        const data = await apiRequest("/v1/automations", { schema: automationsSchema });
+        return { data, message: `${data.length} automation(s) loaded.` };
+    }));
+    register(server, "get_automation", "Inspect an automation's trigger, steps, cost and status.", { automationId: idSchema }, readOnly, async (input) => execute(async () => {
+        const automationId = idSchema.parse(input.automationId);
+        const data = await apiRequest(`/v1/automations/${automationId}`, {
+            schema: automationSchema,
+        });
+        return { data, message: `Automation ${data.name} loaded.` };
+    }));
+    register(server, "prepare_campaign", "Load campaign preflight: guidance, published Atendimento routines, approved templates and coverage.", {}, readOnly, async () => execute(async () => {
+        const [copilot, routines, templates, coverage] = await Promise.all([
+            apiRequest("/v1/operation/copilot/campaign", { schema: z.record(jsonValueSchema) }),
+            apiRequest("/v1/operation/routines", { schema: routinesResponseSchema }),
+            apiRequest("/v1/templates", { schema: templatesSchema }),
+            apiRequest("/v1/operation/coverage", { schema: coverageSchema }),
+        ]);
+        return {
+            data: {
+                copilot,
+                coverage,
+                publishedRoutines: routines.data.filter((routine) => routine.published),
+                approvedTemplates: templates.filter((template) => template.providerStatus === "APPROVED" && template.availableForSending),
+            },
+            message: "Campaign preflight loaded. Review it before publishing.",
+        };
+    }));
+    const campaignContactSchema = z.object({
+        to: e164Schema,
+        variables: z.array(z.string().max(1024)).max(20).default([]),
+    });
+    register(server, "publish_campaign", "Publish a template campaign after validating its template and Atendimento destination routine.", {
+        name: z.string().trim().min(1).max(255),
+        templateName: z.string().trim().min(1),
+        routineKey: routineKeySchema,
+        contacts: z.array(campaignContactSchema).min(1).max(1000),
+        sender: e164Schema.optional(),
+        scheduledAt: z.string().datetime().optional(),
+        idempotencyKey: z.string().uuid().optional(),
+    }, write, async (input) => execute(async () => {
+        const [routines, templates] = await Promise.all([
+            apiRequest("/v1/operation/routines", { schema: routinesResponseSchema }),
+            apiRequest("/v1/templates", { schema: templatesSchema }),
+        ]);
+        const routineKey = routineKeySchema.parse(input.routineKey);
+        if (!routines.data.some((routine) => routine.key === routineKey && routine.published)) {
+            throw new AraraError("ROUTINE_NOT_PUBLISHED", `Atendimento routine '${routineKey}' is not published.`, 409, false);
+        }
+        if (!templates.some((template) => template.name === input.templateName &&
+            template.providerStatus === "APPROVED" &&
+            template.availableForSending)) {
+            throw new AraraError("TEMPLATE_NOT_AVAILABLE", `Template '${String(input.templateName)}' is not approved and available.`, 409, false);
+        }
+        const idempotencyKey = typeof input.idempotencyKey === "string" ? input.idempotencyKey : randomUUID();
+        const data = await apiRequest("/v1/campaigns", {
+            method: "POST",
+            body: {
+                name: input.name,
+                templateName: input.templateName,
+                routineKey,
+                contacts: input.contacts,
+                ...(input.sender === undefined ? {} : { sender: input.sender }),
+                ...(input.scheduledAt === undefined ? {} : { scheduledAt: input.scheduledAt }),
+            },
+            schema: campaignSchema,
+            idempotencyKey,
+        });
+        return {
+            data: { ...data, idempotencyKey },
+            message: `Campaign '${data.name}' accepted with ${data.totalMessages} message(s).`,
+        };
+    }));
+    register(server, "send_whatsapp", "Send one WhatsApp text message to an E.164 number. Accepted means queued, not delivered.", {
+        to: e164Schema,
+        message: z.string().trim().min(1).max(4096),
+        from: e164Schema.optional(),
+        idempotencyKey: z.string().uuid().optional(),
+    }, write, async (input) => execute(async () => {
+        const idempotencyKey = typeof input.idempotencyKey === "string" ? input.idempotencyKey : randomUUID();
+        const data = await apiRequest("/v1/messages", {
+            method: "POST",
+            body: {
+                receiver: input.to,
+                body: input.message,
+                type: "text",
+                ...(input.from === undefined ? {} : { sender: input.from }),
+            },
+            schema: messageSchema,
+            idempotencyKey,
+        });
+        return {
+            data: { ...data, idempotencyKey },
+            message: `Message ${data.id ?? "accepted"} queued. Use check_message to verify delivery.`,
+        };
+    }));
+    register(server, "check_message", "Check the provider delivery state for a message.", { messageId: idSchema }, readOnly, async (input) => execute(async () => {
+        const messageId = idSchema.parse(input.messageId);
+        return {
+            data: await apiRequest(`/v1/messages/${messageId}`, { schema: mutationSchema }),
+            message: "Message status loaded.",
+        };
+    }));
+    const contactSchema = z.object({
+        name: z.string().trim().min(1).max(255),
+        phone: e164Schema,
+        email: z.string().email().max(255).optional(),
+        attributes: z.record(jsonValueSchema).optional(),
+    });
+    register(server, "save_contacts", "Create or update contacts in one batch.", { contacts: z.array(contactSchema).min(1).max(1000) }, idempotentWrite, async (input) => execute(async () => ({
+        data: await apiRequest("/v1/contacts/batch", {
+            method: "POST",
+            body: input.contacts,
+            schema: mutationSchema,
+            retry: false,
+        }),
+        message: "Contact batch processed.",
+    })));
+    register(server, "create_template", "Submit a WhatsApp template for Meta approval.", {
+        name: z
+            .string()
+            .regex(/^[a-z0-9_]+$/)
+            .max(512),
+        category: z.enum(["MARKETING", "UTILITY", "AUTHENTICATION"]),
+        body: z.string().trim().min(1).max(4096),
+        language: z.string().default("pt_BR"),
+        footer: z.string().max(60).optional(),
+    }, write, async (input) => execute(async () => ({
+        data: await apiRequest("/v1/templates", {
+            method: "POST",
+            body: input,
+            schema: templateSchema,
+            retry: false,
+        }),
+        message: "Template submitted for approval.",
+    })));
+    register(server, "get_template_status", "Check the Meta approval status for a template.", { templateId: idSchema }, readOnly, async (input) => execute(async () => {
+        const templateId = idSchema.parse(input.templateId);
+        return {
+            data: await apiRequest(`/v1/templates/${templateId}/status`, {
+                schema: mutationSchema,
+            }),
+            message: "Template status loaded.",
+        };
+    }));
+    register(server, "opt_out", "Record a WhatsApp opt-out and suppress future sends.", { phone: e164Schema, reason: z.string().trim().min(1).max(80).optional() }, destructive, async (input) => execute(async () => ({
+        data: await apiRequest("/v1/opt-outs", {
+            method: "POST",
+            body: input,
+            schema: mutationSchema,
+            retry: false,
+        }),
+        message: "Opt-out recorded.",
+    })));
+};

package/build/transports/http.js

@@ -0,0 +1,140 @@
+import axios from "axios";
+import express from "express";
+import rateLimit from "express-rate-limit";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { runWithAccessToken } from "../auth/context.js";
+import { API_TIMEOUT_MS, getApiBaseUrl, getHttpPort, SERVER_NAME, SERVER_VERSION, } from "../config.js";
+import { identitySchema } from "../lib/schemas.js";
+import { createServer } from "../server/create.js";
+const splitEnv = (name, fallback) => (process.env[name]?.split(",") ?? fallback)
+    .map((item) => item.trim().toLowerCase())
+    .filter(Boolean);
+const extractBearer = (request) => {
+    const header = request.header("authorization");
+    if (typeof header !== "string")
+        return null;
+    const match = /^Bearer ([^\s]+)$/i.exec(header.trim());
+    return match?.[1] ?? null;
+};
+const validateRequestOrigin = (request, response) => {
+    const allowedHosts = splitEnv("MCP_ALLOWED_HOSTS", ["localhost", "127.0.0.1", "mcp.ararahq.com"]);
+    const hostname = request.hostname.toLowerCase();
+    if (!allowedHosts.includes(hostname)) {
+        response
+            .status(403)
+            .json({ error: { code: "HOST_NOT_ALLOWED", message: "Host is not allowed." } });
+        return false;
+    }
+    const origin = request.header("origin");
+    if (!origin)
+        return true;
+    const allowedOrigins = splitEnv("MCP_ALLOWED_ORIGINS", [
+        "https://chatgpt.com",
+        "https://claude.ai",
+    ]);
+    let normalized;
+    try {
+        normalized = new URL(origin).origin.toLowerCase();
+    }
+    catch {
+        response
+            .status(403)
+            .json({ error: { code: "ORIGIN_NOT_ALLOWED", message: "Origin is not allowed." } });
+        return false;
+    }
+    if (!allowedOrigins.includes(normalized)) {
+        response
+            .status(403)
+            .json({ error: { code: "ORIGIN_NOT_ALLOWED", message: "Origin is not allowed." } });
+        return false;
+    }
+    return true;
+};
+const validateToken = async (token) => {
+    try {
+        const response = await axios.get(`${getApiBaseUrl()}/auth/me`, {
+            headers: { Authorization: `Bearer ${token}` },
+            timeout: API_TIMEOUT_MS,
+        });
+        return identitySchema.safeParse(response.data).success;
+    }
+    catch {
+        return false;
+    }
+};
+export const runHttp = async () => {
+    const app = express();
+    app.disable("x-powered-by");
+    app.set("trust proxy", 1);
+    app.use(express.json({ limit: "64kb", strict: true }));
+    app.use(rateLimit({ windowMs: 60_000, limit: 120, standardHeaders: "draft-8", legacyHeaders: false }));
+    app.use((request, response, next) => {
+        if (!validateRequestOrigin(request, response))
+            return;
+        const origin = request.header("origin");
+        if (origin) {
+            response.setHeader("Access-Control-Allow-Origin", origin);
+            response.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+            response.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type, MCP-Protocol-Version");
+            response.setHeader("Vary", "Origin");
+        }
+        if (request.method === "OPTIONS") {
+            response.status(204).end();
+            return;
+        }
+        next();
+    });
+    app.get("/health", (_request, response) => response.json({ status: "ok", name: SERVER_NAME, version: SERVER_VERSION }));
+    const protectedResource = (request, response) => {
+        const protocol = request.header("x-forwarded-proto") ?? request.protocol;
+        const resource = process.env.MCP_PUBLIC_URL ?? `${protocol}://${request.get("host")}/mcp`;
+        response.json({
+            resource,
+            authorization_servers: [process.env.ARARA_OAUTH_ISSUER ?? getApiBaseUrl()],
+            bearer_methods_supported: ["header"],
+            scopes_supported: process.env.ARARA_OAUTH_SCOPES?.split(" ") ?? [],
+        });
+    };
+    app.get("/.well-known/oauth-protected-resource", protectedResource);
+    app.get("/.well-known/oauth-protected-resource/mcp", protectedResource);
+    const handleMcp = async (request, response) => {
+        const token = extractBearer(request);
+        if (!token || !(await validateToken(token))) {
+            const metadataUrl = process.env.MCP_RESOURCE_METADATA_URL ??
+                "https://mcp.ararahq.com/.well-known/oauth-protected-resource/mcp";
+            response.setHeader("WWW-Authenticate", `Bearer resource_metadata="${metadataUrl}"`);
+            response.status(401).json({
+                error: { code: "UNAUTHENTICATED", message: "A valid OAuth bearer token is required." },
+            });
+            return;
+        }
+        const server = createServer();
+        const transport = new StreamableHTTPServerTransport();
+        response.on("close", () => {
+            void transport.close();
+            void server.close();
+        });
+        await server.connect(transport);
+        await runWithAccessToken(token, () => transport.handleRequest(request, response, request.body));
+    };
+    app.post("/mcp", (request, response) => {
+        void handleMcp(request, response).catch(() => {
+            if (!response.headersSent) {
+                response
+                    .status(500)
+                    .json({ error: { code: "INTERNAL_ERROR", message: "Request failed." } });
+            }
+        });
+    });
+    app.get("/mcp", (_request, response) => response.status(405).set("Allow", "POST").end());
+    app.delete("/mcp", (_request, response) => response.status(405).set("Allow", "POST").end());
+    app.use((_request, response) => response.status(404).json({ error: { code: "NOT_FOUND", message: "Not found." } }));
+    const port = getHttpPort();
+    await new Promise((resolve, reject) => {
+        const listener = app.listen(port, () => {
+            process.stderr.write(`AraraHQ MCP ${SERVER_VERSION} listening on ${port}.\n`);
+            resolve();
+        });
+        listener.on("error", reject);
+    });
+};

package/build/transports/stdio.js

@@ -0,0 +1,6 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "../server/create.js";
+export const runStdio = async () => {
+    const server = createServer();
+    await server.connect(new StdioServerTransport());
+};

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@ararahq/mcp",
+  "version": "5.0.0",
+  "description": "The official AraraHQ MCP server for operating WhatsApp support, billing and scheduling with OAuth.",
+  "main": "build/index.js",
+  "bin": {
+    "ararahq-mcp": "build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "scripts": {
+    "clean": "node --eval \"require('node:fs').rmSync('build',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm test && npm run build",
+    "start": "node build/index.js",
+    "dev": "tsx watch src/index.ts --stdio",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "whatsapp",
+    "claude",
+    "claude-code",
+    "cursor",
+    "windsurf",
+    "chatgpt",
+    "ararahq",
+    "customer-support",
+    "customer-service",
+    "atendimento",
+    "ai-agent",
+    "brazil"
+  ],
+  "homepage": "https://docs.ararahq.com/mcp-server",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ararahq/mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ararahq/mcp/issues"
+  },
+  "author": "AraraHQ <devs@ararahq.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "axios": "^1.18.0",
+    "dotenv": "^17.3.1",
+    "express": "^4.22.1",
+    "express-rate-limit": "^8.2.1",
+    "keytar": "^7.9.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.19.11",
+    "eslint": "^9.39.2",
+    "prettier": "^3.8.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.1",
+    "vitest": "^3.2.4"
+  }
+}