@atehra/mcp 0.1.0 → 0.2.0

package/README.md

@@ -4,6 +4,29 @@ Servidor MCP (Model Context Protocol) oficial da Atehra. Permite que Claude, Cur
 
 > **A primeira fintech brasileira projetada pra rodar via agente de IA.**
 
+## Dois jeitos de usar
+
+| Jeito | Quando usar | Como |
+|---|---|---|
+| **Remoto (HTTP/SSE)** | Maioria dos casos. Sem instalar nada. | Cola URL na UI dos Connectors do Claude |
+| **Local (stdio)** | Self-hosting ou ambientes sem internet | `npx -y @atehra/mcp` via config JSON |
+
+## Uso remoto (recomendado) — UI dos Connectors
+
+No Claude Desktop, vai em **Settings → Connectors → Adicionar conector personalizado** e cola:
+
+```
+URL: https://atehra-mcp-production.up.railway.app/mcp
+```
+
+Em **Configurações avançadas**, adiciona header:
+
+```
+x-api-key: atk_test_SUA_CHAVE_AQUI
+```
+
+Salva. Pronto — 16 ferramentas Atehra disponíveis no Claude.
+
 ## O que dá pra fazer
 
 Com este servidor ligado, seu agente de IA pode:
@@ -17,12 +40,13 @@ Com este servidor ligado, seu agente de IA pode:
 - **Ver métricas do negócio** (receita recorrente mensal, taxa de cancelamento, valor por cliente)
 - **Listar clientes, assinaturas e faturas** com filtros
 
-## Instalação
+## Uso local (stdio)
 
 ### Pré-requisitos
 
 1. Conta na Atehra (`atehra.com`)
 2. API key (`atk_test_...` pra sandbox, `atk_live_...` pra produção)
+3. Node.js 18+
 
 ### No Claude Desktop
 

package/dist/env.d.ts

@@ -1,11 +1,16 @@
 /**
- * Lê e valida variáveis de ambiente.
+ * Configuração do servidor MCP.
  *
- * ATEHRA_API_KEY (obrigatória) — chave da API. Prefixo determina o modo:
+ * Duas formas de criar:
+ *
+ *   1. loadEnv() — lê do process.env (uso stdio: ATEHRA_API_KEY + ATEHRA_BASE_URL)
+ *
+ *   2. envFromApiKey(apiKey, baseUrl?) — constrói a partir de uma chave passada
+ *      em runtime (uso HTTP: chave vem do header da requisição)
+ *
+ * Em ambos os casos, o modo (sandbox vs produção) é detectado pelo prefixo da chave:
  *   - 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 {
@@ -13,4 +18,6 @@ export interface Env {
     baseUrl: string;
     mode: Mode;
 }
+export declare function detectMode(apiKey: string): Mode;
+export declare function envFromApiKey(apiKey: string, baseUrl?: string): Env;
 export declare function loadEnv(): Env;

package/dist/env.js

@@ -1,24 +1,34 @@
 /**
- * Lê e valida variáveis de ambiente.
+ * Configuração do servidor MCP.
  *
- * ATEHRA_API_KEY (obrigatória) — chave da API. Prefixo determina o modo:
+ * Duas formas de criar:
+ *
+ *   1. loadEnv() — lê do process.env (uso stdio: ATEHRA_API_KEY + ATEHRA_BASE_URL)
+ *
+ *   2. envFromApiKey(apiKey, baseUrl?) — constrói a partir de uma chave passada
+ *      em runtime (uso HTTP: chave vem do header da requisição)
+ *
+ * Em ambos os casos, o modo (sandbox vs produção) é detectado pelo prefixo da chave:
  *   - atk_test_... → sandbox
  *   - atk_live_... → produção
- *
- * ATEHRA_BASE_URL (opcional) — URL base da API. Default: https://api.atehra.com
  */
