globodai-mcp-payment-manager 1.0.1

package/dist/tools/prepare-payment.js

@@ -0,0 +1,93 @@
+/**
+ * Prepare a payment for confirmation
+ *
+ * This creates a pending transaction that must be confirmed before execution.
+ * Security: User must explicitly confirm with CVV before any charge.
+ */
+import { z } from "zod";
+import { randomUUID } from "crypto";
+import { getCard, logTransaction } from "../lib/cards";
+import { isUnlocked, isPinConfigured } from "../lib/pin-manager";
+export const name = "prepare_payment";
+export const description = "Prepare a payment for a booking (flight, train, hotel, etc.). This creates a PENDING transaction that must be confirmed with confirm_payment before any charge is made.";
+export const parameters = z.object({
+    card_id: z.string().describe("ID of the card to use"),
+    amount: z.number().describe("Amount to charge"),
+    currency: z.string().describe("Currency code (EUR, USD, etc.)"),
+    type: z.enum(["flight", "train", "hotel", "general"]).describe("Type of purchase"),
+    description: z.string().describe("What is being purchased (e.g., 'Paris-London Eurostar 15 Feb')"),
+    provider: z.string().describe("Booking provider (e.g., 'Trainline', 'Air France', 'Booking.com')"),
+    details: z.record(z.unknown()).optional().describe("Additional booking details"),
+});
+export async function execute(args) {
+    // Check cards are unlocked
+    if (!isPinConfigured()) {
+        return {
+            success: false,
+            error: "Master PIN not configured. Use setup_pin first.",
+        };
+    }
+    if (!isUnlocked()) {
+        return {
+            success: false,
+            error: "Cards are locked. Use unlock_cards with your PIN first.",
+        };
+    }
+    // Verify card exists and is enabled
+    const card = await getCard(args.card_id);
+    if (!card) {
+        return {
+            success: false,
+            error: "Card not found",
+        };
+    }
+    if (!card.enabled) {
+        return {
+            success: false,
+            error: "Card is disabled",
+        };
+    }
+    // Check usage restrictions
+    if (!card.allowedUsage.includes("all") && !card.allowedUsage.includes(args.type)) {
+        return {
+            success: false,
+            error: `Card "${card.nickname}" is not allowed for ${args.type} purchases. Allowed: ${card.allowedUsage.join(", ")}`,
+        };
+    }
+    // Check limits
+    if (card.limits?.perTransaction && args.amount > card.limits.perTransaction) {
+        return {
+            success: false,
+            error: `Amount exceeds per-transaction limit of ${card.limits.perTransaction} ${card.limits.currency}`,
+        };
+    }
+    // Create pending transaction
+    const txId = randomUUID();
+    const transaction = {
+        id: txId,
+        cardId: card.id,
+        type: args.type,
+        amount: args.amount,
+        currency: args.currency,
+        description: args.description,
+        provider: args.provider,
+        status: "pending",
+        createdAt: new Date().toISOString(),
+        details: args.details,
+    };
+    await logTransaction(transaction);
+    return {
+        success: true,
+        transaction_id: txId,
+        status: "pending",
+        summary: {
+            card: `${card.nickname} (****${card.lastFourDigits})`,
+            amount: `${args.amount} ${args.currency}`,
+            type: args.type,
+            description: args.description,
+            provider: args.provider,
+        },
+        next_step: "Call confirm_payment with this transaction_id and the card CVV to complete the payment",
+        warning: "NO CHARGE has been made yet. You must confirm to proceed.",
+    };
+}

package/dist/tools/remove-card.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Remove a payment card
+ */
+import { z } from "zod";
+export declare const name = "remove_card";
+export declare const description = "Remove a saved payment card. This action is irreversible.";
+export declare const parameters: z.ZodObject<{
+    card_id: z.ZodString;
+    confirm: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    card_id: string;
+    confirm: boolean;
+}, {
+    card_id: string;
+    confirm: boolean;
+}>;
+export declare function execute(args: z.infer<typeof parameters>): Promise<{
+    success: boolean;
+    error: string;
+    message?: undefined;
+} | {
+    success: boolean;
+    message: string;
+    error?: undefined;
+}>;

package/dist/tools/remove-card.js

