# Destiny MCP

通过 AI 管理你的 Destiny 2 装备、武器和配装。

支持 Claude Code、Claude Desktop、Cursor 等任何 MCP 客户端。

## 快速开始

```bash
# 1. 克隆项目
git clone <repo> && cd Destiny_MCP

# 2. 安装依赖 (需要 uv)
uv sync

# 3. 一键配置 (引导你完成所有设置)
uv run python scripts/setup.py
```

`setup.py` 会交互式引导你完成：
- 填入 Bungie API 凭证
- 完成 OAuth 授权
- 下载游戏数据库

完成后，在 Claude Code 中打开此项目即可使用。

## 仓库结构

```text
src/destiny_mcp/   MCP 后端和业务服务
webui/             当前生产 React 前端和静态宿主
webui_new/         Hermes 兼容 API 后端和 legacy 回滚界面
tests/             MCP/服务聚焦测试
prompts/           模型系统提示和截图提取提示
scripts/           安装、检查、数据导入和运维脚本
deploy/            Docker/Nginx 检查与部署文件
docs/              架构、运维、产品和参考文档
archive/           不参与生产构建的历史原型/发布快照
data/              本地 OAuth/会话运行数据（禁止删除，Git 忽略）
manifest/          可重新下载的 Bungie Manifest（Git 忽略）
```

完整说明见 [仓库布局](docs/repository-layout.md)。

## 导入武器选取率 JSON

将多模态模型输出保存为 JSON，然后运行：

```bash
uv run python scripts/import_weapon_popularity.py /path/to/weapon.json
```

导入器会严格校验结构、拒绝默认覆盖同名武器，在 `data/backups/weapon-popularity/` 保留备份后原子更新内置数据。明确替换旧快照时使用 `--replace`。截图提取规则见 [多模态提示词](prompts/weapon_popularity_image_extraction.md)。

## 检查环境

```bash
uv run python scripts/doctor.py
```

检查所有配置是否就绪，包括 API 连通性测试。

## 手动配置

如果一键脚本不适用，按以下步骤手动操作：

### 1. Bungie API 凭证

前往 [Bungie 开发者门户](https://www.bungie.net/en/Application) 创建应用：
- Redirect URL: `https://localhost:8765/callback`
- Origin Header: `*`
- Scope: 勾选 Read/Move/Equip

### 2. 环境变量

```bash
cp .env.example .env
# 编辑 .env 填入凭证
```

### 3. OAuth 授权

```bash
uv run python scripts/oauth_setup.py
```

浏览器会打开 Bungie 授权页面，授权后 token 自动保存到 `~/.destiny_mcp/tokens.json`。

### 4. MCP 配置

项目根目录的 `.mcp.json` 已为 Claude Code 配置好。

其他客户端参考 [安装指南](docs/installation.md)。

## 可用工具

默认 `DESTINY_MCP_TOOL_PROFILE=normal`，只向模型暴露 8 个稳定的聚合入口：

| 工具 | 覆盖能力 |
|------|----------|
| `player_assistant` | 玩家搜索、角色档案 |
| `inventory_assistant` | 背包、转移、批量装备、邮政官、锁定、任务追踪 |
| `weapon_assistant` | 武器分析、同名对比、perk 池、选取率、条件筛选 |
| `build_assistant` | 护甲配装推荐、诊断、确认后装备 |
| `loadout_assistant` | 本地配装和 Bungie 官方配装槽 |
| `subclass_assistant` | 子职业、碎片、神器 |
| `activity_assistant` | 活动历史、PGCR、武器统计、排行榜 |
| `world_assistant` | 周常、商人、收藏品状态 |

`expert` 会增加常用只读工具，`full` 会暴露全部 76 个工具用于旧客户端兼容和调试。完整路由与确认规则见 [工具文档](prompts/system_prompt.md)。

## 常见问题

**浏览器提示「连接不安全」？**
OAuth 回调用自签名证书，点「高级 → 继续前往」即可，仅本机使用无安全风险。

**Token 过期了？**
不会。`tokens.json` 含 refresh_token，启动时自动刷新。如改了 Bungie 密码需重新跑 OAuth。

**首次启动很慢？**
首次会自动下载 Manifest (~50MB)，之后会缓存。

## 开发

```bash
uv run pytest tests/ -v          # 运行测试
uv run ruff check src/ tests/    # 代码检查
uv run ruff format src/ tests/   # 格式化
```

架构文档见 [docs/](docs/)。