luca-assistant（卢卡助理）

Luca Assistant (撸卡助手)

A credit card rewards optimization tool. Query 150+ US credit cards, compare benefits, track your portfolio, and find the best sign-up bonuses.

When to use this skill

Trigger this skill when the user asks about:

• Credit card recommendations or comparisons
• Sign-up bonuses (SUBs) or welcome offers
• Chase 5/24 status or bank application rules
• Adding/removing cards in their portfolio
• Card benefits, category multipliers, or annual credits

Setup

Check if already installed

Before running setup, check whether Luca is already available:

export PATH="$HOME/.local/bin:$PATH"
command -v luca-mcp && luca-mcp --help

If luca-mcp responds, skip to How to use. Otherwise run setup below.

First-run setup

export PATH="$HOME/.local/bin:$PATH"
bash {baseDir}/scripts/setup.sh

This installs luca-assistant from PyPI via uv and seeds the database (~150 cards from Offer Optimist).

PATH note: uv tool install places binaries in ~/.local/bin. If luca-mcp is not found after setup, ensure ~/.local/bin is on PATH (export PATH="$HOME/.local/bin:$PATH").

Verify setup

luca-mcp --help        # should print MCP server usage
luca cards | head -5   # should list cards from the database

How to use

Luca is an MCP tool server. The database lives at ~/.local/share/luca/luca.db.

If Luca is already configured as an MCP server in the agent's environment, call luca_* tools directly. Otherwise, call tools via the bundled script:

export PATH="$HOME/.local/bin:$PATH"
bash {baseDir}/scripts/mcp_call.sh <tool_name> '<json_args>'

Available MCP tools

Card queries:

• luca_query_card_details(card_name, bank?) — look up a card's benefits, current offers, and 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 benefit comparison
• luca_get_bank_rules(bank) — issuer application rules (Chase 5/24, Amex lifetime language, Citi 8/65, etc.)

Card enrichment:

• luca_update_card_benefit(card_name, category, multiplier, points_type, notes?, bank?, annual_credit?, credit_category?) — add or update a card's category multiplier or credit
• luca_import_cards(source?, force?) — refresh data from 'offer-optimist' (cards + SUBs) or 'cfpb' (APRs + fees)

Portfolio tracking:

• luca_get_user_portfolio() — user's open and closed cards
• luca_check_chase_524_status() — 5/24 count and remaining slots
• luca_add_user_card(card_name, opened_date, bank?, credit_limit?, bonus_earned?, bonus_met_date?, notes?) — add a card to portfolio
• luca_close_user_card(card_name, closed_date, bank?) — mark a card as closed

Examples

# Look up Chase Sapphire Preferred
bash {baseDir}/scripts/mcp_call.sh luca_query_card_details '{"card_name":"Chase Sapphire Preferred"}'

# Find top 5 offers worth at least $500
bash {baseDir}/scripts/mcp_call.sh luca_find_highest_offers '{"min_bonus_usd":500,"limit":5}'

# Compare two cards
bash {baseDir}/scripts/mcp_call.sh luca_compare_card_benefits '{"card_names":["Amex Gold","Chase Sapphire Preferred"]}'

# Check Chase 5/24 status
bash {baseDir}/scripts/mcp_call.sh luca_check_chase_524_status '{}'

Enrichment workflow

When luca_query_card_details returns a multiplier_hint, the card has missing category multiplier data. To fill the gap:

1. Web search for the card on site:doctorofcredit.com OR site:thepointsguy.com
2. Find the earning rates (e.g., "3x on dining, 2x on travel")
3. Call luca_update_card_benefit for each category to persist the data

Optional: USCardForum integration

For community data points from USCardForum (美卡论坛), install the companion nitan skill. It provides discourse_search, discourse_read_topic, discourse_list_hot_topics, and more.

Guidelines

• All card data comes from the database — never fabricate card details
• If a card isn't found, tell the user rather than guessing
• Respond in the user's language (Chinese or English)
• Use luca_import_cards to refresh data if it seems stale