@codespar/mcp-banco-do-brasil 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,60 @@
+# @codespar/mcp-banco-do-brasil
+
+MCP server for [Banco do Brasil](https://developers.bb.com.br) — Brazil's top public bank.
+
+BB exposes one of the broadest public-bank API surfaces in the country across Pix, Cobranças, Conta-Corrente, Open Finance, and Arrecadação. Merchants doing high-volume Pix and boleto operations integrate directly with BB instead of going through a PSP.
+
+## Status: alpha (`0.1.0-alpha.1`)
+
+BB's Developer Portal is **contract-gated** — the full OpenAPI specs are visible only after merchant onboarding. Pix paths follow the BACEN Pix v2 standard; boleto, account, and statement paths are best-guesses based on BB's public marketing pages and conventions shared with peers (Itaú, Santander, Bradesco). Every unverified path is flagged `TODO(verify)` in `src/index.ts`. Pin to exact versions during `0.1.x`.
+
+## Tools (10)
+
+| Tool | Purpose |
+|---|---|
+| `create_pix_cob` | Create immediate Pix charge (cob) |
+| `get_pix_cob` | Get an immediate Pix charge by txid |
+| `list_pix_cob` | List immediate Pix charges by date range |
+| `create_pix_devolucao` | Refund a received Pix (devolução) |
+| `get_pix_devolucao` | Retrieve a devolução by id |
+| `resolve_dict_key` | Resolve a DICT key to account data |
+| `register_dict_key` | Register a DICT key on a BB account |
+| `delete_dict_key` | Delete a DICT key owned by the merchant |
+| `register_boleto` | Issue a boleto via BB Cobranças |
+| `get_boleto` | Retrieve a boleto by nosso_numero |
+| `cancel_boleto` | Cancel (baixa) an outstanding boleto |
+| `get_account_balance` | Conta-corrente balance |
+| `get_statement` | Account statement transactions |
+
+## Install
+
+```bash
+npm install @codespar/mcp-banco-do-brasil@0.1.0-alpha.1
+```
+
+## Environment
+
+```bash
+BB_CLIENT_ID="..."             # OAuth client_id from developers.bb.com.br
+BB_CLIENT_SECRET="..."         # OAuth client_secret
+BB_DEVELOPER_APP_KEY="..."     # gw-dev-app-key — required on most calls
+BB_CERT_PATH="/abs/path/client.crt"   # mTLS cert (production only)
+BB_KEY_PATH="/abs/path/client.key"    # mTLS key  (production only)
+BB_ENV="sandbox"                       # or "production" (default: sandbox)
+```
+
+## Authentication
+
+- **OAuth2 `client_credentials`** — token endpoint at `oauth.{env}.bb.com.br`. Bearer cached until ~60s before expiry.
+- **mTLS** — required by BACEN for Pix v2 in production. Sandbox typically allows TLS-only; cert/key are optional in sandbox and required in production.
+- **`gw-dev-app-key`** — BB API gateway key, appended as a query param on all calls.
+
+## Run
+
+```bash
+npx @codespar/mcp-banco-do-brasil
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,560 @@
+#!/usr/bin/env node
+/**
+ * MCP Server for Banco do Brasil — Brazil's top public bank.
+ *
+ * BB exposes one of the broadest bank API surfaces in the country, covering
+ * Pix, Cobranças (boleto), Conta-Corrente, Open Finance, and Arrecadação
+ * via the Developer Portal at developers.bb.com.br.
+ *
+ * Tools (13):
+ *   create_pix_cob         — create immediate Pix charge (cob) with QR
+ *   get_pix_cob            — retrieve an immediate Pix charge by txid
+ *   list_pix_cob           — list immediate Pix charges by date range
+ *   create_pix_devolucao   — refund (devolução) a received Pix
+ *   get_pix_devolucao      — retrieve a devolução by id
+ *   resolve_dict_key       — resolve a DICT key to account data
+ *   register_dict_key      — register a DICT key on a BB account
+ *   delete_dict_key        — delete a DICT key owned by the merchant
+ *   register_boleto        — issue a boleto via BB Cobranças
+ *   get_boleto             — retrieve a boleto by nosso_numero
+ *   cancel_boleto          — cancel (baixa) an outstanding boleto
+ *   get_account_balance    — Conta-Corrente balance
+ *   get_statement          — Conta-Corrente statement / transactions
+ *
+ * Authentication
+ *   OAuth 2.0 client_credentials + mandatory mTLS in production. BACEN
+ *   requires mTLS for Pix v2; BB enforces it in production across product
+ *   families. Sandbox typically accepts TLS-only — cert/key envs are
+ *   therefore optional but recommended.
+ *
+ *   Additionally, BB requires a developer-app-key (`gw-dev-app-key`)
+ *   query param on every API call for traffic accounting.
+ *
+ * Version: 0.1.0-alpha.1
+ *   developers.bb.com.br is contract-gated — full OpenAPI specs are visible
+ *   only to onboarded merchants. Pix paths follow BACEN Pix v2 standard.
+ *   Boleto / Conta-Corrente paths are best-guesses based on BB public docs
+ *   and conventions shared with peers (Itaú, Santander, Bradesco). Every
+ *   unverified path is marked TODO(verify). Treat 0.1.x as alpha and pin
+ *   to exact versions.
+ *
+ * Environment
+ *   BB_CLIENT_ID            OAuth client id
+ *   BB_CLIENT_SECRET        OAuth client secret
+ *   BB_DEVELOPER_APP_KEY    gw-dev-app-key query param
+ *   BB_CERT_PATH            path to mTLS client cert (production)
+ *   BB_KEY_PATH             path to mTLS private key (production)
+ *   BB_ENV                  "sandbox" | "production" (default: sandbox)
+ *
+ * Docs: https://developers.bb.com.br
+ */
+import { readFileSync } from "node:fs";
+import { Agent as HttpsAgent } from "node:https";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const CLIENT_ID = process.env.BB_CLIENT_ID || "";
+const CLIENT_SECRET = process.env.BB_CLIENT_SECRET || "";
+const DEVELOPER_APP_KEY = process.env.BB_DEVELOPER_APP_KEY || "";
+const CERT_PATH = process.env.BB_CERT_PATH || "";
+const KEY_PATH = process.env.BB_KEY_PATH || "";
+const BB_ENV = (process.env.BB_ENV || "sandbox").toLowerCase();
+const IS_PROD = BB_ENV === "production";
+// TODO(verify): production base hostnames. BB documents distinct hosts per
+// product family (api.bb.com.br for some, api-pix.bb.com.br for Pix). The
+// sandbox subdomain is api.sandbox.bb.com.br for most products.
+const BASE_URL = IS_PROD ? "https://api.bb.com.br" : "https://api.sandbox.bb.com.br";
+const OAUTH_URL = IS_PROD
+    ? "https://oauth.bb.com.br/oauth/token"
+    : "https://oauth.sandbox.bb.com.br/oauth/token";
+// Lazy-load the mTLS agent so `--help` / schema introspection doesn't crash
+// when certs are missing. mTLS is required by BACEN in production but BB
+// sandbox typically accepts TLS-only.
+let mtlsAgent = null;
+function getMtlsAgent() {
+    if (mtlsAgent)
+        return mtlsAgent;
+    if (!CERT_PATH || !KEY_PATH) {
+        if (IS_PROD) {
+            throw new Error("BB mTLS certificates are required in production. Set BB_CERT_PATH and BB_KEY_PATH " +
+                "to the client cert and private-key files issued by developers.bb.com.br.");
+        }
+        return null; // sandbox: fall back to system TLS
+    }
+    mtlsAgent = new HttpsAgent({
+        cert: readFileSync(CERT_PATH),
+        key: readFileSync(KEY_PATH),
+        keepAlive: true,
+    });
+    return mtlsAgent;
+}
+let tokenCache = null;
+async function getAccessToken() {
+    const now = Date.now();
+    if (tokenCache && tokenCache.expiresAt > now + 60_000) {
+        return tokenCache.accessToken;
+    }
+    const basic = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64");
+    const res = await fetchWithMtls(OAUTH_URL, {
+        method: "POST",
+        headers: {
+            Authorization: `Basic ${basic}`,
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        // TODO(verify): scope. BB scopes are product-specific (cob.write,
+        // cob.read, pix.write, pix.read, dict.read, etc.). The sandbox
+        // commonly accepts a blank/all scope for client_credentials.
+        body: "grant_type=client_credentials",
+    });
+    if (!res.ok) {
+        throw new Error(`BB OAuth ${res.status}: ${await res.text()}`);
+    }
+    const data = (await res.json());
+    tokenCache = {
+        accessToken: data.access_token,
+        expiresAt: now + data.expires_in * 1000,
+    };
+    return data.access_token;
+}
+// Node's global fetch does not honour an https.Agent for mTLS; we drop down
+// to node:https manually so the client cert is presented on every call.
+async function fetchWithMtls(url, init) {
+    const agent = getMtlsAgent();
+    const { request } = await import("node:https");
+    return new Promise((resolve, reject) => {
+        const u = new URL(url);
+        const req = request({
+            ...(agent ? { agent } : {}),
+            method: init.method,
+            hostname: u.hostname,
+            port: u.port || 443,
+            path: u.pathname + u.search,
+            headers: init.headers ?? {},
+        }, (res) => {
+            const chunks = [];
+            res.on("data", (c) => chunks.push(c));
+            res.on("end", () => {
+                const buf = Buffer.concat(chunks);
+                const status = res.statusCode ?? 0;
+                resolve({
+                    ok: status >= 200 && status < 300,
+                    status,
+                    text: async () => buf.toString("utf8"),
+                    json: async () => JSON.parse(buf.toString("utf8")),
+                });
+            });
+        });
+        req.on("error", reject);
+        if (init.body)
+            req.write(init.body);
+        req.end();
+    });
+}
+function appendAppKey(path) {
+    if (!DEVELOPER_APP_KEY)
+        return path;
+    const sep = path.includes("?") ? "&" : "?";
+    return `${path}${sep}gw-dev-app-key=${encodeURIComponent(DEVELOPER_APP_KEY)}`;
+}
+async function bbRequest(method, path, body) {
+    const token = await getAccessToken();
+    const fullPath = appendAppKey(path);
+    const res = await fetchWithMtls(`${BASE_URL}${fullPath}`, {
+        method,
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${token}`,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        throw new Error(`BB API ${res.status}: ${await res.text()}`);
+    }
+    return res.json();
+}
+const server = new Server({ name: "mcp-banco-do-brasil", version: "0.1.0-alpha.1" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "create_pix_cob",
+            description: "Create an immediate Pix charge (cob) with QR code. Returns txid, EMV copy-paste payload, and location URL. BACEN Pix v2 standard.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    amount: { type: "string", description: "Amount in BRL major units, e.g. '99.90'" },
+                    payer: {
+                        type: "object",
+                        description: "Payer identification (CPF/CNPJ + name)",
+                        properties: {
+                            document: { type: "string", description: "CPF or CNPJ digits only" },
+                            name: { type: "string" },
+                        },
+                    },
+                    expires_in: { type: "number", description: "QR lifetime in seconds (default 3600)" },
+                    description: { type: "string", description: "Payer-visible description (solicitacaoPagador)" },
+                    dict_key: { type: "string", description: "Recebedor DICT key — must be a key owned by the merchant" },
+                    txid: { type: "string", description: "Optional merchant-supplied txid (26-35 alphanumeric). Omit to have BCB assign one." },
+                },
+                required: ["amount", "dict_key"],
+            },
+        },
+        {
+            name: "get_pix_cob",
+            description: "Retrieve an immediate Pix charge by its txid.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    txid: { type: "string", description: "BACEN txid (26-35 alphanumeric)" },
+                },
+                required: ["txid"],
+            },
+        },
+        {
+            name: "list_pix_cob",
+            description: "List immediate Pix charges (cob) by date range. Paginated per BACEN Pix v2.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    from: { type: "string", description: "Start date-time ISO-8601 (inicio)" },
+                    to: { type: "string", description: "End date-time ISO-8601 (fim)" },
+                    status: { type: "string", description: "Status filter: ATIVA | CONCLUIDA | REMOVIDA_PELO_USUARIO_RECEBEDOR | REMOVIDA_PELO_PSP" },
+                    page: { type: "number", description: "paginacao.paginaAtual" },
+                    page_size: { type: "number", description: "paginacao.itensPorPagina" },
+                },
+                required: ["from", "to"],
+            },
+        },
+        {
+            name: "create_pix_devolucao",
+            description: "Refund (devolução) a previously received Pix. Must reference the original endToEndId and a merchant-side refund id.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    end_to_end_id: { type: "string", description: "Original Pix endToEndId" },
+                    refund_id: { type: "string", description: "Merchant-side refund id (id da devolução, alphanumeric up to 35)" },
+                    amount: { type: "string", description: "Refund amount in BRL major units. Omit for full refund." },
+                    reason: { type: "string", description: "Free-text reason (descricao)" },
+                },
+                required: ["end_to_end_id", "refund_id"],
+            },
+        },
+        {
+            name: "get_pix_devolucao",
+            description: "Retrieve a Pix devolução by its endToEndId + refund id.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    end_to_end_id: { type: "string", description: "Original Pix endToEndId" },
+                    refund_id: { type: "string", description: "Merchant-side refund id" },
+                },
+                required: ["end_to_end_id", "refund_id"],
+            },
+        },
+        {
+            name: "resolve_dict_key",
+            description: "Resolve a DICT key (CPF, CNPJ, email, phone, EVP) to the owner's account data before sending a Pix. Subject to BCB rate limits per consenting payer.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    key: { type: "string", description: "DICT key — CPF, CNPJ, email, phone (+55...), or EVP UUID" },
+                    payer_document: { type: "string", description: "End-payer CPF/CNPJ for BCB audit logging" },
+                },
+                required: ["key"],
+            },
+        },
+        {
+            name: "register_dict_key",
+            description: "Register a DICT key on a BB account owned by the merchant. Some key types (email/phone) require BCB confirmation flows.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    key_type: { type: "string", description: "DICT key type: CPF | CNPJ | EMAIL | PHONE | EVP" },
+                    key: { type: "string", description: "Key value. Omit for EVP (BCB generates UUID)." },
+                    account: {
+                        type: "object",
+                        properties: {
+                            branch: { type: "string", description: "Agência" },
+                            account: { type: "string", description: "Conta" },
+                            account_type: { type: "string", description: "CACC | SVGS | SLRY | TRAN" },
+                        },
+                        required: ["branch", "account", "account_type"],
+                    },
+                },
+                required: ["key_type", "account"],
+            },
+        },
+        {
+            name: "delete_dict_key",
+            description: "Delete a DICT key owned by the merchant. Irreversible — key becomes available for re-registration after BCB lockout window.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    key: { type: "string", description: "DICT key value to delete" },
+                },
+                required: ["key"],
+            },
+        },
+        {
+            name: "register_boleto",
+            description: "Issue a boleto via BB Cobranças. Returns nosso_numero, linha digitável, barcode, and PDF URL.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    amount: { type: "string", description: "Amount in BRL major units, e.g. '150.00'" },
+                    due_date: { type: "string", description: "Due date ISO-8601 (YYYY-MM-DD)" },
+                    convenio: { type: "string", description: "BB convênio (numeroConvenio) registered for the merchant" },
+                    payer: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string" },
+                            document: { type: "string", description: "CPF or CNPJ digits only" },
+                            address: {
+                                type: "object",
+                                properties: {
+                                    street: { type: "string" },
+                                    number: { type: "string" },
+                                    district: { type: "string" },
+                                    city: { type: "string" },
+                                    state: { type: "string", description: "2-letter UF code" },
+                                    postal_code: { type: "string", description: "CEP digits only" },
+                                },
+                            },
+                        },
+                        required: ["name", "document"],
+                    },
+                    our_number: { type: "string", description: "Nosso_numero. Omit to have BB assign one." },
+                    fine: { type: "object", description: "Multa: { percentage?, amount?, days_after_due? }" },
+                    interest: { type: "object", description: "Juros: { percentage?, amount? }" },
+                    discount: { type: "object", description: "Desconto: { percentage?, amount?, until? }" },
+                },
+                required: ["amount", "due_date", "convenio", "payer"],
+            },
+        },
+        {
+            name: "get_boleto",
+            description: "Retrieve a boleto by nosso_numero.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    nosso_numero: { type: "string", description: "BB nosso_numero" },
+                    convenio: { type: "string", description: "BB convênio" },
+                },
+                required: ["nosso_numero", "convenio"],
+            },
+        },
+        {
+            name: "cancel_boleto",
+            description: "Cancel (baixa) an outstanding boleto before payment.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    nosso_numero: { type: "string", description: "BB nosso_numero" },
+                    convenio: { type: "string", description: "BB convênio" },
+                    reason: { type: "string", description: "Cancellation reason code or free text" },
+                },
+                required: ["nosso_numero", "convenio"],
+            },
+        },
+        {
+            name: "get_account_balance",
+            description: "Retrieve the current balance of a BB conta-corrente (checking) account.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    branch: { type: "string", description: "Agência (4 digits)" },
+                    account: { type: "string", description: "Conta (digits, no DV)" },
+                    account_dv: { type: "string", description: "Conta DV (1 digit)" },
+                },
+                required: ["branch", "account"],
+            },
+        },
+        {
+            name: "get_statement",
+            description: "Retrieve account statement transactions for a BB conta-corrente over a date range. Paginated.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    branch: { type: "string", description: "Agência" },
+                    account: { type: "string", description: "Conta" },
+                    from: { type: "string", description: "Start date ISO-8601 (YYYY-MM-DD)" },
+                    to: { type: "string", description: "End date ISO-8601 (YYYY-MM-DD)" },
+                    page: { type: "number", description: "Page number (1-indexed)" },
+                    page_size: { type: "number", description: "Items per page (default 50)" },
+                },
+                required: ["branch", "account", "from", "to"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const a = (args ?? {});
+    try {
+        switch (name) {
+            case "create_pix_cob": {
+                // TODO(verify): path. BACEN Pix v2 standard is PUT /pix/v2/cob/{txid}
+                // when txid is supplied, POST /pix/v2/cob otherwise. BB hosts Pix
+                // under api-pix.bb.com.br in production with /pix/v2 prefix.
+                const txid = a.txid ? `/${encodeURIComponent(String(a.txid))}` : "";
+                const method = a.txid ? "PUT" : "POST";
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(await bbRequest(method, `/pix/v2/cob${txid}`, a), null, 2) },
+                    ],
+                };
+            }
+            case "get_pix_cob": {
+                const txid = encodeURIComponent(String(a.txid ?? ""));
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(await bbRequest("GET", `/pix/v2/cob/${txid}`), null, 2) },
+                    ],
+                };
+            }
+            case "list_pix_cob": {
+                const params = new URLSearchParams();
+                if (a.from !== undefined)
+                    params.set("inicio", String(a.from));
+                if (a.to !== undefined)
+                    params.set("fim", String(a.to));
+                if (a.status !== undefined)
+                    params.set("status", String(a.status));
+                if (a.page !== undefined)
+                    params.set("paginacao.paginaAtual", String(a.page));
+                if (a.page_size !== undefined)
+                    params.set("paginacao.itensPorPagina", String(a.page_size));
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(await bbRequest("GET", `/pix/v2/cob?${params}`), null, 2) },
+                    ],
+                };
+            }
+            case "create_pix_devolucao": {
+                const e2e = encodeURIComponent(String(a.end_to_end_id ?? ""));
+                const rid = encodeURIComponent(String(a.refund_id ?? ""));
+                const body = {};
+                if (a.amount !== undefined)
+                    body.valor = a.amount;
+                if (a.reason !== undefined)
+                    body.descricao = a.reason;
+                // TODO(verify): path. BACEN standard PUT /pix/v2/pix/{e2e}/devolucao/{id}.
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(await bbRequest("PUT", `/pix/v2/pix/${e2e}/devolucao/${rid}`, body), null, 2) },
+                    ],
+                };
+            }
+            case "get_pix_devolucao": {
+                const e2e = encodeURIComponent(String(a.end_to_end_id ?? ""));
+                const rid = encodeURIComponent(String(a.refund_id ?? ""));
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(await bbRequest("GET", `/pix/v2/pix/${e2e}/devolucao/${rid}`), null, 2) },
+                    ],
+                };
+            }
+            case "resolve_dict_key": {
+                const key = encodeURIComponent(String(a.key ?? ""));
+                const qs = a.payer_document ? `&payerDocument=${encodeURIComponent(String(a.payer_document))}` : "";
+                // TODO(verify): path. BACEN DICT consulta is GET /dict/v2/keys/{key}; BB
+                // may also expose it under /pix/v2/dict for client convenience.
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(await bbRequest("GET", `/dict/v2/keys/${key}${qs ? `?${qs.slice(1)}` : ""}`), null, 2) },
+                    ],
+                };
+            }
+            case "register_dict_key": {
+                // TODO(verify): path. BACEN DICT registration is POST /dict/v2/keys
+                // with a chaveEntries body; BB may add a confirmação flow for email/phone.
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(await bbRequest("POST", "/dict/v2/keys", a), null, 2) },
+                    ],
+                };
+            }
+            case "delete_dict_key": {
+                const key = encodeURIComponent(String(a.key ?? ""));
+                // TODO(verify): path. BACEN DICT delete is DELETE /dict/v2/keys/{key}.
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(await bbRequest("DELETE", `/dict/v2/keys/${key}`), null, 2) },
+                    ],
+                };
+            }
+            case "register_boleto": {
+                // TODO(verify): path. BB Cobranças v2 registration is commonly
+                // POST /cobrancas/v2/boletos with numeroConvenio carried in the body.
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(await bbRequest("POST", "/cobrancas/v2/boletos", a), null, 2) },
+                    ],
+                };
+            }
+            case "get_boleto": {
+                const nn = encodeURIComponent(String(a.nosso_numero ?? ""));
+                const conv = encodeURIComponent(String(a.convenio ?? ""));
+                // TODO(verify): path. BB exposes detail at GET /cobrancas/v2/boletos/{nosso_numero}?numeroConvenio=...
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(await bbRequest("GET", `/cobrancas/v2/boletos/${nn}?numeroConvenio=${conv}`), null, 2) },
+                    ],
+                };
+            }
+            case "cancel_boleto": {
+                const nn = encodeURIComponent(String(a.nosso_numero ?? ""));
+                const conv = encodeURIComponent(String(a.convenio ?? ""));
+                const body = { numeroConvenio: a.convenio };
+                if (a.reason !== undefined)
+                    body.motivoBaixa = a.reason;
+                // TODO(verify): path. BB baixa is POST /cobrancas/v2/boletos/{nn}/baixar.
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(await bbRequest("POST", `/cobrancas/v2/boletos/${nn}/baixar?numeroConvenio=${conv}`, body), null, 2) },
+                    ],
+                };
+            }
+            case "get_account_balance": {
+                const branch = encodeURIComponent(String(a.branch ?? ""));
+                const account = encodeURIComponent(String(a.account ?? ""));
+                const dv = a.account_dv ? `&digitoConta=${encodeURIComponent(String(a.account_dv))}` : "";
+                // TODO(verify): path. BB Conta-Corrente saldo: GET /conta-corrente/v1/saldo?agencia=&conta=
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(await bbRequest("GET", `/conta-corrente/v1/saldo?agencia=${branch}&conta=${account}${dv}`), null, 2) },
+                    ],
+                };
+            }
+            case "get_statement": {
+                const params = new URLSearchParams();
+                params.set("agencia", String(a.branch ?? ""));
+                params.set("conta", String(a.account ?? ""));
+                params.set("dataInicio", String(a.from ?? ""));
+                params.set("dataFim", String(a.to ?? ""));
+                if (a.page !== undefined)
+                    params.set("pagina", String(a.page));
+                if (a.page_size !== undefined)
+                    params.set("tamanhoPagina", String(a.page_size));
+                // TODO(verify): path. BB extrato: GET /conta-corrente/v1/extrato.
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(await bbRequest("GET", `/conta-corrente/v1/extrato?${params}`), null, 2) },
+                    ],
+                };
+            }
+            default:
+                return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+        }
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@codespar/mcp-banco-do-brasil",
+  "version": "0.1.0-alpha.1",
+  "description": "MCP server for Banco do Brasil — Brazil's top public bank. Pix, Cobrança (boleto), Conta-Corrente, and Arrecadação via BB's Developer Portal APIs (OAuth2 + mTLS).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "mcp-banco-do-brasil": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.8.0"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "banco-do-brasil",
+    "bb",
+    "banking",
+    "pix",
+    "boleto",
+    "cobranca",
+    "open-finance",
+    "brazil"
+  ],
+  "mcpName": "io.github.codespar/banco-do-brasil"
+}

