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

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:

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

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

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:

Ví dụ:

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:

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à:

Kiểm tra nhanh:

curl http://localhost:8001/health

Response:

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

REST API

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

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

Response mẫu:

{
  "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

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

Quy tắc phân loại:

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:

{
  "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ẻ

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

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

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:

{
  "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:

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.