@atehra/mcp 0.1.0

package/README.md

@@ -0,0 +1,153 @@
+# @atehra/mcp
+
+Servidor MCP (Model Context Protocol) oficial da Atehra. Permite que Claude, Cursor, ChatGPT e qualquer cliente MCP operem a infraestrutura financeira BR da Atehra em linguagem natural.
+
+> **A primeira fintech brasileira projetada pra rodar via agente de IA.**
+
+## O que dá pra fazer
+
+Com este servidor ligado, seu agente de IA pode:
+
+- **Consultar saldo, A receber, antecipações disponíveis** em tempo real
+- **Criar cobranças** em PIX ou boleto pra qualquer cliente
+- **Gerar links de pagamento** reutilizáveis
+- **Antecipar vendas no cartão** com cotação prévia
+- **Sacar saldo** pra conta externa via PIX ou TED
+- **Configurar a régua de cobrança** em linguagem natural
+- **Ver métricas do negócio** (receita recorrente mensal, taxa de cancelamento, valor por cliente)
+- **Listar clientes, assinaturas e faturas** com filtros
+
+## Instalação
+
+### Pré-requisitos
+
+1. Conta na Atehra (`atehra.com`)
+2. API key (`atk_test_...` pra sandbox, `atk_live_...` pra produção)
+
+### No Claude Desktop
+
+Adicione ao arquivo de configuração (`~/Library/Application Support/Claude/claude_desktop_config.json` no macOS):
+
+```json
+{
+  "mcpServers": {
+    "atehra": {
+      "command": "npx",
+      "args": ["-y", "@atehra/mcp"],
+      "env": {
+        "ATEHRA_API_KEY": "atk_test_sua_chave_aqui"
+      }
+    }
+  }
+}
+```
+
+Reinicie o Claude Desktop. Pronto.
+
+### No Cursor
+
+Adicione ao `.cursor/mcp.json` no seu projeto:
+
+```json
+{
+  "mcpServers": {
+    "atehra": {
+      "command": "npx",
+      "args": ["-y", "@atehra/mcp"],
+      "env": {
+        "ATEHRA_API_KEY": "atk_test_sua_chave_aqui"
+      }
+    }
+  }
+}
+```
+
+## Modo sandbox vs produção
+
+O servidor detecta o modo pelo prefixo da chave:
+
+- `atk_test_...` → sandbox (dados de teste, dinheiro não é real)
+- `atk_live_...` → produção (dinheiro é real)
+
+**Recomendação forte:** comece sempre em sandbox.
+
+## Segurança em produção
+
+Em produção (`atk_live_`), ações que movem dinheiro real exigem **confirmação dupla**:
+
+1. Você pede pro Claude executar (ex.: "saca tudo pra minha conta principal")
+2. O servidor retorna: "Vou sacar R$ X pra conta Y. Confirme chamando de novo com `confirm: true`"
+3. Claude repassa pra você pedir confirmação humana
+4. Você confirma
+5. Claude chama de novo com `confirm: true` e a ação executa
+
+Em sandbox a confirmação é pulada (tudo é teste).
+
+## As 16 ferramentas
+
+### Saldo e dinheiro
+- `get_balance` — saldo disponível e a receber
+- `list_anticipatable_payments` — vendas no cartão que dão pra antecipar
+- `quote_anticipation` — calcular taxa e valor líquido
+- `request_anticipation` — antecipar pagamento (confirmação dupla em produção)
+- `request_withdrawal` — sacar saldo (confirmação dupla em produção)
+
+### Cobrar e clientes
+- `create_customer` — criar cliente
+- `list_customers` — listar clientes
+- `create_plan` — criar plano de produto (assinatura ou avulso)
+- `create_checkout_session` — gerar cobrança PIX ou boleto pra um cliente
+- `create_checkout_link` — gerar link de pagamento reutilizável
+- `list_recent_orders` — listar últimas vendas
+
+### Números do negócio
+- `get_metrics_overview` — receita, MRR, churn, ARPU, LTV
+- `list_subscriptions` — assinaturas ativas
+- `list_invoices` — faturas (pagas, pendentes, vencidas)
+
+### Régua de cobrança
+- `get_dunning_config` — ver régua atual
+- `update_dunning_config` — atualizar régua de cobrança
+
+## Exemplos de uso
+
+Com o servidor ligado, peça ao Claude:
+
+> "Quanto eu tenho de saldo e quanto posso antecipar agora?"
+
+> "Cria cliente Maria Silva com email maria@exemplo.com.br e CPF 12345678900, depois cria uma cobrança PIX de R$ 1.500 com vencimento sexta."
+
+> "Configura a régua: tenta cobrar de novo no dia 1, manda email no dia 3, suspende no dia 7."
+
+> "Quais clientes têm fatura vencida há mais de 5 dias?"
+
+> "Como tá o MRR esse mês comparado ao anterior?"
+
+## Variáveis de ambiente
+
+| Variável | Obrigatório | Descrição |
+|---|---|---|
+| `ATEHRA_API_KEY` | Sim | Chave da API (`atk_test_...` ou `atk_live_...`) |
+| `ATEHRA_BASE_URL` | Não | URL base da API. Padrão: `https://api.atehra.com` |
+
+## Desenvolvimento
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+Pra testar localmente com o Claude Desktop, aponte o `command` pro `node` e o `args` pro caminho do `dist/index.js`:
+
+```json
+{
+  "command": "node",
+  "args": ["/caminho/absoluto/para/atehra/mcp/dist/index.js"],
+  "env": { "ATEHRA_API_KEY": "atk_test_..." }
+}
+```
+
+## Licença
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Cliente HTTP simples pra API da Atehra.
+ *
+ * Usa fetch nativo (Node 18+). Autentica via header x-api-key.
+ * Retorna o JSON da resposta; lança erro com mensagem útil se a API responder não-2xx.
+ */
+import type { Env } from "./env.js";
+export declare class AtehraClient {
+    private env;
+    constructor(env: Env);
+    request<T = unknown>(method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE", path: string, opts?: {
+        body?: unknown;
+        query?: Record<string, string | number | undefined>;
+    }): Promise<T>;
+}

