Destiny MCP

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

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

快速开始

# 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 中打开此项目即可使用。

仓库结构

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 忽略）

完整说明见 仓库布局。

导入武器选取率 JSON

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

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

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

检查环境

uv run python scripts/doctor.py

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

手动配置

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

1. Bungie API 凭证

前往 Bungie 开发者门户 创建应用：

• Redirect URL: https://localhost:8765/callback
• Origin Header: *
• Scope: 勾选 Read/Move/Equip

2. 环境变量

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

3. OAuth 授权

uv run python scripts/oauth_setup.py

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

4. MCP 配置

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

其他客户端参考 安装指南。

可用工具

默认 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 个工具用于旧客户端兼容和调试。完整路由与确认规则见 工具文档。

常见问题

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

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

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

开发

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

架构文档见 docs/。