Data Models

Relevant source files

The following files were used as context for generating this wiki page:

• mbbank_mcp/modals.py
• mbbank_mcp/core.py
• mbbank_mcp/main.py
• README.md
• pyproject.toml

The data models in the mbbank-mcp project serve as a structured proxy layer between the raw responses from the MBBank API and the Model Context Protocol (MCP) server. These models, built using the Pydantic library, rename and organize fields from the underlying mbbank-lib into more readable, developer-friendly formats suitable for consumption by LLMs and MCP clients.

The primary purpose of these models is to represent banking entities such as accounts, transactions, credit cards, and savings accounts. By enforcing strict typing and providing clear field names, the models ensure consistency across the different tools provided by the MCP server, such as get_balances, get_transactions, and get_savings.

Sources: mbbank_mcp/modals.py:1-5, mbbank_mcp/core.py:17-21, README.md:1-5

Core Model Architecture

The project utilizes a hierarchical model structure where complex responses are composed of smaller, reusable sub-models. For example, a BalancesModel contains lists of AccountModel objects, and a TransactionsModel contains detailed TransactionModel entries.

Sources: mbbank_mcp/modals.py:7-35

Account and Balance Models

These models represent the financial standing of the user. The BalancesModel acts as a container for both standard and international bank accounts.

Field	Type	Description
accountNumber	str	The unique identifier for the bank account.
accountName	str	The alias or display name of the account.
currency	str	The currency code (e.g., VND, USD).
balance	str	The current available balance in the account.

Sources: mbbank_mcp/modals.py:7-16, mbbank_mcp/core.py:112-125

Transaction History Models

Transactions are modeled to include both historical records and specific transfer details. The TransactionModel captures the movement of funds, while TransactionTransferModel provides metadata about the recipient when applicable.

Transaction Logic

In the core.py implementation, transaction amounts are dynamically prefixed with + for credit amounts and - for debit amounts based on the raw API data.

# From mbbank_mcp/core.py
amount=(
    '+' + transaction.creditAmount if int(transaction.creditAmount)
    else '-' + transaction.debitAmount
)

Sources: mbbank_mcp/core.py:151-154, mbbank_mcp/modals.py:27-35

Card and Savings Models

The system provides detailed models for credit/debit cards and various types of savings instruments (Online Savings Accounts and Branch Savings).

Card Data Structure

The CardsModel categorizes cards into three states: closed, active (listed), and other.

Sources: mbbank_mcp/core.py:175-188, mbbank_mcp/modals.py:37-49

Savings and Detailed Info

Savings data is split between a summary model (SavingModel) used for listing and a detailed model (SavingDetailModel) for in-depth analysis of specific accounts.

Model	Key Fields	Purpose
SavingModel	principalAmount, ratePercentPerYear, maturityDate	General overview of a savings account.
SavingDetailModel	accruedInterestAmount, totalMaturityAmount, interestPaymentType	Detailed financial breakdown of a single saving account.

Sources: mbbank_mcp/modals.py:51-85, mbbank_mcp/core.py:214-228

Internal State Management

Beyond response models, the system manages internal state for sensitive operations like money transfers using TypedDict.

class TransferState(TypedDict):
    create_time: float
    state: TransferContextAsync

The TransferState is used by the transfer_manager to track active sessions, ensuring that transfers are confirmed within a 120-second window before expiration.

Sources: mbbank_mcp/core.py:23-25, mbbank_mcp/core.py:73-82

Execution and Configuration

The application is configured and executed via a command-line interface, which maps environment variables or flags to the internal client initialization.

Sources: mbbank_mcp/main.py:26-44, pyproject.toml:24-25

The data models defined in modals.py ensure that all information extracted from the MBBank API is normalized and safely exposed through the MCP interface, providing a reliable schema for monitoring and analytics tools.

Sources: mbbank_mcp/modals.py:1-85, mbbank_mcp/core.py:31-251