kbk-mcp

MCP-Server für KaboomKartell — bringt das KBK-Radio in jede MCP-fähige KI (Claude, ChatGPT, Perplexity …). Bind die URL einmal als Connector ein, dann reicht „guck mal auf KBK was läuft".

Öffentlicher Endpoint (nach Deploy): https://mcp.kaboomkartell.com/mcp

Tools (13 read-only + vote_track write + 1 App-Tool)

Tool	Was
get_now_playing	Live-Track je Channel (phonk/hardtek) + nächster Track
list_channels	Echte Struktur: 2 Channels, 4 Genres, Mapping, Akzentfarben
get_crowd_control	Die 5 Vote-Kandidaten + Live-Tally (read-only)
get_schedule / get_next_drop	Timetable + nächster Drop
search_tracks / get_track	Library-Suche + Track-Details
list_playlists / get_playlist	Playlists + ihre Tracks
get_stats	Live-Zahlen (wolves online, tracks spun, BPM, aura)
get_twitch_status	Twitch-Live-Status
get_live_alert	Zeitkritischer Live-Trigger (Twitch on air / nächstes Event) — einziger Anlass für eine proaktive Erinnerung
get_multiverse	Kanon des Song-Multiversums als Möglichkeitsraum (Kosmologie + Regeln + versiegelte Zonen) — proxied GET /api/kbk/canon der Website
vote_track	(write) Vote fürs nächste Lied (Crowd Control) mit Agenten-Token; ohne Token → Ein-Klick-Authorize-Link statt Fehler
play_channel	Öffnet das interaktive Player-Widget (MCP-App) und spielt den Live-Stream (Klick auf Play)

Architektur

• src/kbk-client.ts — einzige Kopplungsschicht zu den öffentlichen KBK-APIs.
• src/tools.ts — Registry der 13 read-only Tools (inkl. get_multiverse) + vote_track (write).
• src/player-app.ts — play_channel + UI-Resource (MCP-App).
• src/server.ts — createServer() (transport-agnostisch).
• src/main.ts — stdio-Entry (lokal/Claude Desktop).
• src/http.ts — Streamable HTTP-Entry (remote, /mcp + /health, Rate-Limit).
• src/ui/ — Player-Widget (vite → dist/ui/index.html, Single-File).

Daten-URLs: Tools rufen KBK intern (KBK_BASE_URL, auf dem Server 127.0.0.1:8081); Stream-/Cover-URLs werden auf die öffentliche Domain (KBK_PUBLIC_URL) umgeschrieben, damit der Browser sie laden kann.

Entwicklung

npm install
npm run build        # tsc (server) + vite (player-ui)
npm run smoke        # stdio-Test gegen Live-API (15 Tools + Player-Resource)
npm run smoke:http   # HTTP-Test (Streamable HTTP)

Lokal in Claude Desktop (stdio)

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "kbk": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\…\\kbk-mcp\\dist\\main.js"]
    }
  }
}

Öffentlich nutzen (Remote-Connector)

Sobald deployt, fügt jeder Nutzer den Connector einmal in seiner KI hinzu:

• Claude (Free/Pro/Max/Team/Enterprise): Settings → Connectors → Custom → URL https://mcp.kaboomkartell.com/mcp.
• ChatGPT (Pro + Developer Mode), Perplexity (Pro+): analog.

Danach: „Was läuft gerade auf KaboomKartell?" oder „Mach den KBK-Player auf."

Deploy (mcp.kaboomkartell.com)

Ein Linux-Server, Port 8086, hinter Caddy. Artefakte in deploy/:

• kbk-mcp.service → /etc/systemd/system/ (Port 8086, KBK_BASE_URL intern).
• Caddyfile-snippet.txt → Block in /etc/caddy/Caddyfile + systemctl reload caddy.
• deploy.sh → pull + npm ci + npm run build + restart + health-check.

Erst-Setup (einmalig, als root): Repo nach /opt/kbk-mcp/repo klonen, systemd-Unit + Caddy-Block installieren, systemctl enable --now kbk-mcp. Voraussetzung: die MCP-Domain ist per DNS propagiert. Updates danach via deploy.sh.

Roadmap

• Stufe 3: Voting mit OAuth (Crowd-Control aktiv mitsteuern), vote_next_track.
• Härtetest: Ton beim Weiterchatten — Claude und ChatGPT.

Tech

@modelcontextprotocol/sdk · @modelcontextprotocol/ext-apps · express 5 · zod 4 · vite + vite-plugin-singlefile · TypeScript (ESM).