@mcptoolshop/ai_jam_session 0.1.0

package/README.it.md

@@ -0,0 +1,212 @@
+<p align="center"><a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <strong>Italiano</strong> | <a href="README.pt-BR.md">Português</a></p>
+
+<p align="center">
+  <img src="logo.png" alt="Logo PianoAI" width="180" />
+</p>
+
+<h1 align="center">PianoAI</h1>
+
+<p align="center">
+  Pianoforte AI con motore audio integrato e libreria di 100 brani. Server MCP per Claude, CLI per gli esseri umani.
+</p>
+
+[![MCP Tools](https://img.shields.io/badge/MCP_tools-15-purple)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+[![Songs](https://img.shields.io/badge/songs-100_built--in-blue)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+
+## Cos'e?
+
+Un pianoforte che Claude sa suonare. PianoAI e un server MCP con motore audio integrato: riproduce il suono direttamente dai tuoi altoparlanti, senza bisogno di software esterno. Claude esplora una libreria di 100 brani in 10 generi, sceglie i pezzi, li insegna e ci improvvisa sopra. Funziona anche come CLI indipendente.
+
+## Funzionalita
+
+- **Motore piano integrato** — audio basato su campioni tramite `node-web-audio-api`, riproduce dagli altoparlanti
+- **Libreria di 100 brani** — classica, jazz, pop, blues, rock, R&B, latin, colonne sonore, ragtime, new-age
+- **AI Jam Session** — Claude analizza gli accordi e la melodia di un brano, poi crea la propria interpretazione
+- **Supporto file MIDI** — riproduci qualsiasi file `.mid`: `pianoai play song.mid`
+- **Sistema didattico** — note didattiche per ogni battuta, descrizioni del linguaggio musicale, consigli per lo studio
+- **4 modalita di riproduzione** — completa, battuta per battuta, mani separate, loop
+- **Controllo velocita** — da 0.5x per lo studio lento fino a 4x per la riproduzione veloce
+- **Controlli in tempo reale** — pausa, ripresa, cambio di velocita durante la riproduzione
+- **15 strumenti MCP** — riproduci, esplora, insegna, improvvisa, importa — tutto tramite il protocollo MCP
+- **Aggiungi i tuoi brani** — lo strumento `add_song` accetta JSON SongEntry, `import_midi` converte file MIDI
+- **Uscita MIDI opzionale** — instrada verso software esterno con il flag `--midi` (richiede loopMIDI + VMPK)
+
+## Installazione
+
+```bash
+npm install -g @mcptoolshop/ai_jam_session
+```
+
+Richiede **Node.js 18+**. Tutto qui — nessun driver MIDI, nessuna porta virtuale, nessun software esterno.
+
+## Avvio rapido
+
+```bash
+# Riproduci un brano dalla libreria
+ai-jam-session play let-it-be
+
+# Riproduci un file MIDI
+ai-jam-session play path/to/song.mid
+
+# Esercitati a meta velocita
+ai-jam-session play moonlight-sonata-mvt1 --speed 0.5
+
+# Elenca tutti i brani disponibili
+ai-jam-session list
+
+# Mostra i dettagli di un brano e le note didattiche
+ai-jam-session info autumn-leaves
+```
+
+### Opzioni di riproduzione
+
+| Flag | Descrizione |
+|------|-------------|
+| `--speed <mult>` | Moltiplicatore di velocita: 0.5 = meta, 1.0 = normale, 2.0 = doppia |
+| `--tempo <bpm>` | Sovrascrive il tempo predefinito del brano (10-400 BPM) |
+| `--mode <mode>` | Modalita di riproduzione: `full`, `measure`, `hands`, `loop` |
+| `--midi` | Instrada verso software MIDI esterno invece del motore integrato |
+
+## Server MCP
+
+Il server MCP espone 15 strumenti per l'integrazione con LLM:
+
+| Strumento | Descrizione |
+|-----------|-------------|
+| `list_songs` | Esplora/cerca brani per genere, difficolta o query |
+| `song_info` | Linguaggio musicale completo, obiettivi didattici, suggerimenti per lo studio |
+| `registry_stats` | Conteggio brani per genere e difficolta |
+| `teaching_note` | Nota didattica per battuta, diteggiatura, dinamiche |
+| `suggest_song` | Raccomandazione basata su criteri |
+| `list_measures` | Panoramica delle battute con note didattiche |
+| `practice_setup` | Suggerisce velocita, modalita e impostazioni per un brano |
+| `sing_along` | Testo cantabile (nomi delle note, solfeggio, contorno) per battuta |
+| `play_song` | Riproduci un brano o file MIDI dagli altoparlanti |
+| `pause_playback` | Metti in pausa o riprendi il brano in riproduzione |
+| `set_speed` | Cambia la velocita durante la riproduzione |
+| `stop_playback` | Ferma il brano in riproduzione |
+| `ai_jam_session` | Ottieni un brief per la jam — accordi, melodia, guida stilistica — per l'improvvisazione |
+| `add_song` | Aggiungi un nuovo brano (JSON SongEntry) alla libreria |
+| `import_midi` | Converti un file MIDI in SongEntry e registralo |
+
+### AI Jam Session
+
+Lo strumento `ai_jam_session` estrae un "jam brief" strutturato da qualsiasi brano: progressione di accordi, contorno melodico e guida stilistica specifica per il genere. Claude usa il brief per creare la propria interpretazione.
+
+Due modalita:
+- **Brano specifico:** `ai_jam_session({ songId: "autumn-leaves", style: "blues" })` — improvvisa su Autumn Leaves in stile blues
+- **Scelta casuale per genere:** `ai_jam_session({ genre: "jazz" })` — sceglie un brano jazz a caso e ci improvvisa sopra
+
+Parametri opzionali: `mood` (allegro, malinconico, sognante, ecc.), `difficulty`, `measures` (intervallo come "1-8").
+
+### Configurazione Claude Desktop / Claude Code
+
+```json
+{
+  "mcpServers": {
+    "pianoai": {
+      "command": "npx",
+      "args": ["-y", "-p", "@mcptoolshop/ai_jam_session", "ai-jam-session-mcp"]
+    }
+  }
+}
+```
+
+### Plugin per Claude Code
+
+PianoAI include un plugin per Claude Code che aggiunge comandi slash e personalita agente:
+
+| Comando | Descrizione |
+|---------|-------------|
+| `/pianoai:teach <song>` | Avvia una sessione didattica strutturata |
+| `/pianoai:practice <song>` | Ottieni un piano di studio con raccomandazioni su velocita e modalita |
+| `/pianoai:explore [query]` | Esplora la libreria musicale per genere, difficolta o parola chiave |
+| `/pianoai:jam <song or genre>` | Avvia una jam session — Claude crea la propria interpretazione |
+
+Due personalita agente:
+- **Piano Teacher** — paziente, pedagogico, si adatta al livello dello studente
+- **Jam Musician** — atmosfera rilassata da jam band, prima il groove, incoraggia la sperimentazione
+
+## Libreria musicale
+
+100 brani integrati in 10 generi, 3 livelli di difficolta:
+
+| Genere | Brani | Esempi |
+|--------|-------|--------|
+| Classica | 10 | Fur Elise, Clair de Lune, Moonlight Sonata, Bach Prelude in C |
+| Jazz | 10 | Autumn Leaves, Take Five, So What, Misty |
+| Pop | 10 | Imagine, Hallelujah, Piano Man, Bohemian Rhapsody |
+| Blues | 10 | Basic 12-Bar, St. Louis Blues, Stormy Monday, Thrill Is Gone |
+| Rock | 10 | Stairway Intro, Hotel California, Rocket Man, Layla Coda |
+| R&B | 10 | Superstition, Georgia On My Mind, Lean On Me, My Girl |
+| Latin | 10 | Girl from Ipanema, Besame Mucho, Oye Como Va, Wave |
+| Colonne sonore | 11 | Cinema Paradiso, Moon River, Hedwig's Theme, Spirited Away |
+| Ragtime | 9 | The Entertainer, Maple Leaf Rag, Elite Syncopations |
+| New-Age | 10 | River Flows in You, Snowfall, Crystal Stream, Evening Calm |
+
+## API programmatica
+
+```typescript
+import { createAudioEngine, parseMidiFile, PlaybackController } from "@mcptoolshop/ai_jam_session";
+
+const connector = createAudioEngine();
+await connector.connect();
+
+const midi = await parseMidiFile("song.mid");
+const controller = new PlaybackController(connector, midi);
+
+controller.on("noteOn", (e) => console.log(`Note: ${e.noteName}`));
+await controller.play({ speed: 0.75 });
+
+controller.pause();
+controller.setSpeed(1.5);
+await controller.resume();
+
+await connector.disconnect();
+```
+
+### Riproduci un brano dalla libreria
+
+```typescript
+import { getSong, createSession, createAudioEngine } from "@mcptoolshop/ai_jam_session";
+
+const connector = createAudioEngine();
+await connector.connect();
+
+const song = getSong("autumn-leaves")!;
+const session = createSession(song, connector, {
+  mode: "full",
+  speed: 0.75,
+});
+
+await session.play();
+await connector.disconnect();
+```
+
+## Architettura
+
+```
+MIDI files (.mid)          Built-in song library (JSON)
+       |                              |
+       v                              v
+  MIDI Parser ──────────────── Note Parser
+       |                              |
+       v                              v
+ MidiPlaybackEngine            SessionController
+       |                              |
+       └──────── PlaybackController ──┘
+                 (real-time events, hooks)
+                        |
+          ┌─────────────┼─────────────┐
+          v             v             v
+     AudioEngine   Teaching Hooks  Progress
+     (speakers)    (per-measure)   (callbacks)
+          |
+          v
+    node-web-audio-api (Rust DSP)
+```
+
+## Licenza
+
+MIT

package/README.ja.md

@@ -0,0 +1,214 @@
+<p align="center">
+  <a href="README.md">English</a> | <strong>日本語</strong> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português</a>
+</p>
+
+<p align="center">
+  <img src="logo.png" alt="PianoAI logo" width="180" />
+</p>
+
+<h1 align="center">PianoAI</h1>
+
+<p align="center">
+  内蔵オーディオエンジンと100曲ライブラリを備えたAIピアノプレイヤー。Claude用MCPサーバー、人間用CLI。
+</p>
+
+[![MCP Tools](https://img.shields.io/badge/MCP_tools-15-purple)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+[![Songs](https://img.shields.io/badge/songs-100_built--in-blue)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+
+## これは何ですか？
+
+Claudeが演奏できるピアノです。PianoAIは内蔵オーディオエンジンを搭載したMCPサーバーで、外部ソフトウェア不要でスピーカーから直接再生します。Claudeは10ジャンル100曲のライブラリを閲覧し、楽曲を選び、教え、ジャムセッションを行います。スタンドアロンCLIとしても動作します。
+
+## 機能
+
+- **内蔵ピアノエンジン** — `node-web-audio-api`によるサンプルベースオーディオ、スピーカーから再生
+- **100曲ライブラリ** — クラシック、ジャズ、ポップ、ブルース、ロック、R&B、ラテン、映画音楽、ラグタイム、ニューエイジ
+- **AIジャムセッション** — Claudeが楽曲のコードとメロディを分析し、独自の解釈を創作
+- **MIDIファイル対応** — 任意の`.mid`ファイルを再生: `ai-jam-session play song.mid`
+- **教習システム** — 小節ごとの教習ノート、音楽表現の解説、練習のアドバイス
+- **4つの再生モード** — フル再生、小節ごと、片手ずつ、ループ
+- **速度制御** — 0.5倍のスロー練習から4倍の高速再生まで
+- **リアルタイム操作** — 再生中の一時停止、再開、速度変更
+- **15のMCPツール** — 再生、閲覧、教習、ジャム、インポート — すべてMCPプロトコル経由
+- **楽曲の追加** — `add_song`ツールでSongEntry JSONを受付、`import_midi`でMIDIファイルを変換
+- **オプションのMIDI出力** — `--midi`フラグで外部ソフトウェアに転送（loopMIDI + VMPKが必要）
+
+## インストール
+
+```bash
+npm install -g @mcptoolshop/ai_jam_session
+```
+
+**Node.js 18+**が必要です。それだけです — MIDIドライバも、仮想ポートも、外部ソフトウェアも不要です。
+
+## クイックスタート
+
+```bash
+# 内蔵楽曲を再生
+ai-jam-session play let-it-be
+
+# MIDIファイルを再生
+ai-jam-session play path/to/song.mid
+
+# 半速で練習
+ai-jam-session play moonlight-sonata-mvt1 --speed 0.5
+
+# すべての内蔵楽曲を一覧表示
+ai-jam-session list
+
+# 楽曲の詳細と教習ノートを表示
+ai-jam-session info autumn-leaves
+```
+
+### 再生オプション
+
+| フラグ | 説明 |
+|------|------|
+| `--speed <mult>` | 速度倍率: 0.5 = 半速、1.0 = 通常、2.0 = 倍速 |
+| `--tempo <bpm>` | 楽曲のデフォルトテンポをオーバーライド（10-400 BPM） |
+| `--mode <mode>` | 再生モード: `full`、`measure`、`hands`、`loop` |
+| `--midi` | 内蔵エンジンの代わりに外部MIDIソフトウェアに転送 |
+
+## MCPサーバー
+
+MCPサーバーはLLM連携用に15のツールを公開しています:
+
+| ツール | 説明 |
+|------|------|
+| `list_songs` | ジャンル、難易度、クエリで楽曲を検索・閲覧 |
+| `song_info` | 音楽表現、教習目標、練習提案の詳細情報 |
+| `registry_stats` | ジャンル別・難易度別の楽曲数 |
+| `teaching_note` | 小節ごとの教習ノート、運指、ダイナミクス |
+| `suggest_song` | 条件に基づくおすすめ楽曲 |
+| `list_measures` | 教習ノート付きの小節一覧 |
+| `practice_setup` | 楽曲に適した速度、モード、設定を提案 |
+| `sing_along` | 小節ごとの歌唱テキスト（音名、ソルフェージュ、輪郭） |
+| `play_song` | 楽曲またはMIDIファイルをスピーカーから再生 |
+| `pause_playback` | 現在再生中の楽曲を一時停止または再開 |
+| `set_speed` | 再生中に速度を変更 |
+| `stop_playback` | 現在再生中の楽曲を停止 |
+| `ai_jam_session` | ジャムブリーフを取得 — コード、メロディ、スタイルのガイダンス — 即興演奏用 |
+| `add_song` | 新しい楽曲（SongEntry JSON）をライブラリに追加 |
+| `import_midi` | MIDIファイルをSongEntryに変換してライブラリに登録 |
+
+### AIジャムセッション
+
+`ai_jam_session`ツールは任意の楽曲から構造化された「ジャムブリーフ」を抽出します: コード進行、メロディの輪郭、ジャンル固有のスタイルガイダンス。Claudeはこのブリーフを使って独自の解釈を創作します。
+
+2つのモード:
+- **特定の楽曲:** `ai_jam_session({ songId: "autumn-leaves", style: "blues" })` — Autumn Leavesをブルーススタイルでジャム
+- **ランダムなジャンル選択:** `ai_jam_session({ genre: "jazz" })` — ランダムなジャズ楽曲を選んでジャム
+
+オプションパラメータ: `mood`（アップビート、メランコリック、ドリーミーなど）、`difficulty`、`measures`（"1-8"のような範囲指定）。
+
+### Claude Desktop / Claude Code設定
+
+```json
+{
+  "mcpServers": {
+    "pianoai": {
+      "command": "npx",
+      "args": ["-y", "-p", "@mcptoolshop/ai_jam_session", "ai-jam-session-mcp"]
+    }
+  }
+}
+```
+
+### Claude Codeプラグイン
+
+PianoAIにはスラッシュコマンドとエージェントパーソナリティを追加するClaude Codeプラグインが付属しています:
+
+| コマンド | 説明 |
+|---------|------|
+| `/pianoai:teach <song>` | 構造化された教習セッションを開始 |
+| `/pianoai:practice <song>` | 速度・モードのおすすめ付き練習プランを取得 |
+| `/pianoai:explore [query]` | ジャンル、難易度、キーワードでライブラリを閲覧 |
+| `/pianoai:jam <song or genre>` | ジャムセッションを開始 — Claudeが独自の解釈を創作 |
+
+2つのエージェントパーソナリティ:
+- **ピアノ教師** — 忍耐強く教育的、生徒のレベルに合わせた指導
+- **ジャムミュージシャン** — リラックスしたジャムバンドの雰囲気、グルーヴ重視、実験を促進
+
+## 楽曲ライブラリ
+
+10ジャンル、3段階の難易度にわたる100曲の内蔵楽曲:
+
+| ジャンル | 曲数 | 例 |
+|---------|------|------|
+| クラシック | 10 | Fur Elise, Clair de Lune, Moonlight Sonata, Bach Prelude in C |
+| ジャズ | 10 | Autumn Leaves, Take Five, So What, Misty |
+| ポップ | 10 | Imagine, Hallelujah, Piano Man, Bohemian Rhapsody |
+| ブルース | 10 | Basic 12-Bar, St. Louis Blues, Stormy Monday, Thrill Is Gone |
+| ロック | 10 | Stairway Intro, Hotel California, Rocket Man, Layla Coda |
+| R&B | 10 | Superstition, Georgia On My Mind, Lean On Me, My Girl |
+| ラテン | 10 | Girl from Ipanema, Besame Mucho, Oye Como Va, Wave |
+| 映画音楽 | 11 | Cinema Paradiso, Moon River, Hedwig's Theme, Spirited Away |
+| ラグタイム | 9 | The Entertainer, Maple Leaf Rag, Elite Syncopations |
+| ニューエイジ | 10 | River Flows in You, Snowfall, Crystal Stream, Evening Calm |
+
+## プログラマティックAPI
+
+```typescript
+import { createAudioEngine, parseMidiFile, PlaybackController } from "@mcptoolshop/ai_jam_session";
+
+const connector = createAudioEngine();
+await connector.connect();
+
+const midi = await parseMidiFile("song.mid");
+const controller = new PlaybackController(connector, midi);
+
+controller.on("noteOn", (e) => console.log(`Note: ${e.noteName}`));
+await controller.play({ speed: 0.75 });
+
+controller.pause();
+controller.setSpeed(1.5);
+await controller.resume();
+
+await connector.disconnect();
+```
+
+### 内蔵楽曲を再生
+
+```typescript
+import { getSong, createSession, createAudioEngine } from "@mcptoolshop/ai_jam_session";
+
+const connector = createAudioEngine();
+await connector.connect();
+
+const song = getSong("autumn-leaves")!;
+const session = createSession(song, connector, {
+  mode: "full",
+  speed: 0.75,
+});
+
+await session.play();
+await connector.disconnect();
+```
+
+## アーキテクチャ
+
+```
+MIDIファイル (.mid)          内蔵楽曲ライブラリ (JSON)
+       |                              |
+       v                              v
+  MIDIパーサー ──────────────── ノートパーサー
+       |                              |
+       v                              v
+ MidiPlaybackEngine            SessionController
+       |                              |
+       └──────── PlaybackController ──┘
+                 (リアルタイムイベント、フック)
+                        |
+          ┌─────────────┼─────────────┐
+          v             v             v
+     AudioEngine   教習フック       プログレス
+     (スピーカー)   (小節ごと)      (コールバック)
+          |
+          v
+    node-web-audio-api (Rust DSP)
+```
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,214 @@
+<p align="center">
+  <a href="README.md"><strong>English</strong></a> | <a href="README.ja.md">日本語</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português</a>
+</p>
+
+<p align="center">
+  <img src="logo.png" alt="PianoAI logo" width="180" />
+</p>
+
+<h1 align="center">PianoAI</h1>
+
+<p align="center">
+  AI piano player with built-in audio engine and 100-song library. MCP server for Claude, CLI for humans.
+</p>
+
+[![MCP Tools](https://img.shields.io/badge/MCP_tools-15-purple)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+[![Songs](https://img.shields.io/badge/songs-100_built--in-blue)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+
+## What is this?
+
+A piano that Claude can play. PianoAI is an MCP server with a built-in audio engine — it plays through your speakers, no external software required. Claude browses a 100-song library spanning 10 genres, picks songs, teaches them, and jams on them. Also works as a standalone CLI.
+
+## Features
+
+- **Built-in piano engine** — sample-based audio via `node-web-audio-api`, plays through speakers
+- **100-song library** — classical, jazz, pop, blues, rock, R&B, latin, film, ragtime, new-age
+- **AI Jam Session** — Claude analyzes a song's chords and melody, then creates its own interpretation
+- **MIDI file support** — play any `.mid` file: `pianoai play song.mid`
+- **Teaching system** — per-measure teaching notes, musical language descriptions, practice recommendations
+- **4 playback modes** — full, measure-by-measure, hands separate, loop
+- **Speed control** — 0.5x slow practice to 4x fast
+- **Real-time controls** — pause, resume, speed change during playback
+- **15 MCP tools** — play, browse, teach, jam, import — all through the MCP protocol
+- **Add your own songs** — `add_song` tool accepts SongEntry JSON, `import_midi` converts MIDI files
+- **Optional MIDI output** — route to external software via `--midi` flag (requires loopMIDI + VMPK)
+
+## Install
+
+```bash
+npm install -g @mcptoolshop/ai_jam_session
+```
+
+Requires **Node.js 18+**. That's it — no MIDI drivers, no virtual ports, no external software.
+
+## Quick Start
+
+```bash
+# Play a built-in song
+ai-jam-session play let-it-be
+
+# Play a MIDI file
+ai-jam-session play path/to/song.mid
+
+# Half-speed practice
+ai-jam-session play moonlight-sonata-mvt1 --speed 0.5
+
+# List all built-in songs
+ai-jam-session list
+
+# Show song details + teaching notes
+ai-jam-session info autumn-leaves
+```
+
+### Play Options
+
+| Flag | Description |
+|------|-------------|
+| `--speed <mult>` | Speed multiplier: 0.5 = half, 1.0 = normal, 2.0 = double |
+| `--tempo <bpm>` | Override the song's default tempo (10-400 BPM) |
+| `--mode <mode>` | Playback mode: `full`, `measure`, `hands`, `loop` |
+| `--midi` | Route to external MIDI software instead of built-in engine |
+
+## MCP Server
+
+The MCP server exposes 15 tools for LLM integration:
+
+| Tool | Description |
+|------|-------------|
+| `list_songs` | Browse/search songs by genre, difficulty, or query |
+| `song_info` | Full musical language, teaching goals, practice suggestions |
+| `registry_stats` | Song counts by genre and difficulty |
+| `teaching_note` | Per-measure teaching note, fingering, dynamics |
+| `suggest_song` | Recommendation based on criteria |
+| `list_measures` | Overview of measures with teaching notes |
+| `practice_setup` | Suggest speed, mode, and settings for a song |
+| `sing_along` | Singable text (note names, solfege, contour) per measure |
+| `play_song` | Play a song or MIDI file through speakers |
+| `pause_playback` | Pause or resume the currently playing song |
+| `set_speed` | Change playback speed during playback |
+| `stop_playback` | Stop the currently playing song |
+| `ai_jam_session` | Get a jam brief — chords, melody, style guidance — for improvisation |
+| `add_song` | Add a new song (SongEntry JSON) to the library |
+| `import_midi` | Convert a MIDI file into a SongEntry and register it |
+
+### AI Jam Session
+
+The `ai_jam_session` tool extracts a structured "jam brief" from any song: chord progression, melody contour, and genre-specific style guidance. Claude uses the brief to create its own interpretation.
+
+Two modes:
+- **Specific song:** `ai_jam_session({ songId: "autumn-leaves", style: "blues" })` — jam on Autumn Leaves, blues style
+- **Random genre pick:** `ai_jam_session({ genre: "jazz" })` — pick a random jazz song and jam on it
+
+Optional parameters: `mood` (upbeat, melancholic, dreamy, etc.), `difficulty`, `measures` (range like "1-8").
+
+### Claude Desktop / Claude Code configuration
+
+```json
+{
+  "mcpServers": {
+    "pianoai": {
+      "command": "npx",
+      "args": ["-y", "-p", "@mcptoolshop/ai_jam_session", "ai-jam-session-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code Plugin
+
+PianoAI ships with a Claude Code plugin that adds slash commands and agent personalities:
+
+| Command | Description |
+|---------|-------------|
+| `/pianoai:teach <song>` | Start a structured teaching session |
+| `/pianoai:practice <song>` | Get a practice plan with speed/mode recommendations |
+| `/pianoai:explore [query]` | Browse the song library by genre, difficulty, or keyword |
+| `/pianoai:jam <song or genre>` | Start a jam session — Claude creates its own interpretation |
+
+Two agent personalities:
+- **Piano Teacher** — patient, pedagogical, meets students where they are
+- **Jam Musician** — laid-back jam band vibes, groove-first, encourages experimentation
+
+## Song Library
+
+100 built-in songs across 10 genres, 3 difficulty levels:
+
+| Genre | Songs | Examples |
+|-------|-------|---------|
+| Classical | 10 | Fur Elise, Clair de Lune, Moonlight Sonata, Bach Prelude in C |
+| Jazz | 10 | Autumn Leaves, Take Five, So What, Misty |
+| Pop | 10 | Imagine, Hallelujah, Piano Man, Bohemian Rhapsody |
+| Blues | 10 | Basic 12-Bar, St. Louis Blues, Stormy Monday, Thrill Is Gone |
+| Rock | 10 | Stairway Intro, Hotel California, Rocket Man, Layla Coda |
+| R&B | 10 | Superstition, Georgia On My Mind, Lean On Me, My Girl |
+| Latin | 10 | Girl from Ipanema, Besame Mucho, Oye Como Va, Wave |
+| Film | 11 | Cinema Paradiso, Moon River, Hedwig's Theme, Spirited Away |
+| Ragtime | 9 | The Entertainer, Maple Leaf Rag, Elite Syncopations |
+| New-Age | 10 | River Flows in You, Snowfall, Crystal Stream, Evening Calm |
+
+## Programmatic API
+
+```typescript
+import { createAudioEngine, parseMidiFile, PlaybackController } from "@mcptoolshop/ai_jam_session";
+
+const connector = createAudioEngine();
+await connector.connect();
+
+const midi = await parseMidiFile("song.mid");
+const controller = new PlaybackController(connector, midi);
+
+controller.on("noteOn", (e) => console.log(`Note: ${e.noteName}`));
+await controller.play({ speed: 0.75 });
+
+controller.pause();
+controller.setSpeed(1.5);
+await controller.resume();
+
+await connector.disconnect();
+```
+
+### Play a built-in song
+
+```typescript
+import { getSong, createSession, createAudioEngine } from "@mcptoolshop/ai_jam_session";
+
+const connector = createAudioEngine();
+await connector.connect();
+
+const song = getSong("autumn-leaves")!;
+const session = createSession(song, connector, {
+  mode: "full",
+  speed: 0.75,
+});
+
+await session.play();
+await connector.disconnect();
+```
+
+## Architecture
+
+```
+MIDI files (.mid)          Built-in song library (JSON)
+       |                              |
+       v                              v
+  MIDI Parser ──────────────── Note Parser
+       |                              |
+       v                              v
+ MidiPlaybackEngine            SessionController
+       |                              |
+       └──────── PlaybackController ──┘
+                 (real-time events, hooks)
+                        |
+          ┌─────────────┼─────────────┐
+          v             v             v
+     AudioEngine   Teaching Hooks  Progress
+     (speakers)    (per-measure)   (callbacks)
+          |
+          v
+    node-web-audio-api (Rust DSP)
+```
+
+## License
+
+MIT