@codespar/mcp-dock 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,151 @@
+# @codespar/mcp-dock
+
+> MCP server for **Dock** — Brazilian Banking-as-a-Service (accounts, Pix, card issuing) for fintechs and embedded-finance products
+
+[![npm](https://img.shields.io/npm/v/@codespar/mcp-dock)](https://www.npmjs.com/package/@codespar/mcp-dock)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Why Dock
+
+Dock is one of the two dominant BaaS providers in Brazil. Together with Matera, they power most BR fintechs.
+
+**Matera vs Dock — pick one, same commerce patterns:**
+
+| | Matera | Dock |
+|---|---|---|
+| Core strength | Pix-focused core banking | Broader BaaS: accounts + Pix + **card issuing** |
+| Historical root | Core-banking platform | Card-issuing platform that expanded into accounts + Pix |
+| Typical customer | Fintech building on top of Pix | Fintech / retailer issuing branded cards + accounts |
+| Pix Automático | Live (2025 BCB product) | Roadmap |
+
+BR fintechs usually pick one based on contract terms and pricing. **Agents building fintech products can target both — the commerce patterns are identical; only the vendor relationship changes.** This server exposes Dock's surface in the same shape as `@codespar/mcp-matera` so an agent can swap backends without rewriting tool-call logic.
+
+Use Dock when an agent needs to:
+- Spin up **digital accounts** for end users (CPF holders)
+- Move money via Pix (charges, transfers, DICT, refunds)
+- **Issue cards** (debit / credit / prepaid / virtual) against those accounts — Dock's key differentiator
+
+## Quick Start
+
+### Claude Desktop
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "dock": {
+      "command": "npx",
+      "args": ["-y", "@codespar/mcp-dock"],
+      "env": {
+        "DOCK_CLIENT_ID": "your-client-id",
+        "DOCK_CLIENT_SECRET": "your-client-secret",
+        "DOCK_ENV": "sandbox"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add dock -- npx @codespar/mcp-dock
+```
+
+### Cursor / VS Code
+
+Add to `.cursor/mcp.json` or `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "dock": {
+      "command": "npx",
+      "args": ["-y", "@codespar/mcp-dock"],
+      "env": {
+        "DOCK_CLIENT_ID": "your-client-id",
+        "DOCK_CLIENT_SECRET": "your-client-secret",
+        "DOCK_ENV": "sandbox"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_account` | Open a digital account for an end user |
+| `get_account` | Retrieve account balance, status, coordinates |
+| `send_pix` | Outbound Pix transfer from a Dock account |
+| `get_pix` | Retrieve Pix payment by endToEndId |
+| `create_pix_qr_static` | Reusable Pix QR (points-of-sale, donations) |
+| `create_pix_qr_dynamic` | Single-use expiring Pix QR (e-commerce checkouts) |
+| `refund_pix` | Refund (devolução) a Pix payment |
+| `resolve_dict_key` | DICT lookup — resolve Pix key to account holder |
+| `issue_card` | Issue debit / credit / prepaid / virtual card — Dock's differentiator |
+| `get_card` | Retrieve card status, masked PAN, limits |
+
+## Authentication
+
+OAuth 2.0 Client Credentials. The server calls `POST /oauth/token` with Basic auth (`client_id:client_secret`) and caches the bearer token in memory until a minute before expiry.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DOCK_CLIENT_ID` | Yes | OAuth2 client_id issued by Dock |
+| `DOCK_CLIENT_SECRET` | Yes | OAuth2 client_secret (secret) |
+| `DOCK_ENV` | No | `sandbox` (default) or `production` |
+
+Base URL is derived from `DOCK_ENV`: `https://sandbox.api.dock.tech` (sandbox) or `https://api.dock.tech` (production).
+
+## Status
+
+**v0.1.0-alpha.1 — tool surface is stable, wire paths are NOT yet verified.**
+
+Dock's developer portal at [developers.dock.tech](https://developers.dock.tech) redirects to a ReadMe.com login gate. Public docs are not accessible without a Dock merchant contract, so on 2026-04-21 we could not validate the exact URL paths.
+
+The endpoint paths in `src/index.ts` follow **standard BR BaaS conventions** (matching Matera's shape and the BCB Pix spec) and are best-guesses. Known-suspect items are flagged inline with `TODO(verify)` comments:
+
+| Area | Value in code | Why it's suspect |
+|------|---------------|------------------|
+| Token endpoint | `POST /oauth/token` | Standard candidate, but `/oauth2/token` or `/auth/v1/token` also common |
+| Pix refund | `POST /pix/payments/{e2eid}/refund` | BCB spec names refunds `/pix/{e2eid}/devolucao/{id}` |
+| DICT lookup | `GET /pix/dict/{key}` | BCB DICT is RSFN-gated; Dock's wrapper path unverified |
+
+The 10 tool **names** and **input schemas** above are the public contract and will remain stable. Only the internal HTTP calls in `src/index.ts` will change when we verify against the sandbox. Using this server against a live Dock tenant today may produce 404s on most calls.
+
+PR welcome from anyone with a Dock sandbox.
+
+## Roadmap
+
+### v0.2 (planned)
+- Verified paths against Dock sandbox
+- Card controls: `block_card`, `unblock_card`, `set_card_limits`
+- Account statements and transaction listings
+- Webhook event helpers
+
+### v0.3 (planned)
+- Boleto issuance
+- TED / bank transfers (non-Pix rails)
+- Credit underwriting endpoints (Dock's credit stack)
+
+Want to contribute? [Open a PR](https://github.com/codespar/mcp-dev-brasil) or [request a tool](https://github.com/codespar/mcp-dev-brasil/issues).
+
+## Links
+
+- [Dock](https://www.dock.tech)
+- [Dock Developers](https://developers.dock.tech) (gated — requires merchant login)
+- [MCP Dev Brasil](https://github.com/codespar/mcp-dev-brasil)
+- [Landing Page](https://codespar.dev/mcp)
+
+## Enterprise
+
+Need governance, budget limits, and audit trails for agent-initiated bank transfers and card issuance? [CodeSpar Enterprise](https://codespar.dev/enterprise) adds policy engine, payment routing, and compliance templates on top of these MCP servers.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,376 @@
+#!/usr/bin/env node
+/**
+ * MCP Server for Dock — Brazilian Banking-as-a-Service (BaaS).
+ *
+ * Dock is Matera's main competitor in BR BaaS. Together they power most
+ * Brazilian fintechs. Dock's surface is broader than Matera's: accounts,
+ * Pix, and card issuing (debit / credit / prepaid) are all first-class.
+ * Card issuing is the key differentiator vs Matera — Dock is historically
+ * a card-issuing platform that expanded into full BaaS.
+ *
+ * Tools (10) — Banking + Pix + Card Issuing for v0.1:
+ *   create_account          — POST /accounts (digital account for an end user)
+ *   get_account             — GET  /accounts/{id}
+ *   send_pix                — POST /pix/payments (outbound Pix transfer)
+ *   get_pix                 — GET  /pix/payments/{endToEndId}
+ *   create_pix_qr_static    — POST /pix/qrcodes/static
+ *   create_pix_qr_dynamic   — POST /pix/qrcodes/dynamic
+ *   refund_pix              — POST /pix/payments/{endToEndId}/refund
+ *   resolve_dict_key        — GET  /pix/dict/{key}
+ *   issue_card              — POST /cards (Dock's core differentiator)
+ *   get_card                — GET  /cards/{id}
+ *
+ * -------------------------------------------------------------------------
+ * ALPHA STATUS — endpoint paths below are NOT verified against a live sandbox.
+ *
+ * Dock's developer portal (https://developers.dock.tech) redirects to a
+ * ReadMe.com login gate. Public docs are not accessible without a Dock
+ * merchant contract. The paths below follow standard BR BaaS conventions
+ * (matching Matera's shape and BCB's Pix spec) and are best-guesses.
+ *
+ * The 10 tool names + input schemas are the stable public contract. Only
+ * the internal `dockRequest(method, path, body)` calls will change when
+ * the sandbox verifies the exact paths.
+ * -------------------------------------------------------------------------
+ *
+ * Authentication
+ *   OAuth 2.0 Client Credentials. POST /oauth/token with Basic auth
+ *   (client_id:client_secret) + grant_type=client_credentials. Bearer
+ *   token cached in memory until a minute before expiry.
+ *
+ * Environment
+ *   DOCK_CLIENT_ID      OAuth2 client_id
+ *   DOCK_CLIENT_SECRET  OAuth2 client_secret
+ *   DOCK_ENV            "sandbox" | "production" (default: sandbox)
+ *
+ * Docs: https://developers.dock.tech (gated — requires merchant login)
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const CLIENT_ID = process.env.DOCK_CLIENT_ID || "";
+const CLIENT_SECRET = process.env.DOCK_CLIENT_SECRET || "";
+const DOCK_ENV = (process.env.DOCK_ENV || "sandbox").toLowerCase();
+const BASE_URL = DOCK_ENV === "production"
+    ? "https://api.dock.tech"
+    : "https://sandbox.api.dock.tech";
+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");
+    // TODO(verify): Dock's exact token path is unconfirmed behind the doc gate.
+    // `/oauth/token` and `/oauth2/token` are the standard candidates.
+    const res = await fetch(`${BASE_URL}/oauth/token`, {
+        method: "POST",
+        headers: {
+            "Authorization": `Basic ${basic}`,
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: "grant_type=client_credentials",
+    });
+    if (!res.ok) {
+        throw new Error(`Dock 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;
+}
+async function dockRequest(method, path, body) {
+    const token = await getAccessToken();
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method,
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${token}`,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        throw new Error(`Dock API ${res.status}: ${await res.text()}`);
+    }
+    const text = await res.text();
+    return text ? JSON.parse(text) : {};
+}
+const server = new Server({ name: "mcp-dock", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "create_account",
+            description: "Create a digital account for an end user (CPF holder) on Dock. Returns the account id, agency, and account number. Account holds funds that can be moved via Pix or spent via issued cards.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    holder: {
+                        type: "object",
+                        description: "Account holder identity",
+                        properties: {
+                            cpf: { type: "string", description: "11-digit CPF" },
+                            name: { type: "string", description: "Full name" },
+                            birth_date: { type: "string", description: "ISO-8601 date" },
+                            email: { type: "string" },
+                            phone: { type: "string", description: "E.164 phone number" },
+                            mother_name: { type: "string", description: "Required by BCB onboarding rules" },
+                        },
+                        required: ["cpf", "name"],
+                    },
+                    account_type: {
+                        type: "string",
+                        enum: ["PAYMENT", "CHECKING", "SAVINGS"],
+                        description: "Type of account to open",
+                    },
+                    external_id: { type: "string", description: "Merchant-side account identifier for reconciliation" },
+                },
+                required: ["holder"],
+            },
+        },
+        {
+            name: "get_account",
+            description: "Retrieve a Dock account by id. Returns balance, status, holder info, and account coordinates (agency / account number).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    account_id: { type: "string", description: "Dock account id returned by create_account" },
+                },
+                required: ["account_id"],
+            },
+        },
+        {
+            name: "send_pix",
+            description: "Initiate an outbound Pix transfer from a Dock account to any Pix key in BR. Returns endToEndId once the BCB SPI confirms.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    debtor_account_id: { type: "string", description: "Source account id on Dock" },
+                    creditor_pix_key: { type: "string", description: "Destination Pix key (CPF/CNPJ/email/phone/random UUID)" },
+                    amount: { type: "number", description: "Amount in BRL (decimal, e.g. 10.50)" },
+                    description: { type: "string", description: "Message shown to recipient (optional)" },
+                    idempotency_key: { type: "string", description: "Merchant-side unique id to prevent double-send on retry" },
+                },
+                required: ["debtor_account_id", "creditor_pix_key", "amount"],
+            },
+        },
+        {
+            name: "get_pix",
+            description: "Retrieve an outbound Pix payment by endToEndId.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    end_to_end_id: { type: "string", description: "32-char BCB endToEndId" },
+                },
+                required: ["end_to_end_id"],
+            },
+        },
+        {
+            name: "create_pix_qr_static",
+            description: "Create a static Pix QR (reusable, tied to a merchant Pix key). Returns EMV copy-paste payload and QR image. Use for points-of-sale or donations where the same QR is shown to many payers.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    pix_key: { type: "string", description: "Merchant Pix key" },
+                    amount: { type: "number", description: "Amount in BRL. Omit for open-amount QR." },
+                    description: { type: "string", description: "Free-text description shown to payer" },
+                    merchant_name: { type: "string" },
+                    merchant_city: { type: "string" },
+                    txid: { type: "string", description: "Optional merchant txid (26-35 alphanumerics)" },
+                },
+                required: ["pix_key"],
+            },
+        },
+        {
+            name: "create_pix_qr_dynamic",
+            description: "Create a dynamic Pix QR (single-use, expiring). Returns txid, EMV payload, and QR image. Preferred for e-commerce checkouts and invoices.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    pix_key: { type: "string", description: "Merchant Pix key that receives settlement" },
+                    amount: { type: "number", description: "Amount in BRL" },
+                    description: { type: "string", description: "Description shown to payer" },
+                    expiration: { type: "number", description: "QR lifetime in seconds (e.g. 3600 = 1h)" },
+                    debtor: {
+                        type: "object",
+                        properties: {
+                            cpf: { type: "string" },
+                            cnpj: { type: "string" },
+                            name: { type: "string" },
+                        },
+                    },
+                    txid: { type: "string", description: "Optional merchant txid" },
+                },
+                required: ["pix_key", "amount", "expiration"],
+            },
+        },
+        {
+            name: "refund_pix",
+            description: "Refund (devolução) a Pix payment. Supports full or partial amount. Use BCB MED reason codes when applicable.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    end_to_end_id: { type: "string", description: "endToEndId of the payment to refund" },
+                    amount: { type: "number", description: "Refund amount in BRL. Must be <= original." },
+                    reason: { type: "string", description: "Reason (BCB MED code or free text)" },
+                },
+                required: ["end_to_end_id", "amount", "reason"],
+            },
+        },
+        {
+            name: "resolve_dict_key",
+            description: "Resolve a Pix DICT key to the account holder's identity and ISPB/branch/account. Use before sending large transfers to verify the counterparty. DICT queries are rate-limited and logged by BCB.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    key: { type: "string", description: "Pix key to resolve (CPF/CNPJ/email/phone/random)" },
+                },
+                required: ["key"],
+            },
+        },
+        {
+            name: "issue_card",
+            description: "Issue a card (debit / credit / prepaid / virtual) against a Dock account. Card issuing is Dock's historical core product and the main differentiator vs Matera. Returns card id, PAN masked, CVV (if virtual), and shipping status.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    account_id: { type: "string", description: "Dock account id the card is bound to" },
+                    card_type: {
+                        type: "string",
+                        enum: ["DEBIT", "CREDIT", "PREPAID", "VIRTUAL"],
+                        description: "Type of card to issue",
+                    },
+                    network: {
+                        type: "string",
+                        enum: ["VISA", "MASTERCARD", "ELO"],
+                        description: "Card network (BIN must be pre-provisioned with Dock for the given network)",
+                    },
+                    holder_name: { type: "string", description: "Name to emboss on the card (physical) or shown in-app (virtual)" },
+                    shipping_address: {
+                        type: "object",
+                        description: "Required for physical cards",
+                        properties: {
+                            street: { type: "string" },
+                            number: { type: "string" },
+                            complement: { type: "string" },
+                            neighborhood: { type: "string" },
+                            city: { type: "string" },
+                            state: { type: "string", description: "2-letter UF" },
+                            zip_code: { type: "string" },
+                        },
+                    },
+                    external_id: { type: "string", description: "Merchant-side card identifier for reconciliation" },
+                },
+                required: ["account_id", "card_type", "network", "holder_name"],
+            },
+        },
+        {
+            name: "get_card",
+            description: "Retrieve a card by id. Returns card status (ACTIVE / BLOCKED / CANCELED), masked PAN, expiry, and limits.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    card_id: { type: "string", description: "Dock card id returned by issue_card" },
+                },
+                required: ["card_id"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const a = (args ?? {});
+    try {
+        switch (name) {
+            case "create_account":
+                return { content: [{ type: "text", text: JSON.stringify(await dockRequest("POST", "/accounts", a), null, 2) }] };
+            case "get_account": {
+                const id = encodeURIComponent(String(a.account_id ?? ""));
+                return { content: [{ type: "text", text: JSON.stringify(await dockRequest("GET", `/accounts/${id}`), null, 2) }] };
+            }
+            // TODO(verify): BCB canonical outbound-Pix path is `/pix/payments`.
+            // Dock likely wraps it but the exact wrapper is unverified.
+            case "send_pix":
+                return { content: [{ type: "text", text: JSON.stringify(await dockRequest("POST", "/pix/payments", a), null, 2) }] };
+            case "get_pix": {
+                const e2e = encodeURIComponent(String(a.end_to_end_id ?? ""));
+                return { content: [{ type: "text", text: JSON.stringify(await dockRequest("GET", `/pix/payments/${e2e}`), null, 2) }] };
+            }
+            case "create_pix_qr_static":
+                return { content: [{ type: "text", text: JSON.stringify(await dockRequest("POST", "/pix/qrcodes/static", a), null, 2) }] };
+            case "create_pix_qr_dynamic":
+                return { content: [{ type: "text", text: JSON.stringify(await dockRequest("POST", "/pix/qrcodes/dynamic", a), null, 2) }] };
+            // TODO(verify): BCB spec names refunds `/pix/{e2eid}/devolucao/{id}`.
+            // `/pix/payments/{e2eid}/refund` here is a plausible Dock wrapper.
+            case "refund_pix": {
+                const e2e = encodeURIComponent(String(a.end_to_end_id ?? ""));
+                const body = { amount: a.amount, reason: a.reason };
+                return { content: [{ type: "text", text: JSON.stringify(await dockRequest("POST", `/pix/payments/${e2e}/refund`, body), null, 2) }] };
+            }
+            // TODO(verify): DICT lookup wrapper path is unverified behind the Dock
+            // doc gate; `/pix/dict/{key}` follows the standard BR BaaS convention.
+            case "resolve_dict_key": {
+                const key = encodeURIComponent(String(a.key ?? ""));
+                return { content: [{ type: "text", text: JSON.stringify(await dockRequest("GET", `/pix/dict/${key}`), null, 2) }] };
+            }
+            case "issue_card":
+                return { content: [{ type: "text", text: JSON.stringify(await dockRequest("POST", "/cards", a), null, 2) }] };
+            case "get_card": {
+                const id = encodeURIComponent(String(a.card_id ?? ""));
+                return { content: [{ type: "text", text: JSON.stringify(await dockRequest("GET", `/cards/${id}`), 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() {
+    if (process.argv.includes("--http") || process.env.MCP_HTTP === "true") {
+        const { default: express } = await import("express");
+        const { randomUUID } = await import("node:crypto");
+        const app = express();
+        app.use(express.json());
+        const transports = new Map();
+        app.get("/health", (_req, res) => res.json({ status: "ok", sessions: transports.size }));
+        app.post("/mcp", async (req, res) => {
+            const sid = req.headers["mcp-session-id"];
+            if (sid && transports.has(sid)) {
+                await transports.get(sid).handleRequest(req, res, req.body);
+                return;
+            }
+            if (!sid && isInitializeRequest(req.body)) {
+                const t = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), onsessioninitialized: (id) => { transports.set(id, t); } });
+                t.onclose = () => { if (t.sessionId)
+                    transports.delete(t.sessionId); };
+                const s = new Server({ name: "mcp-dock", version: "0.1.0" }, { capabilities: { tools: {} } });
+                server._requestHandlers.forEach((v, k) => s._requestHandlers.set(k, v));
+                server._notificationHandlers?.forEach((v, k) => s._notificationHandlers.set(k, v));
+                await s.connect(t);
+                await t.handleRequest(req, res, req.body);
+                return;
+            }
+            res.status(400).json({ jsonrpc: "2.0", error: { code: -32000, message: "Bad Request" }, id: null });
+        });
+        app.get("/mcp", async (req, res) => { const sid = req.headers["mcp-session-id"]; if (sid && transports.has(sid))
+            await transports.get(sid).handleRequest(req, res);
+        else
+            res.status(400).send("Invalid session"); });
+        app.delete("/mcp", async (req, res) => { const sid = req.headers["mcp-session-id"]; if (sid && transports.has(sid))
+            await transports.get(sid).handleRequest(req, res);
+        else
+            res.status(400).send("Invalid session"); });
+        const port = Number(process.env.MCP_PORT) || 3000;
+        app.listen(port, () => { console.error(`MCP HTTP server on http://localhost:${port}/mcp`); });
+    }
+    else {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+    }
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@codespar/mcp-dock",
+  "version": "0.1.0-alpha.1",
+  "description": "MCP server for Dock — Brazilian Banking-as-a-Service (accounts, Pix, card issuing) for fintechs and embedded-finance products",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "mcp-dock": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.5.0",
+    "typescript": "^5.8.0"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "dock",
+    "banking",
+    "baas",
+    "card-issuing",
+    "pix",
+    "dict",
+    "accounts",
+    "brazil",
+    "fintech"
+  ],
+  "mcpName": "io.github.codespar/mcp-dock"
+}

package/server.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.codespar/mcp-dock",
+  "description": "MCP server for Dock — Brazilian Banking-as-a-Service (accounts, Pix, card issuing) for fintechs and embedded-finance products",
+  "repository": {
+    "url": "https://github.com/codespar/mcp-dev-brasil",
+    "source": "github",
+    "subfolder": "packages/banking/dock"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@codespar/mcp-dock",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "DOCK_CLIENT_ID",
+          "description": "OAuth2 client_id issued by Dock",
+          "isRequired": true,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "DOCK_CLIENT_SECRET",
+          "description": "OAuth2 client_secret issued by Dock",
+          "isRequired": true,
+          "format": "string",
+          "isSecret": true
+        },
+        {
+          "name": "DOCK_ENV",
+          "description": "Environment: sandbox or production. Defaults to sandbox.",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

package/src/index.ts

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+/**
+ * MCP Server for Dock — Brazilian Banking-as-a-Service (BaaS).
+ *
+ * Dock is Matera's main competitor in BR BaaS. Together they power most
+ * Brazilian fintechs. Dock's surface is broader than Matera's: accounts,
+ * Pix, and card issuing (debit / credit / prepaid) are all first-class.
+ * Card issuing is the key differentiator vs Matera — Dock is historically
+ * a card-issuing platform that expanded into full BaaS.
+ *
+ * Tools (10) — Banking + Pix + Card Issuing for v0.1:
+ *   create_account          — POST /accounts (digital account for an end user)
+ *   get_account             — GET  /accounts/{id}
+ *   send_pix                — POST /pix/payments (outbound Pix transfer)
+ *   get_pix                 — GET  /pix/payments/{endToEndId}
+ *   create_pix_qr_static    — POST /pix/qrcodes/static
+ *   create_pix_qr_dynamic   — POST /pix/qrcodes/dynamic
+ *   refund_pix              — POST /pix/payments/{endToEndId}/refund
+ *   resolve_dict_key        — GET  /pix/dict/{key}
+ *   issue_card              — POST /cards (Dock's core differentiator)
+ *   get_card                — GET  /cards/{id}
+ *
+ * -------------------------------------------------------------------------
+ * ALPHA STATUS — endpoint paths below are NOT verified against a live sandbox.
+ *
+ * Dock's developer portal (https://developers.dock.tech) redirects to a
+ * ReadMe.com login gate. Public docs are not accessible without a Dock
+ * merchant contract. The paths below follow standard BR BaaS conventions
+ * (matching Matera's shape and BCB's Pix spec) and are best-guesses.
+ *
+ * The 10 tool names + input schemas are the stable public contract. Only
+ * the internal `dockRequest(method, path, body)` calls will change when
+ * the sandbox verifies the exact paths.
+ * -------------------------------------------------------------------------
+ *
+ * Authentication
+ *   OAuth 2.0 Client Credentials. POST /oauth/token with Basic auth
+ *   (client_id:client_secret) + grant_type=client_credentials. Bearer
+ *   token cached in memory until a minute before expiry.
+ *
+ * Environment
+ *   DOCK_CLIENT_ID      OAuth2 client_id
+ *   DOCK_CLIENT_SECRET  OAuth2 client_secret
+ *   DOCK_ENV            "sandbox" | "production" (default: sandbox)
+ *
+ * Docs: https://developers.dock.tech (gated — requires merchant login)
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const CLIENT_ID = process.env.DOCK_CLIENT_ID || "";
+const CLIENT_SECRET = process.env.DOCK_CLIENT_SECRET || "";
+const DOCK_ENV = (process.env.DOCK_ENV || "sandbox").toLowerCase();
+const BASE_URL =
+  DOCK_ENV === "production"
+    ? "https://api.dock.tech"
+    : "https://sandbox.api.dock.tech";
+
+let tokenCache: { accessToken: string; expiresAt: number } | 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");
+  // TODO(verify): Dock's exact token path is unconfirmed behind the doc gate.
+  // `/oauth/token` and `/oauth2/token` are the standard candidates.
+  const res = await fetch(`${BASE_URL}/oauth/token`, {
+    method: "POST",
+    headers: {
+      "Authorization": `Basic ${basic}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: "grant_type=client_credentials",
+  });
+  if (!res.ok) {
+    throw new Error(`Dock 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;
+}
+
+async function dockRequest(method: string, path: string, body?: unknown): Promise<unknown> {
+  const token = await getAccessToken();
+  const res = await fetch(`${BASE_URL}${path}`, {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${token}`,
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) {
+    throw new Error(`Dock API ${res.status}: ${await res.text()}`);
+  }
+  const text = await res.text();
+  return text ? JSON.parse(text) : {};
+}
+
+const server = new Server(
+  { name: "mcp-dock", version: "0.1.0" },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "create_account",
+      description: "Create a digital account for an end user (CPF holder) on Dock. Returns the account id, agency, and account number. Account holds funds that can be moved via Pix or spent via issued cards.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          holder: {
+            type: "object",
+            description: "Account holder identity",
+            properties: {
+              cpf: { type: "string", description: "11-digit CPF" },
+              name: { type: "string", description: "Full name" },
+              birth_date: { type: "string", description: "ISO-8601 date" },
+              email: { type: "string" },
+              phone: { type: "string", description: "E.164 phone number" },
+              mother_name: { type: "string", description: "Required by BCB onboarding rules" },
+            },
+            required: ["cpf", "name"],
+          },
+          account_type: {
+            type: "string",
+            enum: ["PAYMENT", "CHECKING", "SAVINGS"],
+            description: "Type of account to open",
+          },
+          external_id: { type: "string", description: "Merchant-side account identifier for reconciliation" },
+        },
+        required: ["holder"],
+      },
+    },
+    {
+      name: "get_account",
+      description: "Retrieve a Dock account by id. Returns balance, status, holder info, and account coordinates (agency / account number).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          account_id: { type: "string", description: "Dock account id returned by create_account" },
+        },
+        required: ["account_id"],
+      },
+    },
+    {
+      name: "send_pix",
+      description: "Initiate an outbound Pix transfer from a Dock account to any Pix key in BR. Returns endToEndId once the BCB SPI confirms.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          debtor_account_id: { type: "string", description: "Source account id on Dock" },
+          creditor_pix_key: { type: "string", description: "Destination Pix key (CPF/CNPJ/email/phone/random UUID)" },
+          amount: { type: "number", description: "Amount in BRL (decimal, e.g. 10.50)" },
+          description: { type: "string", description: "Message shown to recipient (optional)" },
+          idempotency_key: { type: "string", description: "Merchant-side unique id to prevent double-send on retry" },
+        },
+        required: ["debtor_account_id", "creditor_pix_key", "amount"],
+      },
+    },
+    {
+      name: "get_pix",
+      description: "Retrieve an outbound Pix payment by endToEndId.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          end_to_end_id: { type: "string", description: "32-char BCB endToEndId" },
+        },
+        required: ["end_to_end_id"],
+      },
+    },
+    {
+      name: "create_pix_qr_static",
+      description: "Create a static Pix QR (reusable, tied to a merchant Pix key). Returns EMV copy-paste payload and QR image. Use for points-of-sale or donations where the same QR is shown to many payers.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          pix_key: { type: "string", description: "Merchant Pix key" },
+          amount: { type: "number", description: "Amount in BRL. Omit for open-amount QR." },
+          description: { type: "string", description: "Free-text description shown to payer" },
+          merchant_name: { type: "string" },
+          merchant_city: { type: "string" },
+          txid: { type: "string", description: "Optional merchant txid (26-35 alphanumerics)" },
+        },
+        required: ["pix_key"],
+      },
+    },
+    {
+      name: "create_pix_qr_dynamic",
+      description: "Create a dynamic Pix QR (single-use, expiring). Returns txid, EMV payload, and QR image. Preferred for e-commerce checkouts and invoices.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          pix_key: { type: "string", description: "Merchant Pix key that receives settlement" },
+          amount: { type: "number", description: "Amount in BRL" },
+          description: { type: "string", description: "Description shown to payer" },
+          expiration: { type: "number", description: "QR lifetime in seconds (e.g. 3600 = 1h)" },
+          debtor: {
+            type: "object",
+            properties: {
+              cpf: { type: "string" },
+              cnpj: { type: "string" },
+              name: { type: "string" },
+            },
+          },
+          txid: { type: "string", description: "Optional merchant txid" },
+        },
+        required: ["pix_key", "amount", "expiration"],
+      },
+    },
+    {
+      name: "refund_pix",
+      description: "Refund (devolução) a Pix payment. Supports full or partial amount. Use BCB MED reason codes when applicable.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          end_to_end_id: { type: "string", description: "endToEndId of the payment to refund" },
+          amount: { type: "number", description: "Refund amount in BRL. Must be <= original." },
+          reason: { type: "string", description: "Reason (BCB MED code or free text)" },
+        },
+        required: ["end_to_end_id", "amount", "reason"],
+      },
+    },
+    {
+      name: "resolve_dict_key",
+      description: "Resolve a Pix DICT key to the account holder's identity and ISPB/branch/account. Use before sending large transfers to verify the counterparty. DICT queries are rate-limited and logged by BCB.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          key: { type: "string", description: "Pix key to resolve (CPF/CNPJ/email/phone/random)" },
+        },
+        required: ["key"],
+      },
+    },
+    {
+      name: "issue_card",
+      description: "Issue a card (debit / credit / prepaid / virtual) against a Dock account. Card issuing is Dock's historical core product and the main differentiator vs Matera. Returns card id, PAN masked, CVV (if virtual), and shipping status.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          account_id: { type: "string", description: "Dock account id the card is bound to" },
+          card_type: {
+            type: "string",
+            enum: ["DEBIT", "CREDIT", "PREPAID", "VIRTUAL"],
+            description: "Type of card to issue",
+          },
+          network: {
+            type: "string",
+            enum: ["VISA", "MASTERCARD", "ELO"],
+            description: "Card network (BIN must be pre-provisioned with Dock for the given network)",
+          },
+          holder_name: { type: "string", description: "Name to emboss on the card (physical) or shown in-app (virtual)" },
+          shipping_address: {
+            type: "object",
+            description: "Required for physical cards",
+            properties: {
+              street: { type: "string" },
+              number: { type: "string" },
+              complement: { type: "string" },
+              neighborhood: { type: "string" },
+              city: { type: "string" },
+              state: { type: "string", description: "2-letter UF" },
+              zip_code: { type: "string" },
+            },
+          },
+          external_id: { type: "string", description: "Merchant-side card identifier for reconciliation" },
+        },
+        required: ["account_id", "card_type", "network", "holder_name"],
+      },
+    },
+    {
+      name: "get_card",
+      description: "Retrieve a card by id. Returns card status (ACTIVE / BLOCKED / CANCELED), masked PAN, expiry, and limits.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          card_id: { type: "string", description: "Dock card id returned by issue_card" },
+        },
+        required: ["card_id"],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const a = (args ?? {}) as Record<string, unknown>;
+  try {
+    switch (name) {
+      case "create_account":
+        return { content: [{ type: "text", text: JSON.stringify(await dockRequest("POST", "/accounts", a), null, 2) }] };
+      case "get_account": {
+        const id = encodeURIComponent(String(a.account_id ?? ""));
+        return { content: [{ type: "text", text: JSON.stringify(await dockRequest("GET", `/accounts/${id}`), null, 2) }] };
+      }
+      // TODO(verify): BCB canonical outbound-Pix path is `/pix/payments`.
+      // Dock likely wraps it but the exact wrapper is unverified.
+      case "send_pix":
+        return { content: [{ type: "text", text: JSON.stringify(await dockRequest("POST", "/pix/payments", a), null, 2) }] };
+      case "get_pix": {
+        const e2e = encodeURIComponent(String(a.end_to_end_id ?? ""));
+        return { content: [{ type: "text", text: JSON.stringify(await dockRequest("GET", `/pix/payments/${e2e}`), null, 2) }] };
+      }
+      case "create_pix_qr_static":
+        return { content: [{ type: "text", text: JSON.stringify(await dockRequest("POST", "/pix/qrcodes/static", a), null, 2) }] };
+      case "create_pix_qr_dynamic":
+        return { content: [{ type: "text", text: JSON.stringify(await dockRequest("POST", "/pix/qrcodes/dynamic", a), null, 2) }] };
+      // TODO(verify): BCB spec names refunds `/pix/{e2eid}/devolucao/{id}`.
+      // `/pix/payments/{e2eid}/refund` here is a plausible Dock wrapper.
+      case "refund_pix": {
+        const e2e = encodeURIComponent(String(a.end_to_end_id ?? ""));
+        const body: Record<string, unknown> = { amount: a.amount, reason: a.reason };
+        return { content: [{ type: "text", text: JSON.stringify(await dockRequest("POST", `/pix/payments/${e2e}/refund`, body), null, 2) }] };
+      }
+      // TODO(verify): DICT lookup wrapper path is unverified behind the Dock
+      // doc gate; `/pix/dict/{key}` follows the standard BR BaaS convention.
+      case "resolve_dict_key": {
+        const key = encodeURIComponent(String(a.key ?? ""));
+        return { content: [{ type: "text", text: JSON.stringify(await dockRequest("GET", `/pix/dict/${key}`), null, 2) }] };
+      }
+      case "issue_card":
+        return { content: [{ type: "text", text: JSON.stringify(await dockRequest("POST", "/cards", a), null, 2) }] };
+      case "get_card": {
+        const id = encodeURIComponent(String(a.card_id ?? ""));
+        return { content: [{ type: "text", text: JSON.stringify(await dockRequest("GET", `/cards/${id}`), 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() {
+  if (process.argv.includes("--http") || process.env.MCP_HTTP === "true") {
+    const { default: express } = await import("express");
+    const { randomUUID } = await import("node:crypto");
+    const app = express();
+    app.use(express.json());
+    const transports = new Map<string, StreamableHTTPServerTransport>();
+    app.get("/health", (_req, res) => res.json({ status: "ok", sessions: transports.size }));
+    app.post("/mcp", async (req, res) => {
+      const sid = req.headers["mcp-session-id"] as string | undefined;
+      if (sid && transports.has(sid)) {
+        await transports.get(sid)!.handleRequest(req, res, req.body);
+        return;
+      }
+      if (!sid && isInitializeRequest(req.body)) {
+        const t = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), onsessioninitialized: (id) => { transports.set(id, t); } });
+        t.onclose = () => { if (t.sessionId) transports.delete(t.sessionId); };
+        const s = new Server({ name: "mcp-dock", version: "0.1.0" }, { capabilities: { tools: {} } });
+        (server as any)._requestHandlers.forEach((v: any, k: any) => (s as any)._requestHandlers.set(k, v));
+        (server as any)._notificationHandlers?.forEach((v: any, k: any) => (s as any)._notificationHandlers.set(k, v));
+        await s.connect(t);
+        await t.handleRequest(req, res, req.body);
+        return;
+      }
+      res.status(400).json({ jsonrpc: "2.0", error: { code: -32000, message: "Bad Request" }, id: null });
+    });
+    app.get("/mcp", async (req, res) => { const sid = req.headers["mcp-session-id"] as string | undefined; if (sid && transports.has(sid)) await transports.get(sid)!.handleRequest(req, res); else res.status(400).send("Invalid session"); });
+    app.delete("/mcp", async (req, res) => { const sid = req.headers["mcp-session-id"] as string | undefined; if (sid && transports.has(sid)) await transports.get(sid)!.handleRequest(req, res); else res.status(400).send("Invalid session"); });
+    const port = Number(process.env.MCP_PORT) || 3000;
+    app.listen(port, () => { console.error(`MCP HTTP server on http://localhost:${port}/mcp`); });
+  } else {
+    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"]
+}