AmexAnalysis-MCP: Advanced Documentation

🚀 Version 2.0 - The most comprehensive American Express transaction analyzer with payment processor unmasking technology

Table of Contents

1. Overview
2. Architecture
3. Advanced Features
4. Installation & Setup
5. Configuration
6. API Reference
7. Data Structures
8. Algorithms & Logic
9. Performance & Optimization
10. Security & Privacy
11. Troubleshooting
12. Contributing
13. License

Overview

AmexAnalysis-MCP is a sophisticated financial analysis tool that transforms your American Express credit card statements into actionable intelligence. Built on the Model Context Protocol (MCP), it seamlessly integrates with Claude Desktop to provide natural language interaction with your financial data.

Core Capabilities

• 🔍 Vendor Unmasking: Reveals real merchants behind payment processors
• 💳 Subscription Detection: Identifies recurring charges with 95%+ accuracy
• 🚨 Fraud Detection: Multi-layer anomaly detection system
• 📊 Spending Intelligence: Category-based analysis with trends
• 📤 Multi-Format Export: Excel, CSV, JSON with rich metadata
• 🤖 AI Integration: Natural language queries via Claude

What Makes This Different?

Unlike basic expense trackers, AmexAnalysis-MCP understands the modern payment ecosystem where 40%+ of transactions flow through intermediaries like PayPal, Square, and Stripe. Our vendor unmasking technology reveals the actual businesses you're paying, not just the payment processor.

Architecture

System Design

┌─────────────────────────────────────────────────────────────┐
│                     Claude Desktop                          │
│                         ↕ MCP                               │
├─────────────────────────────────────────────────────────────┤
│                  AmexAnalysis-MCP Server                    │
├─────────────────────┬───────────────────┬───────────────────┤
│   CSV Parser        │  Analysis Engine  │  Export Manager   │
├─────────────────────┼───────────────────┼───────────────────┤
│ Transaction Store   │ Vendor Unmasker   │ Pattern Detector  │
└─────────────────────┴───────────────────┴───────────────────┘

Component Overview

1. MCP Server (amex-mcp-server.ts)

   • Handles Claude Desktop communication
   • Routes commands to appropriate handlers
   • Manages tool registration and execution

2. Vendor Unmasker (amex-vendor-unmasker.ts)

   • Pattern recognition engine
   • Processor-specific extraction rules
   • Confidence scoring algorithm
   • Fallback suggestion system

3. Analysis Engine

   • Transaction aggregation
   • Pattern detection (recurring, anomalous)
   • Category inference
   • Insight generation

4. Export Manager

   • Multi-format support (Excel, CSV, JSON)
   • Rich metadata preservation
   • Formatted reporting

Advanced Features

1. Vendor Unmasking Deep Dive

How It Works

The vendor unmasking system uses a multi-stage pipeline:

1. Processor Detection

   // Example: "PAYPAL *GRUBHUB" → Processor: PayPal
   const processor = detectPaymentProcessor(description);
   

2. Pattern Extraction

   // Apply processor-specific rules
   const extracted = applyExtractionRules(description, processor.rules);
   

3. Confidence Calculation

   // Based on extraction quality, pattern matches, context
   const confidence = calculateConfidence(extracted, context);
   

4. Fallback Suggestions

   // For low confidence, suggest based on amount/timing
   const suggestions = generateSuggestions(transaction, similarTransactions);
   

Supported Processors

Processor	Patterns	Extraction Method	Avg Confidence
PayPal	PAYPAL *, PP*	Delimiter split	85%
Square	SQ *, SQUARE *	Delimiter + cleanup	80%
Stripe	STRIPE:, STR*	Colon split	90%
Toast	TST*, TOASTPOS	Delimiter split	85%
Venmo	VENMO PAYMENT	Keyword extraction	75%
Cash App	CASH APP *	Delimiter split	80%
Clover	CLV*, CLOVER	Delimiter split	85%
Apple Pay	APPLE PAY	Context analysis	70%
Google Pay	GOOGLE PAY	Context analysis	70%
Zelle	ZELLE TO	Recipient extraction	90%

2. Subscription Detection Algorithm

Pattern Recognition

interface RecurringPattern {
  frequency: 'daily' | 'weekly' | 'biweekly' | 'monthly' | 'quarterly' | 'annual';
  expectedAmount: number;
  variance: number;
  confidence: number;
  nextExpectedDate?: Date;
}

