# Banking MCP Server

A Model Context Protocol (MCP) server that exposes banking operations as AI-accessible tools. This allows AI assistants like Claude to perform banking operations—creating customers and accounts, checking balances, transferring funds, and viewing transaction history—through a discoverable tool interface.

## Architecture

The system consists of four main components:

```
┌─────────────────┐
│   MCP Host      │  Claude Desktop, VS Code, or custom client
│   (AI Client)   │
└────────┬────────┘
         │ STDIO transport
         ↓
┌─────────────────┐
│   MCP Server    │  Python server exposing 9 banking tools
│                 │  + 5 resources + 3 prompts
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│  SQLite Database│  4 tables: Customer, Account, Transaction, Transfer
└─────────────────┘
```

**Components:**
- **MCP Server** (Python): Exposes banking operations as MCP tools
- **Database** (SQLite): Stores customer, account, and transaction data
- **MCP Client**: Any MCP-compatible host (Claude Desktop, VS Code, custom implementations)
- **Transport**: STDIO (standard input/output) for local communication

## Prerequisites

- **Python 3.14+** (tested on 3.14.0)
- **pip** (Python package manager)
- **Git** (for cloning the repository)

**Optional:**
- **Claude Desktop** or **VS Code** with MCP support (for testing the server)

## Installation

1. **Clone the repository**
   ```bash
   cd path/to/your/projects
   git clone <repository-url>
   cd Banking_Assistant
   ```

2. **Create and activate a virtual environment**
   ```bash
   # Create virtual environment
   python -m venv venv

   # Activate (Windows)
   venv\Scripts\activate

   # Activate (macOS/Linux)
   source venv/bin/activate
   ```

3. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

4. **Initialize the database**
   ```bash
   # Create database with sample data (20 customers, 50 accounts)
   python src/database/init_db.py --seed
   ```

   Expected output:
   ```
   [OK] Created CUSTOMER table
   [OK] Created ACCOUNT table
   [OK] Created TRANSACTION table
   [OK] Created FUND_TRANSFER table
   [OK] Created 20 customers (CUST001 - CUST020)
   [OK] Created 50 accounts (ACC000001 - ACC000050)
   ```

## Configuration

### Claude Desktop Setup

1. **Locate your Claude Desktop config file:**
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

2. **Add the MCP server configuration:**
   ```json
   {
     "mcpServers": {
       "banking-assistant": {
         "command": "python",
         "args": [
           "c:/path/to/Banking_Assistant/src/mcp_server/server.py"
         ]
       }
     }
   }
   ```
   
   **Important:** Use the absolute path to `server.py` on your system.

3. **Restart Claude Desktop** to load the new server.

### VS Code Setup

See [docs/configuration.md](docs/configuration.md) for VS Code MCP extension setup.

## Running the Server

The MCP server runs automatically when invoked by an MCP host (like Claude Desktop). You can also test it directly:

```bash
# Activate your virtual environment first
python src/mcp_server/server.py
```

**Expected output:**
```
Starting Banking MCP Server...
Server name: banking-assistant
Available tools: 9
Available resources: 5
Available prompts: 3
Transport: STDIO
Listening for MCP requests...
```

The server listens on stdin/stdout and waits for MCP protocol messages.

## Testing

### Quick Test in Claude Desktop

1. **Verify the server is connected:**
   ```
   What banking tools do you have available?
   ```
   Expected: Claude lists 9 banking tools

2. **Create a test customer:**
   ```
   Create a bank customer named John Doe with email john@example.com, 
   phone +1234567890, and address 123 Main St, New York, NY 10001
   ```

3. **Open an account and test a transfer:**
   ```
   For the customer just created:
   - Create a SAVINGS account with $5,000
   - Create a CHECKING account with $2,000
   - Transfer $500 from savings to checking
   - Show me the final balances
   ```

For comprehensive test scenarios and troubleshooting, see [docs/testing.md](docs/testing.md).

### Running Unit Tests

```bash
# Run all tests
python -m pytest tests/ -v

# Run specific test file
python -m pytest tests/test_tools.py -v
```

