{"_id":"@ararahq/mcp","_rev":"3-710fd55a10e1a75f7580d083c3312d1f","name":"@ararahq/mcp","dist-tags":{"latest":"6.0.1"},"versions":{"5.0.0":{"name":"@ararahq/mcp","version":"5.0.0","keywords":["mcp","model-context-protocol","whatsapp","claude","claude-code","cursor","windsurf","chatgpt","ararahq","customer-support","customer-service","atendimento","ai-agent","brazil"],"author":{"name":"AraraHQ","email":"devs@ararahq.com"},"license":"MIT","_id":"@ararahq/mcp@5.0.0","maintainers":[{"name":"micas-ararahq","email":"micael@ararahq.com"}],"homepage":"https://docs.ararahq.com/mcp-server","bugs":{"url":"https://github.com/ararahq/mcp/issues"},"bin":{"ararahq-mcp":"build/index.js"},"dist":{"shasum":"831e5a116998d9f4349a37a51f97d1602617acd9","tarball":"https://registry.npmjs.org/@ararahq/mcp/-/mcp-5.0.0.tgz","fileCount":20,"integrity":"sha512-6M8i/z1FWds5mH+OIKu0NmoYuUMJ5BjqzppOJ+rBW+loEpi85CQqT7XFuq7YDCjYWM2JDEw8g6AEFf7uYveG+A==","signatures":[{"sig":"MEUCIAFLQjg7T7vPsjeF6pF4RpsX5d8KJajFO1DsRnRgZsgeAiEAsCVidfkJMI46RZxOSM1BtGbzLXOoKfhqW0ZltNPDP7k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":52813},"main":"build/index.js","type":"module","engines":{"node":">=20"},"gitHead":"2a324df6c455beba8d1f44840fef6f0c22d89001","scripts":{"dev":"tsx watch src/index.ts --stdio","lint":"eslint .","test":"vitest run","build":"npm run clean && tsc -p tsconfig.build.json","check":"npm run format:check && npm run lint && npm run typecheck && npm test && npm run build","clean":"node --eval \"require('node:fs').rmSync('build',{recursive:true,force:true})\"","start":"node build/index.js","format":"prettier --write .","typecheck":"tsc --noEmit","test:watch":"vitest","format:check":"prettier --check .","prepublishOnly":"npm run build"},"_npmUser":{"name":"micas-ararahq","email":"micael@ararahq.com"},"repository":{"url":"git+https://github.com/ararahq/mcp.git","type":"git"},"_npmVersion":"11.11.0","description":"The official AraraHQ MCP server for operating WhatsApp support, billing and scheduling with OAuth.","directories":{},"_nodeVersion":"24.5.0","dependencies":{"zod":"^3.25.76","axios":"^1.18.0","dotenv":"^17.3.1","keytar":"^7.9.0","express":"^4.22.1","express-rate-limit":"^8.2.1","@modelcontextprotocol/sdk":"^1.27.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","eslint":"^9.39.2","vitest":"^3.2.4","prettier":"^3.8.1","@eslint/js":"^9.39.2","typescript":"^5.9.3","@types/node":"^22.19.11","@types/express":"^4.17.21","typescript-eslint":"^8.56.1"},"_npmOperationalInternal":{"tmp":"tmp/mcp_5.0.0_1787368641815_0.3619353135196306","host":"s3://npm-registry-packages-npm-production"}},"6.0.0":{"name":"@ararahq/mcp","version":"6.0.0","keywords":["mcp","model-context-protocol","whatsapp","claude","claude-code","cursor","windsurf","chatgpt","ararahq","broadcast","campaigns","mcp-apps","disparo","ai-agent","brazil"],"author":{"name":"AraraHQ","email":"devs@ararahq.com"},"license":"MIT","_id":"@ararahq/mcp@6.0.0","maintainers":[{"name":"micas-ararahq","email":"micael@ararahq.com"}],"homepage":"https://docs.ararahq.com/mcp-server","bugs":{"url":"https://github.com/ararahq/mcp/issues"},"bin":{"ararahq-mcp":"build/index.js"},"dist":{"shasum":"2512c1e2989374edb8de379b697db9a973faf5ee","tarball":"https://registry.npmjs.org/@ararahq/mcp/-/mcp-6.0.0.tgz","fileCount":39,"integrity":"sha512-CswCGB293UTMXJ4IXPOBekJHiLpvFeuJbNItWlx+D26aNCCPA2+iLsuz/yOGPwwrPZKzvn68b6OwYv73bOFmaw==","signatures":[{"sig":"MEYCIQCGGw3TMSme6U6DqbOhgV+kFsCPAnJ7vEDte8CS4l1g/gIhAJpdW9t/A+pywEM1XYNnmo2TRuyg5bwD13tJxxwlMmEW","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQChAOlkMJ0CuyNxAKPhc3s/pti3Er171dJPsaoz57VWDgIhAPSNRgJCISw6ha3LyFHDyuWd+/TcylsQGWr9MKbWy2Et","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@ararahq%2fmcp@6.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":1378841},"main":"build/index.js","type":"module","engines":{"node":">=20"},"gitHead":"045a5b289338e65d5a066db0a54e306f47cbbe2b","scripts":{"dev":"tsx watch src/index.ts --stdio","lint":"eslint .","test":"vitest run","build":"npm run clean && tsc -p tsconfig.build.json && node scripts/build-ui.mjs","check":"npm run format:check && npm run lint && npm run typecheck && npm test && npm run build","clean":"node --eval \"require('node:fs').rmSync('build',{recursive:true,force:true})\"","start":"node build/index.js","format":"prettier --write .","build:ui":"node scripts/build-ui.mjs","typecheck":"tsc --noEmit && tsc -p src/ui/app/tsconfig.json --noEmit","test:watch":"vitest","format:check":"prettier --check .","prepublishOnly":"npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:2f19e260-b8b6-43cd-bfe0-9ceb61d78d59"}},"repository":{"url":"git+https://github.com/ararahq/mcp.git","type":"git"},"_npmVersion":"12.0.2","description":"The official AraraHQ MCP server for WhatsApp broadcasts and campaigns: send, measure what came back, reply.","directories":{},"_nodeVersion":"24.20.0","dependencies":{"zod":"^3.25.76","axios":"^1.18.0","dotenv":"^17.3.1","keytar":"^7.9.0","express":"^4.22.1","express-rate-limit":"^8.2.1","@modelcontextprotocol/sdk":"^1.30.0","@modelcontextprotocol/ext-apps":"^1.7.5"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","eslint":"^9.39.2","vitest":"^3.2.4","esbuild":"^0.28.2","prettier":"^3.8.1","@eslint/js":"^9.39.2","typescript":"^5.9.3","@types/node":"^22.19.11","@types/express":"^4.17.21","typescript-eslint":"^8.56.1"},"_npmOperationalInternal":{"tmp":"tmp/mcp_6.0.0_1789241780548_0.488201317043337","host":"s3://npm-registry-packages-npm-production"}},"6.0.1":{"_id":"@ararahq/mcp@6.0.1","bin":{"ararahq-mcp":"build/index.js"},"bugs":{"url":"https://github.com/ararahq/mcp/issues"},"dist":{"shasum":"673edb168a831ba0ecc613697f0baac14d7ead22","tarball":"https://registry.npmjs.org/@ararahq/mcp/-/mcp-6.0.1.tgz","fileCount":44,"integrity":"sha512-kgcOGjFoDtNtrlQAKJMdqMIhIj9uJq4aZPZBiTMfdb51jV+CcBvGDMsUJf3Pov/1mjs+9VZ6BJTxvKwUB/lvgw==","signatures":[{"sig":"MEUCIDAcUcl+uUIea856HbYG95Ei94aW/kO/LbHqcsvSJ4j3AiEAwV6qy+5Y6HPhGoxc2Lblu1fNKadvg9GiF/mqz0GPYkE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIF8KD3hJCqyjPCa22o6GB/UGc3ZikA0ekOe40GOjeI86AiBRQHxWp7RDVOVBMmT9WfzOJ3G45vJWz/xHnzdqsgnXdA=="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@ararahq%2fmcp@6.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":165963},"main":"build/index.js","name":"@ararahq/mcp","type":"module","author":{"name":"AraraHQ","email":"devs@ararahq.com"},"engines":{"node":">=20"},"gitHead":"5921800265daa87260c518bcda1aeaac2b126508","license":"MIT","scripts":{"dev":"tsx watch src/index.ts --stdio","lint":"eslint .","test":"vitest run","build":"npm run clean && tsc -p tsconfig.build.json && node scripts/build-ui.mjs","check":"npm run format:check && npm run lint && npm run typecheck && npm test && npm run build","clean":"node --eval \"require('node:fs').rmSync('build',{recursive:true,force:true})\"","start":"node build/index.js","cf:dev":"wrangler dev","format":"prettier --write .","build:ui":"node scripts/build-ui.mjs","cf:deploy":"npm run build && wrangler deploy","typecheck":"tsc --noEmit && tsc -p src/ui/app/tsconfig.json --noEmit","test:watch":"vitest","format:check":"prettier --check .","prepublishOnly":"npm run build"},"version":"6.0.1","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:2f19e260-b8b6-43cd-bfe0-9ceb61d78d59"}},"homepage":"https://docs.ararahq.com/mcp-server","keywords":["mcp","model-context-protocol","whatsapp","claude","claude-code","cursor","windsurf","chatgpt","ararahq","broadcast","campaigns","mcp-apps","disparo","ai-agent","brazil"],"repository":{"url":"git+https://github.com/ararahq/mcp.git","type":"git"},"_npmVersion":"12.0.2","description":"The official AraraHQ MCP server for WhatsApp broadcasts and campaigns: send, measure what came back, reply.","directories":{},"maintainers":[{"name":"micas-ararahq","email":"micael@ararahq.com"}],"_nodeVersion":"24.20.0","dependencies":{"zod":"^3.25.76","axios":"^1.18.0","dotenv":"^17.3.1","keytar":"^7.9.0","express":"^4.22.1","express-rate-limit":"^8.2.1","@modelcontextprotocol/sdk":"^1.30.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","eslint":"^9.39.2","vitest":"^3.2.4","esbuild":"^0.28.2","prettier":"^3.8.1","wrangler":"^4.131.1","@eslint/js":"^9.39.2","typescript":"^5.9.3","@types/node":"^22.19.11","@types/express":"^4.17.21","typescript-eslint":"^8.56.1"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_6.0.1_1789475307532_0.05578587153642167"}}},"time":{"created":"2026-08-22T03:17:21.597Z","modified":"2026-09-15T12:28:27.985Z","5.0.0":"2026-08-22T03:17:21.944Z","6.0.0":"2026-09-12T19:36:20.692Z","6.0.1":"2026-09-15T12:28:27.625Z"},"bugs":{"url":"https://github.com/ararahq/mcp/issues"},"author":{"name":"AraraHQ","email":"devs@ararahq.com"},"license":"MIT","homepage":"https://docs.ararahq.com/mcp-server","keywords":["mcp","model-context-protocol","whatsapp","claude","claude-code","cursor","windsurf","chatgpt","ararahq","broadcast","campaigns","mcp-apps","disparo","ai-agent","brazil"],"repository":{"url":"git+https://github.com/ararahq/mcp.git","type":"git"},"description":"The official AraraHQ MCP server for WhatsApp broadcasts and campaigns: send, measure what came back, reply.","maintainers":[{"name":"micas-ararahq","email":"micael@ararahq.com"}],"readme":"# AraraHQ MCP\n\nOfficial Model Context Protocol server for AraraHQ: talk to your whole WhatsApp base, see what came back, answer who replied.\n\nNode.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).\n\n## What it exposes\n\nNine 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.\n\n| Tool                | What it does                                                                                                         |\n| ------------------- | -------------------------------------------------------------------------------------------------------------------- |\n| `whoami`            | Who is authenticated, which organization sends, plan and wallet balance.                                             |\n| `send_whatsapp`     | One message to one person: free text inside the 24h window, or an approved template with variables any time.         |\n| `broadcast`         | One approved template to up to 1000 people as a campaign. Dry run by default (preview and cost), A/B and scheduling. |\n| `campaign_report`   | Recent campaigns, or the full report of one: sent, delivered, read, clicked, replied, converted, blocked, cost.      |\n| `check_status`      | Did it arrive? Is the 24h window open? Was the template approved?                                                    |\n| `create_template`   | Submit a template for Meta approval, with header, footer, samples and up to 2 buttons.                               |\n| `save_contacts`     | Create or update up to 1000 contacts so you can message by name.                                                     |\n| `opt_out`           | Record that someone asked to stop. Every later send to them is blocked.                                              |\n| `read_conversation` | The raw message timeline with one person, newest first, so you can judge a reply before answering.                   |\n\nResources (`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.\n\nEvery tool returns both human-readable content and stable structured content. Write tools carry MCP safety annotations. Credentials never appear in tool inputs or output.\n\nOperator 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.\n\n## Panels (MCP Apps)\n\nFour 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.\n\n| Tool                | Panel                                                                                        |\n| ------------------- | -------------------------------------------------------------------------------------------- |\n| `campaign_report`   | Funnel with animated bars, headline numbers, block reasons, live refresh while sending.      |\n| `broadcast`         | Phone mockup of the rendered message, audience and cost, approve button, then live delivery. |\n| `check_status`      | Delivery timeline (accepted, sent, delivered, read) that polls until a final state.          |\n| `read_conversation` | Chat thread with an inline reply box that calls `send_whatsapp`.                             |\n\nPanels are single-file HTML bundles (about 15 KB each) 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 speak the MCP Apps protocol through a small postMessage bridge of their own (`src/ui/app/bridge.ts`), call tools through the host and hand follow-ups back to the chat; they never hold credentials.\n\n## Local installation\n\nRequires Node.js 20 or newer.\n\n```bash\nnpx -y @ararahq/mcp login\nnpx -y @ararahq/mcp status\n```\n\nThe 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.\n\nConfigure an MCP client with stdio:\n\n```json\n{\n  \"mcpServers\": {\n    \"ararahq\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ararahq/mcp\", \"--stdio\"]\n    }\n  }\n}\n```\n\nUseful diagnostics:\n\n```bash\nnpx -y @ararahq/mcp doctor\nnpx -y @ararahq/mcp tools\nnpx -y @ararahq/mcp logout\n```\n\n## Hosted transport\n\nThe 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.\n\nOne Web Standard handler (`src/transports/web.ts`) serves every runtime. Host and origin allowlists, the OAuth challenge, the protected resource metadata and the panel assets behave the same everywhere. The bearer is resolved to an identity once per minute per token (Cache API on Workers, memory on Node; only a token fingerprint and the name and e-mail are stored), and rate limits are counted per authenticated user, not per IP.\n\n**Cloudflare Workers** is the production target. `wrangler.jsonc` declares the assets binding for the panels, a rate limiter and the public variables; the native keychain module is aliased to a stub so it never enters the bundle. A merge on `main` deploys through `.github/workflows/deploy.yml` once `CLOUDFLARE_API_TOKEN` exists.\n\n```bash\nnpm run cf:dev      # wrangler dev on http://127.0.0.1:8787\nnpm run cf:deploy   # build + wrangler deploy to mcp.ararahq.com (and the workers.dev fallback)\n```\n\n**Node** remains available for local runs of the hosted mode. It is a thin Express adapter over the same handler:\n\n```bash\nMCP_TRANSPORT=http \\\nPORT=3333 \\\nMCP_PUBLIC_URL=https://mcp.ararahq.com/mcp \\\nMCP_ALLOWED_HOSTS=mcp.ararahq.com \\\nMCP_ALLOWED_ORIGINS=https://chatgpt.com,https://claude.ai \\\nARARA_OAUTH_ISSUER=https://api.ararahq.com/api \\\nnpm start\n```\n\nProtected Resource Metadata is served at:\n\n- `/.well-known/oauth-protected-resource`\n- `/.well-known/oauth-protected-resource/mcp`\n\nAraraHQ 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.\n\n## Behavior worth knowing\n\n- `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.\n- Free text outside the 24h window is refused by Meta. `send_whatsapp` turns that refusal into a list of your approved templates.\n- `broadcast` never drops recipients silently: names that do not resolve are returned next to the campaign id.\n- Message acceptance means queued, not delivered. Delivery is checked with `check_status`.\n- Every mutating call carries an `Idempotency-Key`, so retries are safe.\n- `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.\n\n## Development\n\n```bash\nnpm ci\nnpm run check\nnpm audit --omit=dev\nnpm pack --dry-run\n```\n\nThe server defaults to stdio. Use `MCP_TRANSPORT=http npm start` for Streamable HTTP. Override the API only for controlled environments with `ARARA_API_URL`.\n\nThe 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.\n\n## Security\n\n- OAuth tokens remain server-side and are redacted by design.\n- External HTTP requests have explicit timeouts.\n- Retries are limited to safe methods or requests carrying an idempotency key and honor `Retry-After`.\n- All consumed API payloads are validated before fields are used.\n- Hosted requests are rate-limited and checked against explicit host and origin allowlists.\n- No telemetry is collected by this package.\n\nReport vulnerabilities privately to `security@ararahq.com`.\n\n## License\n\nMIT © AraraHQ\n","readmeFilename":"README.md"}