# BankGuard MCP

A fraud detection engine that AI assistants can operate directly.

BankGuard is an MCP (Model Context Protocol) server. Connect it to Claude Desktop, Claude Code, or any MCP-capable agent, and the AI gets a set of typed tools for running a banking fraud system: submitting transactions, reading alerts, checking portfolio risk, and freezing or unfreezing accounts. You can literally ask Claude "scan the accounts and freeze anything that looks compromised" and watch it work.

The fraud rules themselves live inside the database as SQLite triggers, so they're enforced no matter who writes - the AI, a script, or a human with a sqlite shell. The AI operates the system; it can't bypass the rules.

## Why This Design

Most AI integrations bolt a chatbot onto an app. MCP inverts that: the system exposes a safe operating surface, and any AI client can drive it. This project demonstrates both halves:

- **The engine** - six fraud rules implemented as in-database triggers (invalid amounts, frozen-account blocks, daily limits, velocity detection, risk scoring with auto-freeze, and event emission)
- **The AI surface** - eight MCP tools with docstrings the model reads to decide when and how to act. Destructive actions (freeze/unfreeze) require a reason, which is recorded as an audit alert.

```
Claude Desktop / Claude Code / any agent
        |  MCP (stdio)
        v
   server.py        eight typed tools
        |
        v
   bankguard.db     SQLite + trigger-enforced fraud rules
```

## Tools

| Tool | What it does |
| --- | --- |
| `list_accounts` | All accounts with owner, status, risk score |
| `get_account_activity` | Recent transactions for one account |
| `submit_transaction` | Insert a transaction; fraud rules may reject or flag it |
| `get_fraud_alerts` | Recent alerts raised by the rules |
| `get_notifications` | Queued events for downstream systems |
| `freeze_account` | Analyst freeze, reason required and audited |
| `unfreeze_account` | Reactivate and reset risk, reason audited |
| `risk_summary` | Portfolio totals, alerts by rule, riskiest accounts |

## Setup

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python database.py       # creates bankguard.db with 5 seeded accounts
python test_server.py    # end-to-end test through a real MCP client
```

### Connect to Claude Code

```bash
claude mcp add bankguard -- /path/to/bankguard-mcp/.venv/bin/python /path/to/bankguard-mcp/server.py
```

### Connect to Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "bankguard": {
      "command": "/path/to/bankguard-mcp/.venv/bin/python",
      "args": ["/path/to/bankguard-mcp/server.py"]
    }
  }
}
```

Then try prompts like:

- "Give me a risk summary of the bank"
- "Submit five $100 transactions to account 102 and tell me what happens"
- "Which account is riskiest? Show its recent activity and freeze it if warranted"

## The Fraud Rules

1. **Amount validation** - zero/negative transactions rejected before insert
2. **Status validation** - frozen accounts reject all transactions, even direct DB writes
3. **Daily limit** - per-day spend cap enforced per account
4. **Velocity detection** - 3+ transactions inside 60 seconds raises an alert and +20 risk
5. **Auto-freeze** - account freezes itself when risk reaches 60
6. **Event emission** - velocity and freeze events queue notifications for downstream consumers

`test_server.py` proves all six by driving the server over stdio the same way a real client does.

## Project Structure

```
bankguard-mcp/
    server.py        MCP server - the AI-facing tool surface
    database.py      SQLite engine with trigger-enforced fraud rules
    test_server.py   end-to-end test through the MCP protocol
    requirements.txt
```

## Ideas for Later

- Postgres backend for the same tool surface
- MCP resources exposing the schema and rule documentation
- Human-in-the-loop: mark freeze/unfreeze as requiring client-side approval
- Streamable HTTP transport for remote deployment