@magnolia-financial/banking-mcp 1.0.0

package/README.md

@@ -0,0 +1,180 @@
+# Magnolia MCP Server
+
+An MCP (Model Context Protocol) server that wraps the Magnolia banking API, letting AI agents manage crypto wallets, bank accounts, trading, fiat operations, and Lightning Network payments.
+
+## Prerequisites
+
+- Node.js 18+
+- A Magnolia API key (get one at [clawbot.cash](https://clawbot.cash))
+
+## Install
+
+```bash
+npm install
+npm run build
+```
+
+## Configuration
+
+Set your API key as an environment variable:
+
+```bash
+export MAGNOLIA_API_KEY=magfi_your_api_key_here
+```
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MAGNOLIA_API_KEY` | Yes | — | API key from ClawBot.cash KYC flow |
+| `MAGNOLIA_API_URL` | No | `https://api.magfi.net` | Magnolia API base URL |
+
+## Usage
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "magnolia": {
+      "command": "node",
+      "args": ["/path/to/clawbot.cash/mcp-server/dist/index.js"],
+      "env": {
+        "MAGNOLIA_API_KEY": "magfi_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "magnolia": {
+      "command": "node",
+      "args": ["/path/to/clawbot.cash/mcp-server/dist/index.js"],
+      "env": {
+        "MAGNOLIA_API_KEY": "magfi_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Direct
+
+```bash
+MAGNOLIA_API_KEY=magfi_... node dist/index.js
+```
+
+## Available Tools (30 total)
+
+### Enterprise
+
+| Tool | Description |
+|------|-------------|
+| `list_enterprises` | List all enterprises accessible to this API key |
+
+### Crypto Wallets
+
+| Tool | Description |
+|------|-------------|
+| `list_wallets` | List wallets for a cryptocurrency (btc, eth, tbtc, teth) |
+| `get_wallet` | Get wallet details by coin and wallet ID |
+| `generate_address` | Generate a new receive address for a wallet |
+| `list_addresses` | List all addresses for a wallet |
+| `get_address_balances` | Get address balances for a wallet |
+| `send_crypto` | Send a cryptocurrency transaction |
+| `get_wallet_transfer` | Get transfer status for a wallet |
+| `list_wallet_transfers` | List all transfers for a wallet |
+
+### Bank Accounts
+
+| Tool | Description |
+|------|-------------|
+| `list_bank_accounts` | List linked bank accounts (filterable by type, state, enterprise) |
+| `get_bank_account` | Get bank account details by ID |
+| `add_bank_account` | Add a new bank account (wire, ACH, or SEPA) |
+| `delete_bank_account` | Delete a bank account |
+| `get_deposit_info` | Get deposit/wiring instructions |
+
+### Trading
+
+| Tool | Description |
+|------|-------------|
+| `get_trading_balances` | Get balances for a trading account |
+| `get_trading_products` | List available trading products/pairs |
+| `place_order` | Place a trading order (market, limit, TWAP, steady pace) |
+| `list_orders` | List orders for a trading account |
+| `get_order` | Get order details by ID |
+| `cancel_order` | Cancel a pending order |
+
+### Fiat/ACH
+
+| Tool | Description |
+|------|-------------|
+| `get_ach_agreement` | Get the ACH debit agreement |
+| `accept_ach_agreement` | Accept the ACH debit agreement for a bank account |
+| `create_ach_debit` | Create an ACH debit to pull funds from a bank account |
+
+### Lightning Network
+
+| Tool | Description |
+|------|-------------|
+| `create_lightning_invoice` | Create a Lightning invoice to receive payment |
+| `get_lightning_invoice` | Check Lightning invoice status |
+| `pay_lightning_invoice` | Pay a Lightning invoice |
+| `list_lightning_transactions` | List Lightning transactions for a wallet |
+
+### Utility
+
+| Tool | Description |
+|------|-------------|
+| `lookup_routing_number` | Look up bank info by ACH or wire routing number |
+
+### Auth
+
+| Tool | Description |
+|------|-------------|
+| `list_api_keys` | List all API keys for the authenticated user |
+| `delete_api_key` | Delete an API key by ID |
+
+## Example Interactions
+
+Once configured, you can ask your AI agent things like:
+
+- "List my BTC wallets"
+- "Generate a new receive address for my ETH wallet"
+- "Send 0.001 BTC to address bc1q..."
+- "Show my bank accounts"
+- "Add my Chase checking account for ACH"
+- "Place a market order to buy $100 of BTC"
+- "What are my trading balances?"
+- "Create a Lightning invoice for 10000 sats"
+- "Look up routing number 021000021"
+
+## Testing
+
+```bash
+npm test              # Run all tests
+npm run test:watch    # Watch mode
+npm run test:integration  # Integration tests only
+```
+
+118 tests across 5 suites covering auth, API paths, client methods, edge cases, and backward compatibility.
+
+## Development
+
+```bash
+npm run dev    # Watch mode (recompiles on change)
+npm run build  # One-time build
+npm start      # Run the compiled server
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Magnolia MCP Server
+ *
+ * An MCP server that wraps the Magnolia banking API, allowing AI agents
+ * to manage crypto wallets, bank accounts, trading, fiat operations,
+ * and Lightning Network payments.
+ *
+ * API paths are based on the official Magnolia documentation at
+ * docs.magnolia.financial.
+ *
+ * Usage:
+ *   MAGNOLIA_API_KEY=magfi_... node dist/index.js
+ *   MAGNOLIA_API_KEY=magfi_... MAGNOLIA_API_URL=https://api.magfi.net node dist/index.js
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,582 @@
+#!/usr/bin/env node
+/**
+ * Magnolia MCP Server
+ *
+ * An MCP server that wraps the Magnolia banking API, allowing AI agents
+ * to manage crypto wallets, bank accounts, trading, fiat operations,
+ * and Lightning Network payments.
+ *
+ * API paths are based on the official Magnolia documentation at
+ * docs.magnolia.financial.
+ *
+ * Usage:
+ *   MAGNOLIA_API_KEY=magfi_... node dist/index.js
+ *   MAGNOLIA_API_KEY=magfi_... MAGNOLIA_API_URL=https://api.magfi.net node dist/index.js
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { MagnoliaClient } from "./magnolia-client.js";
+const API_KEY = process.env.MAGNOLIA_API_KEY;
+const API_URL = process.env.MAGNOLIA_API_URL;
+if (!API_KEY) {
+    console.error("Error: MAGNOLIA_API_KEY environment variable is required.\n" +
+        "Get your API key at https://clawbot.cash");
+    process.exit(1);
+}
+const client = new MagnoliaClient(API_KEY, API_URL);
+const server = new McpServer({
+    name: "magnolia",
+    version: "1.0.0",
+});
+// Helper to format JSON responses
+function jsonResponse(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+function errorResponse(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Error: ${message}`,
+            },
+        ],
+        isError: true,
+    };
+}
+// ==========================================
+// Enterprise Tools
+// ==========================================
+server.registerTool("list_enterprises", {
+    description: "List all enterprises accessible to this API key.",
+    inputSchema: {},
+}, async () => {
+    try {
+        const enterprises = await client.getEnterprises();
+        return jsonResponse(enterprises);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+// ==========================================
+// Crypto Wallet Tools — /api/v2/{coin}/wallet
+// ==========================================
+server.registerTool("list_wallets", {
+    description: "List wallets for a specific cryptocurrency. Use coin tickers like 'btc', 'eth', 'tbtc' (testnet BTC), 'teth' (testnet ETH).",
+    inputSchema: {
+        coin: z.string().describe("Coin ticker (e.g., 'btc', 'eth', 'tbtc', 'teth')"),
+    },
+}, async ({ coin }) => {
+    try {
+        const wallets = await client.listWallets(coin);
+        return jsonResponse(wallets);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("get_wallet", {
+    description: "Get details for a specific wallet by coin and wallet ID.",
+    inputSchema: {
+        coin: z.string().describe("Coin ticker (e.g., 'btc', 'eth')"),
+        walletId: z.string().describe("The wallet ID"),
+    },
+}, async ({ coin, walletId }) => {
+    try {
+        const wallet = await client.getWallet(coin, walletId);
+        return jsonResponse(wallet);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("generate_address", {
+    description: "Generate a new receive address for a crypto wallet.",
+    inputSchema: {
+        coin: z.string().describe("Coin ticker (e.g., 'btc', 'eth')"),
+        walletId: z.string().describe("The wallet ID"),
+    },
+}, async ({ coin, walletId }) => {
+    try {
+        const address = await client.generateAddress(coin, walletId);
+        return jsonResponse(address);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("list_addresses", {
+    description: "List all addresses for a crypto wallet.",
+    inputSchema: {
+        coin: z.string().describe("Coin ticker (e.g., 'btc', 'eth')"),
+        walletId: z.string().describe("The wallet ID"),
+    },
+}, async ({ coin, walletId }) => {
+    try {
+        const addresses = await client.listAddresses(coin, walletId);
+        return jsonResponse(addresses);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("get_address_balances", {
+    description: "Get address balances for a crypto wallet.",
+    inputSchema: {
+        coin: z.string().describe("Coin ticker (e.g., 'btc', 'eth')"),
+        walletId: z.string().describe("The wallet ID"),
+    },
+}, async ({ coin, walletId }) => {
+    try {
+        const balances = await client.getAddressBalances(coin, walletId);
+        return jsonResponse(balances);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("send_crypto", {
+    description: "Send a cryptocurrency transaction from a wallet.",
+    inputSchema: {
+        coin: z.string().describe("Coin ticker (e.g., 'btc', 'eth')"),
+        walletId: z.string().describe("Source wallet ID"),
+        address: z.string().describe("Destination address"),
+        amount: z.string().describe("Amount to send (in base units)"),
+        walletPassphrase: z.string().optional().describe("Wallet passphrase for signing"),
+        memo: z.string().optional().describe("Optional memo/tag"),
+    },
+}, async ({ coin, walletId, address, amount, walletPassphrase, memo }) => {
+    try {
+        const tx = await client.sendTransaction(coin, walletId, {
+            address,
+            amount,
+            walletPassphrase,
+            memo,
+        });
+        return jsonResponse(tx);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("get_wallet_transfer", {
+    description: "Get the status of a specific transfer for a wallet.",
+    inputSchema: {
+        coin: z.string().describe("Coin ticker (e.g., 'btc', 'eth')"),
+        walletId: z.string().describe("The wallet ID"),
+        transferId: z.string().describe("The transfer ID"),
+    },
+}, async ({ coin, walletId, transferId }) => {
+    try {
+        const transfer = await client.getWalletTransfer(coin, walletId, transferId);
+        return jsonResponse(transfer);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("list_wallet_transfers", {
+    description: "List all transfers for a specific crypto wallet.",
+    inputSchema: {
+        coin: z.string().describe("Coin ticker (e.g., 'btc', 'eth')"),
+        walletId: z.string().describe("The wallet ID"),
+    },
+}, async ({ coin, walletId }) => {
+    try {
+        const transfers = await client.listWalletTransfers(coin, walletId);
+        return jsonResponse(transfers);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+// ==========================================
+// Bank Account Tools — /api/v2/bankaccounts
+// ==========================================
+server.registerTool("list_bank_accounts", {
+    description: "List all linked bank accounts. Can filter by type, verification state, or enterprise.",
+    inputSchema: {
+        type: z.string().optional().describe("Filter by type: 'wire', 'ach', or 'sepa'"),
+        verificationState: z.string().optional().describe("Filter by verification state"),
+        enterpriseId: z.string().optional().describe("Filter by enterprise ID"),
+    },
+}, async ({ type, verificationState, enterpriseId }) => {
+    try {
+        const accounts = await client.listBankAccounts({
+            type,
+            verificationState,
+            enterpriseId,
+        });
+        return jsonResponse(accounts);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("get_bank_account", {
+    description: "Get details for a specific bank account by ID.",
+    inputSchema: {
+        bankAccountId: z.string().describe("The bank account ID"),
+    },
+}, async ({ bankAccountId }) => {
+    try {
+        const account = await client.getBankAccount(bankAccountId);
+        return jsonResponse(account);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("add_bank_account", {
+    description: "Add a new bank account for deposits and withdrawals.",
+    inputSchema: {
+        type: z.enum(["wire", "ach", "sepa"]).describe("Bank account type"),
+        name: z.string().describe("A label for this bank account"),
+        ownerName: z.string().describe("Name of the account owner"),
+        shortCountryCode: z.string().describe("Two-letter country code (e.g., 'US')"),
+        accountNumber: z.string().describe("Bank account number"),
+        currency: z.string().describe("Currency code (e.g., 'USD')"),
+        routingNumber: z.string().optional().describe("Routing number (required for ACH/wire in US)"),
+        swiftCode: z.string().optional().describe("SWIFT code (for international wire)"),
+        accountType: z.enum(["checking", "saving"]).optional().describe("Account type"),
+        ownerAddressCountryCode: z.string().describe("Two-letter country code for the owner's address (e.g., 'US')"),
+        ownerAddress: z.object({
+            address_line_1: z.string().describe("Street address"),
+            city_locality: z.string().describe("City"),
+            state_province: z.string().describe("State or province"),
+            postal_code: z.string().describe("Postal/ZIP code"),
+        }).describe("Owner's physical address"),
+    },
+}, async ({ type, name, ownerName, shortCountryCode, accountNumber, currency, routingNumber, swiftCode, accountType, ownerAddressCountryCode, ownerAddress }) => {
+    try {
+        const account = await client.addBankAccount({
+            type,
+            name,
+            ownerName,
+            shortCountryCode,
+            accountNumber,
+            currency,
+            routingNumber,
+            swiftCode,
+            accountType,
+            ownerAddressCountryCode,
+            ownerAddress,
+        });
+        return jsonResponse(account);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("delete_bank_account", {
+    description: "Delete a bank account by ID.",
+    inputSchema: {
+        bankAccountId: z.string().describe("The bank account ID to delete"),
+    },
+}, async ({ bankAccountId }) => {
+    try {
+        const result = await client.deleteBankAccount(bankAccountId);
+        return jsonResponse(result);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("get_deposit_info", {
+    description: "Get deposit information for bank accounts (wiring instructions, etc.).",
+    inputSchema: {},
+}, async () => {
+    try {
+        const info = await client.getDepositInfo();
+        return jsonResponse(info);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+// ==========================================
+// Trading Tools — /api/prime/trading/v1
+// ==========================================
+server.registerTool("get_trading_balances", {
+    description: "Get balances for a trading account.",
+    inputSchema: {
+        accountId: z.string().describe("Trading account ID"),
+    },
+}, async ({ accountId }) => {
+    try {
+        const balances = await client.getTradingBalances(accountId);
+        return jsonResponse(balances);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("get_trading_products", {
+    description: "List available trading products (pairs) for an account.",
+    inputSchema: {
+        accountId: z.string().describe("Trading account ID"),
+    },
+}, async ({ accountId }) => {
+    try {
+        const products = await client.getTradingProducts(accountId);
+        return jsonResponse(products);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("place_order", {
+    description: "Place a trading order (market, limit, TWAP, or steady pace).",
+    inputSchema: {
+        accountId: z.string().describe("Trading account ID"),
+        type: z.enum(["market", "limit", "twap", "steady_pace"]).describe("Order type"),
+        product: z.string().describe("Trading product/pair (e.g., 'BTC-USD')"),
+        side: z.enum(["buy", "sell"]).describe("Order side"),
+        quantity: z.string().describe("Order quantity"),
+        quantityCurrency: z.string().describe("Currency of the quantity (e.g., 'USD' or 'BTC')"),
+        limitPrice: z.string().optional().describe("Limit price (required for limit orders)"),
+        duration: z.number().optional().describe("Duration in seconds (for TWAP/steady pace)"),
+        clientOrderId: z.string().optional().describe("Client-defined order ID"),
+        fundingType: z.enum(["margin", "funded"]).optional().describe("Funding type"),
+    },
+}, async ({ accountId, type, product, side, quantity, quantityCurrency, limitPrice, duration, clientOrderId, fundingType }) => {
+    try {
+        const order = await client.placeOrder(accountId, {
+            type,
+            product,
+            side,
+            quantity,
+            quantityCurrency,
+            limitPrice,
+            duration,
+            clientOrderId,
+            fundingType,
+        });
+        return jsonResponse(order);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("list_orders", {
+    description: "List orders for a trading account.",
+    inputSchema: {
+        accountId: z.string().describe("Trading account ID"),
+        limit: z.number().optional().describe("Max number of orders to return"),
+        offset: z.number().optional().describe("Offset for pagination"),
+    },
+}, async ({ accountId, limit, offset }) => {
+    try {
+        const orders = await client.listOrders(accountId, { limit, offset });
+        return jsonResponse(orders);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("get_order", {
+    description: "Get details for a specific trading order.",
+    inputSchema: {
+        accountId: z.string().describe("Trading account ID"),
+        orderId: z.string().describe("The order ID"),
+    },
+}, async ({ accountId, orderId }) => {
+    try {
+        const order = await client.getOrder(accountId, orderId);
+        return jsonResponse(order);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("cancel_order", {
+    description: "Cancel a pending trading order.",
+    inputSchema: {
+        accountId: z.string().describe("Trading account ID"),
+        orderId: z.string().describe("The order ID to cancel"),
+    },
+}, async ({ accountId, orderId }) => {
+    try {
+        const result = await client.cancelOrder(accountId, orderId);
+        return jsonResponse(result);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+// ==========================================
+// Fiat/ACH Tools — /api/fiat/v1
+// ==========================================
+server.registerTool("get_ach_agreement", {
+    description: "Get the ACH debit agreement that must be accepted before making ACH debits.",
+    inputSchema: {},
+}, async () => {
+    try {
+        const agreement = await client.getAchAgreement();
+        return jsonResponse(agreement);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("accept_ach_agreement", {
+    description: "Accept the ACH debit agreement for a specific bank account.",
+    inputSchema: {
+        bankAccountId: z.string().describe("The bank account ID to accept the agreement for"),
+    },
+}, async ({ bankAccountId }) => {
+    try {
+        const result = await client.acceptAchAgreement({ bankAccountId });
+        return jsonResponse(result);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("create_ach_debit", {
+    description: "Create an ACH debit transaction to pull funds from a linked bank account.",
+    inputSchema: {
+        bankAccountId: z.string().describe("Source bank account ID"),
+        amount: z.string().describe("Amount to debit (e.g., '100.00')"),
+        currency: z.string().describe("Currency code (e.g., 'USD')"),
+    },
+}, async ({ bankAccountId, amount, currency }) => {
+    try {
+        const tx = await client.createAchDebit({ bankAccountId, amount, currency });
+        return jsonResponse(tx);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+// ==========================================
+// Lightning Network Tools
+// ==========================================
+server.registerTool("create_lightning_invoice", {
+    description: "Create a Lightning Network invoice to receive a payment.",
+    inputSchema: {
+        walletId: z.string().describe("Bitcoin wallet ID"),
+        amount: z.string().describe("Amount in satoshis"),
+        memo: z.string().optional().describe("Invoice memo/description"),
+    },
+}, async ({ walletId, amount, memo }) => {
+    try {
+        const invoice = await client.createLightningInvoice(walletId, { amount, memo });
+        return jsonResponse(invoice);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("get_lightning_invoice", {
+    description: "Check the status of a Lightning Network invoice.",
+    inputSchema: {
+        walletId: z.string().describe("Bitcoin wallet ID"),
+        paymentHash: z.string().describe("The payment hash of the invoice"),
+    },
+}, async ({ walletId, paymentHash }) => {
+    try {
+        const invoice = await client.getLightningInvoice(walletId, paymentHash);
+        return jsonResponse(invoice);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("pay_lightning_invoice", {
+    description: "Pay a Lightning Network invoice.",
+    inputSchema: {
+        walletId: z.string().describe("Bitcoin wallet ID to pay from"),
+        invoice: z.string().describe("Lightning invoice string (lnbc...)"),
+    },
+}, async ({ walletId, invoice }) => {
+    try {
+        const payment = await client.makeLightningPayment(walletId, { invoice });
+        return jsonResponse(payment);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("list_lightning_transactions", {
+    description: "List Lightning Network transactions for a wallet.",
+    inputSchema: {
+        walletId: z.string().describe("Bitcoin wallet ID"),
+    },
+}, async ({ walletId }) => {
+    try {
+        const txs = await client.listLightningTransactions(walletId);
+        return jsonResponse(txs);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+// ==========================================
+// Utility Tools
+// ==========================================
+server.registerTool("lookup_routing_number", {
+    description: "Look up bank information by routing number. Returns bank name and address.",
+    inputSchema: {
+        bankType: z.enum(["ach", "wire"]).describe("Type of routing number: 'ach' or 'wire'"),
+        routingNumber: z.string().describe("The 9-digit routing number"),
+    },
+}, async ({ bankType, routingNumber }) => {
+    try {
+        const info = await client.lookupRoutingNumber(bankType, routingNumber);
+        return jsonResponse(info);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+// ==========================================
+// Auth Tools
+// ==========================================
+server.registerTool("list_api_keys", {
+    description: "List all API keys for the authenticated user.",
+    inputSchema: {},
+}, async () => {
+    try {
+        const keys = await client.listApiKeys();
+        return jsonResponse(keys);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+server.registerTool("delete_api_key", {
+    description: "Delete an API key by ID. Use list_api_keys first to find the key ID.",
+    inputSchema: {
+        keyId: z.string().describe("The API key ID to delete"),
+    },
+}, async ({ keyId }) => {
+    try {
+        const result = await client.deleteApiKey(keyId);
+        return jsonResponse(result);
+    }
+    catch (e) {
+        return errorResponse(e);
+    }
+});
+// ==========================================
+// Start Server
+// ==========================================
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Magnolia MCP server v1.0 running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/magnolia-client.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Magnolia API client for the MCP server.
+ * Uses API keys obtained from the ClawBot.cash KYC flow.
+ *
+ * IMPORTANT: API paths are based on the official Magnolia documentation at
+ * docs.magnolia.financial. The API has multiple services:
+ *
+ *   - /auth/*                          — Authentication (login, API keys)
+ *   - /api/v2/{coin}/wallet/*          — Crypto wallet operations
+ *   - /api/v2/bankaccounts/*           — Bank account management
+ *   - /api/v2/enterprise/*             — Enterprise management
+ *   - /api/prime/trading/v1/accounts/* — Trading (orders, balances, products)
+ *   - /api/fiat/v1/*                   — Fiat/ACH operations
+ *   - /api/evs/v1/*                    — KYC/Identity verification
+ *   - /api/tradfi/v1/*                 — Traditional finance utilities
+ */
+export declare class MagnoliaClient {
+    private apiUrl;
+    private apiKey;
+    constructor(apiKey: string, apiUrl?: string);
+    private request;
+    /**
+     * Login with email/password to get a JWT token.
+     * JWT tokens expire after 1 hour.
+     */
+    login(email: string, password: string): Promise<unknown>;
+    /**
+     * List all API keys for the authenticated user.
+     */
+    listApiKeys(): Promise<unknown>;
+    /**
+     * Delete an API key by ID.
+     */
+    deleteApiKey(keyId: string): Promise<unknown>;
+    /**
+     * List enterprises accessible to this user.
+     */
+    getEnterprises(): Promise<unknown>;
+    /**
+     * List wallets for a specific cryptocurrency.
+     * @param coin - Coin ticker (e.g., "btc", "eth", "tbtc" for testnet)
+     */
+    listWallets(coin: string): Promise<unknown>;
+    /**
+     * Get a specific wallet by ID.
+     */
+    getWallet(coin: string, walletId: string): Promise<unknown>;
+    /**
+     * Generate a new receive address for a wallet.
+     */
+    generateAddress(coin: string, walletId: string): Promise<unknown>;
+    /**
+     * List all addresses for a wallet.
+     */
+    listAddresses(coin: string, walletId: string): Promise<unknown>;
+    /**
+     * Get address balances for a wallet.
+     */
+    getAddressBalances(coin: string, walletId: string): Promise<unknown>;
+    /**
+     * Send a transaction from a wallet.
+     */
+    sendTransaction(coin: string, walletId: string, data: {
+        address: string;
+        amount: string;
+        walletPassphrase?: string;
+        memo?: string;
+    }): Promise<unknown>;
+    /**
+     * Get transfer status for a wallet.
+     */
+    getWalletTransfer(coin: string, walletId: string, transferId: string): Promise<unknown>;
+    /**
+     * List transfers for a wallet.
+     */
+    listWalletTransfers(coin: string, walletId: string): Promise<unknown>;
+    /**
+     * List all bank accounts.
+     */
+    listBankAccounts(params?: {
+        type?: string;
+        verificationState?: string;
+        enterpriseId?: string;
+    }): Promise<unknown>;
+    /**
+     * Get a specific bank account by ID.
+     */
+    getBankAccount(bankAccountId: string): Promise<unknown>;
+    /**
+     * Add a new bank account.
+     *
+     * NOTE: API requires complete owner address information (discovered via E2E testing).
+     * The ownerAddress object must contain these fields (snake_case):
+     * - address_line_1
+     * - city_locality
+     * - state_province
+     * - postal_code
+     */
+    addBankAccount(data: {
+        type: "wire" | "ach" | "sepa";
+        name: string;
+        ownerName: string;
+        shortCountryCode: string;
+        accountNumber: string;
+        currency: string;
+        routingNumber?: string;
+        swiftCode?: string;
+        accountType?: "checking" | "saving";
+        ownerAddressCountryCode: string;
+        ownerAddress: {
+            address_line_1: string;
+            city_locality: string;
+            state_province: string;
+            postal_code: string;
+        };
+    }): Promise<unknown>;
+    /**
+     * Update a bank account.
+     */
+    updateBankAccount(bankAccountId: string, data: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Delete a bank account.
+     */
+    deleteBankAccount(bankAccountId: string): Promise<unknown>;
+    /**
+     * Get deposit info for bank accounts.
+     */
+    getDepositInfo(): Promise<unknown>;
+    /**
+     * Get account balances for a trading account.
+     */
+    getTradingBalances(accountId: string): Promise<unknown>;
+    /**
+     * List available trading products for an account.
+     */
+    getTradingProducts(accountId: string): Promise<unknown>;
+    /**
+     * Place a trading order.
+     */
+    placeOrder(accountId: string, data: {
+        type: "market" | "limit" | "twap" | "steady_pace";
+        product: string;
+        side: "buy" | "sell";
+        quantity: string;
+        quantityCurrency: string;
+        limitPrice?: string;
+        duration?: number;
+        clientOrderId?: string;
+        fundingType?: "margin" | "funded";
+    }): Promise<unknown>;
+    /**
+     * List orders for a trading account.
+     */
+    listOrders(accountId: string, params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<unknown>;
+    /**
+     * Get a specific order by ID.
+     */
+    getOrder(accountId: string, orderId: string): Promise<unknown>;
+    /**
+     * Cancel an order.
+     */
+    cancelOrder(accountId: string, orderId: string): Promise<unknown>;
+    /**
+     * Get ACH debit agreement.
+     */
+    getAchAgreement(): Promise<unknown>;
+    /**
+     * Accept ACH debit agreement.
+     */
+    acceptAchAgreement(data: {
+        bankAccountId: string;
+    }): Promise<unknown>;
+    /**
+     * Create an ACH debit transaction.
+     */
+    createAchDebit(data: {
+        bankAccountId: string;
+        amount: string;
+        currency: string;
+    }): Promise<unknown>;
+    /**
+     * Create a lightning invoice.
+     */
+    createLightningInvoice(walletId: string, data: {
+        amount: string;
+        memo?: string;
+    }): Promise<unknown>;
+    /**
+     * Get a lightning invoice status.
+     */
+    getLightningInvoice(walletId: string, paymentHash: string): Promise<unknown>;
+    /**
+     * Make a lightning payment.
+     */
+    makeLightningPayment(walletId: string, data: {
+        invoice: string;
+    }): Promise<unknown>;
+    /**
+     * List lightning transactions.
+     */
+    listLightningTransactions(walletId: string): Promise<unknown>;
+    /**
+     * Look up bank routing number information.
+     * @param bankType - "ach" or "wire"
+     */
+    lookupRoutingNumber(bankType: "ach" | "wire", routingNumber: string): Promise<unknown>;
+}

package/dist/magnolia-client.js

@@ -0,0 +1,305 @@
+/**
+ * Magnolia API client for the MCP server.
+ * Uses API keys obtained from the ClawBot.cash KYC flow.
+ *
+ * IMPORTANT: API paths are based on the official Magnolia documentation at
+ * docs.magnolia.financial. The API has multiple services:
+ *
+ *   - /auth/*                          — Authentication (login, API keys)
+ *   - /api/v2/{coin}/wallet/*          — Crypto wallet operations
+ *   - /api/v2/bankaccounts/*           — Bank account management
+ *   - /api/v2/enterprise/*             — Enterprise management
+ *   - /api/prime/trading/v1/accounts/* — Trading (orders, balances, products)
+ *   - /api/fiat/v1/*                   — Fiat/ACH operations
+ *   - /api/evs/v1/*                    — KYC/Identity verification
+ *   - /api/tradfi/v1/*                 — Traditional finance utilities
+ */
+const DEFAULT_API_URL = "https://api.magfi.net";
+export class MagnoliaClient {
+    apiUrl;
+    apiKey;
+    constructor(apiKey, apiUrl) {
+        this.apiKey = apiKey;
+        this.apiUrl = apiUrl || DEFAULT_API_URL;
+    }
+    async request(path, options = {}) {
+        const headers = {
+            "User-Agent": "ClawBot-MCP/1.0",
+            Authorization: `Bearer ${this.apiKey}`,
+            ...(options.headers || {}),
+        };
+        if (options.body && typeof options.body === "string") {
+            headers["Content-Type"] = "application/json";
+        }
+        const res = await fetch(`${this.apiUrl}${path}`, {
+            ...options,
+            headers,
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new Error(`Magnolia API error ${res.status} on ${options.method || "GET"} ${path}: ${text}`);
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    // --- Authentication ---
+    /**
+     * Login with email/password to get a JWT token.
+     * JWT tokens expire after 1 hour.
+     */
+    async login(email, password) {
+        return this.request("/auth/login", {
+            method: "POST",
+            body: JSON.stringify({ email, password }),
+            // Don't send API key for login, use raw request
+        });
+    }
+    /**
+     * List all API keys for the authenticated user.
+     */
+    async listApiKeys() {
+        return this.request("/auth/api-key");
+    }
+    /**
+     * Delete an API key by ID.
+     */
+    async deleteApiKey(keyId) {
+        return this.request(`/auth/api-key/${keyId}`, {
+            method: "DELETE",
+        });
+    }
+    // --- Enterprise ---
+    /**
+     * List enterprises accessible to this user.
+     */
+    async getEnterprises() {
+        return this.request("/api/v2/enterprise");
+    }
+    // --- Crypto Wallets (v2/{coin}/wallet) ---
+    /**
+     * List wallets for a specific cryptocurrency.
+     * @param coin - Coin ticker (e.g., "btc", "eth", "tbtc" for testnet)
+     */
+    async listWallets(coin) {
+        return this.request(`/api/v2/${coin}/wallet`);
+    }
+    /**
+     * Get a specific wallet by ID.
+     */
+    async getWallet(coin, walletId) {
+        return this.request(`/api/v2/${coin}/wallet/${walletId}`);
+    }
+    /**
+     * Generate a new receive address for a wallet.
+     */
+    async generateAddress(coin, walletId) {
+        return this.request(`/api/v2/${coin}/wallet/${walletId}/address`, {
+            method: "POST",
+        });
+    }
+    /**
+     * List all addresses for a wallet.
+     */
+    async listAddresses(coin, walletId) {
+        return this.request(`/api/v2/${coin}/wallet/${walletId}/addresses`);
+    }
+    /**
+     * Get address balances for a wallet.
+     */
+    async getAddressBalances(coin, walletId) {
+        return this.request(`/api/v2/${coin}/wallet/${walletId}/addresses/balances`);
+    }
+    /**
+     * Send a transaction from a wallet.
+     */
+    async sendTransaction(coin, walletId, data) {
+        return this.request(`/api/v2/${coin}/wallet/${walletId}/tx/send`, {
+            method: "POST",
+            body: JSON.stringify(data),
+        });
+    }
+    /**
+     * Get transfer status for a wallet.
+     */
+    async getWalletTransfer(coin, walletId, transferId) {
+        return this.request(`/api/v2/${coin}/wallet/${walletId}/transfer/${transferId}`);
+    }
+    /**
+     * List transfers for a wallet.
+     */
+    async listWalletTransfers(coin, walletId) {
+        return this.request(`/api/v2/${coin}/wallet/${walletId}/transfer`);
+    }
+    // --- Bank Accounts (v2/bankaccounts) ---
+    /**
+     * List all bank accounts.
+     */
+    async listBankAccounts(params) {
+        const query = new URLSearchParams();
+        if (params?.type)
+            query.set("type", params.type);
+        if (params?.verificationState)
+            query.set("verificationState", params.verificationState);
+        if (params?.enterpriseId)
+            query.set("enterpriseId", params.enterpriseId);
+        const qs = query.toString();
+        return this.request(`/api/v2/bankaccounts${qs ? `?${qs}` : ""}`);
+    }
+    /**
+     * Get a specific bank account by ID.
+     */
+    async getBankAccount(bankAccountId) {
+        return this.request(`/api/v2/bankaccounts/${bankAccountId}`);
+    }
+    /**
+     * Add a new bank account.
+     *
+     * NOTE: API requires complete owner address information (discovered via E2E testing).
+     * The ownerAddress object must contain these fields (snake_case):
+     * - address_line_1
+     * - city_locality
+     * - state_province
+     * - postal_code
+     */
+    async addBankAccount(data) {
+        return this.request("/api/v2/bankaccounts", {
+            method: "POST",
+            body: JSON.stringify(data),
+        });
+    }
+    /**
+     * Update a bank account.
+     */
+    async updateBankAccount(bankAccountId, data) {
+        return this.request(`/api/v2/bankaccounts/${bankAccountId}`, {
+            method: "PUT",
+            body: JSON.stringify(data),
+        });
+    }
+    /**
+     * Delete a bank account.
+     */
+    async deleteBankAccount(bankAccountId) {
+        return this.request(`/api/v2/bankaccounts/${bankAccountId}`, { method: "DELETE" });
+    }
+    /**
+     * Get deposit info for bank accounts.
+     */
+    async getDepositInfo() {
+        return this.request("/api/v2/bankaccounts/deposit/info");
+    }
+    // --- Trading (Prime) ---
+    /**
+     * Get account balances for a trading account.
+     */
+    async getTradingBalances(accountId) {
+        return this.request(`/api/prime/trading/v1/accounts/${accountId}/balances`);
+    }
+    /**
+     * List available trading products for an account.
+     */
+    async getTradingProducts(accountId) {
+        return this.request(`/api/prime/trading/v1/accounts/${accountId}/products`);
+    }
+    /**
+     * Place a trading order.
+     */
+    async placeOrder(accountId, data) {
+        return this.request(`/api/prime/trading/v1/accounts/${accountId}/orders`, {
+            method: "POST",
+            body: JSON.stringify(data),
+        });
+    }
+    /**
+     * List orders for a trading account.
+     */
+    async listOrders(accountId, params) {
+        const query = new URLSearchParams();
+        if (params?.limit)
+            query.set("limit", String(params.limit));
+        if (params?.offset)
+            query.set("offset", String(params.offset));
+        const qs = query.toString();
+        return this.request(`/api/prime/trading/v1/accounts/${accountId}/orders${qs ? `?${qs}` : ""}`);
+    }
+    /**
+     * Get a specific order by ID.
+     */
+    async getOrder(accountId, orderId) {
+        return this.request(`/api/prime/trading/v1/accounts/${accountId}/orders/${orderId}`);
+    }
+    /**
+     * Cancel an order.
+     */
+    async cancelOrder(accountId, orderId) {
+        return this.request(`/api/prime/trading/v1/accounts/${accountId}/orders/${orderId}/cancel`, { method: "POST" });
+    }
+    // --- Fiat/ACH ---
+    /**
+     * Get ACH debit agreement.
+     */
+    async getAchAgreement() {
+        return this.request("/api/fiat/v1/transaction/ach-debit/agreement");
+    }
+    /**
+     * Accept ACH debit agreement.
+     */
+    async acceptAchAgreement(data) {
+        return this.request("/api/fiat/v1/transaction/ach-debit/agreement", {
+            method: "POST",
+            body: JSON.stringify(data),
+        });
+    }
+    /**
+     * Create an ACH debit transaction.
+     */
+    async createAchDebit(data) {
+        return this.request("/api/fiat/v1/transaction/ach-debit", {
+            method: "POST",
+            body: JSON.stringify(data),
+        });
+    }
+    // --- Lightning Network ---
+    /**
+     * Create a lightning invoice.
+     */
+    async createLightningInvoice(walletId, data) {
+        return this.request(`/api/v2/wallet/${walletId}/lightning/invoice`, {
+            method: "POST",
+            body: JSON.stringify(data),
+        });
+    }
+    /**
+     * Get a lightning invoice status.
+     */
+    async getLightningInvoice(walletId, paymentHash) {
+        return this.request(`/api/v2/wallet/${walletId}/lightning/invoice/${paymentHash}`);
+    }
+    /**
+     * Make a lightning payment.
+     */
+    async makeLightningPayment(walletId, data) {
+        return this.request(`/api/v2/wallet/${walletId}/lightning/payment`, {
+            method: "POST",
+            body: JSON.stringify(data),
+        });
+    }
+    /**
+     * List lightning transactions.
+     */
+    async listLightningTransactions(walletId) {
+        return this.request(`/api/v2/wallet/${walletId}/lightning/transaction`);
+    }
+    // --- Utility ---
+    /**
+     * Look up bank routing number information.
+     * @param bankType - "ach" or "wire"
+     */
+    async lookupRoutingNumber(bankType, routingNumber) {
+        return this.request(`/api/tradfi/v1/banks/${bankType}/${routingNumber}`);
+    }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@magnolia-financial/banking-mcp",
+  "version": "1.0.0",
+  "description": "MCP server wrapping the Magnolia banking API for AI agents",
+  "main": "dist/index.js",
+  "bin": {
+    "banking-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "MAGNOLIA_API_KEY=${MAGNOLIA_API_KEY} MAGNOLIA_API_URL=https://api.dev.magfi.dev vitest run --reporter=verbose"
+  },
+  "keywords": [
+    "mcp",
+    "magnolia",
+    "banking",
+    "ai-agent"
+  ],
+  "author": "ClawBot",
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}