mihoyo-mcp

Servidor MCP independiente para miHoYo — orientado tanto a 米游社（servidor CN） como a HoYoLAB（servidor internacional）, y que depende de seriaati/genshin.py (MIT). Cualquier cliente MCP (nahida-bot, Claude Desktop, Codex...) puede usarlo directamente.

Límites de diseño

El MCP se encarga de «cómo hablar con mihoyo»; el cliente se encarga de «cuándo preguntar y a quién contárselo».

• Programación (cron), políticas de umbral, envío de mensajes → el cliente (nahida-bot ya tiene Scheduler / Channel)

• Inicio de sesión, almacenamiento de credenciales, llamadas a la API, deduplicación de alertas → este servicio

• Las credenciales nunca salen del perímetro de seguridad: las cookies se guardan siempre dentro del servicio (cifrado Fernet); en los resultados de las herramientas solo aparece account_id, y no habrá ningún token en el contexto del agente.

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

Capacidades actuales

Lista de herramientas

account_id puede omitirse cuando solo hay una cuenta.

Nota sobre los nombres: en el diseño original se usaban nombres con puntos, como mihoyo.auth.start_qr_login, pero el estándar MCP (SEP-986) exige que los nombres de herramientas sigan ^[a-zA-Z0-9_-]{1,64}$; los puntos harían que algunos clientes rechacen la carga, por lo que se ha optado por nombres planos en snake_case, con prefijos auth_ / accounts_ / starrail_ para hacer de espacio de nombres.

Por qué check_alerts está en MCP

El umbral de Resistencia (217 >= 200 && recovery <= 1800) no requiere gastar tokens de LLM, y notificar que «las expediciones han vuelto» en cada comprobación no es aceptable. El estado de deduplicación de alertas (armed/re-arm) forma parte del estado de integración de 米游社, así que pertenece de forma natural a este servicio. El cron del cliente solo necesita:

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

Inicio rápido

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

Ejemplo de configuración del cliente (Claude Desktop / cualquier cliente que admita MCP por stdio):

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

Configuración (variables de entorno)

La ruta del directorio de datos incluye:

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

Estructura de directorios

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）

Inicio de sesión (米游社)

1. auth_start_qr_login("miyoushe") → envía al usuario el QR generado a partir de qr_png_base64 (o login_url)

2. El usuario escanea con la aplicación 米游社 y autoriza desde el código

3. auth_poll_qr_login(session_id) hace polling hasta que llegue confirmed

4. El servicio guarda internamente las v2 cookies (account_id_v2 / account_mid_v2 / ltoken_v2 / cookie_token_v2…) y descubre automáticamente los personajes; a partir de ahí el agente solo ve account_id con forma miyoushe:123456

Hoja de ruta

Según la prioridad de los consumidores (nahida-bot #52, etc.):

1. Account / Auth — Inicio de sesión con QR de 米游社, multusuarios, descubrimiento de personajes

2. Daily Note + Alertas — Notas de Star Rail / Genshin / Zenless Zone Zero, check_alerts

3. Inicio de sesión en HoYoLAB — Contraseña por correo (con el caso de genshin.py ya soportado) o código QR OS (por verificar endpoint)

4. Check-in / códigos canjeables (check_in / codes.list / codes.redeem)

5. Perfil / exhibición de personajes (Enka, consulta de poderes)

6. Datos del juego / Build / cálculo de farmeo (hakush.in / Yatta / Ambr)

7. Importación y estadísticas de Gacha

8. Renderer (generación opcional de imágenes de tarjetas; las herramientas devuelven datos estructurados + una herramienta de renderizado)

Proyectos de referencia y licencias

Este proyecto está bajo MIT License.