# Banking MCP Service

MCP server độc lập cung cấp các công cụ tra cứu ngày giờ Việt Nam, ưu đãi theo ngày và ưu đãi thẻ tín dụng VNBank. Service được xây dựng bằng FastAPI; các REST endpoint được `fastapi-mcp` tự động chuyển thành MCP tools và phục vụ qua Streamable HTTP.

> Dữ liệu ưu đãi trong project là dữ liệu mock phục vụ demo/phát triển, không phải thông tin ưu đãi chính thức từ VNBank.

## Tính năng

- Trả về ngày giờ hiện tại theo múi giờ `Asia/Ho_Chi_Minh` (UTC+7).
- Xác định ưu đãi theo quy tắc ngày đặc biệt.
- Tra cứu ưu đãi theo bốn loại thẻ tín dụng mẫu.
- Cung cấp đồng thời REST API, Swagger UI, ReDoc và MCP endpoint.
- Ghi log request, response status và thời gian xử lý.
- Có health check để kiểm tra trạng thái service.

## Kiến trúc

```text
mcp_server/
├── app/
│   ├── main.py                    # Khởi tạo FastAPI, đăng ký router và mount MCP
│   ├── controllers/               # Khai báo REST endpoint
│   │   ├── datetime_controller.py
│   │   ├── promotions_controller.py
│   │   └── card_offers_controller.py
│   ├── services/                  # Business logic và dữ liệu mock
│   │   ├── datetime_service.py
│   │   ├── promotions_service.py
│   │   └── card_offers_service.py
│   ├── models/                    # Pydantic response/request schema
│   │   ├── request_schema.py
│   │   └── response_schema.py
│   └── core/                      # Cấu hình, logger và middleware
│       ├── config.py
│       ├── logger.py
│       └── middleware.py
├── .env.example
├── requirements.txt
└── README.md
```

Luồng xử lý chính:

```text
MCP client hoặc HTTP client
          │
          ▼
FastAPI / FastApiMCP
          │
          ▼
      Controller
          │
          ▼
       Service
          │
          ▼
   Pydantic response
```

## Yêu cầu

- Python 3.10 trở lên.
- Port mặc định `8001` chưa được ứng dụng khác sử dụng.

## Cài đặt

Chạy các lệnh sau từ thư mục `mcp_server`:

### Windows PowerShell

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
Copy-Item .env.example .env
```

### Linux/macOS

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
cp .env.example .env
```

## Cấu hình

Các biến môi trường được đọc từ file `.env`:

| Biến | Mặc định | Ý nghĩa |
|---|---:|---|
| `MCP_HOST` | `0.0.0.0` | Địa chỉ server lắng nghe |
| `MCP_PORT` | `8001` | Port của service |
| `MCP_LOG_LEVEL` | `INFO` | Mức log dùng khi chạy `app/main.py` |
| `MCP_CONTEXT_PATH` | `/api/v1` | Prefix của REST API, Swagger, ReDoc và OpenAPI schema |

Ví dụ:

```dotenv
MCP_HOST=0.0.0.0
MCP_PORT=8001
MCP_LOG_LEVEL=INFO
MCP_CONTEXT_PATH=/api/v1
```

Không thêm dấu `/` ở cuối `MCP_CONTEXT_PATH`. MCP endpoint luôn được mount tại `/mcp` và health check luôn ở `/health`, không phụ thuộc biến này.

## Khởi chạy

Từ thư mục `mcp_server`, chạy:

```powershell
python app/main.py
```

Server chạy với auto-reload ở chế độ hiện tại. Sau khi khởi động, các địa chỉ mặc định là:

| Thành phần | URL |
|---|---|
| Health check | `http://localhost:8001/health` |
| Swagger UI | `http://localhost:8001/api/v1/docs` |
| ReDoc | `http://localhost:8001/api/v1/redoc` |
| OpenAPI schema | `http://localhost:8001/api/v1/openapi.json` |
| MCP Streamable HTTP | `http://localhost:8001/mcp` |

Kiểm tra nhanh:

```bash
curl http://localhost:8001/health
```

Response:

```json
{
  "status": "healthy",
  "service": "banking-mcp"
}
```

## REST API

