# Luca Assistant (撸卡助手)

[中文文档](README_zh.md)

A credit card optimization tool layer for AI coding agents. Luca provides a database of US credit cards, sign-up bonuses, bank rules, and community data points — exposed as MCP tools that any agent can call.

Luca is a **fuse layer**, not a standalone agent. Your agent (Claude Code, OpenClaw, OpenCode, Codex) owns the LLM and conversation. Luca owns the data.

## Install

### As a Claude Code Plugin

```bash
# Add the marketplace
/plugin marketplace add troyt-666/luca-assistant

# Install
/plugin install luca-assistant@luca-marketplace
```

This gives you 11 MCP tools + 5 slash commands.

### As an MCP Server

```bash
# From PyPI (when available)
claude mcp add --transport stdio luca-assistant -- uvx --from luca-assistant luca-mcp

# From source
git clone https://github.com/troyt-666/luca-assistant
cd luca-assistant
uv sync
claude mcp add --transport stdio luca-assistant -- uv run luca-mcp
```

### Slash Commands (Plugin)

| Command | Description |
|---------|-------------|
| `/luca-assistant:card-lookup` | Look up a card's details and offers |
| `/luca-assistant:compare-cards` | Side-by-side card comparison |
| `/luca-assistant:portfolio` | Your portfolio + 5/24 status |
| `/luca-assistant:bank-rules` | Bank application rules |
| `/luca-assistant:scrape` | Fetch fresh community data |

### MCP Tools (11)

| Tool | Description |
|------|-------------|
| `luca_query_card_details` | Look up a card's benefits, offers, and fees |
| `luca_find_highest_offers` | Find the best current sign-up bonuses |
| `luca_compare_card_benefits` | Side-by-side card comparison |
| `luca_get_bank_rules` | Bank-specific application rules (5/24, lifetime language, etc.) |
| `luca_get_user_portfolio` | Your current card portfolio |
| `luca_check_chase_524_status` | Calculate 5/24 slots remaining |
| `luca_add_user_card` | Add a card to your portfolio |
| `luca_close_user_card` | Mark a card as closed |
| `luca_scrape_source` | Fetch fresh content from a source (doc, reddit, forum) |
| `luca_search_scraped` | Search previously scraped content |
| `luca_get_scrape_status` | Check when each source was last scraped |

## What's in the Database

- **30+ popular US credit cards** — Chase, Amex, Citi, Capital One, Bilt, US Bank, Wells Fargo
- **Current sign-up bonuses** with estimated USD values and spend requirements
- **Category multipliers and credits** (dining, travel, grocery, etc.)
- **Bank application rules** — Chase 5/24, Amex lifetime language, Citi 8/65, 2/90, one-Sapphire, and more
- **Scraped content** from Doctor of Credit, Reddit r/CreditCards, r/churning, and US Card Forum

## CLI

```bash
luca cards                          # List all cards in DB
luca cards --bank Chase             # Filter by bank
luca scrape                         # Scrape all sources
luca scrape --source doc            # Scrape Doctor of Credit only
luca scrape --dry-run               # Show what would be fetched
luca schedule enable --interval 6   # Set up cron job (every 6 hours)
luca schedule status                # Check cron status
luca chat                           # Interactive chat (test harness, needs LLM key)
```

## Development

```bash
git clone https://github.com/troyt-666/luca-assistant
cd luca-assistant
make dev          # Install with dev deps
make test         # Run 67 tests
make lint         # Ruff lint check
make format       # Ruff auto-format
```

## License

MIT
