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.
- package/.env.example +23 -0
- package/.github/workflows/ci.yml +26 -0
- package/.github/workflows/release.yml +82 -0
- package/LICENSE +21 -0
- package/README.md +362 -0
- package/dist/index.d.ts +31 -0
- package/dist/index.js +122 -0
- package/dist/lib/blockchain.d.ts +50 -0
- package/dist/lib/blockchain.js +287 -0
- package/dist/lib/cards.d.ts +83 -0
- package/dist/lib/cards.js +276 -0
- package/dist/lib/cli-runner.d.ts +31 -0
- package/dist/lib/cli-runner.js +77 -0
- package/dist/lib/crypto.d.ts +39 -0
- package/dist/lib/crypto.js +228 -0
- package/dist/lib/cvv-crypto.d.ts +23 -0
- package/dist/lib/cvv-crypto.js +67 -0
- package/dist/lib/mcp-core.d.ts +46 -0
- package/dist/lib/mcp-core.js +86 -0
- package/dist/lib/pin-manager.d.ts +69 -0
- package/dist/lib/pin-manager.js +199 -0
- package/dist/lib/wallets.d.ts +91 -0
- package/dist/lib/wallets.js +227 -0
- package/dist/tools/add-card.d.ts +65 -0
- package/dist/tools/add-card.js +97 -0
- package/dist/tools/add-wallet.d.ts +65 -0
- package/dist/tools/add-wallet.js +104 -0
- package/dist/tools/card-status.d.ts +20 -0
- package/dist/tools/card-status.js +26 -0
- package/dist/tools/confirm-payment.d.ts +44 -0
- package/dist/tools/confirm-payment.js +88 -0
- package/dist/tools/get-total-balance.d.ts +41 -0
- package/dist/tools/get-total-balance.js +98 -0
- package/dist/tools/get-transactions.d.ts +39 -0
- package/dist/tools/get-transactions.js +40 -0
- package/dist/tools/get-wallet-balance.d.ts +43 -0
- package/dist/tools/get-wallet-balance.js +69 -0
- package/dist/tools/list-cards.d.ts +36 -0
- package/dist/tools/list-cards.js +39 -0
- package/dist/tools/list-wallet-transactions.d.ts +63 -0
- package/dist/tools/list-wallet-transactions.js +76 -0
- package/dist/tools/list-wallets.d.ts +41 -0
- package/dist/tools/list-wallets.js +50 -0
- package/dist/tools/lock-cards.d.ts +16 -0
- package/dist/tools/lock-cards.js +23 -0
- package/dist/tools/prepare-crypto-tx.d.ts +69 -0
- package/dist/tools/prepare-crypto-tx.js +93 -0
- package/dist/tools/prepare-payment.d.ts +57 -0
- package/dist/tools/prepare-payment.js +93 -0
- package/dist/tools/remove-card.d.ts +25 -0
- package/dist/tools/remove-card.js +39 -0
- package/dist/tools/remove-wallet.d.ts +27 -0
- package/dist/tools/remove-wallet.js +40 -0
- package/dist/tools/setup-pin.d.ts +26 -0
- package/dist/tools/setup-pin.js +33 -0
- package/dist/tools/sign-crypto-tx.d.ts +42 -0
- package/dist/tools/sign-crypto-tx.js +75 -0
- package/dist/tools/unlock-cards.d.ts +35 -0
- package/dist/tools/unlock-cards.js +41 -0
- package/package.json +50 -0
- package/src/index.ts +139 -0
- package/src/lib/blockchain.ts +375 -0
- package/src/lib/cards.ts +372 -0
- package/src/lib/cli-runner.ts +113 -0
- package/src/lib/crypto.ts +284 -0
- package/src/lib/cvv-crypto.ts +81 -0
- package/src/lib/mcp-core.ts +127 -0
- package/src/lib/pin-manager.ts +252 -0
- package/src/lib/wallets.ts +331 -0
- package/src/tools/add-card.ts +108 -0
- package/src/tools/add-wallet.ts +114 -0
- package/src/tools/card-status.ts +32 -0
- package/src/tools/confirm-payment.ts +103 -0
- package/src/tools/get-total-balance.ts +123 -0
- package/src/tools/get-transactions.ts +49 -0
- package/src/tools/get-wallet-balance.ts +75 -0
- package/src/tools/list-cards.ts +52 -0
- package/src/tools/list-wallet-transactions.ts +83 -0
- package/src/tools/list-wallets.ts +63 -0
- package/src/tools/lock-cards.ts +31 -0
- package/src/tools/prepare-crypto-tx.ts +108 -0
- package/src/tools/prepare-payment.ts +108 -0
- package/src/tools/remove-card.ts +46 -0
- package/src/tools/remove-wallet.ts +47 -0
- package/src/tools/setup-pin.ts +39 -0
- package/src/tools/sign-crypto-tx.ts +90 -0
- package/src/tools/unlock-cards.ts +48 -0
- 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
|
+
[](https://www.npmjs.com/package/@artik0din/mcp-payment-manager)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
[](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
|
package/dist/index.d.ts
ADDED
|
@@ -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);
|