# 星穹铁道抽卡记录 MCP

用 Python + FastMCP 读取《崩坏：星穹铁道》账号跃迁（抽卡）记录，供 Cursor Agent 同步、查询与统计。

## 它做什么

1. 保存抽卡 API 链接（含临时 `authkey`），或从本机游戏 `webCaches` 自动提取  
2. 调用官方 `getGachaLog` 分页拉取记录到本地 `data/`  
3. 在 Cursor 里用 tools 查记录、看垫数 / 五星

**不会**索要账号密码；`authkey` 大约 24 小时过期，过期后需重新进游戏打开跃迁记录。

## 环境准备

```powershell
cd E:\code\mcpTraining
py -3.10 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn
```

## 在 Cursor 中接入

见 [docs/cursor-setup.md](docs/cursor-setup.md)。  
如何获取抽卡链接见 [docs/get-gacha-url.md](docs/get-gacha-url.md)。

推荐 MCP 配置：

```json
{
  "mcpServers": {
    "starrail-gacha": {
      "command": "E:/code/mcpTraining/.venv/Scripts/python.exe",
      "args": ["-m", "starrail_gacha_mcp.server"]
    }
  }
}
```

## 典型用法（对 Agent 说）

1. 「用游戏缓存检测崩铁抽卡链接」→ `detect_gacha_url_from_game_cache`  
2. 「同步抽卡记录」→ `sync_gacha_logs`  
3. 「角色池现在垫了多少、最近五星是谁」→ `gacha_stats` / `list_gacha_logs`

## 本地网页看板

同步记录后，可启动本地网页查看统计（分池垫数、品阶分布、五星历程）：

```powershell
.\.venv\Scripts\Activate.ps1
starrail-gacha-web
# 或: python -m starrail_gacha_mcp.webapp
```

浏览器会打开 `http://127.0.0.1:8765/`。加 `--no-open` 可只启动服务；`--port 9000` 可改端口。

在 Cursor 里也可直接让 Agent 调用 `open_gacha_dashboard`（会自动开浏览器）。

### 边改边看（开发模式）

调 `web/` 排版时用开发模式：保存文件后浏览器自动刷新。

```powershell
starrail-gacha-web --dev
# 或让 Agent: open_gacha_dashboard(dev=True)
```

停止后台看板：`starrail-gacha-web --stop` 或 MCP `stop_gacha_dashboard`。

## 项目结构

```
src/starrail_gacha_mcp/
  server.py      # MCP 入口与 tools
  webapp.py      # 本地网页服务
  auth.py        # URL 解析 / 游戏缓存扫描
  client.py      # 官方 API 分页
  store.py       # 本地 JSON
  stats.py       # 统计与垫数
web/             # 看板静态页（HTML/CSS/JS）
data/            # auth.json、gacha_logs.json（已 gitignore）
```

## 卡池类型

| ID | 名称 |
|----|------|
| 1 | 常驻跃迁 |
| 2 | 新手跃迁 |
| 11 | 角色活动跃迁 |
| 12 | 光锥活动跃迁 |

## 说明

- 官方接口通常只保留约近半年记录，不是无限全历史。  
- Windows 下自动检测最省事；其它系统可用 `set_gacha_url` 粘贴链接。  
- 本项目仅供学习与个人查询，请遵守游戏与平台服务条款。