Customizing 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

Customizing data models in the mbbank-mcp project involves utilizing Pydantic models as a proxy layer between the raw MBBank API responses and the Model Context Protocol (MCP) server outputs. The primary purpose of this customization is to rename complex or technical field names from the underlying API into user-friendly, readable attributes suitable for LLM consumption and human monitoring.

This system ensures that sensitive banking data—such as account balances, transaction histories, and card details—is structured consistently before being transmitted through the MCP tools. By defining these models, the project provides a clean schema for monitoring and analytics while abstracting the complexities of the mbbank-lib response objects.
Sources: mbbank_mcp/modals.py:4, README.md:1-5

Data Model Architecture

The project employs a structured hierarchy of models to represent different banking entities. These models are built using the BaseModel class from pydantic, ensuring type validation and easy serialization to JSON.

Model Hierarchy and Relationships

The architecture separates individual entities (e.g., a single transaction) from collection wrappers (e.g., a list of transactions).

The diagram above illustrates how collection models like BalancesModel and TransactionsModel aggregate individual entity models.
Sources: mbbank_mcp/modals.py:6-33

Core Data Entities

The following table summarizes the key data models defined for the MCP server:

Model Name	Description	Key Fields
AccountModel	Represents a single bank account.	accountNumber, balance, currency
TransactionModel	Represents a financial movement.	transactionDate, amount, description
CardModel	Represents credit/debit card information.	cardId, cardNumber, cardStatus
SavingModel	Represents an active savings account.	principalAmount, ratePercentPerYear, maturityDate
SavingDetailModel	Detailed view of a specific savings plan.	accruedInterestAmount, interestPaymentType

Sources: mbbank_mcp/modals.py:6-105

Data Flow and Transformation

Data models act as the final stage of processing in the core.py module. When a tool is invoked, the server retrieves raw data using mbbank-lib, iterates through the raw objects, and instantiates the customized Pydantic models.

Transformation Logic Example: Balances

The transformation logic re-maps internal API field names (like acctNo and acctAlias) to the standardized model fields (accountNumber and accountName).

# From mbbank_mcp/core.py:126-135
return BalancesModel(
    account=[AccountModel(
        accountNumber=account.acctNo,
        accountName=account.acctAlias,
        currency=account.ccyCd,
        balance=account.currentBalance,
    ) for account in raw_balances.acct_list],
    internationalAccount=[AccountModel(
        accountNumber=account.acctNo,
        # ... mapping continues
    ) for account in raw_balances.internationalAcctList],
)

Sources: mbbank_mcp/core.py:126-138

Transaction Processing Flow

The following sequence diagram demonstrates how data is transformed from the raw MBBank client response into the customized TransactionsModel.

Detailed Model Specifications

Savings and Deposits

The system distinguishes between general savings lists and deep-dive details. SavingModel is used for listing online (OSA) and branch (SBA) savings, while SavingDetailModel provides specific interest and maturity instructions.

# From mbbank_mcp/modals.py:70-80
class SavingModel(BaseModel):
    accountNumber: str
    accountName: str
    currency: str
    principalAmount: Union[int, float]
    openDate: str
    maturityDate: str
    isDeposit: bool
    isWithDraw: bool
    ratePercentPerYear: Union[int, float]
    beneficiaryAccount: str

Sources: mbbank_mcp/modals.py:70-80, mbbank_mcp/core.py:230-245

Card Management

Card data is categorized into three lists: closed cards, active cards, and other cards. The model filters out "New Card" statuses in the core logic before populating the CardsModel.

Field	Type	Description
cardId	str	Internal ID (mapped from cardNo)
cardClassDetail	str	Level of the card (mapped from cardLvl)
cardStatus	Optional[str]	Current status (e.g., "Active", "Closed")

Sources: mbbank_mcp/modals.py:53-68, mbbank_mcp/core.py:195-212

Implementation in MCP Tools

Models are integrated into the FastMCP server via type hints on tool functions. This allows the MCP server to automatically generate the appropriate JSON schemas for the connected client (e.g., Claude Desktop).

# From mbbank_mcp/core.py:120-121
@fast_mcp.tool()
async def get_balances() -> BalancesModel:

Sources: mbbank_mcp/core.py:120-121, mbbank_mcp/main.py:36-39

The use of Pydantic models ensures that the MBBank MCP server maintains a strict, predictable interface for all financial data, facilitating safe monitoring and analytics as defined in the project's scope.
Sources: README.md:68-75