Skip to main content
Glama

maimai DX MCP Server

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

Rust CI Release License


🌟 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").

Tool-Name (Tool Name)

Funktionsbeschreibung

Hauptrückgabe

mai_b50

Abfrage der besten 50 Ergebnisse des Spielers (B35 + B15)

B50-Vorschaubild, Rating und Einzellied-Details

mai_play_score

Abfrage der Einzellied-/Alias-Ergebnisabrechnungskarte des Spielers

Abrechnungsbild, Erreichungsrate, DX-Punkte, Bewertungsstufe

mai_chart_info

Abfrage von Chart-Details, Konstanten und Notenanzahl

Chart-Vorschaubild, Konstanten für jede Schwierigkeit und Designer

mai_rise_score

Berechnung von Punktesteigerungsvorschlägen und Ziel-Rating-Differenz

Empfohlene Lieder zum Punktesammeln und Ziel-Erreichungsrate

mai_search_song

Fuzzy-Suche nach Liedern und Versionen der Liedautoren

Liste der passenden Lieder und Schwierigkeitskonstanten

mai_alias_query

Abfrage aller bekannten Community-Aliase und Tags eines Liedes

Alias-Liste und Abstimmungsinformationen

mai_random_song

Zufällige Auswahl eines Liedes nach Schwierigkeitsgrad/Konstantenbereich

Gezogene Liedkarte und Parameter

mai_what

Ähnlich wie „Was essen wir heute?“ – zufällige Liedempfehlung

Empfohlenes Lied und besonderer Text

mai_level_progress

Abfrage der Fortschrittsübersicht für eine bestimmte Stufe (z. B. 13+)

Übersichtsbild für Durchspielen/FC/AP-Stufen

mai_plate_table

Abfrage des Fortschritts der Schilder der einzelnen Generationen (霸者/舞/将/极/神)

Schild-Fortschrittstabelle und Liste nicht abgeschlossener Lieder

mai_bind_player

Bindet QQ an ein 水鱼/落雪-Konto oder wechselt die Standardquelle

Bindungsbestätigungsstatus und Informationen

mai_user_settings

Anzeigen und Ändern persönlicher Ergebnisabfrage-Präferenzen

Aktuelle Bindungs-Konfiguration, Standardquelle und Anzeigepräferenzen

mai_fortune

Ziehen des heutigen maimai-Glücks und Empfehlungen für günstige/ungünstige Dinge

Glücksbild, Glückswert und empfohlene Lieder

mai_group_rank

Statistik der Gesamt-Rating-Rangliste der gebundenen Mitglieder in der Gruppe

Gruppen-Ranglisten-Diagramm und Platzierungen


⚙️ 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:

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:

📜 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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers