163 lines
4.2 KiB
Markdown
163 lines
4.2 KiB
Markdown
# MCP Wallet Server
|
|
|
|
Virtual Wallet MCP Server for the Trading Platform. Manages credits (USD equivalent) for purchases, subscriptions, and agent funding.
|
|
|
|
## Overview
|
|
|
|
This service provides:
|
|
- **Virtual Wallet System**: Credits-based wallet (1 credit = 1 USD equivalent, not real money)
|
|
- **Transaction Management**: Full audit trail of all wallet operations
|
|
- **MCP Protocol Support**: Tools can be called by AI agents via MCP
|
|
- **REST API**: Traditional API endpoints for frontend integration
|
|
- **Multi-tenancy**: Full RLS support for tenant isolation
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Copy environment config
|
|
cp .env.example .env
|
|
|
|
# Start development server
|
|
npm run dev
|
|
|
|
# Build for production
|
|
npm run build
|
|
|
|
# Start production server
|
|
npm start
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### Health & Info
|
|
- `GET /health` - Health check with database status
|
|
- `GET /info` - Server info and available tools
|
|
|
|
### MCP Protocol
|
|
- `GET /mcp/tools` - List available MCP tools
|
|
- `POST /mcp/tools/:toolName` - Execute a specific tool
|
|
- `POST /mcp/call` - MCP-style call `{name, arguments}`
|
|
|
|
### REST API
|
|
|
|
#### Wallets
|
|
- `POST /api/v1/wallets` - Create wallet
|
|
- `GET /api/v1/wallets/:walletId` - Get wallet
|
|
- `GET /api/v1/wallets/:walletId/balance` - Get balance with limits
|
|
- `GET /api/v1/wallets/:walletId/summary` - Dashboard summary
|
|
- `POST /api/v1/wallets/:walletId/credits` - Add credits (Stripe)
|
|
- `POST /api/v1/wallets/:walletId/debit` - Debit credits
|
|
- `POST /api/v1/wallets/transfer` - Transfer between wallets
|
|
|
|
#### Transactions
|
|
- `GET /api/v1/wallets/:walletId/transactions` - Transaction history
|
|
- `GET /api/v1/transactions/:transactionId` - Get transaction
|
|
- `POST /api/v1/wallets/:walletId/refund` - Process refund
|
|
|
|
## MCP Tools
|
|
|
|
| Tool | Description | Risk Level |
|
|
|------|-------------|------------|
|
|
| `wallet_create` | Create new wallet | MEDIUM |
|
|
| `wallet_get` | Get wallet by ID/user | LOW |
|
|
| `wallet_get_balance` | Get balance with limits | LOW |
|
|
| `wallet_add_credits` | Add credits via Stripe | HIGH |
|
|
| `wallet_debit` | Debit credits | HIGH |
|
|
| `wallet_transfer` | Transfer between wallets | HIGH |
|
|
| `wallet_add_promo` | Add promotional credits | MEDIUM |
|
|
| `wallet_update_limits` | Update spending limits | MEDIUM |
|
|
| `wallet_freeze` | Freeze wallet | HIGH |
|
|
| `wallet_unfreeze` | Unfreeze wallet | HIGH |
|
|
| `transaction_get` | Get transaction details | LOW |
|
|
| `transaction_history` | Get transaction history | LOW |
|
|
| `wallet_summary` | Dashboard summary | LOW |
|
|
| `transaction_refund` | Process refund | HIGH |
|
|
|
|
## Transaction Types
|
|
|
|
- `CREDIT_PURCHASE` - Buy credits via Stripe
|
|
- `AGENT_FUNDING` - Fund Money Manager agent
|
|
- `AGENT_WITHDRAWAL` - Withdraw from agent
|
|
- `AGENT_PROFIT` - Profit from agent trading
|
|
- `AGENT_LOSS` - Loss from agent trading
|
|
- `PRODUCT_PURCHASE` - Buy product/service
|
|
- `SUBSCRIPTION_CHARGE` - Subscription payment
|
|
- `PREDICTION_PURCHASE` - Buy ML predictions
|
|
- `REFUND` - Refund to wallet
|
|
- `PROMO_CREDIT` - Promotional credits
|
|
- `PROMO_EXPIRY` - Expired promo credits
|
|
- `ADJUSTMENT` - Manual adjustment
|
|
- `TRANSFER_IN/OUT` - Wallet transfers
|
|
- `FEE` - Platform fees
|
|
|
|
## Environment Variables
|
|
|
|
```bash
|
|
# Server
|
|
PORT=3090
|
|
NODE_ENV=development
|
|
LOG_LEVEL=info
|
|
|
|
# Database
|
|
DB_HOST=localhost
|
|
DB_PORT=5432
|
|
DB_NAME=trading_platform
|
|
DB_USER=trading_app
|
|
DB_PASSWORD=secret
|
|
|
|
# Wallet Config
|
|
WALLET_DEFAULT_DAILY_LIMIT=1000
|
|
WALLET_DEFAULT_MONTHLY_LIMIT=10000
|
|
WALLET_DEFAULT_SINGLE_TX_LIMIT=500
|
|
WALLET_CURRENCY=USD
|
|
|
|
# Stripe
|
|
STRIPE_SECRET_KEY=sk_test_...
|
|
```
|
|
|
|
## Docker
|
|
|
|
```bash
|
|
# Build
|
|
docker build -t mcp-wallet:1.0.0 .
|
|
|
|
# Run
|
|
docker run -p 3090:3090 --env-file .env mcp-wallet:1.0.0
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
src/
|
|
├── index.ts # Express server entry point
|
|
├── config.ts # Configuration & DB pool
|
|
├── types/
|
|
│ └── wallet.types.ts # TypeScript interfaces
|
|
├── services/
|
|
│ └── wallet.service.ts # Business logic
|
|
├── tools/
|
|
│ ├── index.ts # Tool registry
|
|
│ ├── wallet.ts # Wallet operations
|
|
│ └── transactions.ts # Transaction operations
|
|
└── utils/
|
|
├── logger.ts # Winston logging
|
|
└── errors.ts # Custom error classes
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run tests
|
|
npm test
|
|
|
|
# Watch mode
|
|
npm run test:watch
|
|
```
|
|
|
|
## License
|
|
|
|
UNLICENSED - Private repository
|