vistoazul-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Visto Azul
+
+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,64 @@
+# vistoazul-mcp
+
+> Servidor **MCP** (Model Context Protocol) da **[Visto Azul](https://vistoazul.com.br)**. Dê ao **Claude**, **Claude Code**, **Cursor** e a qualquer cliente MCP a capacidade de operar o **WhatsApp**: enviar texto, mídia e **cobrança PIX**, disparar campanhas, gerenciar contatos e configurar webhooks — tudo pela API REST do Visto Azul, sem taxa por mensagem da Meta e com anti-ban de fábrica.
+
+## O que é
+
+O MCP é o padrão que conecta agentes de IA a ferramentas externas. Com este servidor, você pede em linguagem natural — *"manda um PIX de R$97 pro cliente"*, *"dispara a campanha pra essa lista"* — e o agente executa pela sua conta do Visto Azul.
+
+## Ferramentas
+
+| Ferramenta | O que faz |
+|---|---|
+| `list_instances` | Lista os números conectados e o status |
+| `send_text` | Envia mensagem de texto |
+| `send_media` | Envia imagem, vídeo ou documento |
+| `send_pix` | Envia cobrança PIX na conversa |
+| `send_poll` | Envia enquete |
+| `check_numbers` | Verifica quem tem WhatsApp (anti-ban) |
+| `create_campaign` | Cria campanha (disparo em massa) |
+| `campaign_status` | Status de uma campanha |
+| `list_contacts` | Lista contatos (filtra por tag) |
+| `upsert_contact` | Cria ou atualiza um contato |
+| `set_webhook` | Configura webhook para receber mensagens |
+
+## Instalação
+
+Você precisa de uma **API key** do Visto Azul: crie a conta em [dashboard.vistoazul.com.br](https://dashboard.vistoazul.com.br), conecte seu número e copie a key em *Instâncias*.
+
+### Claude Code
+
+```bash
+claude mcp add vistoazul -e VISTOAZUL_API_KEY=SUA_API_KEY -- npx -y vistoazul-mcp
+```
+
+### Claude Desktop / Cursor (config JSON)
+
+```json
+{
+  "mcpServers": {
+    "vistoazul": {
+      "command": "npx",
+      "args": ["-y", "vistoazul-mcp"],
+      "env": { "VISTOAZUL_API_KEY": "SUA_API_KEY" }
+    }
+  }
+}
+```
+
+## Configuração
+
+| Variável | Obrigatória | Padrão |
+|---|---|---|
+| `VISTOAZUL_API_KEY` | sim | — |
+| `VISTOAZUL_BASE_URL` | não | `https://dashboard.vistoazul.com.br/api/v1` |
+
+## Links
+
+- 🌐 Site: **https://vistoazul.com.br**
+- 📚 Documentação: **https://vistoazul.com.br/docs**
+- 🧩 Node do n8n: **https://www.npmjs.com/package/n8n-nodes-vistoazul**
+
+## Licença
+
+[MIT](./LICENSE)

package/dist/index.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+/**
+ * Servidor MCP da Visto Azul.
+ * Expoe a API REST de WhatsApp do Visto Azul como ferramentas para agentes de IA
+ * (Claude, Claude Code, Cursor e qualquer cliente MCP). Auth por API key (Bearer).
+ * Config: variavel de ambiente VISTOAZUL_API_KEY (obrigatoria) e VISTOAZUL_BASE_URL (opcional).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const API_KEY = process.env.VISTOAZUL_API_KEY ?? "";
+const BASE_URL = (process.env.VISTOAZUL_BASE_URL ?? "https://dashboard.vistoazul.com.br/api/v1").replace(/\/+$/, "");
+if (!API_KEY) {
+    console.error("[vistoazul-mcp] Defina VISTOAZUL_API_KEY com a sua API key do Visto Azul (painel > Instancias).");
+}
+async function call(method, path, body, instance) {
+    const headers = {
+        Authorization: `Bearer ${API_KEY}`,
+        "Content-Type": "application/json",
+    };
+    if (instance)
+        headers["X-Instance"] = instance;
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    const data = text ? (() => { try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    } })() : null;
+    if (!res.ok) {
+        const msg = (data && typeof data === "object" && "error" in data) ? data.error : `Erro ${res.status}`;
+        throw new Error(`${res.status}: ${msg}`);
+    }
+    return data;
+}
+const ok = (data) => ({
+    content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) }],
+});
+const fail = (e) => ({
+    content: [{ type: "text", text: `Erro: ${e instanceof Error ? e.message : String(e)}` }],
+    isError: true,
+});
+const server = new McpServer({ name: "vistoazul", version: "0.1.0" });
+server.tool("list_instances", "Lista as instancias (numeros de WhatsApp) conectadas na conta, com status.", {}, async () => {
+    try {
+        return ok(await call("GET", "/instances"));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("send_text", "Envia uma mensagem de texto no WhatsApp.", {
+    instance: z.string().optional().describe("Nome da instancia (omita se so houver um numero)."),
+    number: z.string().describe("Numero de destino com DDI e DDD, so digitos. Ex: 5511999999999"),
+    text: z.string().describe("Texto da mensagem."),
+}, async ({ instance, number, text }) => {
+    try {
+        const body = { number, text };
+        if (instance)
+            body.instance = instance;
+        return ok(await call("POST", "/messages/text", body));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("send_media", "Envia midia (imagem, video ou documento) por uma URL publica, com legenda opcional.", {
+    instance: z.string().optional(),
+    number: z.string(),
+    type: z.enum(["image", "video", "document"]),
+    file: z.string().describe("URL publica do arquivo."),
+    text: z.string().optional().describe("Legenda (opcional)."),
+}, async ({ instance, number, type, file, text }) => {
+    try {
+        const body = { number, type, file };
+        if (text)
+            body.text = text;
+        return ok(await call("POST", "/wa/send/media", body, instance));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("send_pix", "Envia uma cobranca PIX na conversa do WhatsApp.", {
+    instance: z.string().optional(),
+    number: z.string(),
+    amount: z.number().describe("Valor da cobranca. Ex: 97.00"),
+    pixKey: z.string().describe("Sua chave PIX."),
+    pixType: z.enum(["email", "cpf", "cnpj", "phone", "random"]),
+    title: z.string().optional(),
+    text: z.string().optional(),
+    itemName: z.string().optional(),
+}, async ({ instance, number, amount, pixKey, pixType, title, text, itemName }) => {
+    try {
+        const body = { number, amount, pixKey, pixType };
+        if (title)
+            body.title = title;
+        if (text)
+            body.text = text;
+        if (itemName)
+            body.itemName = itemName;
+        return ok(await call("POST", "/wa/send/request-payment", body, instance));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("send_poll", "Envia uma enquete (poll) no WhatsApp.", {
+    instance: z.string().optional(),
+    number: z.string(),
+    text: z.string().describe("Pergunta da enquete."),
+    choices: z.array(z.string()).describe("Opcoes da enquete."),
+    selectableCount: z.number().optional().describe("Quantas opcoes o contato pode marcar (padrao 1)."),
+}, async ({ instance, number, text, choices, selectableCount }) => {
+    try {
+        const body = { type: "poll", number, text, choices, selectableCount: selectableCount ?? 1 };
+        return ok(await call("POST", "/wa/send/menu", body, instance));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("check_numbers", "Verifica quais numeros tem WhatsApp (use antes de disparar, anti-ban).", {
+    instance: z.string().optional(),
+    numbers: z.array(z.string()).describe("Lista de numeros a verificar."),
+}, async ({ instance, numbers }) => {
+    try {
+        return ok(await call("POST", "/wa/chat/check", { numbers }, instance));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("create_campaign", "Cria uma campanha (disparo em massa com anti-ban). template aceita spintax {a|b} e variaveis {{nome}}.", {
+    instances: z.array(z.string()).describe("Nomes das instancias que vao disparar."),
+    template: z.string(),
+    recipients: z.array(z.object({
+        number: z.string(),
+        vars: z.record(z.string()).optional(),
+    })),
+    minDelayMs: z.number().optional(),
+    maxDelayMs: z.number().optional(),
+    scheduledForMs: z.number().optional().describe("epoch ms; no futuro = agendada."),
+}, async ({ instances, template, recipients, minDelayMs, maxDelayMs, scheduledForMs }) => {
+    try {
+        const body = { instances, template, recipients };
+        if (minDelayMs !== undefined)
+            body.minDelayMs = minDelayMs;
+        if (maxDelayMs !== undefined)
+            body.maxDelayMs = maxDelayMs;
+        if (scheduledForMs !== undefined)
+            body.scheduledForMs = scheduledForMs;
+        return ok(await call("POST", "/campaigns", body));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("campaign_status", "Consulta o status de uma campanha.", { id: z.string() }, async ({ id }) => {
+    try {
+        return ok(await call("GET", `/campaigns/${id}`));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("list_contacts", "Lista contatos da conta. Filtre por tag opcional.", { tag: z.string().optional() }, async ({ tag }) => {
+    try {
+        return ok(await call("GET", `/contacts${tag ? `?tag=${encodeURIComponent(tag)}` : ""}`));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("upsert_contact", "Cria ou atualiza um contato.", {
+    number: z.string(),
+    name: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+}, async ({ number, name, tags }) => {
+    try {
+        const body = { number };
+        if (name)
+            body.name = name;
+        if (tags)
+            body.tags = tags;
+        return ok(await call("POST", "/contacts", body));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("set_webhook", "Configura o webhook de uma instancia para receber mensagens no seu endpoint (para chatbots).", {
+    instance: z.string(),
+    url: z.string().describe("URL do seu endpoint."),
+    enabled: z.boolean().optional(),
+}, async ({ instance, url, enabled }) => {
+    try {
+        return ok(await call("POST", `/instances/${instance}/webhook`, { url, enabled: enabled ?? true }));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("[vistoazul-mcp] servidor MCP iniciado (stdio).");

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "vistoazul-mcp",
+  "version": "0.1.0",
+  "description": "Servidor MCP da Visto Azul: use o WhatsApp (enviar texto, midia, PIX, campanhas, contatos, webhook) direto de agentes de IA como Claude, Claude Code e Cursor, pela API REST do Visto Azul.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "whatsapp",
+    "vistoazul",
+    "whatsapp-api",
+    "pix",
+    "claude",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "homepage": "https://vistoazul.com.br",
+  "author": {
+    "name": "Visto Azul",
+    "url": "https://vistoazul.com.br"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/useideia/vistoazul-mcp.git"
+  },
+  "type": "module",
+  "bin": {
+    "vistoazul-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.5.4"
+  }
+}