+const DEFAULT_BASE_URL = "https://api.atehra.com";
+export function detectMode(apiKey) {
+    if (apiKey.startsWith("atk_live_"))
+        return "live";
+    if (apiKey.startsWith("atk_test_"))
+        return "test";
+    throw new Error("Chave Atehra com prefixo inválido. Use atk_test_... (sandbox) ou atk_live_... (produção).");
+}
+export function envFromApiKey(apiKey, baseUrl) {
+    const mode = detectMode(apiKey);
+    const resolvedBaseUrl = (baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    return { apiKey, baseUrl: resolvedBaseUrl, mode };
+}
 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 };
+    return envFromApiKey(apiKey, process.env["ATEHRA_BASE_URL"]);
 }

package/dist/http-handler.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Handler HTTP do MCP — adapta uma requisição HTTP em uma sessão MCP.
+ *
+ * Usa o transporte Streamable HTTP do SDK oficial (modo stateless — cada
+ * requisição cria seu próprio servidor MCP). Isso simplifica deploy em
+ * ambientes serverless (Vercel, Cloudflare Workers, etc.) onde não há
+ * estado persistente entre invocações.
+ *
+ * Auth: lê a chave Atehra do header `x-api-key` ou `authorization: Bearer ...`.
+ * Sem chave, responde 401.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+export interface HttpHandlerOptions {
+    /** URL base da API Atehra. Default: https://api.atehra.com */
+    baseUrl?: string;
+}
+/**
+ * Handler principal. Use em qualquer framework HTTP Node.js
+ * (express, fastify, vercel function, raw http server).
+ *
+ * Espera o body já parseado em opts.body (pra POST). Pra GET (SSE), passa null.
+ */
+export declare function handleMcpRequest(req: IncomingMessage, res: ServerResponse, body: unknown, options?: HttpHandlerOptions): Promise<void>;

package/dist/http-handler.js

@@ -0,0 +1,78 @@
+/**
+ * Handler HTTP do MCP — adapta uma requisição HTTP em uma sessão MCP.
+ *
+ * Usa o transporte Streamable HTTP do SDK oficial (modo stateless — cada
+ * requisição cria seu próprio servidor MCP). Isso simplifica deploy em
+ * ambientes serverless (Vercel, Cloudflare Workers, etc.) onde não há
+ * estado persistente entre invocações.
+ *
+ * Auth: lê a chave Atehra do header `x-api-key` ou `authorization: Bearer ...`.
+ * Sem chave, responde 401.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { envFromApiKey } from "./env.js";
+import { AtehraClient } from "./client.js";
+import { registerAllTools } from "./register-tools.js";
+/**
+ * Lê a chave Atehra dos headers da requisição.
+ * Aceita `x-api-key: atk_xxx` OU `authorization: Bearer atk_xxx`.
+ */
+function extractApiKey(req) {
+    const xApiKey = req.headers["x-api-key"];
+    if (typeof xApiKey === "string" && xApiKey.length > 0)
+        return xApiKey;
+    if (Array.isArray(xApiKey) && xApiKey[0])
+        return xApiKey[0];
+    const auth = req.headers["authorization"];
+    if (typeof auth === "string" && auth.toLowerCase().startsWith("bearer ")) {
+        return auth.slice(7).trim();
+    }
+    return null;
+}
+/**
+ * Handler principal. Use em qualquer framework HTTP Node.js
+ * (express, fastify, vercel function, raw http server).
+ *
+ * Espera o body já parseado em opts.body (pra POST). Pra GET (SSE), passa null.
+ */
+export async function handleMcpRequest(req, res, body, options = {}) {
+    const apiKey = extractApiKey(req);
+    if (!apiKey) {
+        res.statusCode = 401;
+        res.setHeader("content-type", "application/json");
+        res.end(JSON.stringify({
+            error: "missing_api_key",
+            message: "Passe a chave Atehra no header 'x-api-key' ou em 'authorization: Bearer atk_...'.",
+        }));
+        return;
+    }
+    let env;
+    try {
+        env = envFromApiKey(apiKey, options.baseUrl);
+    }
+    catch (err) {
+        res.statusCode = 401;
+        res.setHeader("content-type", "application/json");
+        res.end(JSON.stringify({
+            error: "invalid_api_key",
+            message: err instanceof Error ? err.message : String(err),
+        }));
+        return;
+    }
+    const client = new AtehraClient(env);
+    const server = new McpServer({ name: "atehra", version: "0.2.0" });
+    registerAllTools(server, client, env);
+    // Modo stateless: cada requisição cria seu próprio servidor + transporte.
+    // sessionIdGenerator: undefined desliga sessão persistente (compatível com serverless).
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+    });
+    // Limpa quando a conexão fecha (importante em serverless)
+    res.on("close", () => {
+        void transport.close();
+        void server.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, body);
+}