@@ -0,0 +1,39 @@
+/**
+ * Remove a payment card
+ */
+import { z } from "zod";
+import { removeCard, getCard } from "../lib/cards";
+export const name = "remove_card";
+export const description = "Remove a saved payment card. This action is irreversible.";
+export const parameters = z.object({
+    card_id: z.string().describe("ID of the card to remove"),
+    confirm: z.boolean().describe("Must be true to confirm deletion"),
+});
+export async function execute(args) {
+    if (!args.confirm) {
+        return {
+            success: false,
+            error: "You must set confirm=true to delete a card",
+        };
+    }
+    const card = await getCard(args.card_id);
+    if (!card) {
+        return {
+            success: false,
+            error: "Card not found",
+        };
+    }
+    const removed = await removeCard(args.card_id);
+    if (removed) {
+        return {
+            success: true,
+            message: `Card "${card.nickname}" (****${card.lastFourDigits}) has been removed`,
+        };
+    }
+    else {
+        return {
+            success: false,
+            error: "Failed to remove card",
+        };
+    }
+}

package/dist/tools/remove-wallet.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Remove a crypto wallet
+ */
+import { z } from "zod";
+export declare const name = "remove_wallet";
+export declare const description = "Remove a saved crypto wallet. This deletes the stored keys (if any). This action is irreversible.";
+export declare const parameters: z.ZodObject<{
+    wallet_id: z.ZodString;
+    confirm: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    confirm: boolean;
+    wallet_id: string;
+}, {
+    confirm: boolean;
+    wallet_id: string;
+}>;
+export declare function execute(args: z.infer<typeof parameters>): Promise<{
+    success: boolean;
+    error: string;
+    message?: undefined;
+    warning?: undefined;
+} | {
+    success: boolean;
+    message: string;
+    warning: string | undefined;
+    error?: undefined;
+}>;

package/dist/tools/remove-wallet.js

@@ -0,0 +1,40 @@
+/**
+ * Remove a crypto wallet
+ */
+import { z } from "zod";
+import { removeWallet, getWallet } from "../lib/wallets";
+export const name = "remove_wallet";
+export const description = "Remove a saved crypto wallet. This deletes the stored keys (if any). This action is irreversible.";
+export const parameters = z.object({
+    wallet_id: z.string().describe("ID of the wallet to remove"),
+    confirm: z.boolean().describe("Must be true to confirm deletion"),
+});
+export async function execute(args) {
+    if (!args.confirm) {
+        return {
+            success: false,
+            error: "You must set confirm=true to delete a wallet",
+        };
+    }
+    const wallet = await getWallet(args.wallet_id);
+    if (!wallet) {
+        return {
+            success: false,
+            error: "Wallet not found",
+        };
+    }
+    const removed = await removeWallet(args.wallet_id);
+    if (removed) {
+        return {
+            success: true,
+            message: `Wallet "${wallet.nickname}" (${wallet.address.slice(0, 10)}...) has been removed`,
+            warning: wallet.type === "hot" ? "Private key has been deleted" : undefined,
+        };
+    }
+    else {
+        return {
+            success: false,
+            error: "Failed to remove wallet",
+        };
+    }
+}

package/dist/tools/setup-pin.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Set up master PIN for card access
+ */
+import { z } from "zod";
+export declare const name = "setup_pin";
+export declare const description = "Set up a master PIN (4-8 characters) for card access. This PIN encrypts your CVVs and must be entered to unlock cards for payments. Choose something you'll remember!";
+export declare const parameters: z.ZodObject<{
+    pin: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    pin: string;
+}, {
+    pin: string;
+}>;
+export declare function execute(args: z.infer<typeof parameters>): Promise<{
+    success: boolean;
+    message: string;
+    note: string;
+    session_timeout: string;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: string | undefined;
+    message?: undefined;
+    note?: undefined;
+    session_timeout?: undefined;
+}>;

package/dist/tools/setup-pin.js