Detection Logic

1. Keyword Analysis

   • Searches for subscription-related terms
   • Weights based on keyword strength

2. Interval Calculation

   • Measures days between transactions
   • Calculates variance for consistency

3. Amount Validation

   • Checks for consistent amounts
   • Allows small variance (± 5%)

4. Confidence Scoring

   Confidence = (Keyword Match × 0.3) + 
                (Interval Consistency × 0.4) + 
                (Amount Consistency × 0.3)
   

3. Fraud Detection System

Multi-Layer Validation

1. Amount Patterns

   • Suspicious amounts ($999, $399)
   • High daily transaction velocity
   • Amount clustering analysis

2. Vendor Analysis

   • Generic vendor names
   • Blacklisted keywords
   • New vendor spike detection

3. Behavioral Anomalies

   • Sudden spending increases
   • Unusual transaction timing
   • Geographic impossibilities

Severity Scoring

enum FraudSeverity {
  LOW = 'low',      // Score 0-30
  MEDIUM = 'medium', // Score 31-70
  HIGH = 'high'      // Score 71-100
}

4. Category Intelligence

Automatic Categorization

Categories are inferred using:

• Vendor name analysis
• Transaction amount ranges
• Time-of-day patterns
• Keyword matching

Category Hierarchy

├── Food & Dining
│   ├── Restaurants
│   ├── Fast Food
│   ├── Coffee Shops
│   └── Delivery Services
├── Transportation
│   ├── Rideshare
│   ├── Public Transit
│   ├── Gas Stations
│   └── Parking
├── Shopping
│   ├── Online Retail
│   ├── Groceries
│   ├── Clothing
│   └── Electronics
└── [More categories...]

Installation & Setup

Prerequisites

• Node.js 18+ (Required for MCP)
• Claude Desktop (Latest version)
• American Express account with CSV export access

Quick Install

# Clone the repository
git clone https://github.com/ogprotege/amex-anaylsis-mcp.git
cd amex-analysis-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

Manual Setup

1. Install Dependencies

   npm install @modelcontextprotocol/sdk papaparse csv-writer exceljs zod
   npm install -D typescript tsx @types/node @types/papaparse
   

2. Configure TypeScript

   {
     "compilerOptions": {
       "target": "ES2022",
       "module": "NodeNext",
       "moduleResolution": "NodeNext",
       "strict": true,
       "esModuleInterop": true
     }
   }
   

3. Build Project

   npx tsc -p amex-mcp-tsconfig.json
   

Claude Desktop Integration

1. Locate Config File

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add MCP Server

   {
     "mcpServers": {
       "amex-analysis": {
         "command": "node",
         "args": ["/absolute/path/to/dist/amex-mcp-server.js"],
         "env": {}
       }
     }
   }
   

3. Restart Claude Desktop

Configuration

Environment Variables

# Optional: Set custom paths
export AMEX_DATA_DIR="/path/to/data"
export AMEX_OUTPUT_DIR="/path/to/output"

# Optional: Debug mode
export AMEX_DEBUG="true"

Custom Configuration

Create amex-config.json:

{
  "analysis": {
    "minTransactionsForSubscription": 2,
    "subscriptionConfidenceThreshold": 0.7,
    "fraudScoreThreshold": 50,
    "maxDuplicateWindowDays": 3
  },
  "export": {
    "excelTemplate": "custom-template.xlsx",
    "dateFormat": "MM/DD/YYYY",
    "currencySymbol": "$"
  },
  "vendorUnmasking": {
    "minConfidence": 0.5,
    "reviewThreshold": 0.7,
    "customProcessors": []
  }
}

API Reference

MCP Tools

Note: The system offers two server modes:

• Basic Server (amex-mcp-server.ts): 6 high-level tools for everyday use
• Enhanced Server (amex-mcp-server-enhanced.ts): 36 specialized tools for power users

See ENHANCED_SERVER_GUIDE.md to enable all 36 tools including vendor unmasking, trend analysis, duplicate detection, tax categorization, and more.

analyze_amex_spending

Comprehensive spending analysis with export options.

Parameters:

{
  csvPath: string;        // Path to Amex CSV file
  outputFormat?: string;  // "excel" | "json" | "csv" | "summary"
  outputPath?: string;    // Where to save results
  options?: {
    includeCharts?: boolean;
    minAmount?: number;
    dateRange?: {
      start: string;
      end: string;
    };
  }
}

