dj-music

DJ Music Plugin

v1.10.0 · MIT · MCP-сервер для управления личной DJ techno библиотекой, построения оптимизированных DJ сетов и интеграции с Яндекс Музыкой.

Surface: MCP (Claude Desktop / Cursor / любой MCP-client) — 20 tools, 27 resources, 19 workflow prompts.

Возможности

• 20 MCP tools — 14 generic dispatchers (v1 polymorphism: entity_{list,get,create,update,delete,aggregate} × 11 entities, provider_{read,write,search} × Yandex, transition_score_pool, sequence_optimize, playlist_sync, unlock_namespace, tool_invoke) + 6 UI Prefab dashboards (camelot wheel, library audit/dashboard, set view, transition score, score-pool matrix)
• 27 MCP resources — per-entity views (local://), session state (session://), schema introspection (schema://), static reference blobs (reference://)
• 19 workflow prompts — core (dj_expert_session, build_set_workflow, deliver_set_workflow, expand_playlist_workflow, full_pipeline, quick_mix_check) + library/analysis, set design (harmonic/subgenre journey, scenario, b2b, extend), set repair (review/fix/replace) и discovery/ops (digging, taste, sync) — см. research
• Audio analysis pipeline — 18 анализаторов (L1→L4 tiered), SharedMemory transport + per-worker AnalysisContext cache
• DJ set generation — генетический алгоритм + greedy builder с transition scoring и section-aware весами
• Transition scoring — 6-компонентная оценка (BPM, гармония, энергия, спектр, грув, тембр) + hard constraints + recipe engine (12 mix-типов) + intent/style/template awareness
• Yandex Music интеграция — provider_search / provider_read / provider_write (playlist add/remove/create/rename/delete/set_description, likes add/remove)
• Экспорт — M3U8, Rekordbox XML, JSON guide, cheat sheet (через local://sets/{id}/cheatsheet + deliver_set_workflow prompt)
• Mood classification — 15 techno subgenres, запускается внутри track_features_analyze handler

Быстрый старт

# Установка
uv sync

# Для audio analysis (BPM, key, beat detection)
uv sync --extra audio

# Настройка
cp .env.example .env
# Заполни DJ_YM_TOKEN и DJ_YM_USER_ID в .env

# Запуск
uv run fastmcp run server.py

Установка как Claude Code плагин

Внутри Claude Code (slash-команды):

/plugin marketplace add evgenygurin/dj-music-plugin
/plugin install dj-music

Из терминала через claude CLI (non-interactive, годится для скриптов и CI):

claude plugin marketplace add evgenygurin/dj-music-plugin
claude plugin install dj-music@dj-music-plugin

Альтернативный синтаксис через git URL (любая ветка/тег/SHA):

claude plugin marketplace add https://github.com/evgenygurin/dj-music-plugin.git#v1.10.0

Session-only тест без install (не пишет в ~/.claude/settings.json):

git clone https://github.com/evgenygurin/dj-music-plugin.git
claude --plugin-dir /path/to/dj-music-plugin              # одноразово
claude --plugin-dir /path/to/dj-music-plugin --debug "plugins,mcp"   # с debug-логом

Полезно для оценки плагина «как новый пользователь» без затирания текущей установки. Каждый запуск подтягивает свежий код.

Pre-install / pre-PR проверка manifest'а:

claude plugin validate /path/to/dj-music-plugin
# Валидирует plugin.json + marketplace.json + frontmatter всех commands/agents/skills + hooks.json

Плагин поднимает два MCP сервера:

Сервер	Назначение
mcp	20 DJ tools + 27 resources + 19 prompts — построение сетов, аудиоанализ, YM, экспорт (FastMCP v3)
db	Read-only инспекция БД: схема, SQL, миграции, логи

Сервер db принудительно изолирован (security hardening по официальным рекомендациям Supabase MCP):

• --read-only — мутации БД блокируются (выполняются через mcp)
• --project-ref=${DJ_DB_PROJECT_REF} — scoped к одному проекту (env-driven для marketplace-portability)
• --features=database,docs,debug — surface ограничен: SQL, схема, миграции, логи. Account/branches/storage/edge-functions tools отключены

Конфигурация в .env:

DJ_DB_ACCESS_TOKEN="sbp_..."         # personal access token
DJ_DB_PROJECT_REF="your_project_ref" # из URL Supabase Dashboard

Реализация — @supabase/[email protected] (запускается через npx). Токен генерится в Supabase Dashboard.

Платформенные ограничения

Сервер db использует bash-wrapper для авто-загрузки .env (Claude Code не делает этого нативно). На Windows без WSL/Git-Bash не запустится — альтернатива: экспортировать DJ_DB_ACCESS_TOKEN в shell вручную и заменить wrapper на нативный env-блок в plugin.json.

Сервер mcp использует нативный command/cwd — pydantic-settings (app/config/) читает .env сам, кроссплатформенно.

Разработка