maimai DX MCP Server

Ein leistungsstarker, leichtgewichtiger, modularer 舞萌 DX (maimai DX) Model Context Protocol (MCP) Server, basierend auf Rust.

• 📖 Konfigurations- und Bereitstellungsanleitung (docs/CONFIG_GUIDE.md)

• 📦 Vorgefertigte Binärdateien herunterladen (GitHub Releases)

• Zeichnungs- und Geschäftsreferenz: Yuri-YuzuChaN/maimaiDX

• Python-Versionsarchiv: legacy-Zweig

🌟 Kernfunktionen

• ⚡ Extreme Leistung und Leichtgewichtigkeit: Reine Rust-Implementierung, Kaltstart in Millisekunden, Speicherverbrauch im Leerlauf unter 15 MB, keine schweren externen C-Bibliotheksabhängigkeiten.

• 🎨 Pixelgenaue reine Rust-Zeichen-Engine:

  • Die Zeichenlayout-, Kunstasset-Verzeichnisformat- und Koordinaten-Rendering-Logik dieses Projekts basieren auf dem absoluten Koordinatensystem des Open-Source-Projekts Yuri-YuzuChaN/maimaiDX und wurden in reinem Rust migriert und optimiert.

  • Basierend auf image + ab_glyph und der rayon-Multithread-Pipeline werden B50, Einzellied-Ergebnis-Karten, Schild-Fortschrittstabellen und Glücksdiagramme streng nach absoluten Koordinaten im 1:1-Verhältnis hochgetreu gerendert.

• 🤖 Freundlich für schwache und kleine Modelle:

  • Tolerante Parameter-Normalisierung: Automatische Kompatibilität mit chinesischen Schwierigkeitsgraden („Lila/Weiß/Gelb/Rot/Grün“), Gleitkomma-Konstanten-Umwandlung und Fuzzy-Matching von Liednamen-Aliasen.

  • Absturzsichere chinesische Fallback-Lösung: Bei fehlenden Daten oder fehlender Bindung werden strukturierte, menschenlesbare Anweisungen zurückgegeben, um Halluzinationen oder das Wiederholen von Aufrufstapeln durch kleine Modelle zu vermeiden.

• 🚀 Sofort einsatzbereit:

  • Zweigleisige Bild-Text-Ausgabe: Standardmäßig werden sowohl der standardmäßige MCP-Image-Content (Base64) als auch der lokale Dateipersistenzpfad zurückgegeben, für nahtlose Integration in verschiedene Bot-Nachrichten.

  • Null-Hürden-Ergebnisabfrage: Nach Konfiguration der globalen Entwickleranmeldedaten genügt die QQ-Nummer im Kontext, um direkt ein Ein-Klick-Ergebnisbild zu erhalten.

Related MCP server: Claud-Ear

🛠️ MCP-Toolübersicht (Tool Registry)

Alle Tools unterstützen optionale Parameter: qq (Benutzer-QQ-Nummer), username (Benutzername), source ("divingfish" oder "lxns"), output_format ("image", "text", "both").

⚙️ Umgebungskonfiguration

Der Server unterstützt die Konfiguration über Umgebungsvariablen oder .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

📁 Vorbereitung statischer Ressourcen und Verzeichnisstruktur

1. Verzeichnisstruktur

Bitte legen Sie den Ordner static für statische Ressourcen im Projektstammverzeichnis ab (oder geben Sie einen absoluten Pfad über MAIMAI_STATIC_DIR an):

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

2. Statische Ressourcen

Laden Sie das Ressourcenpaket herunter und entpacken Sie es:

• Cloudreve

• OneDrive

Notieren Sie den absoluten Pfad des static-Verzeichnisses (d. h. MAIMAI_STATIC_DIR in der Konfiguration). Bitte beachten Sie die Urheberrechtshinweise für Kunst und Schriftarten der Upstream-Projekte.

🚀 Installation und Ausführung

1. Methode A: Vorgefertigte Binärdatei direkt herunterladen (empfohlen)

Laden Sie das für Ihre Systemarchitektur geeignete Archiv (Windows / Linux) von GitHub Releases herunter und verwenden Sie es nach dem Entpacken direkt.

2. Methode B: Aus dem Quellcode kompilieren

cargo build --release

3. Lokaler Test des MCP-Dienstes

Kann über standardmäßiges stdio ausgeführt werden:

./target/release/maimai-mcp

3. Integration in AstrBot / Claude Desktop

Fügen Sie in der mcpServers-Konfiguration hinzu:

{
  "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"
      }
    }
  }
}

🙏 Danksagungen und Open-Source-Erklärung (Credits & Attribution)

Dieses Projekt hat während der Entwicklung die Designs und Ressourcenspezifikationen der folgenden herausragenden Open-Source-Projekte eingehend referenziert und wiederverwendet:

• Yuri-YuzuChaN/maimaiDX (MIT License):

  • Die Zeichen-Rendering-Logik, das UI-Element-Layout, das absolute Pixel-Koordinatensystem und die Verzeichnisstruktur der statischen Ressourcen dieses Projekts stammen aus dem genialen Design dieses Projekts.

  • Besonderer Dank gilt allen Mitwirkenden des maimaiDX-Projekts!

• Ökosystem der Ergebnisabfrage und Datenquellen:

  • Dank an DivingFish (水鱼查分器) für die offene API zur Ergebnisabfrage und die OAuth-Plattform.

  • Dank an 落雪咖啡屋 (LXNS) für die offene Datenschnittstelle und die OAuth-Plattform.

  • Dank an Yuzuchan für die Datenbank der Lied-Aliase.

📜 Lizenz- und Ressourcenrechte-Erklärung

• Dieses Code-Repository ist unter der BSD 2-Clause License lizenziert;

• Die Lizenz des Upstream-Referenzprojekts finden Sie unter LICENSE-UPSTREAM;

• Urheberrechtshinweis zu Ressourcen: Kunst-/Schriftressourcen wie static werden nicht mit diesem Repository verteilt; ihr Urheberrecht richtet sich nach dem Ressourcenpaket und den offiziellen Angaben und fällt nicht unter diese Open-Source-Lizenz. Bitte stellen Sie sicher, dass die Nutzung der Materialien legal und konform ist, und beachten Sie die Urheberrechtshinweise der jeweiligen Schriftarten und Materialien.

📄 Architektur und Designentscheidungen

• Glossar der Domänenmodell-Begriffe (CONTEXT.md)

• Architektur-Entscheidungsprotokoll (docs/adr/)

• Entwicklungs-Implementierungsleitfaden (AGENTS.md)