# CheckMCC - LLM Documentation

> https://check-mcc.sg

CheckMCC is a Singapore-based web application that helps users maximize credit card rewards by providing accurate Merchant Category Code (MCC) information for stores, restaurants, and businesses worldwide.

## Purpose

CheckMCC helps Singapore credit card holders:
- Find MCC codes for any merchant/store
- Determine which credit cards earn bonus rewards at specific merchants
- Optimize credit card usage for maximum rewards/miles
- Understand which MCC codes are eligible for different card rewards programs

## Key Features

### MCC Search Engine
- Search merchants by name, category, or MCC code
- Interactive grid displaying merchants with MCC classifications
- Real-time filtering and sorting

### Credit Card Rewards Optimization
Shows which cards give best rewards for each merchant:
- PPV (UOB Preferred Platinum Visa)
- CRMC (Citibank Rewards MasterCard)
- HSBC Revolution
- UOB Visa Signature
- WWMC (World MasterCard)
- OCBC Rewards
- VS (Visa Signature)

### AI-Powered Chat
- conversational MCC lookup and card advice
- Uses OpenRouter + Vercel AI SDK
- Sentiment analysis on responses

### AI-Powered Text Extraction
- Extract merchant information from unstructured text
- Uses OpenRouter + Gemini AI models
- Automatic MCC code detection

### Expense Tracking
- Log and manage expenses with MCC classification
- Track spending patterns by category
- Supabase-backed storage

### Coupon Codes
- Browse coupons by shopping category
- Stack coupons with credit card rewards
- Category-based browsing (shopping, dining, travel, etc.)

### Browser Extension API
- REST API for domain-based MCC lookup
- Used by browser extension for real-time merchant detection
- Endpoint: `/api/store-by-domain?domain=example.com`

## Technical Architecture

### Tech Stack
- **Frontend**: Next.js 14, React 18, TypeScript, Tailwind CSS
- **Backend**: Next.js API Routes, Node.js
- **Database**: MongoDB (primary), Supabase (auth/expenses), Redis (caching)
- **AI/ML**: OpenRouter, Vercel AI SDK, Anthropic Claude, LangChain
- **Auth**: Supabase Auth (email, Google, magic link)
- **Security**: Cloudflare Turnstile, Sentry monitoring

### Key Pages
- `/` - Main merchant grid search
- `/mcc` - Detailed MCC lookup table with card eligibility
- `/mcc-code/[code]` - Individual MCC code pages (e.g. `/mcc-code/5812`)
- `/mcc-code/[code]/cards` - Cards for a specific MCC code
- `/mcc/singapore` - Singapore MCC guide
- `/mcc/singapore-vs-global` - SG vs global MCC comparison
- `/mcc/shopee` - Shopee MCC page
- `/mcc/lazada-sg` - Lazada MCC page
- `/mcc/airbnb` - Airbnb MCC page
- `/category/[slug]` - Category pages (dining, travel, shopping, etc.)
- `/coupon` - Coupon code categories
- `/coupon/[slug]` - Individual coupon category pages
- `/chat` - AI chat for MCC queries
- `/guide/what-is-mcc` - What is MCC guide
- `/guide/how-mcc-works-with-credit-cards` - MCC & credit cards guide
- `/guide/maximizing-rewards-with-mcc` - Rewards maximization guide
- `/qa/best-card-for-airline-miles` - Best cards for airline miles
- `/qa/best-cards-food-dining` - Best cards for food & dining
- `/faq` - Frequently asked questions
- `/changelog` - Version history
- `/jobs` - Job listings
- `/support` - Support page
- `/profile` - User profile (card preferences)
- `/openclaw` - OpenClaw integration landing page (API docs for AI agents)
- `/login` - Login page
- `/admin` - Administrative dashboard

### MCC Data Structure

#### Whitelisted MCCs (`src/app/mcc/whitelistedMCCs.ts`)
- INCLUDED_PPV_MCC_CODES (54 codes) - Online shopping, dining, travel
- INCLUDED_CRMC_MCC_CODES (11 codes) - Groceries, shopping
- INCLUDED_HSBC_REVO_MCC_CODES (extensive) - Travel, department stores, dining
- INCLUDED_OCBC_REWARDS_MCC_CODES (13 codes) - Shopping, dining

#### Blacklisted MCCs (`src/app/mcc/blacklistedMCCs.ts`)
- EXCLUDED_WWMC_MCC_CODES (46 codes)
- EXCLUDED_PPV_MCC_CODES (43 codes)
- EXCLUDED_CRMC_MCC_CODES (extensive list)
- EXCLUDED_VS_MCC_CODES (43 codes)

## Common MCC Codes

Popular 4-digit MCC codes:
- `5812` - Restaurants, Eating Places
- `5814` - Fast Food Restaurants
- `5411` - Grocery Stores, Supermarkets
- `5399` - Miscellaneous General Merchandise
- `5732` - Electronics Stores
- `5310` - Department Stores
- `5311` - Variety Stores
- `3000-3299` - Airlines (Travel)
- `4121` - Taxicabs/Limousines
- `4784` - Toll and Bridge Fees
- `5541` - Service Stations (with gas)
- `5542` - Automated Fuel Dispensers

## API Endpoints