package/dist/client.js

@@ -0,0 +1,58 @@
+/**
+ * Cliente HTTP simples pra API da Atehra.
+ *
+ * Usa fetch nativo (Node 18+). Autentica via header x-api-key.
+ * Retorna o JSON da resposta; lança erro com mensagem útil se a API responder não-2xx.
+ */
+export class AtehraClient {
+    env;
+    constructor(env) {
+        this.env = env;
+    }
+    async request(method, path, opts = {}) {
+        const url = new URL(path, this.env.baseUrl + "/");
+        if (opts.query) {
+            for (const [k, v] of Object.entries(opts.query)) {
+                if (v !== undefined && v !== "")
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        const headers = {
+            "x-api-key": this.env.apiKey,
+            "user-agent": "@atehra/mcp",
+        };
+        if (opts.body !== undefined)
+            headers["content-type"] = "application/json";
+        const res = await fetch(url.toString(), {
+            method,
+            headers,
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+        });
+        const text = await res.text();
+        let data;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch {
+            data = text;
+        }
+        if (!res.ok) {
+            const msg = extractErrorMessage(data) ?? `HTTP ${res.status}`;
+            const error = new Error(`Atehra API ${method} ${path} → ${msg}`);
+            error.status = res.status;
+            error.data = data;
+            throw error;
+        }
+        return data;
+    }
+}
+function extractErrorMessage(data) {
+    if (data && typeof data === "object" && data !== null) {
+        const obj = data;
+        if (typeof obj["message"] === "string")
+            return obj["message"];
+        if (typeof obj["error"] === "string")
+            return obj["error"];
+    }
+    return null;
+}

package/dist/env.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Lê e valida variáveis de ambiente.
+ *
+ * ATEHRA_API_KEY (obrigatória) — chave da API. Prefixo determina o modo:
+ *   - atk_test_... → sandbox
+ *   - atk_live_... → produção
+ *
+ * ATEHRA_BASE_URL (opcional) — URL base da API. Default: https://api.atehra.com
+ */
+export type Mode = "test" | "live";
+export interface Env {
+    apiKey: string;
+    baseUrl: string;
+    mode: Mode;
+}
+export declare function loadEnv(): Env;

package/dist/env.js

@@ -0,0 +1,24 @@
+/**
+ * Lê e valida variáveis de ambiente.
+ *
+ * ATEHRA_API_KEY (obrigatória) — chave da API. Prefixo determina o modo:
+ *   - atk_test_... → sandbox
+ *   - atk_live_... → produção
+ *
+ * ATEHRA_BASE_URL (opcional) — URL base da API. Default: https://api.atehra.com
+ */
+export function loadEnv() {
+    const apiKey = process.env["ATEHRA_API_KEY"];
+    if (!apiKey) {
+        throw new Error("ATEHRA_API_KEY não definida. Gere uma chave em atehra.com e defina no ambiente.");
+    }
+    const mode = apiKey.startsWith("atk_live_")
+        ? "live"
+        : apiKey.startsWith("atk_test_")
+            ? "test"
+            : (() => {
+                throw new Error("ATEHRA_API_KEY tem prefixo inválido. Use atk_test_... (sandbox) ou atk_live_... (produção).");
+            })();
+    const baseUrl = (process.env["ATEHRA_BASE_URL"] ?? "https://api.atehra.com").replace(/\/+$/, "");
+    return { apiKey, baseUrl, mode };
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * @atehra/mcp — Servidor MCP oficial da Atehra
+ *
+ * Sobe um servidor MCP via stdio e registra as 16 ferramentas da V1:
+ *
+ *   Saldo (5): get_balance, list_anticipatable_payments, quote_anticipation,
+ *              request_anticipation, request_withdrawal
+ *
+ *   Cobrar (6): create_customer, list_customers, create_plan,
+ *               create_checkout_session, create_checkout_link, list_recent_orders
+ *
+ *   Números (3): get_metrics_overview, list_subscriptions, list_invoices
+ *
+ *   Régua (2): get_dunning_config, update_dunning_config
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * @atehra/mcp — Servidor MCP oficial da Atehra
+ *
+ * Sobe um servidor MCP via stdio e registra as 16 ferramentas da V1:
+ *
+ *   Saldo (5): get_balance, list_anticipatable_payments, quote_anticipation,
+ *              request_anticipation, request_withdrawal
+ *
+ *   Cobrar (6): create_customer, list_customers, create_plan,
+ *               create_checkout_session, create_checkout_link, list_recent_orders
+ *
+ *   Números (3): get_metrics_overview, list_subscriptions, list_invoices
+ *
+ *   Régua (2): get_dunning_config, update_dunning_config
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadEnv } from "./env.js";
+import { AtehraClient } from "./client.js";
+import { registerBalanceTools } from "./tools/balance.js";
+import { registerCustomerTools } from "./tools/customers.js";
+import { registerPlanTools } from "./tools/plans.js";
+import { registerChargeTools } from "./tools/charges.js";
+import { registerMetricsTools } from "./tools/metrics.js";
+import { registerBillingTools } from "./tools/billing.js";
+import { registerDunningTools } from "./tools/dunning.js";
+async function main() {
+    const env = loadEnv();
+    const client = new AtehraClient(env);
+    const server = new McpServer({
+        name: "atehra",
+        version: "0.1.0",
+    });
+    // Registra todas as 16 ferramentas
+    registerBalanceTools(server, client, env);
+    registerCustomerTools(server, client);
+    registerPlanTools(server, client);
+    registerChargeTools(server, client);
+    registerMetricsTools(server, client);
+    registerBillingTools(server, client);
+    registerDunningTools(server, client);
+    // Log de boot vai pra stderr (stdout é reservado pro protocolo MCP)
+    process.stderr.write(`[atehra-mcp] iniciado. Modo: ${env.mode}. Base URL: ${env.baseUrl}\n`);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`[atehra-mcp] erro fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/safety.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Confirmação dupla pra ações que movem dinheiro real.
+ *
+ * Em produção (atk_live_), ações sensíveis (saque, antecipação) exigem que
+ * o caller chame a tool 2x: a primeira chamada retorna um aviso pedindo confirmação,
+ * a segunda (com `confirm: true`) executa de fato.
+ *
+ * Em sandbox (atk_test_), o aviso é pulado — tudo é teste.
+ */
+import type { Mode } from "./env.js";
+export interface ConfirmationCheck {
+    mode: Mode;
+    confirm: boolean | undefined;
+    actionDescription: string;
+}
+export interface ConfirmationResult {
+    shouldExecute: boolean;
+    warningMessage?: string;
+}
+export declare function checkConfirmation({ mode, confirm, actionDescription }: ConfirmationCheck): ConfirmationResult;

package/dist/safety.js

@@ -0,0 +1,28 @@
+/**
+ * Confirmação dupla pra ações que movem dinheiro real.
+ *
+ * Em produção (atk_live_), ações sensíveis (saque, antecipação) exigem que
+ * o caller chame a tool 2x: a primeira chamada retorna um aviso pedindo confirmação,
+ * a segunda (com `confirm: true`) executa de fato.
+ *
+ * Em sandbox (atk_test_), o aviso é pulado — tudo é teste.
+ */
+export function checkConfirmation({ mode, confirm, actionDescription }) {
+    // Em sandbox, sempre executa
+    if (mode === "test")
+        return { shouldExecute: true };
+    // Em produção, exige confirm: true explícito
+    if (confirm === true)
+        return { shouldExecute: true };
+    return {
+        shouldExecute: false,
+        warningMessage: [
+            `⚠️  AÇÃO EM PRODUÇÃO — MOVIMENTAÇÃO REAL DE DINHEIRO`,
+            ``,
+            actionDescription,
+            ``,
+            `Pra confirmar e executar de fato, chame esta ferramenta de novo com o parâmetro \`confirm: true\`.`,
+            `Antes de confirmar, repasse pro usuário humano e peça autorização explícita.`,
+        ].join("\n"),
+    };
+}