Example:

{
  "csvPath": "data/amex-2024.csv",
  "outputFormat": "excel",
  "outputPath": "output/analysis.xlsx",
  "options": {
    "includeCharts": true,
    "minAmount": 10
  }
}

find_subscriptions

Identifies recurring charges and subscriptions.

Parameters:

{
  csvPath: string;
  confidenceThreshold?: number;  // 0-1, default 0.7
  includeManual?: boolean;       // Include manual review items
}

analyze_vendor

Deep analysis of specific vendor transactions.

Parameters:

{
  csvPath: string;
  vendorName: string;
  fuzzyMatch?: boolean;  // Allow partial matches
  includeRelated?: boolean;  // Include payment processor variants
}

find_anomalies

Detects fraud and unusual patterns.

Parameters:

{
  csvPath: string;
  severityThreshold?: "low" | "medium" | "high";
  includePatterns?: boolean;  // Show pattern details
}

spending_by_category

Category-based spending breakdown.

Parameters:

{
  csvPath: string;
  customCategories?: Record<string, string[]>;  // Custom rules
  sortBy?: "amount" | "count" | "name";
}

export_analysis

Export analysis in various formats.

Parameters:

{
  csvPath: string;
  format: "excel" | "csv" | "json";
  outputPath: string;
  options?: {
    includeRaw?: boolean;
    includeMetadata?: boolean;
    compress?: boolean;
  }
}

Direct API Usage

import { AmexSpendingAnalyzer } from './amex-mcp-server.js';

const analyzer = new AmexSpendingAnalyzer();

// Parse CSV
await analyzer.parseAmexCsv('data/amex.csv');

// Run analysis
const results = analyzer.analyze();

// Access specific data
const subscriptions = results.recurringCharges;
const fraudulent = results.anomalies.filter(a => a.severity === 'high');

// Export
await analyzer.exportToExcel(results, 'output/report.xlsx');

Data Structures

Core Interfaces

interface AmexTransaction {
  date: Date;
  description: string;
  amount: number;
  extendedDetails?: string;
  appearsOnStatementAs?: string;
  address?: string;
  city?: string;
  state?: string;
  zipCode?: string;
  country?: string;
  reference?: string;
  category?: string;
  cardMember?: string;
}

interface VendorProfile {
  name: string;
  normalizedName: string;
  displayName: string;
  totalSpent: number;
  transactionCount: number;
  firstSeen: Date;
  lastSeen: Date;
  averageAmount: number;
  minAmount: number;
  maxAmount: number;
  isRecurring: boolean;
  recurringPattern?: RecurringPattern;
  category: string;
  transactions: AmexTransaction[];
  metadata: VendorMetadata;
}

interface VendorMetadata {
  isSubscription: boolean;
  isFraudulent: boolean;
  anomalyScore: number;
  tags: string[];
  isObscured: boolean;
  originalDescription?: string;
  processor?: string;
  unmaskingConfidence?: number;
  needsManualReview?: boolean;
  possibleVendors?: string[];
}

Analysis Results

interface SpendingAnalysis {
  scanDate: Date;
  dateRange: { start: Date; end: Date };
  totalSpent: number;
  vendorCount: number;
  transactionCount: number;
  subscriptionCount: number;
  subscriptionTotal: number;
  topVendors: VendorProfile[];
  categoryBreakdown: CategoryStats;
  recurringCharges: VendorProfile[];
  anomalies: Anomaly[];
  duplicateCharges: DuplicateCharge[];
  insights: Insight[];
  unmaskingReport?: UnmaskingReport;
}

Algorithms & Logic

Vendor Normalization

function normalizeVendorName(name: string): string {
  // Remove special characters
  let normalized = name.toLowerCase()
    .replace(/[^\w\s]/g, ' ')
    .replace(/\s+/g, ' ')
    .trim();
  
  // Remove common suffixes
  const suffixes = ['inc', 'llc', 'ltd', 'corp', 'company'];
  for (const suffix of suffixes) {
    normalized = normalized.replace(new RegExp(`\\s+${suffix}$`), '');
  }
  
  // Apply company mappings
  return companyNormalization[normalized] || normalized;
}

Subscription Detection