package/dist/index-http.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Entry point HTTP standalone — sobe um servidor HTTP escutando em PORT (default 3000)
+ * que aceita requisições MCP em /mcp.
+ *
+ * Pra uso local (testar antes de deploy) ou self-hosting (rodar em VPS/Railway/etc).
+ *
+ * Pra deploy serverless (Vercel), use api/mcp.ts em vez disso.
+ *
+ * Variáveis de ambiente:
+ *   PORT — porta do servidor (default: 3000)
+ *   ATEHRA_BASE_URL — URL da API Atehra (default: https://api.atehra.com)
+ */
+export {};

package/dist/index-http.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Entry point HTTP standalone — sobe um servidor HTTP escutando em PORT (default 3000)
+ * que aceita requisições MCP em /mcp.
+ *
+ * Pra uso local (testar antes de deploy) ou self-hosting (rodar em VPS/Railway/etc).
+ *
+ * Pra deploy serverless (Vercel), use api/mcp.ts em vez disso.
+ *
+ * Variáveis de ambiente:
+ *   PORT — porta do servidor (default: 3000)
+ *   ATEHRA_BASE_URL — URL da API Atehra (default: https://api.atehra.com)
+ */
+import { createServer } from "node:http";
+import { handleMcpRequest } from "./http-handler.js";
+const PORT = Number.parseInt(process.env["PORT"] ?? "3000", 10);
+const BASE_URL = process.env["ATEHRA_BASE_URL"];
+async function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => {
+            const raw = Buffer.concat(chunks).toString("utf8");
+            if (!raw)
+                return resolve(null);
+            try {
+                resolve(JSON.parse(raw));
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+        req.on("error", reject);
+    });
+}
+const server = createServer(async (req, res) => {
+    // CORS pra cliente MCP web
+    res.setHeader("access-control-allow-origin", "*");
+    res.setHeader("access-control-allow-methods", "GET, POST, OPTIONS");
+    res.setHeader("access-control-allow-headers", "content-type, x-api-key, authorization, mcp-session-id, mcp-protocol-version");
+    res.setHeader("access-control-expose-headers", "mcp-session-id");
+    if (req.method === "OPTIONS") {
+        res.statusCode = 204;
+        res.end();
+        return;
+    }
+    // Health check
+    if (req.url === "/health" || req.url === "/") {
+        res.statusCode = 200;
+        res.setHeader("content-type", "application/json");
+        res.end(JSON.stringify({
+            name: "atehra-mcp",
+            version: "0.2.0",
+            status: "ok",
+            usage: "POST /mcp com header x-api-key: atk_test_... ou atk_live_...",
+        }));
+        return;
+    }
+    // MCP endpoint
+    if (req.url === "/mcp" || req.url?.startsWith("/mcp?")) {
+        try {
+            const body = req.method === "POST" ? await readBody(req) : null;
+            await handleMcpRequest(req, res, body, { baseUrl: BASE_URL });
+        }
+        catch (err) {
+            if (!res.headersSent) {
+                res.statusCode = 500;
+                res.setHeader("content-type", "application/json");
+                res.end(JSON.stringify({
+                    error: "internal_error",
+                    message: err instanceof Error ? err.message : String(err),
+                }));
+            }
+        }
+        return;
+    }
+    // 404
+    res.statusCode = 404;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ error: "not_found" }));
+});
+server.listen(PORT, () => {
+    process.stderr.write(`[atehra-mcp-http] escutando em http://localhost:${PORT}/mcp\n`);
+});

