fraud-detection-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Advanced Fraud Detection MCP server built with FastMCP. Combines behavioral biometrics (keystroke dynamics, mouse patterns), ML-based anomaly detection (Isolation Forest, Autoencoders), graph-based fraud ring detection (NetworkX), SHAP explainability, AI agent-to-agent transaction protection, defense compliance modules, RFC 9421 HTTP Message Signature verification with Content-Digest body coverage and @query/@query-param derived components (Visa TAP / Mastercard Web Bot Auth / Stripe ACP), and a training/benchmarking pipeline into a unified MCP tool interface with 28 exposed tools (19 core + 5 compliance + 4 agent commerce Tier 0). XGBoost is available optionally via the training pipeline but is not in the default detection path.

See docs/roadmap/agentic_commerce_2026.md for the full Stripe ACP / Visa TAP / Mastercard Verifiable Intent / Google AP2 / Coinbase x402 feature roadmap. Tier 0 — RFC 9421 verifier (incl. Content-Digest + @query + JWKS retry-with-backoff), nonce cache (peek/consume split), idempotency store, 13-feature behavioral fingerprint with cyclical hour encoding, claimed-vs-verified traffic classification fully wired through analyze_agent_transaction_impl, issuer-to-protocol mapping, and real JWT signature verification — is implemented and live. Tiers 1 and 2 are open work.

Development Commands

# Setup
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# Run MCP server
python server.py

# Run tests (with coverage, CI requires 60% minimum)
python run_tests.py

# Run tests directly
python -m pytest tests/ -v --tb=short --cov=server --cov-report=term-missing

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

# Run tests by marker
python -m pytest -m unit           # Unit tests only
python -m pytest -m integration    # Integration tests
python -m pytest -m behavioral     # Behavioral biometrics tests
python -m pytest -m network        # Network/graph analysis tests
python -m pytest -m transaction    # Transaction analysis tests
python -m pytest -m explainability # SHAP explainability tests
python -m pytest -m synthetic      # Synthetic data generation tests
python -m pytest -m benchmark      # Benchmark tests
python -m pytest -m security       # Security utility tests
python -m pytest -m velocity       # User history / velocity tests
python -m pytest -m signature      # RFC 9421 / JWS / JWT signature verification

# Linting (CI uses ruff)
ruff check . --output-format=github
ruff format --check .

# Security scanning
bandit -r . -x ./tests,./.venv -ll

# Type checking
mypy server.py --ignore-missing-imports