Balance Monitoring Feature

Relevant source files

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

• mbbank_mcp/core.py
• mbbank_mcp/modals.py
• mbbank_mcp/__main__.py
• README.md
• pyproject.toml
• mbbank_mcp/__init__.py

The Balance Monitoring Feature is a core component of the mbbank-mcp server, designed to provide real-time visibility into Military Commercial Joint Stock Bank (MBBank) accounts. This system leverages the Model Context Protocol (MCP) to expose secure tools for retrieving financial data, including account balances, transaction histories, and savings details.

The feature acts as a read-only interface (with the exception of transfer initiation) for monitoring and analytics purposes. It allows users and AI agents to query current balances across multiple account types (standard and international), track spending through transaction logs, and view detailed information regarding online and branch-based savings accounts.

Sources: README.md:1-5, mbbank_mcp/core.py:118-135

System Architecture

The balance monitoring system follows a layered architecture where the MCP server acts as a bridge between the user (or MCP client) and the underlying mbbank-lib library, which interacts with the bank's internal APIs.

The architecture ensures that data retrieved from the bank is transformed into standardized Pydantic models before being returned to the client.

Sources: mbbank_mcp/core.py:22-30, mbbank_mcp/modals.py:1-5, pyproject.toml:14-22

Account and Balance Retrieval

The system provides a centralized method to fetch balances from all linked MBBank accounts. It distinguishes between standard domestic accounts and international accounts.

Data Flow: Get Balances

When the get_balances tool is invoked, the server performs the following steps:

1. Calls the getBalance() method of the MBBankAsync client.
2. Receives a raw response containing account lists.
3. Maps the raw data into BalancesModel and AccountModel structures.

Balance Data Structure

The following table describes the fields returned for each account:

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/core.py:118-135, mbbank_mcp/modals.py:7-17

Transaction History Monitoring

The system allows for historical analysis of financial activity through two distinct tools: one for standard bank accounts and another for card-specific transactions.

Transaction Filtering

Users can filter transactions by specifying a date range in the dd-mm-yyyy format. The system provides a helper tool, get_today_date, to facilitate generating the current date for query parameters.

Tool Name	Key Parameters	Return Type
get_transactions	account_number, from_date, to_date	TransactionsModel
get_card_transactions	card_id, from_date, to_date	TransactionsModel

Transaction Attributes

Transaction records include detailed metadata to assist in reconciliation:

• Amount Identification: The system prepends + for credit transactions and - for debit transactions by checking the creditAmount field.
• Beneficiary Info: For transfers, the transferredTo object includes the destination account number, name, and bank.

Sources: mbbank_mcp/core.py:145-224, mbbank_mcp/modals.py:25-42

Savings and Investment Monitoring

The monitoring feature extends to savings products, allowing users to track interest rates and maturity dates for both Online Savings Accounts (OSA) and Branch Saving Accounts (SBA).

Savings Details

The get_saving_details tool provides granular data for a specific savings account, including:

• Accrued Interest: The amount of interest earned since the start date.
• Maturity Instructions: Information on what happens to the funds upon maturity.
• Interest Rate: The annual percentage rate (ratePercentPerYear).

Sources: mbbank_mcp/core.py:226-285, mbbank_mcp/modals.py:61-91

Implementation Details

The feature is implemented within mbbank_mcp/core.py using the FastMCP framework.

@fast_mcp.tool()
async def get_balances() -> BalancesModel:
    raw_balances = await mbbank.getBalance()
    return BalancesModel(
        account=[AccountModel(
            accountNumber=account.acctNo,
            accountName=account.acctAlias,
            currency=account.ccyCd,
            balance=account.currentBalance,
        ) for account in raw_balances.acct_list],
        # ... international account mapping
    )

Sources: mbbank_mcp/core.py:118-128, mbbank_mcp/modals.py:7-17

Conclusion

The Balance Monitoring Feature provides a comprehensive read-only view of a user's MBBank financial status. By leveraging standardized data models and MCP tools, it enables secure, programmatic access to balances, transactions, and savings information while maintaining clear separation between domestic and international assets.