package/dist/index.d.ts

@@ -1,17 +1,10 @@
 #!/usr/bin/env node
 /**
- * @atehra/mcp — Servidor MCP oficial da Atehra
+ * @atehra/mcp — Servidor MCP oficial da Atehra (transporte stdio)
  *
- * Sobe um servidor MCP via stdio e registra as 16 ferramentas da V1:
+ * Pra uso local via npx ou config do Claude Desktop. Lê a chave da API
+ * da variável ATEHRA_API_KEY e roda como subprocess.
  *
- *   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
+ * Pra uso remoto (via UI dos Connectors do Claude), veja src/index-http.ts.
  */
 export {};

package/dist/index.js

@@ -1,47 +1,26 @@
 #!/usr/bin/env node
 /**
- * @atehra/mcp — Servidor MCP oficial da Atehra
+ * @atehra/mcp — Servidor MCP oficial da Atehra (transporte stdio)
  *
- * Sobe um servidor MCP via stdio e registra as 16 ferramentas da V1:
+ * Pra uso local via npx ou config do Claude Desktop. Lê a chave da API
+ * da variável ATEHRA_API_KEY e roda como subprocess.
  *
- *   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
+ * Pra uso remoto (via UI dos Connectors do Claude), veja src/index-http.ts.
  */
 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";
+import { registerAllTools } from "./register-tools.js";
 async function main() {
     const env = loadEnv();
     const client = new AtehraClient(env);
     const server = new McpServer({
         name: "atehra",
-        version: "0.1.0",
+        version: "0.2.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`);
+    registerAllTools(server, client, env);
+    process.stderr.write(`[atehra-mcp] iniciado (stdio). Modo: ${env.mode}. Base URL: ${env.baseUrl}\n`);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/register-tools.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Registro centralizado das 16 ferramentas Atehra.
+ *
+ * Compartilhado entre o transporte stdio (uso local via npx) e o transporte
+ * HTTP/SSE (uso remoto via UI Connectors do Claude). Mantém a lista de tools
+ * em um único lugar — toda nova feature aparece nos dois transportes ao mesmo tempo.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AtehraClient } from "./client.js";
+import type { Env } from "./env.js";
+export declare function registerAllTools(server: McpServer, client: AtehraClient, env: Env): void;

package/dist/register-tools.js

@@ -0,0 +1,23 @@
+/**
+ * Registro centralizado das 16 ferramentas Atehra.
+ *
+ * Compartilhado entre o transporte stdio (uso local via npx) e o transporte
+ * HTTP/SSE (uso remoto via UI Connectors do Claude). Mantém a lista de tools
+ * em um único lugar — toda nova feature aparece nos dois transportes ao mesmo tempo.
+ */
+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";
+export function registerAllTools(server, client, env) {
+    registerBalanceTools(server, client, env);
+    registerCustomerTools(server, client);
+    registerPlanTools(server, client);
+    registerChargeTools(server, client);
+    registerMetricsTools(server, client);
+    registerBillingTools(server, client);
+    registerDunningTools(server, client);
+}

package/package.json

@@ -1,20 +1,22 @@
 {
   "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",
+  "version": "0.2.0",
+  "description": "Servidor MCP oficial da Atehra — opere a infraestrutura financeira BR via Claude, Cursor, ChatGPT e qualquer cliente MCP. Suporta stdio (local) e HTTP/SSE (remoto, via Connectors UI do Claude).",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "atehra-mcp": "dist/index.js"
+    "atehra-mcp": "dist/index.js",
+    "atehra-mcp-http": "dist/index-http.js"
   },
   "files": [
     "dist",
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && chmod +x dist/index.js dist/index-http.js",
     "dev": "tsc --watch",
-    "start": "node dist/index.js",
+    "start": "node dist/index-http.js",
+    "start:stdio": "node dist/index.js",
     "smoke": "node --test dist/tests/smoke.test.js",
     "prepublishOnly": "npm run build"
   },