globodai-mcp-payment-manager 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/.env.example +23 -0
  2. package/.github/workflows/ci.yml +26 -0
  3. package/.github/workflows/release.yml +82 -0
  4. package/LICENSE +21 -0
  5. package/README.md +362 -0
  6. package/dist/index.d.ts +31 -0
  7. package/dist/index.js +122 -0
  8. package/dist/lib/blockchain.d.ts +50 -0
  9. package/dist/lib/blockchain.js +287 -0
  10. package/dist/lib/cards.d.ts +83 -0
  11. package/dist/lib/cards.js +276 -0
  12. package/dist/lib/cli-runner.d.ts +31 -0
  13. package/dist/lib/cli-runner.js +77 -0
  14. package/dist/lib/crypto.d.ts +39 -0
  15. package/dist/lib/crypto.js +228 -0
  16. package/dist/lib/cvv-crypto.d.ts +23 -0
  17. package/dist/lib/cvv-crypto.js +67 -0
  18. package/dist/lib/mcp-core.d.ts +46 -0
  19. package/dist/lib/mcp-core.js +86 -0
  20. package/dist/lib/pin-manager.d.ts +69 -0
  21. package/dist/lib/pin-manager.js +199 -0
  22. package/dist/lib/wallets.d.ts +91 -0
  23. package/dist/lib/wallets.js +227 -0
  24. package/dist/tools/add-card.d.ts +65 -0
  25. package/dist/tools/add-card.js +97 -0
  26. package/dist/tools/add-wallet.d.ts +65 -0
  27. package/dist/tools/add-wallet.js +104 -0
  28. package/dist/tools/card-status.d.ts +20 -0
  29. package/dist/tools/card-status.js +26 -0
  30. package/dist/tools/confirm-payment.d.ts +44 -0
  31. package/dist/tools/confirm-payment.js +88 -0
  32. package/dist/tools/get-total-balance.d.ts +41 -0
  33. package/dist/tools/get-total-balance.js +98 -0
  34. package/dist/tools/get-transactions.d.ts +39 -0
  35. package/dist/tools/get-transactions.js +40 -0
  36. package/dist/tools/get-wallet-balance.d.ts +43 -0
  37. package/dist/tools/get-wallet-balance.js +69 -0
  38. package/dist/tools/list-cards.d.ts +36 -0
  39. package/dist/tools/list-cards.js +39 -0
  40. package/dist/tools/list-wallet-transactions.d.ts +63 -0
  41. package/dist/tools/list-wallet-transactions.js +76 -0
  42. package/dist/tools/list-wallets.d.ts +41 -0
  43. package/dist/tools/list-wallets.js +50 -0
  44. package/dist/tools/lock-cards.d.ts +16 -0
  45. package/dist/tools/lock-cards.js +23 -0
  46. package/dist/tools/prepare-crypto-tx.d.ts +69 -0
  47. package/dist/tools/prepare-crypto-tx.js +93 -0
  48. package/dist/tools/prepare-payment.d.ts +57 -0
  49. package/dist/tools/prepare-payment.js +93 -0
  50. package/dist/tools/remove-card.d.ts +25 -0
  51. package/dist/tools/remove-card.js +39 -0
  52. package/dist/tools/remove-wallet.d.ts +27 -0
  53. package/dist/tools/remove-wallet.js +40 -0
  54. package/dist/tools/setup-pin.d.ts +26 -0
  55. package/dist/tools/setup-pin.js +33 -0
  56. package/dist/tools/sign-crypto-tx.d.ts +42 -0
  57. package/dist/tools/sign-crypto-tx.js +75 -0
  58. package/dist/tools/unlock-cards.d.ts +35 -0
  59. package/dist/tools/unlock-cards.js +41 -0
  60. package/package.json +50 -0
  61. package/src/index.ts +139 -0
  62. package/src/lib/blockchain.ts +375 -0
  63. package/src/lib/cards.ts +372 -0
  64. package/src/lib/cli-runner.ts +113 -0
  65. package/src/lib/crypto.ts +284 -0
  66. package/src/lib/cvv-crypto.ts +81 -0
  67. package/src/lib/mcp-core.ts +127 -0
  68. package/src/lib/pin-manager.ts +252 -0
  69. package/src/lib/wallets.ts +331 -0
  70. package/src/tools/add-card.ts +108 -0
  71. package/src/tools/add-wallet.ts +114 -0
  72. package/src/tools/card-status.ts +32 -0
  73. package/src/tools/confirm-payment.ts +103 -0
  74. package/src/tools/get-total-balance.ts +123 -0
  75. package/src/tools/get-transactions.ts +49 -0
  76. package/src/tools/get-wallet-balance.ts +75 -0
  77. package/src/tools/list-cards.ts +52 -0
  78. package/src/tools/list-wallet-transactions.ts +83 -0
  79. package/src/tools/list-wallets.ts +63 -0
  80. package/src/tools/lock-cards.ts +31 -0
  81. package/src/tools/prepare-crypto-tx.ts +108 -0
  82. package/src/tools/prepare-payment.ts +108 -0
  83. package/src/tools/remove-card.ts +46 -0
  84. package/src/tools/remove-wallet.ts +47 -0
  85. package/src/tools/setup-pin.ts +39 -0
  86. package/src/tools/sign-crypto-tx.ts +90 -0
  87. package/src/tools/unlock-cards.ts +48 -0
  88. package/tsconfig.json +19 -0