@@ -0,0 +1,33 @@
+/**
+ * Set up master PIN for card access
+ */
+import { z } from "zod";
+import { setupPin, isPinConfigured } from "../lib/pin-manager";
+export const name = "setup_pin";
+export const description = "Set up a master PIN (4-8 characters) for card access. This PIN encrypts your CVVs and must be entered to unlock cards for payments. Choose something you'll remember!";
+export const parameters = z.object({
+    pin: z.string().describe("Your master PIN (4-8 characters). This will encrypt your CVVs."),
+});
+export async function execute(args) {
+    if (isPinConfigured()) {
+        return {
+            success: false,
+            error: "PIN already configured. Use change_pin to modify it.",
+        };
+    }
+    const result = setupPin(args.pin);
+    if (result.success) {
+        return {
+            success: true,
+            message: "Master PIN configured! Cards are now unlocked.",
+            note: "Your PIN encrypts all CVVs. Without it, cards cannot be used.",
+            session_timeout: "30 minutes of inactivity will lock cards automatically",
+        };
+    }
+    else {
+        return {
+            success: false,
+            error: result.error,
+        };
+    }
+}

package/dist/tools/sign-crypto-tx.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Sign and broadcast a prepared crypto transaction
+ */
+import { z } from "zod";
+export declare const name = "sign_crypto_tx";
+export declare const description = "Sign and broadcast a prepared crypto transaction.\n\nFor hot wallets: signs with the stored private key.\nFor hardware wallets: requires the device to be connected (integration needed).\nFor watch-only: not allowed.";
+export declare const parameters: z.ZodObject<{
+    transaction_id: z.ZodString;
+    confirm: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    confirm: boolean;
+    transaction_id: string;
+}, {
+    confirm: boolean;
+    transaction_id: string;
+}>;
+export declare function execute(args: z.infer<typeof parameters>): Promise<{
+    success: boolean;
+    error: string;
+    status?: undefined;
+    transaction_id?: undefined;
+    message?: undefined;
+    summary?: undefined;
+    note?: undefined;
+    next_steps?: undefined;
+    explorer?: undefined;
+} | {
+    success: boolean;
+    status: string;
+    transaction_id: string;
+    message: string;
+    summary: {
+        from: string;
+        to: string;
+        amount: string;
+        chain: string;
+    };
+    note: string;
+    next_steps: string[];
+    explorer: string;
+    error?: undefined;
+}>;

package/dist/tools/sign-crypto-tx.js

@@ -0,0 +1,75 @@
+/**
+ * Sign and broadcast a prepared crypto transaction
+ */
+import { z } from "zod";
+import { getWallet, getCryptoTransactions, updateCryptoTransaction, CHAIN_CONFIG } from "../lib/wallets";
+export const name = "sign_crypto_tx";
+export const description = `Sign and broadcast a prepared crypto transaction.
+
+For hot wallets: signs with the stored private key.
+For hardware wallets: requires the device to be connected (integration needed).
+For watch-only: not allowed.`;
+export const parameters = z.object({
+    transaction_id: z.string().describe("ID of the pending transaction to sign"),
+    confirm: z.boolean().describe("Must be true to confirm you want to sign and broadcast"),
+});
+export async function execute(args) {
+    if (!args.confirm) {
+        return {
+            success: false,
+            error: "You must set confirm=true to sign and broadcast the transaction",
+        };
+    }
+    // Find the pending transaction
+    const transactions = await getCryptoTransactions(100);
+    const tx = transactions.find((t) => t.id === args.transaction_id);
+    if (!tx) {
+        return { success: false, error: "Transaction not found" };
+    }
+    if (tx.status !== "pending") {
+        return { success: false, error: `Transaction is already ${tx.status}` };
+    }
+    // Get the wallet
+    const wallet = await getWallet(tx.walletId);
+    if (!wallet) {
+        return { success: false, error: "Wallet no longer exists" };
+    }
+    if (wallet.type === "watch-only") {
+        return { success: false, error: "Watch-only wallets cannot sign transactions" };
+    }
+    const chainConfig = CHAIN_CONFIG[wallet.chain];
+    // Here we would:
+    // 1. For hot wallets: sign with ethers.js/viem using the private key
+    // 2. For hardware wallets: prompt for Ledger/Trezor connection
+    // 3. Broadcast to the network
+    // For now, mark as signed and return what would be needed
+    await updateCryptoTransaction(tx.id, {
+        status: "signed",
+        signedAt: new Date().toISOString(),
+    });
+    const amountDisplay = tx.tokenSymbol
+        ? `${tx.value} ${tx.tokenSymbol}`
+        : `${tx.value} ${chainConfig?.nativeCurrency ?? "tokens"}`;
+    return {
+        success: true,
+        status: "signed",
+        transaction_id: tx.id,
+        message: wallet.type === "hardware"
+            ? "Transaction prepared for hardware signing"
+            : "Transaction signed (ready for broadcast)",
+        summary: {
+            from: wallet.nickname,
+            to: tx.to,
+            amount: amountDisplay,
+            chain: chainConfig?.name ?? wallet.chain,
+        },
+        // In production, this would return the actual tx hash
+        note: "Integration with ethers.js/viem needed for actual signing and broadcast",
+        next_steps: [
+            "Integrate with ethers.js or viem for transaction signing",
+            "Add RPC endpoint configuration for each chain",
+            "For hardware wallets, integrate with @ledgerhq/hw-transport or similar",
+        ],
+        explorer: chainConfig?.explorerUrl,
+    };
+}

