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 号即可直出一键查分图。

🛠️ 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)