Data Validation

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
• pyproject.toml
• README.md

Data validation in the mbbank-mcp project is implemented through a combination of Pydantic models for response structuring, strict argument typing in MCP tools, and runtime authentication checks. The system ensures that data received from the MBBank API is transformed into sanitized, well-defined schemas before being presented to the Model Context Protocol (MCP) interface.

The validation layer serves as a proxy, renaming complex or inconsistent fields from the internal mbbank-lib into user-friendly names while enforcing data types such as strings, integers, and optional fields. This prevents malformed data from propagating through the server to the client application.
Sources: mbbank_mcp/modals.py:5-7, README.md:1-5

Pydantic Schema Validation

The project utilizes Pydantic BaseModel to define the structure of data returned by the server. These models act as a validation gate for account balances, transaction histories, card information, and savings details.

Model Categories

The system categorizes validation models into specific domains to handle different bank data structures.

Model Category	Key Fields	Purpose
Account	accountNumber, balance, currency	Validates bank account summaries.
Transaction	transactionId, amount, transferredTo	Validates history and transfer details.
Card	cardId, cardStatus, cardType	Validates debit/credit card metadata.
Saving	principalAmount, maturityDate, interestRate	Validates deposit and savings accounts.

Sources: mbbank_mcp/modals.py:9-106

Data Flow for Validation

When a tool is invoked, the raw data from the underlying mbbank-lib is mapped into these Pydantic models.

The core.py file contains the logic that extracts raw fields (e.g., acctNo, acctAlias) and maps them to validated fields (e.g., accountNumber, accountName).
Sources: mbbank_mcp/core.py:115-128, mbbank_mcp/modals.py:9-14

Tool Argument Validation

Each MCP tool defined in core.py uses Python type hinting to validate input arguments. The FastMCP framework uses these hints to ensure the LLM or client provides the correct data types before the function logic executes.

Input Constraints

• Literal Types: Certain parameters are restricted to specific string values using typing.Literal. For example, interest rate queries only accept "VND", "USD", or "EUR".
• Date Formatting: Tools like get_transactions expect a specific string format (dd-mm-yyyy), which is validated via datetime.strptime within the tool logic.
• Session IDs: The verify_transfer tool validates the existence and expiration of a sid (Session ID) within an internal transfer_manager.

Sources: mbbank_mcp/core.py:145-148, mbbank_mcp/core.py:240-244, mbbank_mcp/core.py:255-259

Transfer State Validation

Money transfers require a multi-stage validation process involving a QR code generation phase and an OTP verification phase. The server manages state validation using a TransferState TypedDict and a time-based expiration mechanism.

The server enforces a 120-second expiration for transfer sessions. Any attempt to verify a transfer after this period results in a validation failure.
Sources: mbbank_mcp/core.py:34-40, mbbank_mcp/core.py:80-90, mbbank_mcp/core.py:100-108

Authentication & Environment Validation

Before the server starts, it validates the presence of required credentials and the connectivity to MBBank.

1. CLI Argument Validation: The main function in __main__.py checks if --username and --password are provided via CLI or environment variables. If missing, it exits with an error.
2. Authentication Handshake: The server calls mbbank_client._authenticate() during startup. If authentication fails, the server does not proceed to run.
3. Dependency Validation: The pyproject.toml ensures that specific versions of mbbank-lib, mcp, and pydantic are present to maintain data integrity.

Sources: mbbank_mcp/main.py:35-45, mbbank_mcp/main.py:47-49, pyproject.toml:13-21

Error Handling during Validation

Data validation errors are handled through two primary methods:

• Pydantic Validation: If the data from the bank doesn't match the expected modals.py schema, Pydantic raises a validation error, preventing corrupted data from being sent to the client.
• Explicit Returns: Tools like get_saving_details return a SavingDetailsModel which contains an optional error field to communicate validation or retrieval issues gracefully.

Sources: mbbank_mcp/modals.py:102-104, mbbank_mcp/core.py:245-252

This structured approach ensures that the MCP server acts as a reliable intermediary, strictly governing the flow of sensitive financial data between the bank API and the protocol client.