mihoyo-mcp

Автономный MCP-сервер miHoYo — одновременно для Miyoushe (米游社, китайский сервер) и HoYoLAB (международный сервер), на базе horia/or/does not matter (MIT). Любой MCP-клиент (nahida-bot, Claude Desktop, Codex…) может использовать его напрямую.

Границы проектирования

MCP отвечает за «как говорить с миHoYo»; клиент — за «когда спрашивать и кому потом сообщить».

• Планирование (cron), пороговые стратегии, доставка сообщений → клиент (у nahida-bot уже есть Scheduler / Channel)

• Вход, хранение учётных данных, вызовы API, дедупликация оповещений → этот сервис

• Учётные данные никогда не покидают границы безопасности: Cookie всегда хранятся внутри сервиса (шифрование Fernet), в результатах инструментов присутствует только account_id, в контексте агента token не появляется.

                ┌─────────────────────┐
                │     nahida-bot      │
                │  Cron / Scheduler   │
                │       │             │
                │       ▼             │
                │  MCP Client ───────────────┐
                │       ▼             │     │ MCP (stdio)
                │  QQ Channel         │     ▼
                └─────────────────────┘ ┌──────────────────┐
                                       │    mihoyo-mcp     │
                                       │ QR login          │
                                       │ credential vault  │
                                       │ daily notes       │
                                       │ alert dedup state │
                                       └────────┬──────────┘
                                                │
                                         genshin.py
                                                │
                                     米游社 / HoYoLAB API

Related MCP server: Xiaohongshu MCP Server

Текущие возможности

Обзор инструментов

account_id можно опустить, если аккаунт только один.

О названиях: в черновике использовались имена с точками вроде mihoyo.auth.start_qr_login, но спецификация MCP (SEP-986) требует, чтобы имя инструмента совпадало с ^[a-zA-Z0-9_-]{1,64}$; точки приводят к тому, что некоторые клиенты отказываются загружать инструменты. Поэтому принято плоское snake_case с примеными префиксами auth_ / accounts_ / starrail_.

Почему check_alerts живёт в MCP

Проверка порога бодрости (217 >= 200 && recovery <= 1800) не должна расходовать токены LLM, а сообщение «экспедиция вернулась» при каждом опросе — неприемлемо. Состояние дедупликации оповещений (armed/re-arm) — часть состояния интеграции с Miyoushe и по определению относится к этому сервису. Клиентскому cron остаётся только:

starrail_check_alerts() → alerts == [] → 静默
                      → alerts != [] → 推送消息

Быстрый старт

uv sync                       # 安装依赖
uv run pytest                 # 运行测试
uv run python scripts/smoke_stdio.py   # stdio 握手冒烟测试
uv run mihoyo-mcp             # 启动 stdio server

Пример конфигурации клиента (Claude Desktop / любой клиент со stdio MCP):

{
  "mcpServers": {
    "mihoyo": {
      "command": "uv",
      "args": ["run", "--directory", "D:/Projects/mihoyo-mcp", "mihoyo-mcp"]
    }
  }
}

Конфигурация (переменные окружения)

Содержимое каталога данных:

~/.mihoyo-mcp/
├── accounts.json     # 公开账号元数据（无秘密）
├── credentials.enc   # Fernet 加密的 Cookie/token 库
├── alert_state.json  # 告警去重状态
└── fernet.key        # 未设置环境变量时自动生成的 key（带告警日志）

Структура каталога

src/mihoyo_mcp/
├── server.py          # MCPServer 装配 + stdio 入口
├── config.py          # 环境变量配置
├── context.py         # AppContext 单例装配
├── errors.py          # 领域错误（映射为 MCP tool error）
├── accounts/          # 账号模型 / 注册表 / 加密凭据库
├── auth/              # 扫码登录（start/poll 会话）
├── games/             # genshin.py 客户端工厂 + 便笺获取/归一化
├── alerts/            # 告警去重状态机（纯逻辑，可测）
└── tools/             # MCP 工具注册（auth / accounts / notes）

Процесс входа (Miyoushe)

1. auth_start_qr_login("miyoushe") → отправляешь пользователю QR-код из login_url (или сгенерированный из qr_png_base64)

2. Пользователь сканирует QR в приложении Miyoushe и подтверждает входящий с телефона.

3. Поллишь auth_poll_qr_login(session_id), пока не станет confirmed

4. Сервис изнутри сохраняет cookies v2 (account_id_v2 / account_mid_v2 / ltoken_v2 / cookie_token_v2...) и автоматически находит игровых персонажей; дальше агент видит только account_id вида miyoushe:123456.

Дорожная карта

Отсортирована по приоритету потребителей (nahida-bot #52 и др.):

1. ✅ Account / Auth — вход Miyoushe по QR, мультиаккаунте, обнаружение персонажей

2. ✅ Daily Note + оповещения — заметки Star Rail / Genshin / ZZZ, check_alerts

3. ⏳ HoYoLAB login — почта/пароль (genshin.py уже поддерживает) или QR OS (эндпоинт нужно проверить)

4. Sign in (check-in) / коды (check_in / codes.list / codes.redeem)

5. Profile / витрины персонажей (Enka, панели)

6. Игровые данные / Build / расчёт прокачки (hakush.in / Yatta / Ambr)

7. Импорт и статистика гачи

8. Рендеринг (необязательно—создание картинок; инструмент возвращает structured data + отдельный рендер-инструмент)

Справочные проекты и лицензии

Этот проект использует MIT License.