# Luca 撸卡助手

[English](README.md)

美国信用卡优化工具层，专为 AI 编程代理设计。Luca 提供信用卡数据库、开卡奖励、银行规则和社区数据点，通过 MCP 工具暴露给任何代理调用。

Luca 是一个**融合层**，不是独立的 Agent。你的代理（Claude Code、OpenClaw、OpenCode、Codex）负责 LLM 和对话，Luca 负责数据。

## 安装

### 作为 Claude Code 插件

```bash
# 添加市场
/plugin marketplace add troyt-666/luca-assistant

# 安装插件
/plugin install luca-assistant@luca-marketplace
```

安装后你将获得 11 个 MCP 工具 + 5 个斜杠命令。

### 作为 MCP 服务器

```bash
# 从 PyPI 安装（可用时）
claude mcp add --transport stdio luca-assistant -- uvx --from luca-assistant luca-mcp

# 从源码安装
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
```

### 斜杠命令（插件模式）

| 命令 | 说明 |
|------|------|
| `/luca-assistant:card-lookup` | 查询卡片详情和当前奖励 |
| `/luca-assistant:compare-cards` | 卡片对比 |
| `/luca-assistant:portfolio` | 查看持卡组合 + 5/24 状态 |
| `/luca-assistant:bank-rules` | 银行申请规则 |
| `/luca-assistant:scrape` | 抓取社区最新数据 |

### MCP 工具（11 个）

| 工具 | 说明 |
|------|------|
| `luca_query_card_details` | 查询卡片福利、奖励和年费 |
| `luca_find_highest_offers` | 查找当前最高开卡奖励 |
| `luca_compare_card_benefits` | 多卡对比 |
| `luca_get_bank_rules` | 银行申请规则（5/24、lifetime language 等） |
| `luca_get_user_portfolio` | 查看持卡组合 |
| `luca_check_chase_524_status` | 计算 5/24 剩余名额 |
| `luca_add_user_card` | 添加卡片到组合 |
| `luca_close_user_card` | 标记关卡 |
| `luca_scrape_source` | 从指定来源抓取新内容（doc、reddit、forum） |
| `luca_search_scraped` | 搜索已抓取内容 |
| `luca_get_scrape_status` | 查看各来源最后抓取时间 |

## 数据库内容

- **30+ 张热门美卡** — Chase、Amex、Citi、Capital One、Bilt、US Bank、Wells Fargo
- **当前开卡奖励** 含估值和消费要求
- **消费类别倍率和年度返现** （餐饮、旅行、超市等）
- **银行申请规则** — Chase 5/24、Amex lifetime language、Citi 8/65、2/90、One Sapphire 等
- **社区数据** 来自 Doctor of Credit、Reddit r/CreditCards、r/churning、美卡论坛

## 命令行

```bash
luca cards                          # 列出所有卡片
luca cards --bank Chase             # 按银行筛选
luca scrape                         # 抓取所有来源
luca scrape --source doc            # 只抓取 Doctor of Credit
luca scrape --dry-run               # 预览会抓取什么
luca schedule enable --interval 6   # 设置定时任务（每6小时）
luca schedule status                # 查看定时任务状态
luca chat                           # 交互式对话（测试用，需要 LLM 密钥）
```

## 开发

```bash
git clone https://github.com/troyt-666/luca-assistant
cd luca-assistant
make dev          # 安装开发依赖
make test         # 运行 67 个测试
make lint         # Ruff 代码检查
make format       # Ruff 自动格式化
```

## 许可证

MIT