package/.env.example ADDED
@@ -0,0 +1,23 @@
1
+ # Payment Manager Configuration
2
+
3
+ # Encryption (Required for secure card storage)
4
+ MCP_MASTER_KEY=your_master_encryption_key_here_256_bit
5
+ AWS_KMS_KEY_ID=arn:aws:kms:region:account:key/your-kms-key-id
6
+
7
+ # AWS Credentials (for KMS encryption)
8
+ AWS_ACCESS_KEY_ID=your_aws_access_key
9
+ AWS_SECRET_ACCESS_KEY=your_aws_secret_key
10
+ AWS_REGION=us-east-1
11
+
12
+ # Blockchain Explorer APIs (for wallet balance and transaction history)
13
+ ETHERSCAN_API_KEY=your_etherscan_api_key
14
+ POLYGONSCAN_API_KEY=your_polygonscan_api_key
15
+ ARBISCAN_API_KEY=your_arbiscan_api_key
16
+ BASESCAN_API_KEY=your_basescan_api_key
17
+ BSCSCAN_API_KEY=your_bscscan_api_key
18
+
19
+ # Solana RPC (for Solana wallets)
20
+ SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
21
+
22
+ # Payment Providers (optional)
23
+ STRIPE_API_KEY=sk_test_your_stripe_api_key
@@ -0,0 +1,26 @@
1
+ name: CI
2
+
3
+ on:
4
+ pull_request:
5
+ branches: [master, main]
6
+ push:
7
+ branches: [master, main]
8
+
9
+ concurrency:
10
+ group: ${{ github.workflow }}-${{ github.ref }}
11
+ cancel-in-progress: true
12
+
13
+ jobs:
14
+ build:
15
+ name: Build & Typecheck
16
+ runs-on: ubuntu-latest
17
+ strategy:
18
+ matrix:
19
+ node-version: [20, 22]
20
+ steps:
21
+ - uses: actions/checkout@v4
22
+ - uses: actions/setup-node@v4
23
+ with:
24
+ node-version: ${{ matrix.node-version }}
25
+ - run: npm ci
26
+ - run: npm run build
@@ -0,0 +1,82 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ branches: [master, main]
6
+ workflow_dispatch:
7
+
8
+ permissions:
9
+ contents: write
10
+ packages: write
11
+
12
+ jobs:
13
+ release:
14
+ name: Release
15
+ runs-on: ubuntu-latest
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+ with:
19
+ fetch-depth: 0
20
+ token: ${{ secrets.GITHUB_TOKEN }}
21
+ - uses: actions/setup-node@v4
22
+ with:
23
+ node-version: '20'
24
+ registry-url: 'https://registry.npmjs.org'
25
+ - run: npm ci
26
+ - run: npm run build
27
+ - name: Configure Git
28
+ run: |
29
+ git config user.name "github-actions[bot]"
30
+ git config user.email "github-actions[bot]@users.noreply.github.com"
31
+ - name: Get version bump type
32
+ id: version-type
33
+ run: |
34
+ LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
35
+ COMMITS=$(git log $LAST_TAG..HEAD --pretty=format:"%s" 2>/dev/null || git log --pretty=format:"%s")
36
+ if echo "$COMMITS" | grep -qE "^(feat|feature)(\(.+\))?!:|BREAKING CHANGE"; then
37
+ echo "bump=major" >> $GITHUB_OUTPUT
38
+ elif echo "$COMMITS" | grep -qE "^(feat|feature)(\(.+\))?:"; then
39
+ echo "bump=minor" >> $GITHUB_OUTPUT
40
+ else
41
+ echo "bump=patch" >> $GITHUB_OUTPUT
42
+ fi
43
+ - name: Bump version
44
+ id: bump
45
+ run: |
46
+ NEW_VERSION=$(npm version ${{ steps.version-type.outputs.bump }} --no-git-tag-version)
47
+ echo "version=${NEW_VERSION#v}" >> $GITHUB_OUTPUT
48
+ - name: Generate changelog
49
+ id: changelog
50
+ run: |
51
+ LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
52
+ if [ -z "$LAST_TAG" ]; then
53
+ CHANGELOG=$(git log --pretty=format:"- %s (%h)" --no-merges)
54
+ else
55
+ CHANGELOG=$(git log $LAST_TAG..HEAD --pretty=format:"- %s (%h)" --no-merges)
56
+ fi
57
+ echo "changelog<<EOF" >> $GITHUB_OUTPUT
58
+ echo "$CHANGELOG" >> $GITHUB_OUTPUT
59
+ echo "EOF" >> $GITHUB_OUTPUT
60
+ - name: Commit & tag
61
+ run: |
62
+ git add package.json package-lock.json 2>/dev/null || git add package.json
63
+ git commit -m "chore(release): v${{ steps.bump.outputs.version }}" || true
64
+ git tag -a "v${{ steps.bump.outputs.version }}" -m "Release v${{ steps.bump.outputs.version }}"
65
+ git push && git push origin "v${{ steps.bump.outputs.version }}"
66
+ - name: Create GitHub Release
67
+ uses: softprops/action-gh-release@v2
68
+ with:
69
+ tag_name: v${{ steps.bump.outputs.version }}
70
+ name: v${{ steps.bump.outputs.version }}
71
+ body: |
72
+ ## What's Changed
73
+ ${{ steps.changelog.outputs.changelog }}
74
+ draft: false
75
+ prerelease: false
76
+ env:
77
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
78
+ - name: Publish to npm
79
+ run: npm publish --access public
80
+ env:
81
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
82
+ continue-on-error: true
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kevin Valfin
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,362 @@
1
+ # 💳 Payment Manager MCP Server
2
+
3
+ [![npm version](https://img.shields.io/npm/v/@artik0din/mcp-payment-manager.svg)](https://www.npmjs.com/package/@artik0din/mcp-payment-manager)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
+ [![MCP](https://img.shields.io/badge/MCP-compatible-blue.svg)](https://modelcontextprotocol.io)
6
+
7
+ > A comprehensive, enterprise-grade personal finance management system with encrypted card storage and multi-chain crypto wallet support
8
+
9
+ ## 🌟 Key Features
10
+
11
+ ### 🏦 Bank Card Management
12
+ - **🔐 Military-Grade Encryption** - AES-256-GCM + AWS KMS for card data
13
+ - **🔑 PIN-Protected Access** - CVV encrypted with master PIN
14
+ - **🛡️ Two-Step Payments** - Prepare → Confirm workflow for safety
15
+ - **🔒 Card Controls** - Lock/unlock cards instantly
16
+ - **📊 Transaction History** - Complete audit trail with timestamps
17
+
18
+ ### 🪙 Cryptocurrency Wallets
19
+ - **🌐 Multi-Chain Support** - Ethereum, Polygon, Arbitrum, Base, Solana, Bitcoin
20
+ - **🔥 Hot Wallets** - Encrypted private key storage for instant access
21
+ - **👀 Watch-Only** - Monitor addresses without spending capability
22
+ - **🔧 Hardware Integration** - Support for Ledger, Trezor workflows
23
+ - **⚡ Real-Time Data** - Live balances and transaction history via blockchain APIs
24
+ - **💰 Portfolio Tracking** - USD values and total balance calculation
25
+
26
+ ### 🛡️ Enterprise Security
27
+ - **🔐 End-to-End Encryption** - All sensitive data encrypted at rest
28
+ - **🌩️ AWS KMS Integration** - Enterprise key management
29
+ - **📋 Complete Audit Logs** - Every action logged with timestamps
30
+ - **🎯 Zero-Knowledge Architecture** - Your keys, your control
31
+ - **🔄 Backup & Recovery** - Encrypted backup capabilities
32
+
33
+ ## 📋 Prerequisites
34
+
35
+ - Node.js >= 20
36
+ - AWS account (for KMS encryption) OR local master key
37
+ - Blockchain API keys (Etherscan, Polygonscan, etc.)
38
+ - Basic understanding of cryptocurrency concepts
39
+
40
+ ## 🚀 Quick Start
41
+
42
+ ### Using npx (recommended)
43
+ ```bash
44
+ npx @artik0din/mcp-payment-manager
45
+ ```
46
+
47
+ ### Install globally
48
+ ```bash
49
+ npm install -g @artik0din/mcp-payment-manager
50
+ ```
51
+
52
+ ## ⚙️ Configuration
53
+
54
+ ### Security Setup (Critical)
55
+
56
+ #### Option 1: AWS KMS (Recommended for Production)
57
+ 1. Create AWS KMS key in your AWS account
58
+ 2. Set environment variables:
59
+ ```bash
60
+ export AWS_KMS_KEY_ID="arn:aws:kms:region:account:key/your-key-id"
61
+ export AWS_ACCESS_KEY_ID="your-aws-access-key"
62
+ export AWS_SECRET_ACCESS_KEY="your-aws-secret"
63
+ export AWS_REGION="us-east-1"
64
+ ```
65
+
66
+ #### Option 2: Local Master Key (Development)
67
+ ```bash
68
+ export MCP_MASTER_KEY="your-256-bit-master-key-here"
69
+ ```
70
+
71
+ ### Blockchain API Configuration
72
+
73
+ #### Required APIs for Full Functionality
74
+ | Provider | Purpose | Environment Variable |
75
+ |----------|---------|----------------------|
76
+ | [Etherscan](https://etherscan.io/apis) | Ethereum data | `ETHERSCAN_API_KEY` |
77
+ | [Polygonscan](https://polygonscan.com/apis) | Polygon data | `POLYGONSCAN_API_KEY` |
78
+ | [Arbiscan](https://arbiscan.io/apis) | Arbitrum data | `ARBISCAN_API_KEY` |
79
+ | [Basescan](https://basescan.org/apis) | Base data | `BASESCAN_API_KEY` |
80
+ | [BSCScan](https://bscscan.com/apis) | BSC data | `BSCSCAN_API_KEY` |
81
+
82
+ #### Solana Configuration
83
+ ```bash
84
+ export SOLANA_RPC_URL="https://api.mainnet-beta.solana.com"
85
+ ```
86
+
87
+ ### Environment Variables
88
+
89
+ | Variable | Required | Description |
90
+ |----------|----------|-------------|
91
+ | `MCP_MASTER_KEY` | Yes | 256-bit master encryption key |
92
+ | `AWS_KMS_KEY_ID` | Optional | AWS KMS key ARN (alternative to master key) |
93
+ | `AWS_ACCESS_KEY_ID` | If using KMS | AWS access key |
94
+ | `AWS_SECRET_ACCESS_KEY` | If using KMS | AWS secret key |
95
+ | `AWS_REGION` | If using KMS | AWS region |
96
+ | `ETHERSCAN_API_KEY` | For ETH | Ethereum blockchain data |
97
+ | `POLYGONSCAN_API_KEY` | For MATIC | Polygon blockchain data |
98
+ | `ARBISCAN_API_KEY` | For ARB | Arbitrum blockchain data |
99
+ | `BASESCAN_API_KEY` | For BASE | Base blockchain data |
100
+ | `BSCSCAN_API_KEY` | For BNB | BSC blockchain data |
101
+ | `SOLANA_RPC_URL` | For SOL | Solana RPC endpoint |
102
+ | `STRIPE_API_KEY` | Optional | Stripe integration |
103
+
104
+ ### MCP Client Setup
105
+
106
+ #### Claude Desktop / Cursor
107
+ ```json
108
+ {
109
+ "mcpServers": {
110
+ "payment-manager": {
111
+ "command": "npx",
112
+ "args": ["-y", "@artik0din/mcp-payment-manager"],
113
+ "env": {
114
+ "MCP_MASTER_KEY": "your-256-bit-encryption-key",
115
+ "ETHERSCAN_API_KEY": "your-etherscan-api-key",
116
+ "POLYGONSCAN_API_KEY": "your-polygonscan-api-key"
117
+ }
118
+ }
119
+ }
120
+ }
121
+ ```
122
+
123
+ ## 🔧 Available Tools
124
+
125
+ ### 🏦 Card Management Tools
126
+
127
+ #### add_card
128
+ Add a new payment card with full encryption.
129
+
130
+ **Parameters:**
131
+ - `nickname` (string, required): Friendly card name
132
+ - `card_number` (string, required): Full card number (encrypted)
133
+ - `expiration` (string, required): MM/YY format
134
+ - `cvv` (string, required): CVV/CVC (PIN-encrypted)
135
+ - `cardholder_name` (string, required): Name on card
136
+ - `brand` (string, optional): Card brand detection
137
+ - `usage` (string, optional): Card usage type (`personal`, `business`, `emergency`)
138
+
139
+ #### list_cards
140
+ List all stored cards with masked details.
141
+
142
+ **Parameters:**
143
+ - `include_locked` (boolean, optional): Include locked cards
144
+ - `usage_filter` (string, optional): Filter by usage type
145
+
146
+ #### remove_card
147
+ Permanently remove a card from storage.
148
+
149
+ **Parameters:**
150
+ - `card_id` (string, required): Card ID to remove
151
+ - `confirm` (boolean, required): Must be true to confirm
152
+
153
+ #### card_status
154
+ Check status and details of a specific card.
155
+
156
+ **Parameters:**
157
+ - `card_id` (string, required): Card ID to check
158
+
159
+ #### lock_cards / unlock_cards
160
+ Lock or unlock cards for security.
161
+
162
+ **Parameters:**
163
+ - `card_ids` (array of strings, optional): Specific cards (all if omitted)
164
+ - `reason` (string, optional): Lock reason
165
+
166
+ ### 🪙 Wallet Management Tools
167
+
168
+ #### add_wallet
169
+ Add a cryptocurrency wallet (hot, watch-only, or hardware).
170
+
171
+ **Parameters:**
172
+ - `nickname` (string, required): Friendly wallet name
173
+ - `address` (string, required): Public wallet address
174
+ - `chain` (string, required): Blockchain (`ethereum`, `polygon`, `arbitrum`, `base`, `solana`, `bitcoin`)
175
+ - `type` (string, required): Wallet type (`hot`, `watch_only`, `hardware`)
176
+ - `private_key` (string, optional): Private key (for hot wallets - encrypted)
177
+ - `derivation_path` (string, optional): HD derivation path
178
+ - `hardware_device` (string, optional): Hardware device type
179
+
180
+ #### list_wallets
181
+ List all configured wallets.
182
+
183
+ **Parameters:**
184
+ - `chain` (string, optional): Filter by blockchain
185
+ - `type` (string, optional): Filter by wallet type
186
+
187
+ #### remove_wallet
188
+ Remove a wallet from storage.
189
+
190
+ **Parameters:**
191
+ - `wallet_id` (string, required): Wallet ID to remove
192
+ - `confirm` (boolean, required): Must be true to confirm
193
+
194
+ #### get_wallet_balance
195
+ Get real-time balance for a specific wallet.
196
+
197
+ **Parameters:**
198
+ - `wallet_id` (string, optional): Wallet ID
199
+ - `address` (string, optional): Wallet address (alternative)
200
+ - `include_usd` (boolean, optional): Include USD value
201
+
202
+ #### get_total_balance
203
+ Get total portfolio value across all wallets.
204
+
205
+ **Parameters:**
206
+ - `chain` (string, optional): Filter by specific chain
207
+ - `include_breakdown` (boolean, optional): Include per-wallet breakdown
208
+
209
+ #### list_wallet_transactions
210
+ Get transaction history for a wallet.
211
+
212
+ **Parameters:**
213
+ - `wallet_id` (string, required): Wallet ID
214
+ - `limit` (number, optional): Number of transactions (default: 50)
215
+ - `include_internal` (boolean, optional): Include internal transactions
216
+
217
+ ### 💸 Transaction Tools
218
+
219
+ #### get_transactions
220
+ Get transaction history across cards and wallets.
221
+
222
+ **Parameters:**
223
+ - `account_type` (string, optional): Filter by `cards` or `wallets`
224
+ - `since_date` (string, optional): Start date (ISO format)
225
+ - `limit` (number, optional): Maximum transactions
226
+ - `include_pending` (boolean, optional): Include pending transactions
227
+
228
+ #### prepare_payment
229
+ Prepare a card payment for confirmation (Step 1 of 2).
230
+
231
+ **Parameters:**
232
+ - `card_id` (string, required): Card ID to charge
233
+ - `amount` (number, required): Amount in card currency
234
+ - `currency` (string, optional): Currency code (default: USD)
235
+ - `merchant` (string, required): Merchant/description
236
+ - `category` (string, optional): Expense category
237
+
238
+ #### confirm_payment
239
+ Confirm and execute a prepared payment (Step 2 of 2).
240
+
241
+ **Parameters:**
242
+ - `transaction_id` (string, required): Prepared transaction ID
243
+ - `cvv` (string, required): Card CVV for final authorization
244
+
245
+ #### prepare_crypto_tx
246
+ Prepare a cryptocurrency transaction.
247
+
248
+ **Parameters:**
249
+ - `wallet_id` (string, required): Source wallet
250
+ - `to_address` (string, required): Recipient address
251
+ - `amount` (string, required): Amount to send
252
+ - `token` (string, optional): Token contract (for ERC-20)
253
+ - `gas_price` (string, optional): Custom gas price
254
+
255
+ #### sign_crypto_tx
256
+ Sign and broadcast a prepared crypto transaction.
257
+
258
+ **Parameters:**
259
+ - `transaction_id` (string, required): Prepared transaction ID
260
+ - `confirm` (boolean, required): Must be true to sign
261
+
262
+ ### 🔐 Security Tools
263
+
264
+ #### setup_pin
265
+ Configure or change master PIN for CVV encryption.
266
+
267
+ **Parameters:**
268
+ - `new_pin` (string, required): New PIN (4-8 digits)
269
+ - `current_pin` (string, optional): Current PIN (for changes)
270
+ - `confirm_pin` (string, required): PIN confirmation
271
+
272
+ ## 🔒 Security Architecture
273
+
274
+ ### Encryption Layers
275
+ 1. **Card Numbers**: AES-256-GCM with AWS KMS or master key
276
+ 2. **CVV Codes**: Encrypted with PIN-derived key (PBKDF2)
277
+ 3. **Private Keys**: AES-256-GCM with additional entropy
278
+ 4. **Metadata**: Encrypted storage of all sensitive fields
279
+
280
+ ### Key Management
281
+ - **AWS KMS**: Enterprise-grade key management
282
+ - **Local Keys**: PBKDF2-derived from master password
283
+ - **PIN System**: Separate PIN for CVV access
284
+ - **Key Rotation**: Automatic key rotation support
285
+
286
+ ### Access Controls
287
+ - **PIN Required**: CVV access requires PIN unlock
288
+ - **Session Timeout**: Automatic lock after inactivity
289
+ - **Audit Logging**: All actions logged with timestamps
290
+ - **No Plain Text**: No sensitive data stored in plain text
291
+
292
+ ## 🌐 Supported Blockchains
293
+
294
+ | Blockchain | Symbol | RPC Support | Explorer API | Features |
295
+ |------------|--------|-------------|--------------|----------|
296
+ | **Ethereum** | ETH | ✅ | Etherscan | ERC-20, NFTs, DeFi |
297
+ | **Polygon** | MATIC | ✅ | Polygonscan | Low fees, fast |
298
+ | **Arbitrum** | ARB | ✅ | Arbiscan | Layer 2, cheap |
299
+ | **Base** | BASE | ✅ | Basescan | Coinbase L2 |
300
+ | **BSC** | BNB | ✅ | BSCScan | Binance Chain |
301
+ | **Solana** | SOL | ✅ | RPC Direct | High speed |
302
+ | **Bitcoin** | BTC | ⏳ | Coming Soon | Store of value |
303
+
304
+ ## 🚨 Security Best Practices
305
+
306
+ ### Environment Security
307
+ - Never commit API keys or encryption keys to version control
308
+ - Use AWS KMS for production deployments
309
+ - Rotate API keys regularly
310
+ - Monitor access logs
311
+
312
+ ### Wallet Security
313
+ - Use hardware wallets for large amounts
314
+ - Keep hot wallets for spending amounts only
315
+ - Regular backup of encrypted data
316
+ - Test recovery procedures
317
+
318
+ ### Card Security
319
+ - Use unique PINs not used elsewhere
320
+ - Enable card locks when not needed
321
+ - Monitor transaction logs regularly
322
+ - Keep CVV access locked when possible
323
+
324
+ ## 📊 Data Storage
325
+
326
+ All data is stored locally in encrypted files:
327
+ - `~/.mcp-payment-manager/cards/` - Encrypted card data
328
+ - `~/.mcp-payment-manager/wallets/` - Encrypted wallet data
329
+ - `~/.mcp-payment-manager/transactions/` - Transaction logs
330
+ - `~/.mcp-payment-manager/audit/` - Security audit logs
331
+
332
+ ## 🔄 Backup & Recovery
333
+
334
+ ### Export Encrypted Data
335
+ ```bash
336
+ # Backup entire data directory
337
+ tar -czf payment-manager-backup.tar.gz ~/.mcp-payment-manager/
338
+ ```
339
+
340
+ ### Recovery Process
341
+ 1. Restore data directory
342
+ 2. Ensure same encryption keys are available
343
+ 3. Verify data integrity with `list_cards` and `list_wallets`
344
+
345
+ ## ⚠️ Important Disclaimers
346
+
347
+ - **Not Financial Advice**: This tool is for personal finance management only
348
+ - **Security Responsibility**: You are responsible for securing your encryption keys
349
+ - **Backup Critical**: Always backup your encrypted data and keys
350
+ - **Test First**: Test with small amounts before storing significant value
351
+ - **Key Loss**: Lost encryption keys = lost data permanently
352
+
353
+ ## 📄 License
354
+
355
+ MIT - See LICENSE for details
356
+
357
+ ## 🙏 Credits
358
+
359
+ - **Author:** Kevin Valfin
360
+ - **MCP SDK:** @modelcontextprotocol/sdk
361
+ - **Cryptography:** Node.js crypto + AWS KMS
362
+ - **Blockchain APIs:** Etherscan, Polygonscan, and others
@@ -0,0 +1,31 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Payment Manager MCP Server
4
+ *
5
+ * Comprehensive personal finance management with bank cards and crypto wallets:
6
+ *
7
+ * 🏦 CARDS (Fiat):
8
+ * - Encrypted card storage (AES-256-GCM + AWS KMS)
9
+ * - PIN-protected CVV access
10
+ * - Two-step payment flow (prepare → confirm)
11
+ * - Card status management (lock/unlock)
12
+ *
13
+ * 🪙 WALLETS (Crypto):
14
+ * - Multi-chain support (ETH, Polygon, Arbitrum, Base, Solana, Bitcoin)
15
+ * - Hot, watch-only, and hardware wallet types
16
+ * - Encrypted private key storage
17
+ * - Real-time balance and transaction fetching
18
+ *
19
+ * 🔐 SECURITY:
20
+ * - All sensitive data encrypted at rest
21
+ * - PIN-based access control
22
+ * - Complete audit logging
23
+ * - AWS KMS integration for enterprise security
24
+ *
25
+ * Environment Variables:
26
+ * - MCP_MASTER_KEY: Master encryption key (256-bit)
27
+ * - AWS_KMS_KEY_ID: AWS KMS key ARN
28
+ * - ETHERSCAN_API_KEY: For Ethereum data
29
+ * - [CHAIN]SCAN_API_KEY: For other chain data
30
+ */
31
+ export {};
package/dist/index.js ADDED
@@ -0,0 +1,122 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Payment Manager MCP Server
4
+ *
5
+ * Comprehensive personal finance management with bank cards and crypto wallets:
6
+ *
7
+ * 🏦 CARDS (Fiat):
8
+ * - Encrypted card storage (AES-256-GCM + AWS KMS)
9
+ * - PIN-protected CVV access
10
+ * - Two-step payment flow (prepare → confirm)
11
+ * - Card status management (lock/unlock)
12
+ *
13
+ * 🪙 WALLETS (Crypto):
14
+ * - Multi-chain support (ETH, Polygon, Arbitrum, Base, Solana, Bitcoin)
15
+ * - Hot, watch-only, and hardware wallet types
16
+ * - Encrypted private key storage
17
+ * - Real-time balance and transaction fetching
18
+ *
19
+ * 🔐 SECURITY:
20
+ * - All sensitive data encrypted at rest
21
+ * - PIN-based access control
22
+ * - Complete audit logging
23
+ * - AWS KMS integration for enterprise security
24
+ *
25
+ * Environment Variables:
26
+ * - MCP_MASTER_KEY: Master encryption key (256-bit)
27
+ * - AWS_KMS_KEY_ID: AWS KMS key ARN
28
+ * - ETHERSCAN_API_KEY: For Ethereum data
29
+ * - [CHAIN]SCAN_API_KEY: For other chain data
30
+ */
31
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
32
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
33
+ // Card management tools
34
+ import * as addCard from "./tools/add-card.js";
35
+ import * as listCards from "./tools/list-cards.js";
36
+ import * as removeCard from "./tools/remove-card.js";
37
+ import * as cardStatus from "./tools/card-status.js";
38
+ import * as lockCards from "./tools/lock-cards.js";
39
+ import * as unlockCards from "./tools/unlock-cards.js";
40
+ // Wallet management tools
41
+ import * as addWallet from "./tools/add-wallet.js";
42
+ import * as listWallets from "./tools/list-wallets.js";
43
+ import * as removeWallet from "./tools/remove-wallet.js";
44
+ import * as getWalletBalance from "./tools/get-wallet-balance.js";
45
+ import * as getTotalBalance from "./tools/get-total-balance.js";
46
+ import * as listWalletTransactions from "./tools/list-wallet-transactions.js";
47
+ // Transaction tools
48
+ import * as getTransactions from "./tools/get-transactions.js";
49
+ import * as preparePayment from "./tools/prepare-payment.js";
50
+ import * as confirmPayment from "./tools/confirm-payment.js";
51
+ import * as prepareCryptoTx from "./tools/prepare-crypto-tx.js";
52
+ import * as signCryptoTx from "./tools/sign-crypto-tx.js";
53
+ // Security tools
54
+ import * as setupPin from "./tools/setup-pin.js";
55
+ const tools = [
56
+ // Card Management
57
+ addCard,
58
+ listCards,
59
+ removeCard,
60
+ cardStatus,
61
+ lockCards,
62
+ unlockCards,
63
+ // Wallet Management
64
+ addWallet,
65
+ listWallets,
66
+ removeWallet,
67
+ getWalletBalance,
68
+ getTotalBalance,
69
+ listWalletTransactions,
70
+ // Transactions
71
+ getTransactions,
72
+ preparePayment,
73
+ confirmPayment,
74
+ prepareCryptoTx,
75
+ signCryptoTx,
76
+ // Security
77
+ setupPin,
78
+ ];
79
+ async function main() {
80
+ // Verify critical environment variables
81
+ const requiredEnvs = ['MCP_MASTER_KEY'];
82
+ const missing = requiredEnvs.filter(env => !process.env[env]);
83
+ if (missing.length > 0) {
84
+ console.error(`❌ Missing critical environment variables: ${missing.join(', ')}`);
85
+ console.error('⚠️ Payment Manager requires encryption keys for security!');
86
+ process.exit(1);
87
+ }
88
+ const server = new McpServer({
89
+ name: "mcp-payment-manager",
90
+ version: "1.0.0",
91
+ });
92
+ // Register all tools
93
+ for (const tool of tools) {
94
+ server.tool(tool.name, tool.description, tool.parameters.shape, async (args) => {
95
+ try {
96
+ const result = await tool.execute(args);
97
+ return {
98
+ content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
99
+ };
100
+ }
101
+ catch (error) {
102
+ return {
103
+ content: [
104
+ {
105
+ type: "text",
106
+ text: JSON.stringify({
107
+ success: false,
108
+ error: error instanceof Error ? error.message : "Unknown error",
109
+ }),
110
+ },
111
+ ],
112
+ isError: true,
113
+ };
114
+ }
115
+ });
116
+ }
117
+ // Connect to stdio transport
118
+ const transport = new StdioServerTransport();
119
+ await server.connect(transport);
120
+ console.error("🔒 Payment Manager MCP Server started - All data encrypted at rest");
121
+ }
122
+ main().catch(console.error);