### Manual Tool Testing

```bash
# Test individual tools
python test_tools.py
```

## Project Structure

```
Banking_Assistant/
├── src/
│   ├── mcp_server/
│   │   ├── server.py          # Main MCP server entry point
│   │   ├── tools.py           # 9 banking tool implementations
│   │   ├── resources.py       # 5 MCP resources (read-only data access)
│   │   └── prompts.py         # 3 MCP prompt templates
│   ├── database/
│   │   ├── init_db.py         # Database schema creation and seeding
│   │   ├── models.py          # Data models (Customer, Account, etc.)
│   │   └── operations.py      # CRUD operations
│   ├── client/
│   │   └── mcp_client.py      # Example MCP client implementation
│   └── utils/
│       └── validators.py      # Input validation functions
├── data/
│   └── banking.db             # SQLite database (created by init_db.py)
├── tests/
│   ├── test_tools.py          # Tool unit tests
│   ├── test_database.py       # Database operation tests
│   └── test_integration.py    # Integration tests
├── demo/
│   └── walkthrough.py         # End-to-end demo script
├── docs/
│   ├── api-reference.md       # Tool, resource, and prompt specifications
│   ├── testing.md             # Testing guide and scenarios
│   └── configuration.md       # Detailed configuration instructions
├── requirements.txt           # Python dependencies
├── README.md                  # This file
└── CLAUDE.md                  # Context for AI assistants working on this repo
```

### Key Files

- **`src/mcp_server/server.py`** - Entry point that registers and exposes all tools
- **`src/mcp_server/tools.py`** - Implementation of the 9 banking operations
- **`src/database/init_db.py`** - Run this to create and populate the database
- **`data/banking.db`** - SQLite database (created automatically)

## API Overview

### Tools (9)
- `create_customer` - Create a new customer
- `create_account` - Open a bank account
- `get_balance` - Check account balance
- `get_last_10_transactions` - View transaction history
- `transfer_funds` - Transfer money between accounts
- `update_customer_address` - Update customer address
- `update_customer_phone` - Update customer phone number
- `get_customer_info` - Retrieve customer details
- `get_customer_accounts` - List all accounts for a customer

### Resources (5)
- `customers://all` - List all customers
- `accounts://all` - List all accounts
- `accounts://{id}` - Get specific account details
- `transactions://recent` - View recent transactions
- `transfers://history` - View transfer history

### Prompts (3)
- `customer_summary` - Generate customer profile summary
- `account_summary` - Generate account overview
- `spending_pattern` - Analyze spending patterns

For detailed specifications, see [docs/api-reference.md](docs/api-reference.md).

## Database Schema

The SQLite database contains 4 tables:

- **CUSTOMER** - Customer information (ID, name, email, phone, address)
- **ACCOUNT** - Bank accounts (account number, customer ID, type, balance, status)
- **TRANSACTION** - Transaction history (ID, account, date, amount, type, description)
- **FUND_TRANSFER** - Transfer records (ID, from/to accounts, amount, status, timestamp)

Sample data includes 20 customers and 50 accounts with realistic balances and transaction history.

## Troubleshooting

**Server not appearing in Claude Desktop:**
- Verify the config file path is correct
- Check that the absolute path to `server.py` is correct
- Restart Claude Desktop after config changes
- Check Claude Desktop logs for errors

**Database errors:**
- Ensure `data/banking.db` exists (run `init_db.py` if not)
- Check file permissions on the database file
- Re-run `init_db.py --seed` to recreate the database

**Import errors:**
- Verify virtual environment is activated
- Run `pip install -r requirements.txt` again
- Check Python version is 3.14+

## License

Educational project for the Claude Champion Program.

## Additional Documentation

- **[API Reference](docs/api-reference.md)** - Complete tool, resource, and prompt specifications
- **[Testing Guide](docs/testing.md)** - Test scenarios and troubleshooting
- **[Configuration](docs/configuration.md)** - Detailed MCP client setup instructions