# 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