package/server.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.codespar/banco-do-brasil",
+  "description": "MCP server for Banco do Brasil — Brazil's top public bank. Pix, Cobrança (boleto), Conta-Corrente, and Arrecadação via BB's Developer Portal APIs (OAuth2 + mTLS).",
+  "repository": {
+    "url": "https://github.com/codespar/mcp-dev-brasil",
+    "source": "github",
+    "subfolder": "packages/banking/banco-do-brasil"
+  },
+  "version": "0.1.0-alpha.1",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@codespar/mcp-banco-do-brasil",
+      "version": "0.1.0-alpha.1",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "BB_CLIENT_ID",
+          "description": "Banco do Brasil OAuth client_id issued via developers.bb.com.br after contract onboarding.",
+          "isRequired": true,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "BB_CLIENT_SECRET",
+          "description": "Banco do Brasil OAuth client_secret.",
+          "isRequired": true,
+          "format": "string",
+          "isSecret": true
+        },
+        {
+          "name": "BB_DEVELOPER_APP_KEY",
+          "description": "BB Developer App Key (gw-dev-app-key) — appended as a query param on most BB API calls.",
+          "isRequired": true,
+          "format": "string",
+          "isSecret": true
+        },
+        {
+          "name": "BB_CERT_PATH",
+          "description": "Absolute path to the mTLS client certificate (.crt or .pem). BACEN mandates mTLS for Pix v2 in production.",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "BB_KEY_PATH",
+          "description": "Absolute path to the mTLS private key (.key or .pem).",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": true
+        },
+        {
+          "name": "BB_ENV",
+          "description": "Environment: 'sandbox' or 'production'. Defaults to 'sandbox'.",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

package/src/index.ts

@@ -0,0 +1,586 @@
+#!/usr/bin/env node
+
+/**
+ * MCP Server for Banco do Brasil — Brazil's top public bank.
+ *
+ * BB exposes one of the broadest bank API surfaces in the country, covering
+ * Pix, Cobranças (boleto), Conta-Corrente, Open Finance, and Arrecadação
+ * via the Developer Portal at developers.bb.com.br.
+ *
+ * Tools (13):
+ *   create_pix_cob         — create immediate Pix charge (cob) with QR
+ *   get_pix_cob            — retrieve an immediate Pix charge by txid
+ *   list_pix_cob           — list immediate Pix charges by date range
+ *   create_pix_devolucao   — refund (devolução) a received Pix
+ *   get_pix_devolucao      — retrieve a devolução by id
+ *   resolve_dict_key       — resolve a DICT key to account data
+ *   register_dict_key      — register a DICT key on a BB account
+ *   delete_dict_key        — delete a DICT key owned by the merchant
+ *   register_boleto        — issue a boleto via BB Cobranças
+ *   get_boleto             — retrieve a boleto by nosso_numero
+ *   cancel_boleto          — cancel (baixa) an outstanding boleto
+ *   get_account_balance    — Conta-Corrente balance
+ *   get_statement          — Conta-Corrente statement / transactions
+ *
+ * Authentication
+ *   OAuth 2.0 client_credentials + mandatory mTLS in production. BACEN
+ *   requires mTLS for Pix v2; BB enforces it in production across product
+ *   families. Sandbox typically accepts TLS-only — cert/key envs are
+ *   therefore optional but recommended.
+ *
+ *   Additionally, BB requires a developer-app-key (`gw-dev-app-key`)
+ *   query param on every API call for traffic accounting.
+ *
+ * Version: 0.1.0-alpha.1
+ *   developers.bb.com.br is contract-gated — full OpenAPI specs are visible
+ *   only to onboarded merchants. Pix paths follow BACEN Pix v2 standard.
+ *   Boleto / Conta-Corrente paths are best-guesses based on BB public docs
+ *   and conventions shared with peers (Itaú, Santander, Bradesco). Every
+ *   unverified path is marked TODO(verify). Treat 0.1.x as alpha and pin
+ *   to exact versions.
+ *
+ * Environment
+ *   BB_CLIENT_ID            OAuth client id
+ *   BB_CLIENT_SECRET        OAuth client secret
+ *   BB_DEVELOPER_APP_KEY    gw-dev-app-key query param
+ *   BB_CERT_PATH            path to mTLS client cert (production)
+ *   BB_KEY_PATH             path to mTLS private key (production)
+ *   BB_ENV                  "sandbox" | "production" (default: sandbox)
+ *
+ * Docs: https://developers.bb.com.br
+ */
+
+import { readFileSync } from "node:fs";
+import { Agent as HttpsAgent } from "node:https";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const CLIENT_ID = process.env.BB_CLIENT_ID || "";
+const CLIENT_SECRET = process.env.BB_CLIENT_SECRET || "";
+const DEVELOPER_APP_KEY = process.env.BB_DEVELOPER_APP_KEY || "";
+const CERT_PATH = process.env.BB_CERT_PATH || "";
+const KEY_PATH = process.env.BB_KEY_PATH || "";
+const BB_ENV = (process.env.BB_ENV || "sandbox").toLowerCase();
+const IS_PROD = BB_ENV === "production";
+
+// TODO(verify): production base hostnames. BB documents distinct hosts per
+// product family (api.bb.com.br for some, api-pix.bb.com.br for Pix). The
+// sandbox subdomain is api.sandbox.bb.com.br for most products.
+const BASE_URL = IS_PROD ? "https://api.bb.com.br" : "https://api.sandbox.bb.com.br";
+const OAUTH_URL = IS_PROD
+  ? "https://oauth.bb.com.br/oauth/token"
+  : "https://oauth.sandbox.bb.com.br/oauth/token";
+
+// Lazy-load the mTLS agent so `--help` / schema introspection doesn't crash
+// when certs are missing. mTLS is required by BACEN in production but BB
+// sandbox typically accepts TLS-only.
+let mtlsAgent: HttpsAgent | null = null;
+function getMtlsAgent(): HttpsAgent | null {
+  if (mtlsAgent) return mtlsAgent;
+  if (!CERT_PATH || !KEY_PATH) {
+    if (IS_PROD) {
+      throw new Error(
+        "BB mTLS certificates are required in production. Set BB_CERT_PATH and BB_KEY_PATH " +
+          "to the client cert and private-key files issued by developers.bb.com.br."
+      );
+    }
+    return null; // sandbox: fall back to system TLS
+  }
+  mtlsAgent = new HttpsAgent({
+    cert: readFileSync(CERT_PATH),
+    key: readFileSync(KEY_PATH),
+    keepAlive: true,
+  });
+  return mtlsAgent;
+}
+
+interface TokenCache {
+  accessToken: string;
+  expiresAt: number;
+}
+
+let tokenCache: TokenCache | null = null;
+
+async function getAccessToken(): Promise<string> {
+  const now = Date.now();
+  if (tokenCache && tokenCache.expiresAt > now + 60_000) {
+    return tokenCache.accessToken;
+  }
+  const basic = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64");
+  const res = await fetchWithMtls(OAUTH_URL, {
+    method: "POST",
+    headers: {
+      Authorization: `Basic ${basic}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    // TODO(verify): scope. BB scopes are product-specific (cob.write,
+    // cob.read, pix.write, pix.read, dict.read, etc.). The sandbox
+    // commonly accepts a blank/all scope for client_credentials.
+    body: "grant_type=client_credentials",
+  });
+  if (!res.ok) {
+    throw new Error(`BB OAuth ${res.status}: ${await res.text()}`);
+  }
+  const data = (await res.json()) as { access_token: string; expires_in: number };
+  tokenCache = {
+    accessToken: data.access_token,
+    expiresAt: now + data.expires_in * 1000,
+  };
+  return data.access_token;
+}
+
+// Node's global fetch does not honour an https.Agent for mTLS; we drop down
+// to node:https manually so the client cert is presented on every call.
+async function fetchWithMtls(
+  url: string,
+  init: { method: string; headers?: Record<string, string>; body?: string }
+): Promise<{ ok: boolean; status: number; text: () => Promise<string>; json: () => Promise<unknown> }> {
+  const agent = getMtlsAgent();
+  const { request } = await import("node:https");
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const req = request(
+      {
+        ...(agent ? { agent } : {}),
+        method: init.method,
+        hostname: u.hostname,
+        port: u.port || 443,
+        path: u.pathname + u.search,
+        headers: init.headers ?? {},
+      },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on("data", (c: Buffer) => chunks.push(c));
+        res.on("end", () => {
+          const buf = Buffer.concat(chunks);
+          const status = res.statusCode ?? 0;
+          resolve({
+            ok: status >= 200 && status < 300,
+            status,
+            text: async () => buf.toString("utf8"),
+            json: async () => JSON.parse(buf.toString("utf8")),
+          });
+        });
+      }
+    );
+    req.on("error", reject);
+    if (init.body) req.write(init.body);
+    req.end();
+  });
+}
+
+function appendAppKey(path: string): string {
+  if (!DEVELOPER_APP_KEY) return path;
+  const sep = path.includes("?") ? "&" : "?";
+  return `${path}${sep}gw-dev-app-key=${encodeURIComponent(DEVELOPER_APP_KEY)}`;
+}
+
+async function bbRequest(method: string, path: string, body?: unknown): Promise<unknown> {
+  const token = await getAccessToken();
+  const fullPath = appendAppKey(path);
+  const res = await fetchWithMtls(`${BASE_URL}${fullPath}`, {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`,
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) {
+    throw new Error(`BB API ${res.status}: ${await res.text()}`);
+  }
+  return res.json();
+}
+
+const server = new Server(
+  { name: "mcp-banco-do-brasil", version: "0.1.0-alpha.1" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "create_pix_cob",
+      description:
+        "Create an immediate Pix charge (cob) with QR code. Returns txid, EMV copy-paste payload, and location URL. BACEN Pix v2 standard.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          amount: { type: "string", description: "Amount in BRL major units, e.g. '99.90'" },
+          payer: {
+            type: "object",
+            description: "Payer identification (CPF/CNPJ + name)",
+            properties: {
+              document: { type: "string", description: "CPF or CNPJ digits only" },
+              name: { type: "string" },
+            },
+          },
+          expires_in: { type: "number", description: "QR lifetime in seconds (default 3600)" },
+          description: { type: "string", description: "Payer-visible description (solicitacaoPagador)" },
+          dict_key: { type: "string", description: "Recebedor DICT key — must be a key owned by the merchant" },
+          txid: { type: "string", description: "Optional merchant-supplied txid (26-35 alphanumeric). Omit to have BCB assign one." },
+        },
+        required: ["amount", "dict_key"],
+      },
+    },
+    {
+      name: "get_pix_cob",
+      description: "Retrieve an immediate Pix charge by its txid.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          txid: { type: "string", description: "BACEN txid (26-35 alphanumeric)" },
+        },
+        required: ["txid"],
+      },
+    },
+    {
+      name: "list_pix_cob",
+      description: "List immediate Pix charges (cob) by date range. Paginated per BACEN Pix v2.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          from: { type: "string", description: "Start date-time ISO-8601 (inicio)" },
+          to: { type: "string", description: "End date-time ISO-8601 (fim)" },
+          status: { type: "string", description: "Status filter: ATIVA | CONCLUIDA | REMOVIDA_PELO_USUARIO_RECEBEDOR | REMOVIDA_PELO_PSP" },
+          page: { type: "number", description: "paginacao.paginaAtual" },
+          page_size: { type: "number", description: "paginacao.itensPorPagina" },
+        },
+        required: ["from", "to"],
+      },
+    },
+    {
+      name: "create_pix_devolucao",
+      description:
+        "Refund (devolução) a previously received Pix. Must reference the original endToEndId and a merchant-side refund id.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          end_to_end_id: { type: "string", description: "Original Pix endToEndId" },
+          refund_id: { type: "string", description: "Merchant-side refund id (id da devolução, alphanumeric up to 35)" },
+          amount: { type: "string", description: "Refund amount in BRL major units. Omit for full refund." },
+          reason: { type: "string", description: "Free-text reason (descricao)" },
+        },
+        required: ["end_to_end_id", "refund_id"],
+      },
+    },
+    {
+      name: "get_pix_devolucao",
+      description: "Retrieve a Pix devolução by its endToEndId + refund id.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          end_to_end_id: { type: "string", description: "Original Pix endToEndId" },
+          refund_id: { type: "string", description: "Merchant-side refund id" },
+        },
+        required: ["end_to_end_id", "refund_id"],
+      },
+    },
+    {
+      name: "resolve_dict_key",
+      description:
+        "Resolve a DICT key (CPF, CNPJ, email, phone, EVP) to the owner's account data before sending a Pix. Subject to BCB rate limits per consenting payer.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          key: { type: "string", description: "DICT key — CPF, CNPJ, email, phone (+55...), or EVP UUID" },
+          payer_document: { type: "string", description: "End-payer CPF/CNPJ for BCB audit logging" },
+        },
+        required: ["key"],
+      },
+    },
+    {
+      name: "register_dict_key",
+      description:
+        "Register a DICT key on a BB account owned by the merchant. Some key types (email/phone) require BCB confirmation flows.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          key_type: { type: "string", description: "DICT key type: CPF | CNPJ | EMAIL | PHONE | EVP" },
+          key: { type: "string", description: "Key value. Omit for EVP (BCB generates UUID)." },
+          account: {
+            type: "object",
+            properties: {
+              branch: { type: "string", description: "Agência" },
+              account: { type: "string", description: "Conta" },
+              account_type: { type: "string", description: "CACC | SVGS | SLRY | TRAN" },
+            },
+            required: ["branch", "account", "account_type"],
+          },
+        },
+        required: ["key_type", "account"],
+      },
+    },
+    {
+      name: "delete_dict_key",
+      description:
+        "Delete a DICT key owned by the merchant. Irreversible — key becomes available for re-registration after BCB lockout window.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          key: { type: "string", description: "DICT key value to delete" },
+        },
+        required: ["key"],
+      },
+    },
+    {
+      name: "register_boleto",
+      description: "Issue a boleto via BB Cobranças. Returns nosso_numero, linha digitável, barcode, and PDF URL.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          amount: { type: "string", description: "Amount in BRL major units, e.g. '150.00'" },
+          due_date: { type: "string", description: "Due date ISO-8601 (YYYY-MM-DD)" },
+          convenio: { type: "string", description: "BB convênio (numeroConvenio) registered for the merchant" },
+          payer: {
+            type: "object",
+            properties: {
+              name: { type: "string" },
+              document: { type: "string", description: "CPF or CNPJ digits only" },
+              address: {
+                type: "object",
+                properties: {
+                  street: { type: "string" },
+                  number: { type: "string" },
+                  district: { type: "string" },
+                  city: { type: "string" },
+                  state: { type: "string", description: "2-letter UF code" },
+                  postal_code: { type: "string", description: "CEP digits only" },
+                },
+              },
+            },
+            required: ["name", "document"],
+          },
+          our_number: { type: "string", description: "Nosso_numero. Omit to have BB assign one." },
+          fine: { type: "object", description: "Multa: { percentage?, amount?, days_after_due? }" },
+          interest: { type: "object", description: "Juros: { percentage?, amount? }" },
+          discount: { type: "object", description: "Desconto: { percentage?, amount?, until? }" },
+        },
+        required: ["amount", "due_date", "convenio", "payer"],
+      },
+    },
+    {
+      name: "get_boleto",
+      description: "Retrieve a boleto by nosso_numero.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          nosso_numero: { type: "string", description: "BB nosso_numero" },
+          convenio: { type: "string", description: "BB convênio" },
+        },
+        required: ["nosso_numero", "convenio"],
+      },
+    },
+    {
+      name: "cancel_boleto",
+      description: "Cancel (baixa) an outstanding boleto before payment.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          nosso_numero: { type: "string", description: "BB nosso_numero" },
+          convenio: { type: "string", description: "BB convênio" },
+          reason: { type: "string", description: "Cancellation reason code or free text" },
+        },
+        required: ["nosso_numero", "convenio"],
+      },
+    },
+    {
+      name: "get_account_balance",
+      description: "Retrieve the current balance of a BB conta-corrente (checking) account.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          branch: { type: "string", description: "Agência (4 digits)" },
+          account: { type: "string", description: "Conta (digits, no DV)" },
+          account_dv: { type: "string", description: "Conta DV (1 digit)" },
+        },
+        required: ["branch", "account"],
+      },
+    },
+    {
+      name: "get_statement",
+      description: "Retrieve account statement transactions for a BB conta-corrente over a date range. Paginated.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          branch: { type: "string", description: "Agência" },
+          account: { type: "string", description: "Conta" },
+          from: { type: "string", description: "Start date ISO-8601 (YYYY-MM-DD)" },
+          to: { type: "string", description: "End date ISO-8601 (YYYY-MM-DD)" },
+          page: { type: "number", description: "Page number (1-indexed)" },
+          page_size: { type: "number", description: "Items per page (default 50)" },
+        },
+        required: ["branch", "account", "from", "to"],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const a = (args ?? {}) as Record<string, unknown>;
+
+  try {
+    switch (name) {
+      case "create_pix_cob": {
+        // TODO(verify): path. BACEN Pix v2 standard is PUT /pix/v2/cob/{txid}
+        // when txid is supplied, POST /pix/v2/cob otherwise. BB hosts Pix
+        // under api-pix.bb.com.br in production with /pix/v2 prefix.
+        const txid = a.txid ? `/${encodeURIComponent(String(a.txid))}` : "";
+        const method = a.txid ? "PUT" : "POST";
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(await bbRequest(method, `/pix/v2/cob${txid}`, a), null, 2) },
+          ],
+        };
+      }
+      case "get_pix_cob": {
+        const txid = encodeURIComponent(String(a.txid ?? ""));
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(await bbRequest("GET", `/pix/v2/cob/${txid}`), null, 2) },
+          ],
+        };
+      }
+      case "list_pix_cob": {
+        const params = new URLSearchParams();
+        if (a.from !== undefined) params.set("inicio", String(a.from));
+        if (a.to !== undefined) params.set("fim", String(a.to));
+        if (a.status !== undefined) params.set("status", String(a.status));
+        if (a.page !== undefined) params.set("paginacao.paginaAtual", String(a.page));
+        if (a.page_size !== undefined) params.set("paginacao.itensPorPagina", String(a.page_size));
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(await bbRequest("GET", `/pix/v2/cob?${params}`), null, 2) },
+          ],
+        };
+      }
+      case "create_pix_devolucao": {
+        const e2e = encodeURIComponent(String(a.end_to_end_id ?? ""));
+        const rid = encodeURIComponent(String(a.refund_id ?? ""));
+        const body: Record<string, unknown> = {};
+        if (a.amount !== undefined) body.valor = a.amount;
+        if (a.reason !== undefined) body.descricao = a.reason;
+        // TODO(verify): path. BACEN standard PUT /pix/v2/pix/{e2e}/devolucao/{id}.
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(await bbRequest("PUT", `/pix/v2/pix/${e2e}/devolucao/${rid}`, body), null, 2) },
+          ],
+        };
+      }
+      case "get_pix_devolucao": {
+        const e2e = encodeURIComponent(String(a.end_to_end_id ?? ""));
+        const rid = encodeURIComponent(String(a.refund_id ?? ""));
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(await bbRequest("GET", `/pix/v2/pix/${e2e}/devolucao/${rid}`), null, 2) },
+          ],
+        };
+      }
+      case "resolve_dict_key": {
+        const key = encodeURIComponent(String(a.key ?? ""));
+        const qs = a.payer_document ? `&payerDocument=${encodeURIComponent(String(a.payer_document))}` : "";
+        // TODO(verify): path. BACEN DICT consulta is GET /dict/v2/keys/{key}; BB
+        // may also expose it under /pix/v2/dict for client convenience.
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(await bbRequest("GET", `/dict/v2/keys/${key}${qs ? `?${qs.slice(1)}` : ""}`), null, 2) },
+          ],
+        };
+      }
+      case "register_dict_key": {
+        // TODO(verify): path. BACEN DICT registration is POST /dict/v2/keys
+        // with a chaveEntries body; BB may add a confirmação flow for email/phone.
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(await bbRequest("POST", "/dict/v2/keys", a), null, 2) },
+          ],
+        };
+      }
+      case "delete_dict_key": {
+        const key = encodeURIComponent(String(a.key ?? ""));
+        // TODO(verify): path. BACEN DICT delete is DELETE /dict/v2/keys/{key}.
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(await bbRequest("DELETE", `/dict/v2/keys/${key}`), null, 2) },
+          ],
+        };
+      }
+      case "register_boleto": {
+        // TODO(verify): path. BB Cobranças v2 registration is commonly
+        // POST /cobrancas/v2/boletos with numeroConvenio carried in the body.
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(await bbRequest("POST", "/cobrancas/v2/boletos", a), null, 2) },
+          ],
+        };
+      }
+      case "get_boleto": {
+        const nn = encodeURIComponent(String(a.nosso_numero ?? ""));
+        const conv = encodeURIComponent(String(a.convenio ?? ""));
+        // TODO(verify): path. BB exposes detail at GET /cobrancas/v2/boletos/{nosso_numero}?numeroConvenio=...
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(await bbRequest("GET", `/cobrancas/v2/boletos/${nn}?numeroConvenio=${conv}`), null, 2) },
+          ],
+        };
+      }
+      case "cancel_boleto": {
+        const nn = encodeURIComponent(String(a.nosso_numero ?? ""));
+        const conv = encodeURIComponent(String(a.convenio ?? ""));
+        const body: Record<string, unknown> = { numeroConvenio: a.convenio };
+        if (a.reason !== undefined) body.motivoBaixa = a.reason;
+        // TODO(verify): path. BB baixa is POST /cobrancas/v2/boletos/{nn}/baixar.
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(await bbRequest("POST", `/cobrancas/v2/boletos/${nn}/baixar?numeroConvenio=${conv}`, body), null, 2) },
+          ],
+        };
+      }
+      case "get_account_balance": {
+        const branch = encodeURIComponent(String(a.branch ?? ""));
+        const account = encodeURIComponent(String(a.account ?? ""));
+        const dv = a.account_dv ? `&digitoConta=${encodeURIComponent(String(a.account_dv))}` : "";
+        // TODO(verify): path. BB Conta-Corrente saldo: GET /conta-corrente/v1/saldo?agencia=&conta=
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(await bbRequest("GET", `/conta-corrente/v1/saldo?agencia=${branch}&conta=${account}${dv}`), null, 2) },
+          ],
+        };
+      }
+      case "get_statement": {
+        const params = new URLSearchParams();
+        params.set("agencia", String(a.branch ?? ""));
+        params.set("conta", String(a.account ?? ""));
+        params.set("dataInicio", String(a.from ?? ""));
+        params.set("dataFim", String(a.to ?? ""));
+        if (a.page !== undefined) params.set("pagina", String(a.page));
+        if (a.page_size !== undefined) params.set("tamanhoPagina", String(a.page_size));
+        // TODO(verify): path. BB extrato: GET /conta-corrente/v1/extrato.
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(await bbRequest("GET", `/conta-corrente/v1/extrato?${params}`), null, 2) },
+          ],
+        };
+      }
+      default:
+        return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+    }
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+      isError: true,
+    };
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "declaration": true
+  },
+  "include": ["src"]
+}