maimai DX MCP Server

Servidor de Model Context Protocol (MCP) para 舞萌 DX (maimai DX), de alto rendimiento, ligero y modular, construido en Rust.

• 📖 Guía de configuración y despliegue (docs/CONFIG_GUIDE.md)

• 📦 Descargar binarios precompilados (GitHub Releases)

• Referencia de dibujo y lógica de negocio: Yuri-YuzuChaN/maimaiDX

• Versión Python archivada: rama legacy

🌟 Características principales

• ⚡ Rendimiento extremo y ligereza: implementación en Rust puro, arranque en frío en milisegundos, uso de memoria en reposo inferior a 15 MB y sin dependencias de bibliotecas C externas pesadas.

• 🎨 Motor de dibujo en Rust puro a nivel de píxel:

  • El diseño de dibujo, el formato del directorio de recursos artísticos y la lógica de renderizado por coordenadas de este proyecto se basan en el sistema de coordenadas absolutas del proyecto de código abierto Yuri-YuzuChaN/maimaiDX, migrado y optimizado a Rust puro.

  • Basado en la canalización multiproceso de image + ab_glyph y rayon, renderiza con alta fidelidad y estricta proporción 1:1 según coordenadas absolutas las tarjetas de resultados B50 y de una sola canción, las tablas de progreso de placas y las imágenes de fortuna.

• 🤖 Amigable con los modelos de IA débiles y de parámetros pequeños:

  • Normalización tolerante de parámetros: compatible automáticamente con las dificultades en chino ("púrpura/blanco/amarillo/rojo/verde"), conversión de constantes de punto flotante y coincidencia difusa de alias de nombres de canciones.

  • Respaldo en chino a prueba de fallos: cuando no se encuentran datos o no hay cuenta vinculada, devuelve una guía estructurada y legible para humanos, para evitar alucinaciones de los modelos pequeños o la repetición de la pila de llamadas.

• 🚀 Listo para usar:

  • Salida dual de imagen y texto: por defecto devuelve a la vez el contenido de imagen MCP estándar (Base64) y la ruta de persistencia en archivo local, integrándose sin problemas con el envío de mensajes de distintos bots.

  • Consulta de puntuaciones sin barreras: tras configurar las credenciales globales de desarrollador, solo se necesita el número de QQ en el contexto para generar directamente la imagen de consulta de puntuaciones con un solo clic.

Related MCP server: Claud-Ear

🛠️ Lista de herramientas MCP (Tool Registry)

Todas las herramientas admiten parámetros opcionales: qq (número de QQ del usuario), username (nombre de usuario), source ("divingfish" o "lxns") y output_format ("image", "text", "both").

⚙️ Configuración del entorno

El servidor admite configuración mediante variables de entorno o un archivo .env:

# 水鱼查分网开发者 Token（配置后仅凭 QQ 号即可直接查分）
DIVINGFISH_DEVELOPER_TOKEN=your_divingfish_developer_token

# 落雪查分网开发者 Token（可选）
LXNS_DEVELOPER_TOKEN=your_lxns_token

# 静态资源根目录（默认 ./static 或 ../maimaiDX/static）
MAIMAI_STATIC_DIR=./static

# 本地数据与用户配置存储目录（默认 ./data）
MAIMAI_DATA_DIR=./data

# 生成图片临时保存目录（默认 ./output）
MAIMAI_OUTPUT_DIR=./output

📁 Preparación de recursos estáticos y estructura de directorios

1. Estructura de directorios

Coloque la carpeta de recursos estáticos static en el directorio raíz del proyecto (o especifique la ruta absoluta mediante MAIMAI_STATIC_DIR):

static/
├── font/              # 字体文件 (ResourceHanRoundedCN-Bold.ttf 等)
├── data/              # 歌曲/别名/牌子数据缓存 (music_data.json 等)
└── mai/
    ├── pic/           # UI 边框、评级底图、段位图标
    ├── cover/         # 曲目封面 (以 song_id 命名)
    ├── plate/         # 姓名框与牌子背景
    ├── shougou/       # 称号底图
    └── plate_version/ # 各版本牌子标识

2. Recursos estáticos

Descargue y extraiga el paquete de recursos:

• Cloudreve

• OneDrive

Anote la ruta absoluta del directorio static (es decir, MAIMAI_STATIC_DIR en la configuración). Respete las declaraciones upstream sobre recursos artísticos y fuentes.

🚀 Instalación y ejecución

1. Opción A: descargar directamente el binario precompilado (recomendado)

Descargue desde GitHub Releases el paquete comprimido adecuado para la arquitectura de su sistema (Windows / Linux); descomprímalo y úselo directamente.

2. Opción B: compilar desde el código fuente

cargo build --release

3. Probar el servicio MCP localmente

Se puede ejecutar mediante stdio estándar:

./target/release/maimai-mcp

3. Integración en AstrBot / Claude Desktop

Añada en la configuración de mcpServers:

{
  "mcpServers": {
    "maimai": {
      "command": "/path/to/maimai-mcp",
      "env": {
        "MAIMAI_STATIC_DIR": "/path/to/static",
        "DIVINGFISH_CLIENT_ID": "your_divingfish_client_id",
        "DIVINGFISH_CLIENT_SECRET": "your_divingfish_client_secret"
      }
    }
  }
}

🙏 Agradecimientos y declaración de código abierto (Credits & Attribution)

Durante el desarrollo, este proyecto ha consultado en profundidad y ha reutilizado los diseños y las especificaciones de recursos de los siguientes excelentes proyectos de código abierto:

• Yuri-YuzuChaN/maimaiDX (MIT License):

  • La lógica de renderizado de los dibujos, el diseño de los elementos de la UI, el sistema de coordenadas de píxeles absolutos y la estructura de directorios de los recursos estáticos de este proyecto provienen del ingenioso diseño de dicho proyecto.

  • ¡Agradecemos especialmente a todos los contribuyentes del proyecto maimaiDX!

• Ecosistema de consulta de puntuaciones y fuentes de datos:

  • Gracias a DivingFish (水鱼查分器) por su API abierta de consulta de puntuaciones y su plataforma OAuth.

  • Gracias a 落雪咖啡屋 (LXNS) por su interfaz de datos abierta y su plataforma OAuth.

  • Gracias a Yuzuchan por su base de datos de alias de canciones.

📜 Licencia y declaración de derechos de recursos

• Este repositorio de código se publica como código abierto bajo la BSD 2-Clause License;

• El acuerdo de licencia del proyecto de referencia upstream se encuentra en LICENSE-UPSTREAM;

• Aviso de derechos de autor de los recursos: los recursos artísticos / de fuentes, como static, no se distribuyen junto con este repositorio; sus derechos de autor se rigen por el paquete de recursos y las declaraciones oficiales, y quedan fuera del ámbito de esta licencia de código abierto. Los usuarios deben asegurarse por sí mismos de que el uso de los materiales sea legal y conforme a la normativa, y respetar las declaraciones de los autores originales de cada fuente y material.

📄 Arquitectura y decisiones de diseño

• Glosario de términos del modelo de dominio (CONTEXT.md)

• [Registro de decisiones de arquitectura (docs/adr/)