# Vigil Fraud Alert — API + MCP Server

Proximity-based card fraud detection for Vigil / Ebenova Solutions.

Turns the Vigil proximity engine into a callable REST API and MCP server with
Claude-powered transaction analysis, risk scoring, and AML report generation.

---

## Quick Start

```bash
cd vigil-fraud-alert-mcp
npm install
npm run build          # esbuild — fast, no memory issues
npm run start:http     # REST API + MCP on http://localhost:3000
```

**Test it's running:**
```bash
curl http://localhost:3000/
curl http://localhost:3000/api/v1/health
```

---

## Claude Desktop Setup (stdio MCP)

Add to `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "vigil-fraud-alert": {
      "command": "node",
      "args": ["C:/projects/ProximityGuard/vigil-fraud-alert-mcp/dist/index.js"]
    }
  }
}
```

Restart Claude Desktop. You'll have 13 tools available instantly.

---

## MCP Tools (13 total)

### Core Authorization
| Tool | What it does |
|------|-------------|
| `vigil_authorize` | Run a transaction through the proximity engine → approve/decline |
| `vigil_get_card` | Get card config + GPS freshness |
| `vigil_update_card_mode` | Switch home / travel / lockdown |
| `vigil_update_gps` | Push fresh GPS snapshot |
| `vigil_add_travel_plan` | Add country + date range travel plan |

### Transactions & Alerts
| Tool | What it does |
|------|-------------|
| `vigil_list_transactions` | Query decision history |
| `vigil_confirm_transaction` | Record "was this you?" response |
| `vigil_list_alerts` | List fraud alerts by status/severity |
| `vigil_update_alert` | Advance alert through investigation workflow |
| `vigil_get_risk_profile` | Live risk score 0–100 per card |

### AI-Powered (Claude Haiku / Sonnet)
| Tool | What it does |
|------|-------------|
| `vigil_analyze_transaction` | AI risk analysis — factors, SMS copy, recommendation |
| `vigil_block_transaction` | Emergency card lockdown + alert escalation |
| `vigil_generate_report` | Full AML compliance report (Claude Sonnet) |

---

## REST API

### Core endpoints
```
POST   /api/v1/authorize                  # Proximity engine decision
GET    /api/v1/cards/:id                  # Card config + GPS age
PATCH  /api/v1/cards/:id/mode             # { mode: "home"|"travel"|"lockdown" }
POST   /api/v1/cards/:id/gps              # GPS snapshot update
POST   /api/v1/cards/:id/travel-plans     # Add travel plan
GET    /api/v1/transactions               # ?card_id=&approved=&limit=
POST   /api/v1/transactions/:id/confirm   # { confirmed: "yes"|"no" }
GET    /api/v1/alerts                     # ?card_id=&status=&severity=
PATCH  /api/v1/alerts/:id                 # { status, notes }
GET    /api/v1/cards/:id/risk             # Risk profile
```

### AI endpoints (Anthropic-powered)
```
POST   /api/v1/fraud/analyze              # AI transaction analysis
GET    /api/v1/fraud/score/:card_id       # Risk score 0–100 + explanation
POST   /api/v1/fraud/report               # AML compliance report
```

### Example: Authorize a transaction
```bash
curl -X POST http://localhost:3000/api/v1/authorize \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": "card_01",
    "merchant_name": "Safeway",
    "merchant_city": "Calgary",
    "merchant_country": "CA",
    "merchant_network_id": "safeway_yyc_001",
    "merchant_mcc": "5411",
    "merchant_lat": 51.049,
    "merchant_lng": -114.08,
    "amount_cents": 4250,
    "currency": "cad"
  }'
```

### Example: AI fraud analysis
```bash
curl -X POST http://localhost:3000/api/v1/fraud/analyze \
  -H "Content-Type: application/json" \
  -d '{ "transaction_id": "txn_002" }'
```

### Example: AML report
```bash
curl -X POST http://localhost:3000/api/v1/fraud/report \
  -H "Content-Type: application/json" \
  -d '{ "card_id": "card_01", "period_start": "2026-03-01", "period_end": "2026-03-31" }'
```

---

## Architecture

```
Stripe/Lithic webhook → POST /api/v1/authorize
                               ↓
                    Proximity Engine (issuer-agnostic)
                    decision-engine.ts / haversine
                               ↓
                    AuthorizationDecision
                    + auto-create FraudAlert
                               ↓
                    (async) POST /api/v1/fraud/analyze
                    → Claude Haiku: risk score, SMS copy
                               ↓
                    (async) Twilio SMS → user
                               ↓
                    User replies NO → vigil_block_transaction
                    → card.mode = lockdown
                    → Stripe card.update({ status: 'canceled' })
```

---

## Demo Cards

| Card | Location | Mode |
|------|----------|------|
| `card_01` | Calgary, CA | home (radius 50km) |
| `card_02` | Toronto→London | travel (GB plan active) |
| `card_03` | New York, US | lockdown |

---

## What AI Does / Does Not Do

**Does:** Pattern analysis, human-readable risk explanations, SMS copy generation,
AML report writing, anomaly reason generation.

**Does not:** Hold funds, make final block decisions, store card numbers (PCI).
Final authority to block always rests with the user or human analyst.
Stripe/Lithic hold the regulated licenses — Vigil is software-only.

---

## Environment Variables

```env
PORT=3000                  # HTTP port (default 3000)
TRANSPORT=http             # http or stdio (default stdio)
# Anthropic API key is handled by the platform (Claude.ai / Claude Desktop)
# In standalone deployment, set: ANTHROPIC_API_KEY=sk-ant-...
```

*Part of Ebenova Solutions — Vigil LLC*