🔌 mcp-banking-tools

Deterministic Financial Tooling Microservice: High-performance, production-grade Model Context Protocol (MCP) server built with FastMCP Python (SSE Mode), Threaded Database Connection Pooling, Bandit SAST Security Scanning, and Pytest Unit Testing, containerized and published to GitHub Container Registry (ghcr.io).

🎯 Executive Summary & Architectural Purpose

In autonomous AI agent systems, granting language models direct database access or relying on probabilistic text instructions is a catastrophic security risk.

mcp-banking-tools acts as the isolated deterministic execution bridge between AI Agents (via NVIDIA NeMo Guardrails) and the core financial ledger (PostgreSQL). Every action is encapsulated within type-safe, auditable tools enforcing strict integer-cents monetary precision (amount_cents: int).

🏛️ Strategic Architecture & DevSecOps Matrix

                                 [ Kubernetes Cluster (K3s) ]
                                 
  +-----------------------+      SSE (HTTP :8001)      +---------------------------------+
  |  NVIDIA NeMo Server   |  ----------------------->  |  mcp-banking-tools (FastMCP)    |
  |  / Agentic Framework  |                            |  - Threaded Connection Pool     |
  +-----------------------+                            +---------------------------------+
                                                                       |
                                                                       | SQL (TCP :5432)
                                                                       v
                                                       +---------------------------------+
                                                       |  PostgreSQL 16 Alpine           |
                                                       |  - characters (balances)        |
                                                       |  - blocked_pix_keys (BACEN)     |
                                                       |  - transactions (audit ledger)  |
                                                       +---------------------------------+

🛡️ Quality & DevSecOps Pipeline

Every push to main triggers a 2-stage GitHub Actions pipeline enforcing enterprise standards:

Tooling Layer	Technology	Engineering Guarantee
Linter & Formatter	Ruff & Black	100% PEP 8 compliant, ultra-fast Python code formatting.
Static Type Checker	Mypy	Enforces strict static typing on all tool parameters.
SAST Security Scanner	Bandit	Scans for SQL injection risks, hardcoded credentials, and unsafe sockets.
Automated Unit Tests	Pytest + pytest-mock	Validates tool logic, balance checks, and transaction edge cases.
Container Registry	GHCR (`ghcr.io`)	Multi-architecture builds (`linux/amd64`, `linux/arm64`) pushed to GitHub Container Registry.

🛠️ Provided FastMCP Tools Registry

1. `get_account_balance(pix_key: str)`

Description: Fetches real-time account balances (in cents and BRL) and risk profiles for test characters (Leo Vance, Maria Silva, Enterprise X Corp).
Return Contract: { "status": "success", "name": str, "pix_key": str, "balance_cents": int, "balance_brl": float, "risk_profile": str }

2. `check_blocked_pix_key(pix_key: str)`

Description: Queries the BACEN (Central Bank of Brazil) fraud registry table (blocked_pix_keys) for malicious PIX keys ([email protected]).
Return Contract: { "status": "blocked" | "clean", "is_fraud": bool, "pix_key": str, "reason": str }

3. `transfer_pix(origin_pix_key: str, destination_pix_key: str, amount_cents: int)`

Description: Executes an atomic, thread-safe PIX financial transfer between accounts.
Financial Precision: Enforces integer cents (amount_cents: int) to eliminate floating-point IEEE 754 rounding vulnerabilities. Applies FOR UPDATE row locking in PostgreSQL to prevent race conditions.

📖 Auxiliary Technical Documentation

📄 FastMCP Execution & Sequence Flow Specification

🚀 Local Development & Testing

# 1. Install dependencies & quality tools
pip install -r requirements.txt

# 2. Run code quality checks
ruff check src/ tests/
black --check src/ tests/
mypy src/
bandit -r src/

# 3. Run unit tests
pytest -v tests/

# 4. Start FastMCP Server locally (SSE mode)
python -m src.server

🔌 mcp-banking-tools