DJ Music Plugin
v1.4.0 · MIT · MCP-сервер для управления личной DJ techno библиотекой, построения оптимизированных DJ сетов и интеграции с Яндекс Музыкой.
Surface: MCP (Claude Desktop / Cursor / любой MCP-client) — 20 tools, 27 resources, 6 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://)
- 6 workflow prompts —
dj_expert_session, build_set_workflow, deliver_set_workflow, expand_playlist_workflow, full_pipeline, quick_mix_check
- 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.4.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 + 6 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/mcp-server-supabase@0.7.0 (запускается через 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 сам, кроссплатформенно.
Разработка