> **Machine-readable manifest:** [/docs/api-manifest.json](https://www.check-mcc.sg/docs/api-manifest.json) — structured JSON with all endpoint metadata, params, and examples for agent consumption.

### Credit Card Details
```
GET /api/cards
```

Returns all credit card details:
```json
{
  "success": true,
  "data": [
    {
      "name": "HSBC Revolution",
      "shortName": "HSBC_REVO",
      "mpd": "4 MPD",
      "spendCap": "Cap at $1,500 a month",
      "specialConditions": null
    }
  ]
}
```

### Store-by-Domain Lookup
```
GET /api/store-by-domain?domain=example.com
```

Returns merchant data with MCC code and card eligibility:
```json
{
  "id": "merchant_id",
  "Store": "Merchant Name",
  "MCC": "1234",
  "Country": "SG",
  "Category": "Category Name",
  "cards": ["PPV", "CRMC"],
  "type": "online",
  "url": "https://example.com",
  "eligibleCards": [
    {
      "key": "PPV",
      "name": "Preferred Platinum Visa",
      "shortName": "PPV",
      "eligible": true
    }
  ]
}
```

### Chat API
```
POST /api/chat
```

Conversational AI endpoint for MCC queries and card recommendations.

### Extract Merchant Text
```
POST /api/extract-merchant-text
```

Extracts merchant information from unstructured text using AI.

### Extract Expense
```
POST /api/extract-expense
```

AI-powered expense extraction from text/receipts.

### User Expenses
```
GET /api/user/expenses
POST /api/user/expenses
DELETE /api/user/expenses/[id]
```

CRUD operations for user expense tracking.

### Auth Endpoints
- `POST /api/auth/sign-in` - Sign in (Supabase)
- `POST /api/auth/sign-up` - Register
- `POST /api/auth/sign-out` - Sign out
- `GET /api/auth/callback` - OAuth callback

### User Card Preferences
- `GET /api/user/cards` - Get user's disabled cards
- `POST /api/user/cards/update` - Update card preferences

### Admin APIs
- `/api/admin/stores` - Store CRUD operations
- `/api/admin/stores/[id]` - Individual store management
- `/api/store/search` - Store search
- `/api/merchants/search` - Merchant search
- `/api/mcc/codes` - MCC code listing
- `/api/mcc/blacklist` - Blacklisted MCCs
- `/api/mcc/whitelist` - Whitelisted MCCs

## Rewards Programs

### Key Cards for General Spending

1. **UOB Visa Signature** - Best Overall
   - 4 MPD (10X UNI$) on wide variety of categories
   - Capped at $1,200, min spend $1,000
   - Requires mobile wallet or PayWave

2. **PPV (UOB Preferred Platinum Visa)** - Best for Online
   - 4 MPD (10X UNI$) on online shopping, dining, travel
   - Amount rounded down to nearest $5
   - No minimum spend requirement

3. **CRMC (Citibank Rewards MasterCard)** - Best for Groceries
   - 10X on groceries and specific categories
   - Specific MCC exclusions apply

## Deployment

- **Production URL**: https://check-mcc.sg
- **Platform**: Coolify (Docker on VPS)
- **Database**: MongoDB, Supabase
- **Monitoring**: Sentry
- **Analytics**: Google Analytics, PostHog, Hotjar

## Browser Extension Integration

The CheckMCC browser extension uses the store-by-domain API to:
1. Detect current website's domain
2. Fetch MCC code and card eligibility
3. Display eligible credit cards with visual indicators
4. Cache results for 5 minutes

Repository: https://github.com/gibtang/check-mcc-browser-extension

## OpenClaw Integration

CheckMCC is available as an OpenClaw skill for AI agents. This lets any OpenClaw-compatible agent look up MCC codes, search merchants, and get credit card recommendations.

### Install

```bash
openclaw skill install check-mcc
```

### Commands

- `scripts/check-mcc.sh lookup <domain>` — Look up a store by website domain (returns MCC, category, country, eligible cards)
- `scripts/check-mcc.sh search <query>` — Search stores by name
- `scripts/check-mcc.sh mcc <code_or_keyword>` — Look up MCC code by number or keyword
- `scripts/check-mcc.sh cards <mcc_code>` — Get eligible Singapore credit cards for an MCC code

### Direct API (for agents)

| Endpoint | Description |
|----------|-------------|
| `GET /api/store-by-domain?domain=X` | Lookup by domain (includes eligibleCards) |
| `GET /api/store/search?q=X` | Search stores by name |
| `GET /api/mcc` | All ~300 MCC codes |
| `GET /api/mcc/codes` | MCC code list only |

### Example Response (domain lookup)

```json
{
  "Store": "NTUC FairPrice Online",
  "MCC": "5411",
  "Category": "Grocery Stores, Supermarkets",
  "Country": "Singapore",
  "eligibleCards": [
    { "name": "UOB Preferred Platinum Visa", "eligible": true, "mpd": "4 MPD", "spendCap": "Cap at $1,000 a month" },
    { "name": "DBS Woman's Card", "eligible": false, "reason": "Not in whitelist" }
  ]
}
```

- Landing page: https://check-mcc.sg/openclaw
- No API key required — uses public endpoints
- Card eligibility is Singapore-specific (MPD = miles per dollar)

## Related Resources

- MCC Reference: https://check-mcc.sg/mcc
- Singapore MCC Guide: https://check-mcc.sg/mcc/singapore
- Best Cards Guide: https://check-mcc.sg/qa/best-card-for-airline-miles
- What is MCC: https://check-mcc.sg/guide/what-is-mcc
- Browser Extension: https://github.com/gibtang/check-mcc-browser-extension
- OpenClaw Integration: https://check-mcc.sg/openclaw

---

Last Updated: April 2026

This file helps AI assistants and LLMs understand the CheckMCC application structure, features, and API endpoints for better user assistance.