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, dannreicht „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 Server127.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).
