Skip to main content
Glama

maimai DX MCP Server

Rust ベースの高性能・軽量・モジュール式 舞萌 DX (maimai DX) Model Context Protocol (MCP) サーバー。

Rust CI Release License


🌟 コア機能

  • ⚡ 最高のパフォーマンスと軽量性:純 Rust 実装により、コールドスタートはミリ秒単位、アイドル時メモリ使用量は 15MB 未満、重い外部 C ライブラリへの依存なし。

  • 🎨 ピクセル単位の純 Rust 描画エンジン:

    • 本プロジェクトの描画レイアウト、アートアセットディレクトリ形式、座標レンダリングロジックは、オープンソースプロジェクト Yuri-YuzuChaN/maimaiDX の絶対座標体系をベースに純 Rust へ移行・最適化したものです。

    • image + ab_glyph と rayon マルチスレッドパイプラインに基づき、絶対座標を 1:1 で忠実に再現し、B50・単曲決算カード・牌子進捗表・運勢図を高精細にレンダリングします。

  • 🤖 弱い知能モデル・小パラメータモデルにフレンドリー:

    • 寛容なパラメータ正規化:中国語の難易度(「紫/白/黄/红/绿」)、浮動小数点定数の変換、曲名エイリアスの曖昧一致を自動対応。

    • クラッシュ防止の中国語フォールバック:データなし・未バインド時は構造化された人間可読なガイダンスを返し、小モデルの幻覚や呼び出しスタックの繰り返しを回避。

  • 🚀 すぐに使える:

    • 二系統の図文出力:デフォルトで標準 MCP Image Content(Base64)とローカルファイル永続化パスを同時に返し、各種 Bot メッセージ送信にシームレスに対応。

    • ゼロハードルでスコア照会:グローバル開発者認証情報を設定すれば、コンテキスト内の QQ 番号だけでワンクリックでスコア画像を出力。


Related MCP server: Claud-Ear

🛠️ MCP ツール一覧 (Tool Registry)

すべてのツールはオプションパラメータに対応:qq(ユーザー QQ 番号)、username(ユーザー名)、source("divingfish" または "lxns")、output_format("image"、"text"、"both")。

ツール名 (Tool Name)

機能説明

主な戻り値

mai_b50

プレイヤーのベスト 50 曲成績を照会 (B35 + B15)

B50 プレビュー画像、Rating および単曲詳細

mai_play_score

プレイヤーの単曲/エイリアス成績決算カードを照会

決算画像、達成率、DX スコア、評価ランク

mai_chart_info

譜面詳細、定数、Note 物量を照会

譜面プレビュー画像、各難易度の定数とデザイナー

mai_rise_score

スコアアップ提案と目標 Rating との差を計算

おすすめのスコア稼ぎ曲と目標達成率

mai_search_song

曲名とアーティスト・バージョン情報を曖昧検索

一致した曲リストと難易度定数

mai_alias_query

曲の既知のコミュニティエイリアスとタグをすべて照会

エイリアスリストと投票情報

mai_random_song

難易度/定数範囲でランダムに曲を選択

抽選された曲カードとパラメータ

mai_what

「今日何を食べるか」風のランダムおすすめ曲

おすすめ曲と特徴的なコピー

mai_level_progress

指定レベル(例:13+)の達成度サマリーを照会

クリア/FC/AP レベル帯サマリー図

mai_plate_table

各世代の牌子(霸者/舞/将/极/神)の進捗を照会

牌子達成度進捗表および未クリアリスト

mai_bind_player

QQ を水鱼/落雪アカウントにバインド、またはデフォルトソースを切り替え

バインド確認ステータスと情報

mai_user_settings

個人のスコア照会設定を表示・変更

現在のバインド設定、デフォルトソース、表示設定

mai_fortune

今日の舞萌運勢とおすすめの宜忌を抽選

運勢画像、運勢値、おすすめ曲

mai_group_rank

グループ内のバインド済みメンバーの総合 Rating ランキングを集計

グループランキングチャートと順位


⚙️ 環境設定の説明

サーバーは環境変数または .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

📁 静的リソースの準備とディレクトリ構造

1. ディレクトリ構造

static 静的リソースフォルダをプロジェクトルートに配置してください(または MAIMAI_STATIC_DIR で絶対パスを指定):

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

2. 静的リソース

リソースパックをダウンロードして解凍します:

その中の static ディレクトリの絶対パス(設定内の MAIMAI_STATIC_DIR)を控えてください。 上流のアート・フォント関連の声明を遵守してください。


🚀 インストールと実行

1. 方法 A:プリコンパイル済みバイナリを直接ダウンロード(推奨)

GitHub Releases からお使いのシステムアーキテクチャに合った圧縮パッケージ(Windows / Linux)をダウンロードし、解凍後そのまま使用できます。

2. 方法 B:ソースコードからコンパイル

cargo build --release

3. ローカルで MCP サービスをテスト

標準 stdio で実行できます:

./target/release/maimai-mcp

3. AstrBot / Claude Desktop での接続

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

🙏 謝辞とオープンソース声明 (Credits & Attribution)

本プロジェクトは開発過程で以下の優れたオープンソースプロジェクトの設計とリソース仕様を深く参考にし、再利用しています:

  • Yuri-YuzuChaN/maimaiDX (MIT License):

    • 本プロジェクトの描画レンダリングロジック、UI 要素レイアウト、絶対ピクセル座標体系、静的リソースディレクトリ構造はすべてこのプロジェクトの精巧な設計に由来しています。

    • maimaiDX プロジェクトのすべてのコントリビューターに感謝します!

  • スコア照会・データソースエコシステム:

    • スコア照会のオープン API と OAuth プラットフォームを提供してくれた DivingFish (水鱼查分器) に感謝します。

    • オープンデータインターフェースと OAuth プラットフォームを提供してくれた 落雪咖啡屋 (LXNS) に感謝します。

    • 曲エイリアスデータベースを提供してくれた Yuzuchan に感謝します。

📜 ライセンスとリソース権利の声明

  • 本コードリポジトリは BSD 2-Clause License でオープンソース化されています;

  • 上流参考プロジェクトの規約は LICENSE-UPSTREAM を参照してください;

  • リソース著作権声明:static などのアート/フォントリソースは本コードリポジトリでは配布されません。その著作権はリソースパックと公式声明に従い、本オープンソースライセンスの許諾範囲外です。利用者は素材使用の合法性・コンプライアンスを自ら確保し、各フォント・素材の原作者の声明を遵守してください。


📄 アーキテクチャと設計決定

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