maimai DX MCP Server

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

• 📖 設定・導入チュートリアル (docs/CONFIG_GUIDE.md)

• 📦 プリコンパイル済みバイナリのダウンロード (GitHub Releases)

• 描画・業務参考：Yuri-YuzuChaN/maimaiDX

• Python 版アーカイブ：legacy ブランチ

🌟 コア機能

• ⚡ 最高のパフォーマンスと軽量性：純 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"）。

⚙️ 環境設定の説明

サーバーは環境変数または .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. 静的リソース

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

• Cloudreve

• OneDrive

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

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

• ドメインモデル用語集 (CONTEXT.md)

• アーキテクチャ決定記録 (docs/adr/)

• 開発実装ガイド (AGENTS.md)