package/dist/tools/unlock-cards.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Unlock cards with master PIN
+ */
+import { z } from "zod";
+export declare const name = "unlock_cards";
+export declare const description = "Unlock your cards by entering your master PIN. Required before making any payment. Cards stay unlocked for 30 minutes of activity.";
+export declare const parameters: z.ZodObject<{
+    pin: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    pin: string;
+}, {
+    pin: string;
+}>;
+export declare function execute(args: z.infer<typeof parameters>): Promise<{
+    success: boolean;
+    message: string;
+    remaining_minutes: number | undefined;
+    session_expires_in?: undefined;
+    tip?: undefined;
+    error?: undefined;
+} | {
+    success: boolean;
+    message: string;
+    session_expires_in: string;
+    tip: string;
+    remaining_minutes?: undefined;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: string | undefined;
+    message?: undefined;
+    remaining_minutes?: undefined;
+    session_expires_in?: undefined;
+    tip?: undefined;
+}>;

package/dist/tools/unlock-cards.js

@@ -0,0 +1,41 @@
+/**
+ * Unlock cards with master PIN
+ */
+import { z } from "zod";
+import { unlock, isPinConfigured, getStatus } from "../lib/pin-manager";
+export const name = "unlock_cards";
+export const description = "Unlock your cards by entering your master PIN. Required before making any payment. Cards stay unlocked for 30 minutes of activity.";
+export const parameters = z.object({
+    pin: z.string().describe("Your master PIN"),
+});
+export async function execute(args) {
+    if (!isPinConfigured()) {
+        return {
+            success: false,
+            error: "No PIN configured. Use setup_pin first.",
+        };
+    }
+    const status = getStatus();
+    if (status.unlocked) {
+        return {
+            success: true,
+            message: "Cards already unlocked",
+            remaining_minutes: status.remainingMinutes,
+        };
+    }
+    const result = unlock(args.pin);
+    if (result.success) {
+        return {
+            success: true,
+            message: "Cards unlocked! You can now make payments.",
+            session_expires_in: `${result.expiresIn} minutes`,
+            tip: "Cards will auto-lock after 30 minutes of inactivity",
+        };
+    }
+    else {
+        return {
+            success: false,
+            error: result.error,
+        };
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "globodai-mcp-payment-manager",
+  "version": "1.0.1",
+  "description": "MCP Server for Payment Management - Secure card storage and crypto wallet management with encryption",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "mcp-payment-manager": "dist/index.js"
+  },
+  "scripts": {
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "payment",
+    "crypto",
+    "wallet",
+    "blockchain",
+    "cards",
+    "finance",
+    "encryption",
+    "ai",
+    "llm",
+    "claude"
+  ],
+  "author": "Kevin Valfin <kevin@globodai.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/globodai-group/mcp-payment-manager.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "@aws-sdk/client-kms": "^3.0.0",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "tsx": "^4.0.0",
+    "@types/node": "^22.0.0"
+  },
+  "homepage": "https://github.com/globodai-group/mcp-payment-manager#readme",
+  "bugs": {
+    "url": "https://github.com/globodai-group/mcp-payment-manager/issues"
+  }
+}