| Method | Endpoint | Tham số | Mô tả |
|---|---|---|---|
| `GET` | `/health` | Không có | Kiểm tra trạng thái service |
| `GET` | `/api/v1/get-datetime` | Không có | Lấy ngày giờ hiện tại tại Việt Nam |
| `GET` | `/api/v1/get-promotions` | Query `date` không bắt buộc, định dạng `YYYY-MM-DD` | Lấy ưu đãi của ngày chỉ định; mặc định là hôm nay |
| `GET` | `/api/v1/get-card-offers/{card_type}` | Path `card_type` bắt buộc | Lấy ưu đãi của loại thẻ chỉ định |

### Lấy ngày giờ Việt Nam

```bash
curl http://localhost:8001/api/v1/get-datetime
```

Response mẫu:

```json
{
  "datetime": "2026-08-19T11:30:00.123456+07:00",
  "date": "2026-08-19",
  "time": "11:30:00",
  "timezone": "Asia/Ho_Chi_Minh",
  "weekday_vi": "Thứ Tư"
}
```

### Lấy ưu đãi theo ngày

```bash
curl "http://localhost:8001/api/v1/get-promotions?date=2026-05-05"
```

Quy tắc phân loại:

| Điều kiện | Loại ưu đãi |
|---|---|
| Ngày bằng tháng, ví dụ `01-01`, `05-05`, `12-12` | `shopping_voucher` |
| Ngày có chữ số cuối là 5: ngày 5, 15 hoặc 25 | `savings` |
| Ngày 1, 2 hoặc 3 hằng tháng | `loan` |

Một ngày có thể thỏa nhiều điều kiện và nhận nhiều ưu đãi. Ngày thường trả về mảng `promotions` rỗng. Giá trị `date` sai định dạng hoặc không tồn tại trả về HTTP `400`.

Response mẫu cho ngày `2026-05-05`:

```json
{
  "date": "2026-05-05",
  "promotions": [
    {
      "type": "shopping_voucher",
      "description": "Ưu đãi ngày đôi: Voucher mua sắm giảm giá đặc biệt",
      "details": "Giảm đến 20% tại các đối tác thương mại..."
    },
    {
      "type": "savings",
      "description": "Ưu đãi ngày 5: Lãi suất tiết kiệm tăng thêm",
      "details": "Tăng thêm 0.5%/năm cho kỳ hạn 1–6 tháng..."
    }
  ],
  "total_promotions": 2
}
```

### Lấy ưu đãi theo loại thẻ

```bash
curl http://localhost:8001/api/v1/get-card-offers/platinum
```

Các giá trị `card_type` hợp lệ:

| Giá trị | Tên thẻ |
|---|---|
| `standard` | VNBank Standard Credit Card |
| `gold` | VNBank Gold Credit Card |
| `platinum` | VNBank Platinum Credit Card |
| `VNBank_stepup` | VNBank StepUp Mastercard |

Giá trị khác danh sách trên trả về HTTP `400`.

## Kết nối MCP client

Service sử dụng MCP Streamable HTTP. Cấu hình URL `http://localhost:8001/mcp` trong client có hỗ trợ transport này. Ví dụ cấu hình tổng quát:

```json
{
  "mcpServers": {
    "banking-mcp": {
      "url": "http://localhost:8001/mcp"
    }
  }
}
```

Tên cấu hình và cấu trúc file có thể khác tùy MCP client.

Với `fastapi-mcp==0.4.0`, service hiện expose bốn tools sau:

| MCP tool | Input |
|---|---|
| `get_datetime_api_v1_get_datetime_get` | Không có |
| `get_promotions_api_v1_get_promotions_get` | `date?: string` (`YYYY-MM-DD`) |
| `get_card_offers_api_v1_get_card_offers__card_type__get` | `card_type: string` |
| `health_health_get` | Không có |

Tên tool được sinh tự động từ OpenAPI operation. Do `requirements.txt` dùng version range (`fastapi-mcp>=0.3.0`), tên hoặc schema tool có thể thay đổi khi nâng version thư viện; MCP client nên lấy danh sách tools trực tiếp từ server thay vì hard-code nếu có thể.

## Lưu ý vận hành

- Service hiện chưa cấu hình authentication/authorization. Chỉ expose ra mạng tin cậy hoặc bổ sung cơ chế bảo vệ trước khi triển khai production.
- Ưu đãi thẻ và nội dung khuyến mãi đang được khai báo tĩnh trong source code.
- `valid_until` của dữ liệu thẻ hiện là `2026-12-31`.
- Chế độ `reload=True` phù hợp cho phát triển; khi triển khai production nên chạy bằng process manager phù hợp và tắt auto-reload.