function detectSubscription(vendor: VendorProfile): boolean {
  // Check keywords
  const hasKeyword = subscriptionKeywords.some(keyword => 
    vendor.normalizedName.includes(keyword)
  );
  
  // Check pattern
  if (vendor.recurringPattern) {
    const { confidence, frequency } = vendor.recurringPattern;
    const isRegular = ['monthly', 'annual', 'quarterly'].includes(frequency);
    return confidence > 0.7 && isRegular;
  }
  
  return hasKeyword && vendor.transactionCount >= 2;
}

Fraud Scoring

function calculateFraudScore(vendor: VendorProfile): number {
  let score = 0;
  
  // Amount patterns
  if (suspiciousAmounts.includes(vendor.averageAmount)) {
    score += 30;
  }
  
  // Vendor name patterns
  if (blacklistedKeywords.some(kw => vendor.name.includes(kw))) {
    score += 40;
  }
  
  // Behavioral analysis
  if (vendor.transactions.length === 1 && vendor.totalSpent > 500) {
    score += 20;
  }
  
  return Math.min(score, 100);
}

Performance & Optimization

Memory Management

• Streaming CSV Parser: Handles files up to 1GB
• Batch Processing: Processes transactions in chunks
• Lazy Loading: Loads analysis components on demand
• Efficient Data Structures: Uses Maps for O(1) lookups

Performance Metrics

Operation	1K Trans	10K Trans	100K Trans
CSV Parse	0.1s	0.8s	7.2s
Analysis	0.05s	0.4s	3.8s
Excel Export	0.2s	1.2s	11.5s
Memory Usage	15MB	85MB	750MB

Optimization Tips

1. Use Date Ranges: Filter large datasets
2. Batch Exports: Process multiple months separately
3. Custom Categories: Reduce inference overhead
4. Disable Charts: For faster Excel generation

Security & Privacy

Data Protection

1. 100% Local Processing: No network calls
2. No Data Persistence: RAM only during analysis
3. No Telemetry: Zero tracking or analytics
4. Secure File Handling: Proper permissions

Best Practices

1. CSV Storage: Encrypt sensitive files
2. Output Protection: Secure export directories
3. Access Control: Limit MCP permissions
4. Regular Cleanup: Delete old analyses

Compliance

• PCI DSS: No card number processing
• GDPR: No personal data retention
• SOC 2: Secure development practices

Troubleshooting

Common Issues

1. CSV Parse Errors

Symptom: "Invalid CSV format"

Solutions:

• Verify Amex export format
• Check for special characters
• Ensure UTF-8 encoding
• Remove manual edits

2. Vendor Unmasking Issues

Symptom: Too many "Unknown Vendor"

Solutions:

• Update to latest version
• Check extended details in CSV
• Add custom processor patterns
• Report new processors

3. Memory Errors

Symptom: "Out of memory"

Solutions:

• Process smaller date ranges
• Increase Node.js memory limit
• Disable chart generation
• Use streaming mode

4. MCP Connection Failed

Symptom: Claude doesn't recognize commands

Solutions:

• Verify config path
• Check file permissions
• Restart Claude Desktop
• Review server logs

Debug Mode

Enable detailed logging:

export AMEX_DEBUG=true
npm run dev

Log Analysis

# View MCP communication
tail -f ~/.claude/logs/mcp.log

# Check server errors
node dist/amex-mcp-server.js --debug

Contributing

Development Setup

# Fork and clone
git clone https://github.com/ogprotege/amex-anaylsis-mcp.git
cd amex-analysis-mcp

# Install dev dependencies
npm install

# Run in watch mode
npm run dev

Code Style

• TypeScript strict mode
• ESLint configuration
• Prettier formatting
• Comprehensive JSDoc

Testing

# Run all tests
npm test

# Run specific test
npm run test-unmasking

# Coverage report
npm run coverage

Pull Request Guidelines

1. Fork the repository
2. Create feature branch
3. Add comprehensive tests
4. Update documentation
5. Submit PR with details

License

MIT License - See LICENSE file for details

---

Quick Links

• Cheatsheet - Quick command reference
• Changelog - Version history
• Examples - Sample analyses
• Support - Report issues

Acknowledgments

Built on the foundation of subscripz-buster, adapted for comprehensive credit card analysis. Special thanks to the MCP team for enabling natural language financial analysis.