package/src/index.ts

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+/**
+ * Payment Manager MCP Server
+ * 
+ * Comprehensive personal finance management with bank cards and crypto wallets:
+ * 
+ * 🏦 CARDS (Fiat):
+ * - Encrypted card storage (AES-256-GCM + AWS KMS)
+ * - PIN-protected CVV access
+ * - Two-step payment flow (prepare → confirm)
+ * - Card status management (lock/unlock)
+ * 
+ * 🪙 WALLETS (Crypto):
+ * - Multi-chain support (ETH, Polygon, Arbitrum, Base, Solana, Bitcoin)
+ * - Hot, watch-only, and hardware wallet types
+ * - Encrypted private key storage
+ * - Real-time balance and transaction fetching
+ * 
+ * 🔐 SECURITY:
+ * - All sensitive data encrypted at rest
+ * - PIN-based access control
+ * - Complete audit logging
+ * - AWS KMS integration for enterprise security
+ * 
+ * Environment Variables:
+ * - MCP_MASTER_KEY: Master encryption key (256-bit)
+ * - AWS_KMS_KEY_ID: AWS KMS key ARN
+ * - ETHERSCAN_API_KEY: For Ethereum data
+ * - [CHAIN]SCAN_API_KEY: For other chain data
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// Card management tools
+import * as addCard from "./tools/add-card.js";
+import * as listCards from "./tools/list-cards.js";
+import * as removeCard from "./tools/remove-card.js";
+import * as cardStatus from "./tools/card-status.js";
+import * as lockCards from "./tools/lock-cards.js";
+import * as unlockCards from "./tools/unlock-cards.js";
+
+// Wallet management tools
+import * as addWallet from "./tools/add-wallet.js";
+import * as listWallets from "./tools/list-wallets.js";
+import * as removeWallet from "./tools/remove-wallet.js";
+import * as getWalletBalance from "./tools/get-wallet-balance.js";
+import * as getTotalBalance from "./tools/get-total-balance.js";
+import * as listWalletTransactions from "./tools/list-wallet-transactions.js";
+
+// Transaction tools
+import * as getTransactions from "./tools/get-transactions.js";
+import * as preparePayment from "./tools/prepare-payment.js";
+import * as confirmPayment from "./tools/confirm-payment.js";
+import * as prepareCryptoTx from "./tools/prepare-crypto-tx.js";
+import * as signCryptoTx from "./tools/sign-crypto-tx.js";
+
+// Security tools
+import * as setupPin from "./tools/setup-pin.js";
+
+const tools = [
+  // Card Management
+  addCard,
+  listCards,
+  removeCard,
+  cardStatus,
+  lockCards,
+  unlockCards,
+  // Wallet Management
+  addWallet,
+  listWallets,
+  removeWallet,
+  getWalletBalance,
+  getTotalBalance,
+  listWalletTransactions,
+  // Transactions
+  getTransactions,
+  preparePayment,
+  confirmPayment,
+  prepareCryptoTx,
+  signCryptoTx,
+  // Security
+  setupPin,
+];
+
+async function main() {
+  // Verify critical environment variables
+  const requiredEnvs = ['MCP_MASTER_KEY'];
+  const missing = requiredEnvs.filter(env => !process.env[env]);
+  if (missing.length > 0) {
+    console.error(`❌ Missing critical environment variables: ${missing.join(', ')}`);
+    console.error('⚠️  Payment Manager requires encryption keys for security!');
+    process.exit(1);
+  }
+
+  const server = new McpServer({
+    name: "mcp-payment-manager",
+    version: "1.0.0",
+  });
+
+  // Register all tools
+  for (const tool of tools) {
+    server.tool(
+      tool.name,
+      tool.description,
+      tool.parameters.shape,
+      async (args: Record<string, unknown>) => {
+        try {
+          const result = await tool.execute(args as any);
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+          };
+        } catch (error) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify({
+                  success: false,
+                  error: error instanceof Error ? error.message : "Unknown error",
+                }),
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+    );
+  }
+
+  // Connect to stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  
+  console.error("🔒 Payment Manager MCP Server started - All data encrypted at rest");
+}
+
+main().catch(console.error);