# Luca Assistant (撸卡助手)

## For users: Use the MCP tools directly

When answering credit card questions, **call the luca MCP tools directly**. Do NOT read source code or explore the codebase — the tools handle everything.

### Card queries
- `luca_query_card_details(card_name, bank?)` — look up a card's benefits, offers, fees
- `luca_find_highest_offers(bank?, min_bonus_usd?, is_business?, limit?)` — best current sign-up bonuses
- `luca_compare_card_benefits(card_names)` — side-by-side comparison

### Card enrichment
- `luca_update_card_benefit(card_name, category, multiplier, points_type, ...)` — add/update a card's category multiplier or credit after finding it via web search
- When `luca_query_card_details` returns a `multiplier_hint`, use **web search** targeting `site:doctorofcredit.com OR site:thepointsguy.com` to find the data, then call `luca_update_card_benefit` to persist it

### Bank rules
- `luca_get_bank_rules(bank)` — application rules (5/24, lifetime language, 8/65, etc.)

### Portfolio
- `luca_get_user_portfolio()` — user's open/closed cards
- `luca_check_chase_524_status()` — 5/24 count and slots remaining
- `luca_add_user_card(card_name, opened_date, bank?, ...)` — add a card
- `luca_close_user_card(card_name, closed_date, bank?)` — mark a card closed

### Data import
- `luca_import_cards(source?, force?)` — import from 'offer-optimist' (cards + SUBs) or 'cfpb' (APRs + fees)

### Important
- For **USCardForum**, use the external `uscardforum` MCP server tools (discourse_search, discourse_list_hot_topics, discourse_read_topic, etc.)
- For news/updates from DoC or TPG, use your own **web browsing** — Luca does not scrape these sites
- **Just call the tools.** Do not read source files, explore the codebase, or run Python scripts. The MCP tools are the interface.
- If a card isn't in the database, tell the user — don't try to modify seed data or run scripts.
- All card data comes from the database, never fabricated.
- Respond in the user's language (Chinese/English).
- If you need to run CLI commands, always use `uv run` (e.g., `uv run luca cards`), never bare `python3`.

---

## For developers: project internals

### Tech Stack
- Python 3.12, uv + hatchling, SQLite + SQLAlchemy
- httpx for data imports, Typer CLI, Rich console, MCP server (FastMCP)
- No built-in agent — Luca is a pure tool server consumed by external agents (NanoClaw, OpenClaw, Claude Code, etc.)

### Data Sources
- **Offer Optimist YAML** — primary source for ~150+ cards, SUBs, credits (auto-downloaded on first seed)
- **CFPB TCCP Survey** — government data: APRs, FX fees, late fees, grace period, secured flag
- **Curated seed** — category multipliers for core cards + bank rules (no public structured source)
- **Agent web search** — fills multiplier gaps by directing agents to DoC/TPG

### Commands
- `make dev` / `make test` / `make lint` / `make format`
- `luca cards [--bank X]`
- `luca import [--source offer-optimist|cfpb] [--force] [--status]`

### Code Style
- ruff, 100-char line length, frozen dataclasses, type hints everywhere
