maimai DX MCP Server

Высокопроизводительный, лёгкий и модульный сервер Model Context Protocol (MCP) для 舞萌 DX (maimai DX), написанный на Rust.

• 📖 Руководство по настройке и развёртыванию (docs/CONFIG_GUIDE.md)

• 📦 Скачать предварительно скомпилированный бинарный файл (GitHub Releases)

• Справочный проект по отрисовке и бизнес-логике: Yuri-YuzuChaN/maimaiDX

• Архив Python-версии: ветка legacy

🌟 Ключевые особенности

• ⚡ Максимальная производительность и лёгкость: полностью реализовано на Rust, холодный старт занимает миллисекунды, потребление памяти в простое — ниже 15 МБ, отсутствуют тяжёлые внешние зависимости от C-библиотек.

• 🎨 Чистый Rust-движок отрисовки с попиксельной точностью:

  • Макет отрисовки, формат каталога графических ресурсов и логика координатного рендеринга в этом проекте основаны на абсолютной системе координат открытого проекта Yuri-YuzuChaN/maimaiDX, перенесённой на чистый Rust и оптимизированной.

  • На базе image + ab_glyph и многопоточного конвейера rayon строго по абсолютным координатам с точностью 1:1 и высокой точностью отрисовываются B50, карточки результатов отдельных треков, таблицы прогресса плашек и изображения прогноза.

• 🤖 Дружелюбность к слабоинтеллектуальным и малопараметрическим моделям:

  • Гибкая нормализация параметров: автоматически поддерживаются китайские обозначения сложности («фиолетовый/белый/жёлтый/красный/зелёный»), преобразование плавающих констант сложности и нечёткое сопоставление алиасов названий треков.

  • Устойчивый к сбоям запасной вариант (на китайском языке): при отсутствии данных или невыполненной привязке возвращаются структурированные человекочитаемые подсказки, что предотвращает галлюцинации малых моделей или повторение стека вызовов.

• 🚀 Готов к использованию из коробки:

  • Двухканальный вывод изображений и текста: по умолчанию одновременно возвращаются стандартный MCP Image Content (Base64) и локальный путь к сохранённому файлу — это бесшовно интегрируется с отправкой сообщений в различных ботах.

  • Проверка результатов без порога входа: после настройки глобальных учётных данных разработчика достаточно 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!

• Экосистема проверки результатов и источников данных:

  • Благодарим DivingFish (水鱼查分器) за открытый API проверки результатов и платформу OAuth.

  • Благодарим 落雪咖啡屋 (LXNS) за открытый интерфейс данных и платформу OAuth.

  • Благодарим Yuzuchan за базу данных алиасов треков.

📜 Лицензия и заявление о правах на ресурсы

• Исходный код этого репозитория распространяется под лицензией BSD 2-Clause License;

• Лицензионное соглашение вышестоящего справочного проекта см. в LICENSE-UPSTREAM;

• Заявление об авторских правах на ресурсы: графические / шрифтовые ресурсы, такие как static, не распространяются вместе с данным репозиторием; их авторские права определяются архивом ресурсов и официальными заявлениями и не входят в объём действия данной лицензии с открытым исходным кодом. Пожалуйста, самостоятельно убедитесь в законности использования материалов и соблюдайте заявления авторов шрифтов и материалов.

📄 Архитектура и проектные решения

• Глоссарий терминов предметной области (CONTEXT.md)

• Журнал архитектурных решений (docs/adr/)

• Руководство по разработке и внедрению (AGENTS.md)