# 🏦 MCP Banking Server

A production-ready banking server built with **FastMCP** (Model Context Protocol) featuring modern API design patterns, real-time updates, and enterprise-grade features.

## ✨ Features

| Feature | Description |
|---------|-------------|
| **API Key Authentication** | Secure endpoints with `X-API-Key` header |
|  **Idempotency Support** | Prevent duplicate transactions with `Idempotency-Key` |
|  **WebSocket Updates** | Real-time transaction notifications |
|  **CSV Export** | Stream transaction history as CSV |
|  **OpenAPI Docs** | Auto-generated Swagger UI at `/docs` |
|  **Docker Ready** | One-command containerized deployment |
|  **MCP Integration** | LLM-compatible tools for AI assistants |

##  Quick Start

### Prerequisites

- Python 3.10+
- pip or uv package manager

### Installation

```bash
# Clone or navigate to the project directory
cd mcp

# Install dependencies
pip install -r requirements.txt
```

### Run the Server

```bash
# Start the server
python server.py

# Or use uvicorn directly
uvicorn server:app --reload --port 8000
```

The server will start and display:
- 🔑 Your default API key (save this!)
- 📚 API documentation URL

### Access the API

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
- **Health Check**: http://localhost:8000/health

## 🔑 Authentication

All endpoints (except health check and root) require an API key.

Include the `X-API-Key` header in your requests:

```bash
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:8000/accounts/1234567890
```

The default API key is displayed when the server starts.

### Disabling Authentication (for Demo/Testing)

To run the server without authentication (useful for demos or when being scanned by other services):

```bash
# Windows PowerShell
$env:DISABLE_AUTH="true"; python server.py

# Windows CMD
set DISABLE_AUTH=true && python server.py

# Linux/Mac
DISABLE_AUTH=true python server.py
```

When disabled, all endpoints become publicly accessible without needing the `X-API-Key` header.

## 📖 API Reference

### Accounts

#### Create Account
```bash
curl -X POST http://localhost:8000/accounts \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"holder_name": "John Doe"}'
```

#### Get Account Details
```bash
curl http://localhost:8000/accounts/1234567890 \
  -H "X-API-Key: YOUR_API_KEY"
```

### Transactions

#### Deposit (with idempotency)
```bash
curl -X POST http://localhost:8000/accounts/1234567890/deposit \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{"amount": 100.00}'
```

#### Withdraw
```bash
curl -X POST http://localhost:8000/accounts/1234567890/withdraw \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50.00}'
```

#### Get Transaction History
```bash
curl "http://localhost:8000/accounts/1234567890/transactions?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"
```

#### Export Transactions as CSV
```bash
curl http://localhost:8000/accounts/1234567890/transactions/export \
  -H "X-API-Key: YOUR_API_KEY" \
  -o transactions.csv
```

## 📡 WebSocket Live Updates

Connect to receive real-time transaction notifications:

```javascript
// Browser JavaScript example
const ws = new WebSocket('ws://localhost:8000/ws/transactions/1234567890');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Transaction update:', data);
};

ws.onopen = () => {
  console.log('Connected to transaction updates');
};
```

### WebSocket Message Types

```json
// Connection established
{"type": "connected", "message": "Connected to transaction updates", "account_number": "1234567890"}

// Transaction notification
{"type": "transaction", "data": {"id": 1, "type": "DEPOSIT", "amount": 100.0, ...}}

// Ping response
{"type": "pong"}
```

##  MCP Tools

For LLM integration, the following MCP tools are available:

| Tool | Description |
|------|-------------|
| `create_account` | Create a new bank account |
| `deposit` | Add funds to an account |
| `withdraw` | Remove funds from an account |
| `get_balance` | Check account balance |
| `get_transaction_history` | View recent transactions |

### Using with FastMCP CLI

```bash
# Run in MCP mode
fastmcp run server.py:mcp --transport http --port 8000

# Development mode with inspector
fastmcp dev server.py:mcp
```

##  Docker Deployment

### Build and Run

```bash
# Build the image
docker build -t mcp-banking-server .

# Run the container
docker run -d -p 8000:8000 --name banking-server mcp-banking-server
```

### Docker Compose (optional)

```yaml
version: '3.8'
services:
  banking-server:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - ./data:/app/data
    restart: unless-stopped
```

## 📁 Project Structure

```
mcp/
├── server.py              # Main FastMCP server with MCP tools & REST API
├── database.py            # SQLite database operations
├── auth.py                # API key authentication
├── websocket_manager.py   # WebSocket connection management
├── requirements.txt       # Python dependencies
├── Dockerfile             # Container configuration
├── README.md              # This file
└── bank.db                # SQLite database (created at runtime)
```

## Idempotency

The `deposit` and `withdraw` endpoints support idempotency to prevent duplicate transactions:

1. Include an `Idempotency-Key` header with a unique identifier
2. If the same key is used again within 24 hours, the original response is returned
3. The `idempotent_replay: true` flag indicates a cached response

```bash
# First request - processes the transaction
curl -X POST ... -H "Idempotency-Key: txn-abc-123" -d '{"amount": 100}'

# Second request with same key - returns cached response
curl -X POST ... -H "Idempotency-Key: txn-abc-123" -d '{"amount": 100}'
# Response includes: "idempotent_replay": true
```