{
  "markdown": "# DJ Music Plugin\n\n**v1.12.0** · MIT · MCP-сервер для управления личной DJ techno библиотекой, построения оптимизированных DJ сетов и интеграции с Яндекс Музыкой.\n\nSurface: **MCP** (Claude Desktop / Cursor / любой MCP-client) — 20 tools, 27 resources, 19 workflow prompts.\n\n## Возможности\n\n- **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)\n- **27 MCP resources** — per-entity views (`local://`), session state (`session://`), schema introspection (`schema://`), static reference blobs (`reference://`)\n- **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](docs/research/2026-06-22-techno-set-construction-and-mcp-prompts.md)\n- **Audio analysis pipeline** — 18 анализаторов (L1→L4 tiered), SharedMemory transport + per-worker AnalysisContext cache\n- **DJ set generation** — генетический алгоритм + greedy builder с transition scoring и section-aware весами\n- **Transition scoring** — 6-компонентная оценка (BPM, гармония, энергия, спектр, грув, тембр) + hard constraints + recipe engine (12 mix-типов) + intent/style/template awareness\n- **Yandex Music интеграция** — `provider_search` / `provider_read` / `provider_write` (playlist add/remove/create/rename/delete/set_description, likes add/remove)\n- **Экспорт** — M3U8, Rekordbox XML, JSON guide, cheat sheet (через `local://sets/{id}/cheatsheet` + `deliver_set_workflow` prompt)\n- **Mood classification** — 15 techno subgenres, запускается внутри `track_features_analyze` handler\n\n## Быстрый старт\n\n```bash\n# Установка\nuv sync\n\n# Для audio analysis (BPM, key, beat detection)\nuv sync --extra audio\n\n# Настройка\ncp .env.example .env\n# Заполни DJ_YM_TOKEN и DJ_YM_USER_ID в .env\n\n# Запуск\nuv run fastmcp run server.py\n```\n\n### Установка как Claude Code плагин\n\nВнутри Claude Code (slash-команды):\n\n```bash\n/plugin marketplace add evgenygurin/dj-music-plugin\n/plugin install dj-music\n```\n\nИз терминала через `claude` CLI (non-interactive, годится для скриптов и CI):\n\n```bash\nclaude plugin marketplace add evgenygurin/dj-music-plugin\nclaude plugin install dj-music@dj-music-plugin\n```\n\nАльтернативный синтаксис через git URL (любая ветка/тег/SHA):\n\n```bash\nclaude plugin marketplace add https://github.com/evgenygurin/dj-music-plugin.git#v1.12.0\n```\n\n**Session-only тест без install** (не пишет в `~/.claude/settings.json`):\n\n```bash\ngit clone https://github.com/evgenygurin/dj-music-plugin.git\nclaude --plugin-dir /path/to/dj-music-plugin              # одноразово\nclaude --plugin-dir /path/to/dj-music-plugin --debug \"plugins,mcp\"   # с debug-логом\n```\n\nПолезно для оценки плагина «как новый пользователь» без затирания текущей установки. Каждый запуск подтягивает свежий код.\n\n**Pre-install / pre-PR проверка manifest'а:**\n\n```bash\nclaude plugin validate /path/to/dj-music-plugin\n# Валидирует plugin.json + marketplace.json + frontmatter всех commands/agents/skills + hooks.json\n```\n\nПлагин поднимает два MCP сервера:\n\n| Сервер | Назначение |\n|--------|------------|\n| `mcp` | 20 DJ tools + 27 resources + 19 prompts — построение сетов, аудиоанализ, YM, экспорт (FastMCP v3) |\n| `db` | Read-only инспекция БД: схема, SQL, миграции, логи |\n\nСервер `db` принудительно изолирован (security hardening по [официальным рекомендациям Supabase MCP](https://github.com/supabase-community/supabase-mcp#security-risks)):\n\n- `--read-only` — мутации БД блокируются (выполняются через `mcp`)\n- `--project-ref=${DJ_DB_PROJECT_REF}` — scoped к одному проекту (env-driven для marketplace-portability)\n- `--features=database,docs,debug` — surface ограничен: SQL, схема, миграции, логи. Account/branches/storage/edge-functions tools отключены\n\nКонфигурация в [.env](.env.example):\n\n```bash\nDJ_DB_ACCESS_TOKEN=\"sbp_...\"         # personal access token\nDJ_DB_PROJECT_REF=\"your_project_ref\" # из URL Supabase Dashboard\n```\n\n> Реализация — `@supabase/mcp-server-supabase@0.7.0` (запускается через `npx`). Токен генерится в [Supabase Dashboard](https://supabase.com/dashboard/account/tokens).\n\n#### Платформенные ограничения\n\nСервер `db` использует `bash`-wrapper для авто-загрузки `.env` (Claude Code не делает этого нативно). На **Windows без WSL/Git-Bash не запустится** — альтернатива: экспортировать `DJ_DB_ACCESS_TOKEN` в shell вручную и заменить wrapper на нативный `env`-блок в `plugin.json`.\n\nСервер `mcp` использует нативный `command`/`cwd` — pydantic-settings (`app/config/`) читает `.env` сам, кроссплатформенно.\n\n## Разработка\n\n```bash\nuv run pytest -q                           # Тесты (1323 passed)\nuv run ruff check && uv run ruff format --check  # Линтер\nuv run mypy app/                           # Типы (есть pre-existing tech debt)\nuv run lint-imports                        # Архитектурные контракты (5/5)\nuv run alembic upgrade head                # Миграции\nmake check                                 # Всё вместе (lint + typecheck + arch + test)\n\n# Верификация audio pipeline на реальном MP3\nuv run python scripts/verify_audio_pipeline.py [path/to/track.mp3]\n```\n\n## Архитектура\n\nFastMCP v3 + FileSystemProvider (standalone `@tool` / `@resource` / `@prompt`, auto-discovery):\n\n```text\ntools/       # 14 @tool dispatchers (entity/provider/compute/sync/admin) + 6 UI Prefab\nresources/   # 27 @resource URIs\nprompts/     # 19 @prompt workflow recipes\nhandlers/    # 6 entity-scoped side-effect handlers\nregistry/    # EntityRegistry + ProviderRegistry + defaults\nrepositories/# BaseRepository[M] + UnitOfWork aggregator\nmodels/      # SQLAlchemy 2.0 — 12 aggregate roots\nschemas/     # Pydantic DTOs per entity\ndomain/      # Pure compute: transition / optimization / camelot / template / audit\naudio/       # 18 analyzers + tiered pipeline + 15-subgenre classifier\nproviders/   # External platforms (yandex/ …)\nserver/      # FastMCP composition: app.py, lifespan, 16 middleware, transforms, visibility\nshared/      # errors, constants, filters, ids, pagination, time (leaf)\nconfig/      # 9 per-domain Settings modules\ndb/          # session, seed, Alembic migrations\n```\n\n**Ключевые решения:**\n- **MCP — primary interface.** Композиция — через prompts / CodeMode / Tool Search, а не императивный service-слой.\n- **Polymorphism over proliferation.** 20 tools вместо 88 (v0.8) — 14 generic dispatchers + 6 UI Prefab.\n- **Anchor на DB entities.** Один aggregate root = один model + один repo + семья Pydantic schemas.\n- **Unit of Work.** Одна `UnitOfWork` на tool call, commit/rollback через `DbSessionMiddleware`.\n- **Pure domain.** `app/domain/` не знает о DB / HTTP / FastMCP (enforced by import-linter).\n\n### Audio module (`app/audio/`)\n\nLayered tiered pipeline L1→L4 (see [docs/audio-pipeline.md](docs/audio-pipeline.md)):\n\n```text\ncore/             ← DSP primitives (0 app deps)\n  types.py           FrameParams, AudioSignal, AnalyzerResult\n  framing.py         frame energies, energy slope\n  spectral.py        STFT, band energies, centroid, rolloff\n  loader.py          AudioLoader (soundfile → librosa → wave)\n  context.py         AnalysisContext (eager STFT, thread-safe)\n\nanalyzers/        ← 18 feature extractors\n  base.py            BaseAnalyzer (Template Method), @register_analyzer\n  beat, bpm, energy, key, loudness, mfcc, spectral, structure,\n  beats_loudness, bpm_histogram, danceability, dissonance,\n  dynamic_complexity, phrase, pitch_salience, spectral_complexity,\n  tempogram, tonnetz\n\nclassification/   ← 15 techno subgenres (rule-based)\n  profiles.py        SubgenreProfile dataclasses\n  classifier.py      MoodClassifier (Strategy pattern)\n\npipeline.py, level_config.py, temp_download.py, timeseries.py\n```\n\n- **Two-phase pipeline**: independent analyzers run in parallel, dependent analyzers receive merged results\n- **Tiered L1→L4**: L1+L2 triage (6 analyzers) → L3 scoring (+beat) → L4 transition (+structure + permanent MP3)\n- **Registry auto-discovery**: `@register_analyzer` + `pkgutil.iter_modules()`\n- **Eager context**: STFT/magnitude/freqs computed once, shared read-only — thread-safe\n- **SharedMemory transport** + per-worker `AnalysisContext` LRU — эффективный ProcessPool path\n\n**Server middleware (15 слоёв):** domain error → ToolError, Sentry context, FastMCP timing, audit log, retry, response limit/caching, deprecation, cost tracking, sampling budget, progress throttle, tool timeout, provider rate limit, DB session (UoW), structured logging.\n\nАрхитектурный блюпринт v1: [docs/superpowers/specs/2026-04-17-architecture-blueprint-design.md](docs/superpowers/specs/2026-04-17-architecture-blueprint-design.md)\n\n## Конфигурация\n\nВсе настройки через переменные окружения с префиксом `DJ_`. См. [.env.example](.env.example).\n\n### LLM-assisted discovery\n\nИспользуй prompt `expand_playlist_workflow` — он оркестрирует `provider_search` / `provider_read(entity=\"track_similar\")` → `entity_create(entity=\"track\")` → `entity_create(entity=\"track_features\")`.\n\nДля headless-сценариев опционально включи server-side sampling:\n\n```bash\n# В .env\nDJ_ANTHROPIC_API_KEY=sk-ant-...\n```\n\n`ctx.sample()` fallback подтягивает Anthropic API (см. `app/server/sampling.py`).\n\n## E2E Pipeline\n\nПолный цикл обработки трека (v1 dispatchers + handlers):\n\n```text\nentity_create(\"track\",...)  → entity_create(\"audio_file\",...)  → entity_create(\"track_features\",...)  → entity_create(\"set_version\",...)\n      │                              │                                 │                                        │\n track_import                 audio_file_download             track_features_analyze                 set_version_build\n      │                              │                                 │                                        │\n  Track row                   DjLibraryItem +                 18 analyzers → ~60 features           GA / greedy + mix points\n  (+ YM metadata)             MP3 on disk                     + mood classification                 + transition_persist\n```\n\nДополнительно: `transition_score_pool` → `sequence_optimize` → `entity_create(\"set_version\")` — trust-chain для сета из существующего пула.\n\n## Требования\n\n- Python 3.12+\n- uv (менеджер пакетов)\n- Supabase PostgreSQL 16+ (prod), SQLite in-memory (tests only)\n- Опционально: librosa (audio analysis), demucs (stem separation), fastmcp[tasks] (background tasks)\n\n## Документация\n\n| Тема | Документ |\n|---|---|\n| Архитектурный блюпринт v1 | [docs/superpowers/specs/2026-04-17-architecture-blueprint-design.md](docs/superpowers/specs/2026-04-17-architecture-blueprint-design.md) |\n| Bounded contexts + data flow | [docs/architecture.md](docs/architecture.md) |\n| MCP tool catalog (20 tools, 27 resources, 19 prompts) | [docs/tool-catalog.md](docs/tool-catalog.md) |\n| Audio analysis pipeline L1→L4 | [docs/audio-pipeline.md](docs/audio-pipeline.md) |\n| Transition scoring (6-component formula) | [docs/transition-scoring.md](docs/transition-scoring.md) |\n| Yandex Music API quirks | [docs/ym-api-guide.md](docs/ym-api-guide.md) |\n| DJ-терминология (BPM, Camelot, LUFS, subgenres) | [docs/domain-glossary.md](docs/domain-glossary.md) |\n\n## Лицензия\n\n[MIT](LICENSE) © Evgeny Gurin\n",
  "bytes": 11551,
  "sha": "57703777ea1d0551b359c7d8ff729ddb248c2a1cebbe5ef014cc5fad85468417",
  "repo_slug": "evgenygurin/dj-music-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_evgenygurin_dj_music_plugin_7c10222c/readme"
}