package/dist/tools/balance.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Grupo A — Saldo e dinheiro (5 ferramentas)
+ *
+ * get_balance, list_anticipatable_payments, quote_anticipation,
+ * request_anticipation, request_withdrawal
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AtehraClient } from "../client.js";
+import type { Env } from "../env.js";
+export declare function registerBalanceTools(server: McpServer, client: AtehraClient, env: Env): void;

package/dist/tools/balance.js

@@ -0,0 +1,161 @@
+/**
+ * Grupo A — Saldo e dinheiro (5 ferramentas)
+ *
+ * get_balance, list_anticipatable_payments, quote_anticipation,
+ * request_anticipation, request_withdrawal
+ */
+import { z } from "zod";
+import { checkConfirmation } from "../safety.js";
+export function registerBalanceTools(server, client, env) {
+    // ── get_balance ────────────────────────────────────────────────────────────
+    server.tool("get_balance", "Retorna o saldo da conta Atehra: quanto está disponível pra saque agora, quanto ainda está a receber (cobrado mas aguardando liberação) e a moeda. Use sempre que o usuário perguntar quanto tem na conta, quanto pode sacar ou quanto está pra entrar.", {}, async () => {
+        const balance = await client.request("GET", "/v1/balance");
+        const formatBRL = (cents) => `R$ ${(cents / 100).toLocaleString("pt-BR", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `Modo: ${env.mode === "live" ? "🟢 produção" : "🟡 sandbox"}`,
+                        `Saldo disponível pra saque: ${formatBRL(balance.available)}`,
+                        `A receber (cobrado, aguardando liberação): ${formatBRL(balance.pending)}`,
+                        `Moeda: ${balance.currency}`,
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    // ── list_anticipatable_payments ────────────────────────────────────────────
+    server.tool("list_anticipatable_payments", "Lista todos os pagamentos no cartão que estão pendentes de liberação e podem ser antecipados. Cada item traz o valor bruto, o valor líquido após taxa, o tipo (PIX, BOLETO, CREDIT_CARD), o vencimento e quantos dias faltam pra liberação automática. Use quando o usuário quiser antecipar recebíveis ou ver o que dá pra antecipar.", {}, async () => {
+        const payments = await client.request("GET", "/v1/balance/anticipatable-payments");
+        if (payments.length === 0) {
+            return {
+                content: [
+                    { type: "text", text: "Nenhum pagamento disponível pra antecipação no momento." },
+                ],
+            };
+        }
+        const total = payments.reduce((sum, p) => sum + p.net, 0);
+        const formatBRL = (cents) => `R$ ${(cents / 100).toLocaleString("pt-BR", { minimumFractionDigits: 2 })}`;
+        const lines = [
+            `${payments.length} pagamento(s) disponível(is) pra antecipar.`,
+            `Total líquido se antecipar tudo: ${formatBRL(total)}`,
+            ``,
+            ...payments.map((p, i) => `${i + 1}. id=${p.id} · ${p.billingType} · bruto ${formatBRL(p.gross)} · líquido ${formatBRL(p.net)} · vence ${p.dueDate} (em ${p.daysUntilDue} dias)`),
+        ];
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    });
+    // ── quote_anticipation ─────────────────────────────────────────────────────
+    server.tool("quote_anticipation", "Calcula a taxa e o valor líquido pra antecipar um pagamento específico. Não executa a antecipação, só simula. Use SEMPRE antes de chamar request_anticipation pra mostrar pro usuário quanto vai chegar líquido e a taxa efetiva. Passe paymentId OU installmentId (não os dois).", {
+        paymentId: z
+            .string()
+            .optional()
+            .describe("ID do pagamento Asaas. Use quando antecipar um pagamento avulso."),
+        installmentId: z
+            .string()
+            .optional()
+            .describe("ID da parcela. Use quando antecipar parcelas de cartão."),
+    }, async ({ paymentId, installmentId }) => {
+        if (!paymentId && !installmentId) {
+            return {
+                content: [
+                    { type: "text", text: "Erro: passe paymentId OU installmentId. Pelo menos um é obrigatório." },
+                ],
+                isError: true,
+            };
+        }
+        const quote = await client.request("GET", "/v1/balance/anticipations/quote", {
+            query: { paymentId, installmentId },
+        });
+        const formatBRL = (cents) => `R$ ${(cents / 100).toLocaleString("pt-BR", { minimumFractionDigits: 2 })}`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `Cotação de antecipação:`,
+                        `  Valor bruto: ${formatBRL(quote.grossAmount)}`,
+                        `  Taxa: ${formatBRL(quote.feeAmount)} (${(quote.effectiveRate * 100).toFixed(2)}% efetivo)`,
+                        `  Valor líquido (chega pra você): ${formatBRL(quote.netAmount)}`,
+                        ``,
+                        `Pra executar a antecipação, chame request_anticipation com o mesmo ID.`,
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    // ── request_anticipation ───────────────────────────────────────────────────
+    server.tool("request_anticipation", "Executa a antecipação de um pagamento. AÇÃO IRREVERSÍVEL que move dinheiro. Em produção exige confirm:true (após o usuário humano autorizar). Em sandbox executa direto. Sempre chame quote_anticipation antes pra mostrar a cotação.", {
+        paymentId: z.string().optional().describe("ID do pagamento Asaas a antecipar."),
+        installmentId: z.string().optional().describe("ID da parcela a antecipar."),
+        confirm: z
+            .boolean()
+            .optional()
+            .describe("Em produção: passe true SÓ após o usuário humano autorizar explicitamente. Em sandbox: ignorado."),
+    }, async ({ paymentId, installmentId, confirm }) => {
+        if (!paymentId && !installmentId) {
+            return {
+                content: [{ type: "text", text: "Erro: passe paymentId OU installmentId." }],
+                isError: true,
+            };
+        }
+        const check = checkConfirmation({
+            mode: env.mode,
+            confirm,
+            actionDescription: `Antecipar ${paymentId ? `pagamento ${paymentId}` : `parcela ${installmentId}`}. O valor líquido cai na conta Atehra na hora; a taxa é descontada do bruto.`,
+        });
+        if (!check.shouldExecute) {
+            return { content: [{ type: "text", text: check.warningMessage }] };
+        }
+        const result = await client.request("POST", "/v1/balance/anticipations", {
+            body: { paymentId, installmentId },
+        });
+        return {
+            content: [
+                { type: "text", text: `Antecipação executada com sucesso.\n\n${JSON.stringify(result, null, 2)}` },
+            ],
+        };
+    });
+    // ── request_withdrawal ─────────────────────────────────────────────────────
+    server.tool("request_withdrawal", "Saca dinheiro do saldo da Atehra pra uma conta externa via PIX ou TED. AÇÃO IRREVERSÍVEL que move dinheiro real. Em produção exige confirm:true após autorização humana explícita. Em sandbox executa direto.", {
+        amount: z
+            .number()
+            .int()
+            .positive()
+            .describe("Valor a sacar em centavos (ex: 100000 = R$ 1.000,00). Mínimo R$ 10,00 (1000)."),
+        destinationType: z.enum(["PIX", "TED"]).describe("Método de saque."),
+        pixKey: z.string().optional().describe("Chave PIX de destino (obrigatório se destinationType=PIX)."),
+        pixKeyType: z
+            .enum(["CPF", "CNPJ", "EMAIL", "PHONE", "EVP"])
+            .optional()
+            .describe("Tipo da chave PIX."),
+        bankCode: z.string().optional().describe("Código do banco (obrigatório se destinationType=TED)."),
+        bankAgency: z.string().optional().describe("Agência (obrigatório se destinationType=TED)."),
+        bankAccount: z.string().optional().describe("Número da conta (obrigatório se destinationType=TED)."),
+        bankAccountType: z
+            .enum(["CHECKING", "SAVINGS"])
+            .optional()
+            .describe("Tipo da conta TED (corrente ou poupança)."),
+        confirm: z.boolean().optional().describe("Em produção: true só após autorização humana."),
+    }, async (args) => {
+        const { confirm, ...payload } = args;
+        const formatBRL = (cents) => `R$ ${(cents / 100).toLocaleString("pt-BR", { minimumFractionDigits: 2 })}`;
+        const destinationDesc = payload.destinationType === "PIX"
+            ? `via PIX pra chave ${payload.pixKey} (${payload.pixKeyType})`
+            : `via TED pra banco ${payload.bankCode}, ag ${payload.bankAgency}, conta ${payload.bankAccount}`;
+        const check = checkConfirmation({
+            mode: env.mode,
+            confirm,
+            actionDescription: `Sacar ${formatBRL(payload.amount)} ${destinationDesc}.`,
+        });
+        if (!check.shouldExecute) {
+            return { content: [{ type: "text", text: check.warningMessage }] };
+        }
+        const result = await client.request("POST", "/v1/balance/withdrawals", { body: payload });
+        return {
+            content: [
+                { type: "text", text: `Saque solicitado com sucesso.\n\n${JSON.stringify(result, null, 2)}` },
+            ],
+        };
+    });
+}

package/dist/tools/billing.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Grupo C (parte 2) — Assinaturas e faturas (2 ferramentas)
+ *
+ * list_subscriptions, list_invoices
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AtehraClient } from "../client.js";
+export declare function registerBillingTools(server: McpServer, client: AtehraClient): void;

package/dist/tools/billing.js

@@ -0,0 +1,63 @@
+/**
+ * Grupo C (parte 2) — Assinaturas e faturas (2 ferramentas)
+ *
+ * list_subscriptions, list_invoices
+ */
+import { z } from "zod";
+export function registerBillingTools(server, client) {
+    // ── list_subscriptions ─────────────────────────────────────────────────────
+    server.tool("list_subscriptions", "Lista assinaturas da conta com filtro opcional por status. Status possíveis: active (ativa), trialing (em teste grátis), past_due (atrasada), suspended (suspensa por inadimplência), cancelled (cancelada). Use pra ver quem está pagando, quem cancelou, quem está em risco.", {
+        status: z
+            .enum(["active", "trialing", "past_due", "suspended", "cancelled"])
+            .optional()
+            .describe("Filtrar por status. Sem filtro = todas."),
+        limit: z.number().int().positive().max(100).optional().describe("Quantas retornar (default: 20)."),
+    }, async ({ status, limit }) => {
+        const result = await client.request("GET", "/v1/subscriptions", { query: { status, limit: limit ?? 20 } });
+        if (result.data.length === 0) {
+            return { content: [{ type: "text", text: "Nenhuma assinatura encontrada com esses filtros." }] };
+        }
+        const formatBRL = (cents) => `R$ ${(cents / 100).toLocaleString("pt-BR", { minimumFractionDigits: 2 })}`;
+        const lines = [
+            `Total: ${result.total}`,
+            `Mostrando ${result.data.length}:`,
+            ``,
+            ...result.data.map((s, i) => {
+                const customer = s.customer?.email ?? "—";
+                const plan = s.plan ? `${s.plan.name} (${formatBRL(s.plan.price)})` : "—";
+                const renewsAt = s.currentPeriodEnd
+                    ? new Date(s.currentPeriodEnd).toLocaleDateString("pt-BR")
+                    : "—";
+                return `${i + 1}. ${customer} · ${plan} · ${s.status} · próximo ciclo: ${renewsAt} (id=${s.id})`;
+            }),
+        ];
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    });
+    // ── list_invoices ──────────────────────────────────────────────────────────
+    server.tool("list_invoices", "Lista faturas (cobranças geradas, dentro ou fora de assinatura) com filtro opcional por status e período. Status: paid (paga), pending (pendente), overdue (vencida), refunded. Use pra ver fluxo de pagamentos, identificar inadimplência, gerar relatórios.", {
+        status: z.enum(["paid", "pending", "overdue", "refunded"]).optional().describe("Filtrar por status."),
+        period: z
+            .string()
+            .regex(/^\d{4}-\d{2}$/)
+            .optional()
+            .describe("Período YYYY-MM. Default: todas."),
+    }, async ({ status, period }) => {
+        const invoices = await client.request("GET", "/v1/billing/invoices", { query: { status, period } });
+        if (invoices.length === 0) {
+            return { content: [{ type: "text", text: "Nenhuma fatura encontrada com esses filtros." }] };
+        }
+        const formatBRL = (cents) => `R$ ${(cents / 100).toLocaleString("pt-BR", { minimumFractionDigits: 2 })}`;
+        const lines = [
+            `Total de faturas: ${invoices.length}`,
+            ``,
+            ...invoices.slice(0, 50).map((inv, i) => {
+                const customer = inv.customer?.email ?? "—";
+                const due = inv.dueDate ? new Date(inv.dueDate).toLocaleDateString("pt-BR") : "—";
+                const paid = inv.paidAt ? ` · paga em ${new Date(inv.paidAt).toLocaleDateString("pt-BR")}` : "";
+                return `${i + 1}. ${customer} · ${formatBRL(inv.amount)} · ${inv.status} · vence ${due}${paid} (id=${inv.id})`;
+            }),
+            invoices.length > 50 ? `\n(mostrando primeiras 50 de ${invoices.length})` : "",
+        ].filter(Boolean);
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    });
+}

package/dist/tools/charges.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Grupo B (parte 3) — Cobranças (3 ferramentas)
+ *
+ * create_checkout_session, create_checkout_link, list_recent_orders
+ *
+ * IMPORTANTE: este MCP só expõe cobrança em PIX e BOLETO.
+ * Cobrança em CREDIT_CARD exige dados sensíveis do cartão e deve ser feita
+ * via dashboard ou checkout link público — não via agente de IA.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AtehraClient } from "../client.js";
+export declare function registerChargeTools(server: McpServer, client: AtehraClient): void;

package/dist/tools/charges.js

@@ -0,0 +1,98 @@
+/**
+ * Grupo B (parte 3) — Cobranças (3 ferramentas)
+ *
+ * create_checkout_session, create_checkout_link, list_recent_orders
+ *
+ * IMPORTANTE: este MCP só expõe cobrança em PIX e BOLETO.
+ * Cobrança em CREDIT_CARD exige dados sensíveis do cartão e deve ser feita
+ * via dashboard ou checkout link público — não via agente de IA.
+ */
+import { z } from "zod";
+export function registerChargeTools(server, client) {
+    // ── create_checkout_session ────────────────────────────────────────────────
+    server.tool("create_checkout_session", "Cria uma cobrança imediata em PIX ou BOLETO pra um cliente específico em cima de um plano. Retorna o link de pagamento e (se PIX) o QR code. Use depois de ter o cliente (create_customer) e o plano (create_plan). Pra cartão de crédito, use create_checkout_link em vez (cartão exige dados sensíveis).", {
+        customerId: z.string().describe("ID interno Atehra do cliente (do create_customer ou list_customers)."),
+        planId: z.string().describe("ID do plano a cobrar (do create_plan)."),
+        taxId: z
+            .string()
+            .describe("CPF ou CNPJ do cliente final (só números, ex: '12345678900'). Obrigatório pra geração de cobrança."),
+        billingType: z.enum(["PIX", "BOLETO"]).describe("Método de cobrança: PIX (instantâneo) ou BOLETO."),
+        couponCode: z.string().optional().describe("Código de cupom de desconto, se aplicável."),
+    }, async (args) => {
+        const session = await client.request("POST", "/v1/checkout/session", {
+            body: args,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `Cobrança criada com sucesso (${args.billingType}).`,
+                        ``,
+                        `Dados retornados pela plataforma:`,
+                        JSON.stringify(session, null, 2),
+                        ``,
+                        `Compartilhe o link/QR com o cliente. A plataforma vai te avisar via webhook quando ele pagar.`,
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    // ── create_checkout_link ───────────────────────────────────────────────────
+    server.tool("create_checkout_link", "Gera um link de pagamento reutilizável pra um plano. O cliente abre o link, escolhe o método (PIX, boleto ou cartão) e paga. Bom pra divulgação em redes sociais, email, WhatsApp. Diferente de create_checkout_session, este é genérico (não exige cliente nem CPF antes).", {
+        planId: z.string().describe("ID do plano a vender."),
+        name: z.string().optional().describe("Label interno do link (ex: 'Black Friday 2026'). Só pra organização."),
+        slug: z
+            .string()
+            .regex(/^[a-zA-Z0-9_-]+$/)
+            .min(3)
+            .max(64)
+            .optional()
+            .describe("Slug customizado da URL. Auto-gerado se omitido."),
+        successUrl: z.string().url().optional().describe("URL pra redirecionar após pagamento bem-sucedido."),
+        cancelUrl: z.string().url().optional().describe("URL pra redirecionar se o cliente cancelar."),
+        maxUses: z.number().int().positive().optional().describe("Máximo de usos permitidos. Default: ilimitado."),
+        expiresAt: z.string().datetime().optional().describe("Data/hora de expiração ISO 8601. Default: nunca expira."),
+    }, async (args) => {
+        const link = await client.request("POST", "/v1/checkout/links", {
+            body: args,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Link de pagamento criado:\n\n${JSON.stringify(link, null, 2)}`,
+                },
+            ],
+        };
+    });
+    // ── list_recent_orders ─────────────────────────────────────────────────────
+    server.tool("list_recent_orders", "Lista as vendas (orders) mais recentes da conta. Cada venda tem cliente, plano, valor, status (pending/paid/refunded/cancelled) e data. Use pra ver atividade recente, identificar quem pagou ou quem está pendente.", {
+        status: z
+            .enum(["pending", "paid", "refunded", "cancelled"])
+            .optional()
+            .describe("Filtrar por status."),
+        customerId: z.string().optional().describe("Filtrar por cliente específico."),
+        limit: z.number().int().positive().max(50).optional().describe("Quantas vendas retornar (default: 10, máx 50)."),
+    }, async ({ status, customerId, limit }) => {
+        const result = await client.request("GET", "/v1/orders", {
+            query: { status, customerId, limit: limit ?? 10 },
+        });
+        if (result.data.length === 0) {
+            return { content: [{ type: "text", text: "Nenhuma venda encontrada com esses filtros." }] };
+        }
+        const formatBRL = (cents) => `R$ ${(cents / 100).toLocaleString("pt-BR", { minimumFractionDigits: 2 })}`;
+        const lines = [
+            `Total de vendas que batem com o filtro: ${result.total}`,
+            `Mostrando ${result.data.length}:`,
+            ``,
+            ...result.data.map((o, i) => {
+                const customer = o.customer?.email ?? "—";
+                const plan = o.plan?.name ?? "—";
+                const date = new Date(o.createdAt).toLocaleDateString("pt-BR");
+                return `${i + 1}. ${customer} · ${plan} · ${formatBRL(o.amount)} · ${o.status} · ${date} (id=${o.id})`;
+            }),
+        ];
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    });
+}

