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: 사전 빌드 바이너리 직접 다운로드 (권장)

자신의 시스템 아키텍처에 맞는 압축 패키지(Windows / Linux)를 GitHub Releases에서 다운로드하여 압축을 푼 뒤 바로 사용하세요.

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)