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)

Related MCP server: beatport-mcp-server

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).