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를 DivingFish/LXNS 계정에 바인딩하거나 기본 소스 전환

바인딩 확인 상태와 정보

mai_user_settings

개인 점수 조회 기본 설정 조회 및 수정

현재 바인딩 설정, 기본 소스 및 표시 기본 설정

mai_fortune

오늘의 maimai 운세와 길흉 추천 뽑기

운세 이미지, 운세 수치 및 추천 곡

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

자신의 시스템 아키텍처에 맞는 압축 패키지(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 등 아트/글꼴 리소스는 이 코드 저장소와 함께 배포되지 않으며, 저작권은 리소스 패키지 및 공식 고지에 따릅니다. 본 오픈소스 라이선스 범위에 포함되지 않습니다. 사용자는 리소스 사용의 적법성과 규정 준수를 스스로 확인하고 각 글꼴 및 리소스의 원저작자 고지를 준수해야 합니다.


📄 아키텍처 및 설계 결정

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