MCP Tool Registration

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
• mbbank_mcp/init.py
• README.md
• pyproject.toml

The Model Context Protocol (MCP) Tool Registration system within mbbank-mcp facilitates the exposure of MBBank API functionalities to LLM-based clients. By utilizing the FastMCP framework, the project transforms asynchronous Python methods into discoverable tools that can perform actions ranging from account balance inquiries to multi-step fund transfers.

This system acts as a bridge between the mbbank-lib underlying library and the MCP standard, handling authentication, data modeling, and state management for complex operations like transaction verification.

Sources: mbbank_mcp/core.py:1-25, README.md:1-10

Server Initialization and Lifecycle

The MCP server is instantiated through a factory function that configures the FastMCP instance with necessary MBBank client credentials. The server supports multiple communication modes, including standard input/output (stdio) for local CLI usage and Server-Sent Events (SSE) for remote web-based interactions.

Component Relationship

The following diagram illustrates how the crate_mcp_server function integrates the MBBank client and registers various tool groups.

Tool Categories and Implementation

Tools are registered using the @fast_mcp.tool() decorator, which automatically handles the conversion of docstrings and type hints into the tool definitions required by MCP clients.

Account and Identity Tools

These tools provide read-only access to account metadata and current financial standings.

Tool Name	Purpose	Return Type
get_balances	Retrieves current balances for all accounts.	BalancesModel
get_bank_list	Lists supported banks and their internal codes.	dict[str, str]
get_today_date	Provides date in dd-mm-yyyy format for queries.	str

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

Transfer and Verification System

The transfer system is unique because it requires a two-step stateful process. Since MCP tools are typically stateless, the server maintains an internal transfer_manager dictionary to track pending transactions.

1. start_transfer: Initiates the request and generates a QR code for D-OTP (Digital OTP) authentication.
2. verify_transfer: Completes the transaction using the session ID (sid) and the user-provided OTP.

Transaction and Card Management

These tools allow for historical data analysis and card-specific monitoring.

• get_transactions: Fetches account history. It requires an account_number, from_date, and to_date.
• get_cards: Lists all active and closed cards.
• get_card_transactions: Fetches history specifically for a card ID.

Sources: mbbank_mcp/core.py:147-200, mbbank_mcp/modals.py:27-44

Data Modeling for MCP

To ensure type safety and clean JSON responses for LLM consumption, the registration system utilizes Pydantic models defined in modals.py. These models proxy the raw responses from mbbank-lib into simplified structures.

Key Data Structures

Model	Key Fields	Source File
TransactionModel	transactionId, amount, description, transferredTo	modals.py:27-34
SavingModel	principalAmount, maturityDate, ratePercentPerYear	modals.py:53-64
CardModel	cardId, cardNumber, cardStatus	modals.py:38-45

Sources: mbbank_mcp/modals.py:1-100

State and Expiration Logic

The transfer_manager in core.py implements a cleanup task to prevent memory leaks from abandoned transfer sessions.

async def _remove_expired_transfers():
    await asyncio.sleep(130)  # Buffer for expiration
    current_time = time.time()
    expired_sids = [
        sid for sid, info in transfer_manager.items()
        if current_time - info["create_time"] > 120  # 2 min limit
    ]
    for sid in expired_sids:
        del transfer_manager[sid]

The expiration logic is triggered as a background task via asyncio.create_task during every transfer initiation.
Sources: mbbank_mcp/core.py:75-86

Summary

The MCP Tool Registration system in mbbank-mcp effectively modularizes banking operations into discrete, AI-accessible tools. By combining FastMCP decorators with custom state management for transfers and Pydantic for data validation, it provides a secure and structured interface for monitoring and interacting with MBBank accounts.