package/dist/tools/customers.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Grupo B (parte 1) — Clientes (2 ferramentas)
+ *
+ * create_customer, list_customers
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AtehraClient } from "../client.js";
+export declare function registerCustomerTools(server: McpServer, client: AtehraClient): void;

package/dist/tools/customers.js

@@ -0,0 +1,54 @@
+/**
+ * Grupo B (parte 1) — Clientes (2 ferramentas)
+ *
+ * create_customer, list_customers
+ */
+import { z } from "zod";
+export function registerCustomerTools(server, client) {
+    // ── create_customer ────────────────────────────────────────────────────────
+    server.tool("create_customer", "Cria um novo cliente final no catálogo da Atehra. Esse cliente é vinculado à conta da Atehra do usuário (não ao Asaas). Use antes de criar cobrança ou assinatura pra um cliente novo. Se o cliente já existe, use list_customers pra encontrar.", {
+        externalId: z
+            .string()
+            .min(1)
+            .describe("ID único do cliente no seu sistema (ex: 'user_123', 'cliente-acme'). Não pode repetir."),
+        email: z.string().email().describe("Email do cliente. Usado pra cobranças, dunning, comunicação."),
+        name: z.string().optional().describe("Nome do cliente. Opcional mas recomendado pra personalização."),
+    }, async ({ externalId, email, name }) => {
+        const customer = await client.request("POST", "/v1/customers", { body: { externalId, email, name } });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `Cliente criado:`,
+                        `  ID interno Atehra: ${customer.id}`,
+                        `  ID externo: ${customer.externalId}`,
+                        `  Email: ${customer.email}`,
+                        `  Nome: ${customer.name ?? "(sem nome)"}`,
+                        ``,
+                        `Use o ID interno (${customer.id}) pra criar cobranças e assinaturas.`,
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    // ── list_customers ─────────────────────────────────────────────────────────
+    server.tool("list_customers", "Lista clientes do catálogo com paginação. Use pra encontrar um cliente existente pelo email ou nome, ou pra ver quantos clientes a conta tem. Retorna até 20 clientes por chamada.", {
+        page: z.number().int().positive().optional().describe("Página (default: 1)."),
+        limit: z.number().int().positive().max(100).optional().describe("Quantos por página (default: 20, máximo 100)."),
+    }, async ({ page, limit }) => {
+        const result = await client.request("GET", "/v1/customers", {
+            query: { page: page ?? 1, limit: limit ?? 20 },
+        });
+        if (result.data.length === 0) {
+            return { content: [{ type: "text", text: "Nenhum cliente cadastrado ainda." }] };
+        }
+        const lines = [
+            `Total de clientes: ${result.total}`,
+            `Mostrando página ${result.page} (${result.data.length} de ${result.total})`,
+            ``,
+            ...result.data.map((c, i) => `${i + 1}. ${c.email}${c.name ? ` (${c.name})` : ""} — id=${c.id} · externalId=${c.externalId}`),
+        ];
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    });
+}

package/dist/tools/dunning.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Grupo D — Régua de cobrança (2 ferramentas)
+ *
+ * get_dunning_config, update_dunning_config
+ *
+ * A régua define o que acontece quando um cliente atrasa:
+ *  - retryDays: em quais dias após o vencimento a régua dispara
+ *  - actions: o que fazer em cada dia (retry, email, whatsapp, suspend)
+ *
+ * IMPORTANTE: as ações 'email' e 'whatsapp' DISPARAM WEBHOOK pra o sistema
+ * do cliente integrar. A Atehra não envia diretamente.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AtehraClient } from "../client.js";
+export declare function registerDunningTools(server: McpServer, client: AtehraClient): void;

package/dist/tools/dunning.js

@@ -0,0 +1,100 @@
+/**
+ * Grupo D — Régua de cobrança (2 ferramentas)
+ *
+ * get_dunning_config, update_dunning_config
+ *
+ * A régua define o que acontece quando um cliente atrasa:
+ *  - retryDays: em quais dias após o vencimento a régua dispara
+ *  - actions: o que fazer em cada dia (retry, email, whatsapp, suspend)
+ *
+ * IMPORTANTE: as ações 'email' e 'whatsapp' DISPARAM WEBHOOK pra o sistema
+ * do cliente integrar. A Atehra não envia diretamente.
+ */
+import { z } from "zod";
+export function registerDunningTools(server, client) {
+    // ── get_dunning_config ─────────────────────────────────────────────────────
+    server.tool("get_dunning_config", "Retorna a configuração atual da régua de cobrança: em quais dias após o vencimento ela age, e o que faz em cada dia (tentar cobrar de novo, disparar webhook pra email, disparar webhook pra WhatsApp, suspender acesso).", {}, async () => {
+        const raw = await client.request("GET", "/v1/dunning/config");
+        // A API retorna { configured: false } quando nunca foi configurada
+        if ("configured" in raw && raw.configured === false) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `Régua de cobrança ainda não configurada.`,
+                            ``,
+                            `Use update_dunning_config pra criar uma régua. Exemplo de régua agressiva:`,
+                            `  retryDays: [1, 3, 5, 7]`,
+                            `  actions: [`,
+                            `    { day: 1, action: "retry" },`,
+                            `    { day: 3, action: "email" },`,
+                            `    { day: 5, action: "whatsapp" },`,
+                            `    { day: 7, action: "suspend" }`,
+                            `  ]`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        }
+        const config = raw;
+        const lines = [
+            `Régua de cobrança atual:`,
+            ``,
+            `Dias de tentativa após o vencimento: ${config.retryDays.join(", ")}`,
+            ``,
+            `Ações configuradas:`,
+            ...config.actions.map((a) => `  Dia ${a.day}: ${describeAction(a.action)}`),
+            ``,
+            config.whatsappMessage
+                ? `Mensagem WhatsApp configurada: "${config.whatsappMessage}"`
+                : `Mensagem WhatsApp: usando default da plataforma`,
+            ``,
+            `Nota: 'email' e 'whatsapp' disparam webhook pra o sistema do cliente integrar com o provedor dele (Resend, Twilio, etc.). A Atehra não envia diretamente.`,
+        ];
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    });
+    // ── update_dunning_config ──────────────────────────────────────────────────
+    server.tool("update_dunning_config", "Atualiza a régua de cobrança. Defina em quais dias após o vencimento ela age e o que faz. Exemplo de régua agressiva: retry no dia 1, email no dia 3, WhatsApp no dia 5, suspende no dia 7. Use linguagem natural do usuário pra montar.", {
+        retryDays: z
+            .array(z.number().int().positive())
+            .min(1)
+            .describe("Lista de dias após o vencimento em que a régua roda. Dias devem ser positivos (1, 3, 5...). Ex: [1, 3, 5, 7]."),
+        actions: z
+            .array(z.object({
+            day: z.number().int().positive().describe("Em qual dia da retryDays a ação acontece. Deve ser positivo."),
+            action: z
+                .enum(["retry", "email", "whatsapp", "suspend"])
+                .describe("retry = nova tentativa de cobrança (cria PIX como alternativa). email = dispara webhook dunning.email. whatsapp = dispara webhook dunning.whatsapp. suspend = bloqueia acesso do cliente (revoga entitlements)."),
+        }))
+            .describe("Lista de ações em cada dia. Pode ter múltiplas ações no mesmo dia."),
+        whatsappMessage: z
+            .string()
+            .optional()
+            .describe("Template da mensagem WhatsApp. Default: 'Olá! Identificamos um pagamento pendente de R$X. Podemos ajudar?'"),
+    }, async (args) => {
+        const updated = await client.request("PUT", "/v1/dunning/config", { body: args });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Régua atualizada com sucesso.\n\nNova configuração:\n${JSON.stringify(updated, null, 2)}`,
+                },
+            ],
+        };
+    });
+}
+function describeAction(action) {
+    switch (action) {
+        case "retry":
+            return "tentar nova cobrança (cria PIX alternativo via Asaas)";
+        case "email":
+            return "disparar webhook 'dunning.email' (cliente integra com seu provedor)";
+        case "whatsapp":
+            return "disparar webhook 'dunning.whatsapp' (cliente integra com seu provedor)";
+        case "suspend":
+            return "suspender assinatura (revoga acesso do cliente final)";
+        default:
+            return action;
+    }
+}

package/dist/tools/metrics.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Grupo C (parte 1) — Métricas (1 ferramenta)
+ *
+ * get_metrics_overview
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AtehraClient } from "../client.js";
+export declare function registerMetricsTools(server: McpServer, client: AtehraClient): void;

package/dist/tools/metrics.js

@@ -0,0 +1,42 @@
+/**
+ * Grupo C (parte 1) — Métricas (1 ferramenta)
+ *
+ * get_metrics_overview
+ */
+import { z } from "zod";
+export function registerMetricsTools(server, client) {
+    server.tool("get_metrics_overview", "Retorna a visão geral dos números do negócio pra um período: receita total, MRR (receita recorrente mensal), assinaturas ativas, total de clientes, taxa de cancelamento (churn), ARPU (receita média por cliente) e LTV (valor total do cliente). Use sempre que o usuário perguntar como o negócio está indo, ou pedir números do mês/comparação entre períodos.", {
+        period: z
+            .string()
+            .regex(/^\d{4}-\d{2}$/, "Formato deve ser YYYY-MM (ex: '2026-05').")
+            .optional()
+            .describe("Período no formato YYYY-MM. Default: mês atual."),
+    }, async ({ period }) => {
+        const metrics = await client.request("GET", "/v1/metrics/overview", {
+            query: period ? { period } : undefined,
+        });
+        const formatBRL = (cents) => `R$ ${(cents / 100).toLocaleString("pt-BR", { minimumFractionDigits: 2 })}`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `Visão geral — período ${metrics.period}`,
+                        ``,
+                        `Receita total no período: ${formatBRL(metrics.revenue)}`,
+                        `MRR (receita recorrente mensal): ${formatBRL(metrics.mrr)}`,
+                        `ARR (receita recorrente anual projetada): ${formatBRL(metrics.arr)}`,
+                        ``,
+                        `Assinaturas ativas: ${metrics.activeSubscriptions}`,
+                        `Em teste grátis: ${metrics.trialingSubscriptions}`,
+                        `Total de clientes: ${metrics.totalCustomers}`,
+                        ``,
+                        `ARPU (receita média por cliente): ${formatBRL(metrics.arpu)}`,
+                        `LTV (valor total estimado por cliente): ${formatBRL(metrics.ltv)}`,
+                        `Taxa de cancelamento (churn): ${metrics.churnRate.toFixed(2)}%`,
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/plans.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Grupo B (parte 2) — Planos (1 ferramenta)
+ *
+ * create_plan
+ *
+ * A plataforma Atehra é baseada em planos. Toda cobrança é cobrança de um plano.
+ * Pra cobrar valor avulso arbitrário (ex: "R$ 2.000"), o caller precisa criar
+ * um plano com aquele preço primeiro e depois criar a checkout session.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AtehraClient } from "../client.js";
+export declare function registerPlanTools(server: McpServer, client: AtehraClient): void;

package/dist/tools/plans.js

@@ -0,0 +1,64 @@
+/**
+ * Grupo B (parte 2) — Planos (1 ferramenta)
+ *
+ * create_plan
+ *
+ * A plataforma Atehra é baseada em planos. Toda cobrança é cobrança de um plano.
+ * Pra cobrar valor avulso arbitrário (ex: "R$ 2.000"), o caller precisa criar
+ * um plano com aquele preço primeiro e depois criar a checkout session.
+ */
+import { z } from "zod";
+export function registerPlanTools(server, client) {
+    server.tool("create_plan", "Cria um plano de produto. Toda cobrança na Atehra é feita em cima de um plano. Use 'one_time' pra cobrança avulsa (ex: 'Pacote 2000') ou 'subscription' pra assinatura recorrente (mensal/anual). Depois use create_checkout_session ou create_checkout_link pra cobrar.", {
+        name: z.string().min(1).describe("Nome legível do plano (ex: 'Plano Premium', 'Cobrança Avulsa 2000')."),
+        slug: z
+            .string()
+            .regex(/^[a-z0-9_-]+$/, "Slug deve ter só letras minúsculas, números, hifens e underscores.")
+            .min(1)
+            .describe("Slug único usado em URLs (ex: 'premium', 'avulso_2000', 'pacote-pro')."),
+        price: z
+            .number()
+            .int()
+            .positive()
+            .describe("Preço em centavos (ex: 200000 = R$ 2.000,00)."),
+        type: z
+            .enum(["subscription", "one_time"])
+            .describe("'subscription' pra recorrente. 'one_time' pra pagamento único (cobrança avulsa)."),
+        interval: z
+            .enum(["month", "year"])
+            .optional()
+            .describe("Apenas pra type=subscription: 'month' ou 'year'. Default: 'month'."),
+        description: z.string().optional().describe("Descrição opcional pro cliente final."),
+        trialDays: z.number().int().nonnegative().optional().describe("Dias de teste grátis. Só pra assinatura."),
+    }, async ({ name, slug, price, type, interval, description, trialDays }) => {
+        const body = { name, slug, price, type };
+        if (description !== undefined)
+            body["description"] = description;
+        if (type === "subscription") {
+            body["interval"] = interval ?? "month";
+            if (trialDays !== undefined) {
+                body["trialType"] = "time";
+                body["trialDays"] = trialDays;
+            }
+        }
+        const plan = await client.request("POST", "/v1/plans", { body });
+        const formatBRL = (cents) => `R$ ${(cents / 100).toLocaleString("pt-BR", { minimumFractionDigits: 2 })}`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `Plano criado:`,
+                        `  ID: ${plan.id}`,
+                        `  Nome: ${plan.name}`,
+                        `  Slug: ${plan.slug}`,
+                        `  Tipo: ${plan.type}${type === "subscription" ? ` (${interval ?? "month"})` : ""}`,
+                        `  Preço: ${formatBRL(plan.price)}`,
+                        ``,
+                        `Use o ID do plano (${plan.id}) pra criar cobranças via create_checkout_session ou links via create_checkout_link.`,
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@atehra/mcp",
+  "version": "0.1.0",
+  "description": "Servidor MCP oficial da Atehra — opere a infraestrutura financeira BR via Claude, Cursor, ChatGPT e qualquer cliente MCP",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "atehra-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "smoke": "node --test dist/tests/smoke.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "atehra",
+    "mcp",
+    "model-context-protocol",
+    "fintech",
+    "billing",
+    "brazil",
+    "pix",
+    "boleto",
+    "claude",
+    "cursor"
+  ],
+  "license": "MIT",
+  "homepage": "https://atehra.com/mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/atehra/atehra.git",
+    "directory": "mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}