mihoyo-mcp

Ein eigenständiger MCP-Server für MiHoYo-Spiele – ausgelegt für Miyoushe (CN-Server) und HoYoLAB (Global-Server), basierend auf seriaati/genshin.py (MIT). Er kann von jedem MCP-Client (nahida-bot, Claude Desktop, Codex …) direkt verwendet werden.

Designgrenzen

MCP regelt, „wie mit MiHoYo gesprochen wird“; der Client regelt, „wann gefragt wird und wem das Ergebnis danach mitgeteilt wird.“

• Planung (Cron), Schwellenwertstrategien, Nachrichten-Push → Client (nahida-bot hat bereits Scheduler / Channel)

• Login, Speicherung der Zugangsdaten, API-Aufrufe, Alarm-Deduplizierung → dieser Dienst

• Zugangsdaten verlassen nie die Sicherheitsgrenze: Cookies liegen vollständig im Dienst (Fernet-Verschlüsselung), Tool-Ergebnisse enthalten nur account_id, im Agent-Kontext erscheinen keine Tokens

                ┌─────────────────────┐
                │     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

Aktuelle Funktionen

Tool-Übersicht

account_id kann weggelassen werden, wenn nur ein Konto vorhanden ist.

Namenskonvention: Im Entwurf wurden punktierte Namen wie mihoyo.auth.start_qr_login verwendet; die MCP-Spezifikation (SEP-986) verlangt aber, dass Toolnamenchild ^[a-zA-Z0-9_-]{1,64}$ passen. Punkte würden dazu führen, dass einige Clients das Laden verweigern. Daher wird die flache Snake-Case-Namensgebung benutzt, mit Präfixen wie auth_ / accounts_ / starrail_ als Namensraum.

Warum check_alerts in der MCP ist

Die Ressourcen-Schwellenwertlogik (217 >= 200 && recovery <= 1800) muss keine LLM-Tokens verbrauchen, während „Expeditionen zurück“ bei jedem Abruf erneut gemeldet wird, inakzeptabel ist. Der Status der Alarm-Deduplizierung (armed/re-arm) gehört zum Integrationszustand von Mioshe-In Munishe und damit natürlich in diesen Dienst. Der Cron des Clients braucht nur noch:

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

Schnellstart

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

Beispielkonfiguration für Clients (Claude Desktop / beliebige stdio-MCP-fähige Clients, bel):

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

Konfiguration (Umgebungsvariablen)

Datenordner-Inhalt:

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

Verzeichnisstruktur

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）

Login-Ablauf (Miyoushe)

1. auth_start_qr_login("miyoushe") → sende dem Benutzer den QR-Code, der aus qr_png_base64 (oder login_url) erzeugt wird

2. Der Benutzer scannt den QR-Code mit der Miyoushe-App und bestätigt auf dem Telefon

3. auth_poll_qr_login(session_id) pollt solange, bis confirmed

4. Der Dienst speichert intern die v2-Cookies (account_id_v2 / account_mid_v2 / ltoken_v2 / cookie_token_v2 …) and er ermittelt automatisch die Spielkonten; danach ist für den Agenten nur eine account_id wie miyoushe:123456 sichtbar

Roadmap

Priorität sortiert nach abnehmenden Projekten (nahida-bot-channel #57 etc.):

1. ✅ Account / Auth – Miyoushe-Tool-Login, Multi-Konto, Rollenerkennung

2. ✅ Daily Note + Alerts – EDT / Genshin / ZZZ-Notizen, check_alerts

3. ⏳ HoYoLAB-Login – E-Mail/Passwort (von genshin.py unterstützt) oder OS-QR-Scan (Endpoint noch zu verifizieren)

4. Check-in / Einlösungscodes (check_in / codes.list / codes.redeem)

5. Profile / Charakterverkart (Enka, Panel-Query)

6. Spielressourcen / Build / Aufbauberechnung (hakush.in / Yatta / Ambr)

7. Gakya import & statistics

8. Renderer (optional Bildkartengenerierung, falls Tools liefern temporary-data + eigener Renderer tool)

Referenzprojekte und Lizenzen

Dieses Projekt ist unter MIT License (Linkvaluelicensstat) erlaubt.